DOCSEARCHbyAlgolia
Submit Docs

Maputnik Documentation

repository·main·Indexed 25 days ago

https://github.com/maplibre/maputnik

A free and open visual style editor for MapLibre GL styles, designed for developers and map designers. Maputnik allows users to create and edit map styles visually and can be run as a cross-platform desktop executable, via Docker, or in a development environment. It includes a desktop HTTP API for programmatically managing style files and supports advanced styling logic through zoom functions, data functions, and MapLibre GL expressions.

Tokens
6.4K
Snippets
14
Records
38
Agent score
82%

What's inside Maputnik

  1. How Maputnik handles language selection

    main

    Maputnik uses two mechanisms for determining the active language:

    1. Automatic Detection: It automatically localizes based on the user's browser language settings.
    2. Persistence: The selected language is stored in the browser's local storage.

    To test the first-time user experience (where no local storage exists), use an incognito/private browsing window.

  2. Run End-to-End (E2E) tests with Playwright

    main

    Maputnik uses Playwright for E2E testing. Tests are located in the e2e directory and utilize the MaputnikDriver page object.

    Before running tests for the first time, you must install the required Chromium browser. The npm run test command automatically starts the development server for you.

    # install the browser
npx playwright install chromium

# run the tests
npm run test

# see the tests run in a headed browser
npm run test -- --headed

# run a single spec / filter by title
npm run test -- e2e/map.spec.ts
npm run test -- -g "zoom level"

# open the interactive UI mode
npx playwright test --ui

  4. Run Maputnik locally for development

    main

    To develop Maputnik locally, you need to install dependencies and start the development server. The editor will be available at http://localhost:8888/.

    If you need the dev server to be accessible from other devices on your network, use the --host option to bind to 0.0.0.0.

    # install dependencies
npm install

# start dev server
npm run start

# start externally accessible dev server
npm run start -- --host 0.0.0.0

  5. Add localization for a new feature

    main

    If you introduce a new feature that requires translatable text, you must update the translation files. Run the following command to identify and generate the necessary keys:

    npm run i18n:refresh

    After running this, check your working directory for new files and add or correct the translations as needed. You can verify the UI by using the language dropdown in the top menu of the Maputnik interface.

  8. Add a new language to Maputnik

    main

    To add a new language translation to Maputnik, follow these three steps:

    1. Edit configuration

    Add the new language's ISO Code to the configuration files in alphabetical order:

    • Add the ISO Code to the locales array in /i18next-parser.config.ts.
    • Add the ISO Code and its localized name to the supported languages list in /src/i18n.ts.

    2. Generate and populate translation strings

    Run the i18n refresh command to generate a new directory under /src/locales/ for your language:

    npm install
npm run i18n:refresh

    Locate the newly generated translation.json file and replace every instance of the placeholder __STRING_NOT_TRANSLATED__ with the actual translation. Ensure all keys are translated.

    3. Test the locale

    Start a local instance of Maputnik to verify the implementation:

    npm run start
    npm install
npm run i18n:refresh
npm run start

  9. Run Maputnik using Docker

    main

    You can run Maputnik in a Docker container to host the editor locally. Once running, access the editor by browsing to http://localhost:8888. Use Ctrl+C to stop the server.

    To view available CLI options (such as file watching or style serving), run the container with the --help flag. Note that you may need to mount a volume using the -v flag to persist or access local files.

    docker run -it --rm -p 8888:8000 ghcr.io/maplibre/maputnik:main

  10. Understand FieldFunction data types

    main

    The FieldFunction component manages how different types of MapLibre style properties are edited. It determines the appropriate sub-component to render based on the current value and fieldSpec. The component identifies four primary data types:

    • value: A primitive value (string, boolean, number) or a simple array of primitives. This is the base state for a property.
    • zoom_function: A property that changes based on the map zoom level (e.g., using a stops array where keys are zoom levels).
    • data_function: A property that changes based on data attributes (e.g., categorical or interval types) often combined with zoom levels.
    • expression: A complex MapLibre GL expression (e.g., ['get', 'property'] or ['interpolate', ...]) used for advanced styling logic.

    Transitions between these types are triggered by user actions like clicking 'Zoom', 'Data', or 'Expression' buttons within the UI.

  12. Run Unit and Component tests with Vitest

    main

    Unit and component tests are executed using Vitest. Component tests (files ending in *.browser.test.tsx) run in Vitest's browser mode using the Playwright provider.

    npm run test-unit