{"id":13220,"library":"geostyler-mapbox-parser","title":"GeoStyler Mapbox Parser","description":"geostyler-mapbox-parser is a JavaScript/TypeScript library that provides an implementation for the GeoStyler-Style-Parser interface, specifically for converting between GeoStyler's abstract style representation and Mapbox GL JS style specifications. The current stable version is 6.2.0, with regular updates and new feature releases (e.g., v6.2.0 in late 2025, v6.1.0 and v6.0.0 in 2024). It serves as a critical component in the GeoStyler ecosystem, enabling developers to define styles once and apply them across various mapping libraries. Key differentiators include its adherence to the GeoStyler abstract style format, comprehensive support for Mapbox GL JS style properties, and explicit handling of Mapbox-specific concepts like spritesheets (requiring a companion API endpoint) and source definitions (managed in metadata for data/style separation). The library transitioned to an ESM-only build in v6.0.0, impacting import patterns for consumers.","status":"active","version":"6.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/geostyler/geostyler-mapbox-parser","tags":["javascript","mapbox","geostyler","typescript"],"install":[{"cmd":"npm install geostyler-mapbox-parser","lang":"bash","label":"npm"},{"cmd":"yarn add geostyler-mapbox-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add geostyler-mapbox-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for the abstract GeoStyler style definition and utilities.","package":"geostyler-style","optional":false},{"reason":"TypeScript type definitions for Mapbox GL JS styles.","package":"@types/mapbox-gl","optional":true}],"imports":[{"note":"Since v6.0.0, the package is ESM-only. CommonJS `require()` is not supported directly without bundler configuration.","wrong":"const MapboxParser = require('geostyler-mapbox-parser');","symbol":"MapboxParser","correct":"import MapboxParser from 'geostyler-mapbox-parser';"},{"note":"When loaded directly in a browser via a script tag, the parser is exposed under the global `GeoStylerMapboxParser` object.","symbol":"GeoStylerMapboxParser","correct":"const parser = new GeoStylerMapboxParser.MapboxStyleParser();"},{"note":"These types are useful for TypeScript projects to infer the shape of the parser's input/output.","symbol":"ReadStyleResult, WriteStyleResult","correct":"import type { ReadStyleResult, WriteStyleResult } from 'geostyler-mapbox-parser';"}],"quickstart":{"code":"import MapboxParser from \"geostyler-mapbox-parser\";\n\nconst pointSimplePoint = {\n  name: \"My Style\",\n  rules: [\n    {\n      name: \"My Rule\",\n      symbolizers: [\n        {\n          kind: \"Mark\",\n          wellKnownName: \"circle\",\n          color: \"#FF0000\",\n          radius: 6\n        }\n      ]\n    }\n  ]\n};\n\nconst parser = new MapboxParser();\n\nasync function convertStyle() {\n  try {\n    const { output: mbStyle } = await parser.writeStyle(pointSimplePoint);\n    console.log(mbStyle);\n    /*\n    Expected output structure similar to:\n    {\n      \"version\": 8,\n      \"name\": \"My Style\",\n      \"layers\": [\n        {\n          \"id\": \"My_Rule\",\n          \"type\": \"circle\",\n          \"paint\": {\n            \"circle-color\": \"#FF0000\",\n            \"circle-radius\": 6\n          }\n        }\n      ]\n    }\n    */\n  } catch (error) {\n    console.error(\"Error converting style:\", error);\n  }\n}\n\nconvertStyle();","lang":"typescript","description":"Demonstrates how to initialize the parser and convert a simple GeoStyler point style object into a Mapbox GL JS style definition asynchronously."},"warnings":[{"fix":"Update import statements to use ES6 `import` syntax. If using CommonJS, configure your bundler (e.g., Webpack, Rollup) to handle ESM or ensure your Node.js environment supports ESM. For browser usage via script tags, access `GeoStylerMapboxParser.MapboxStyleParser`.","message":"Version 6.0.0 switched to an ESM (ECMAScript Module) build. This fundamentally changes how the package is imported and used, especially in CommonJS environments or older bundler setups.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Review existing sprite definitions and update them to conform to the `geostyler-style` Sprite object structure.","message":"Version 5.0.0 changed the handling of sprites. Instead of simple string syntax, it now uses `geostyler-style`'s `Sprite` object, requiring users to adapt their sprite definitions.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure all Mapbox style objects passed to the parser include a valid `source` property.","message":"Version 5.0.0 made the `source` property a required field within the `MbStyle` type to align with the Mapbox Style Specification. Styles that previously omitted this property will now cause type errors or runtime issues.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Implement the `/sprites` API endpoint in your application that returns a reference to a single image based on `name` and `baseurl` query parameters.","message":"The parser's sprite/icon handling depends on the consuming application implementing a specific API endpoint (`GET /sprites/?name&baseurl`) to resolve sprite images. Without this, sprite rendering may fail.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"When reading a style, extract `sources`, `sourceMapping`, and `layerSourceMapping` from `style.metadata['mapbox:ref']` to correctly re-create the layer structure with your map library.","message":"To maintain a clear separation between style and data, GeoStyler-Mapbox-Parser stores Mapbox style `sources` and layer-to-source mappings within the `metadata` block of the GeoStyler style (under `mapbox:ref`), not directly in the main style object.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) or use a bundler to transpile.","cause":"Attempting to use ES6 `import` syntax in a CommonJS environment or without proper module configuration in Node.js after v6.0.0.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Ensure the library is loaded via a `<script>` tag and then instantiate `new GeoStylerMapboxParser.MapboxStyleParser()`.","cause":"Attempting to instantiate `MapboxParser` incorrectly in a browser environment, or the script for the library was not loaded.","error":"TypeError: GeoStylerMapboxParser.MapboxStyleParser is not a constructor"},{"fix":"Add a `source` property to your Mapbox style input object, even if it's an empty object if no specific source is needed at the style level (though typically a valid source ID is expected).","cause":"Passing a Mapbox style object to the parser that lacks the mandatory `source` property, enforced since v5.0.0.","error":"Property 'source' is missing in type '{ ... }' but required in type 'MbStyle'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}