Set up local environment

Setup Python development environment

1. Ensure you are using Python 3.10 (We recommend using pyenv to handle different Python versions.)

2. Ensure you have the dependency management tool Poetry installed by this guide. The easiest is to do pip install poetry

3. Ensure you have the dependency tool tesseract installed, following the instructions in this guide.

4. From the root folder, install the dependencies in a virtual environment:

   poetry install -E parsers
   

You can now run a few different commands:

poetry run lint # linting
poetry run test # run unit tests
poetry run check # run both linting and tests

You might need to have zlib and libjpeg installed on your machine.

To ensure all dependencies required by opencv are installed, you can run apt-get update && apt-get install -y python3-opencv

Having problems?

First up, make sure you're using Python 3.10. Also, see Troubleshooting for fixes to common issues.

If it's still not working, please create an issue where you include the output from poetry debug so that we can help debug it.

Setup frontend environment

1. Ensure you have nodejs 20 installed (based on compatibility).

2. Run:

   sudo npm install --global pnpm

3. In the web folder run:

   pnpm install

4. Do the same from the mockserver folder:

   pnpm install

Running the frontend map

There are two ways to run the frontend map the quickest and easiest way is to use the vite dev server and the second way is to use build to create a full production build, the later is only recommended when testing the build pipeline.

Vite development server

1. Run the following command in the web folder:

   pnpm run dev

2. Go to http://localhost:5173/ and you should see the map!

3. Color the map by opening a new terminal in the web folder and starting the mockserver with the following command:

   pnpm run mockserver

Vite production build

1. Provide a value for the required environment variables, listed here. These can be set in a .env file inside the web folder.

2. Run the following command in the web folder:

   pnpm run build

3. Start the preview server with:

   pnpm run preview

Notes:

• The backend handles the calculation of carbon emissions. The map data from the mock server provides dummy data from the state file.

See Troubleshooting for common issues and fixes when building the map locally.

Code formatting

Your code contributions can't be merged with the codebase unless they respect the Electricity Maps contrib code formatting.

To check whether you code respects the formatting, you can run the following commands:

Python

poetry run check

If you see that your code fails the formatting check, you can autoformat it by running:

poetry run format

JavaScript, JSON, CSS, YML and more:

npx prettier --check .

And if the check fails you can run the following command to fix it:

npx prettier --write .