Registry / serialization / geostyler-mapbox-parser

geostyler-mapbox-parser

library6.2.0jsnpmunverified

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.

serialization

npm install geostyler-mapbox-parser

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GEOSTYLER-MAPBOX-P

geostyler-mapbox-parser

serializationjavascriptv6.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MapboxParser

✓ import MapboxParser from 'geostyler-mapbox-parser';

✗ const MapboxParser = require('geostyler-mapbox-parser');

Since v6.0.0, the package is ESM-only. CommonJS `require()` is not supported directly without bundler configuration.

GeoStylerMapboxParser

✓ const parser = new GeoStylerMapboxParser.MapboxStyleParser();

When loaded directly in a browser via a script tag, the parser is exposed under the global `GeoStylerMapboxParser` object.

ReadStyleResult, WriteStyleResult

✓ import type { ReadStyleResult, WriteStyleResult } from 'geostyler-mapbox-parser';

These types are useful for TypeScript projects to infer the shape of the parser's input/output.

Demonstrates how to initialize the parser and convert a simple GeoStyler point style object into a Mapbox GL JS style definition asynchronously.

import MapboxParser from "geostyler-mapbox-parser"; const pointSimplePoint = { name: "My Style", rules: [ { name: "My Rule", symbolizers: [ { kind: "Mark", wellKnownName: "circle", color: "#FF0000", radius: 6 } ] } ] }; const parser = new MapboxParser(); async function convertStyle() { try { const { output: mbStyle } = await parser.writeStyle(pointSimplePoint); console.log(mbStyle); /* Expected output structure similar to: { "version": 8, "name": "My Style", "layers": [ { "id": "My_Rule", "type": "circle", "paint": { "circle-color": "#FF0000", "circle-radius": 6 } } ] } */ } catch (error) { console.error("Error converting style:", error); } } convertStyle();

Debug

Known issues

breakingVersion 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.

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`.

affects: >=6.0.0

breakingVersion 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.

fix

Review existing sprite definitions and update them to conform to the `geostyler-style` Sprite object structure.

affects: >=5.0.0

breakingVersion 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.

fix

Ensure all Mapbox style objects passed to the parser include a valid `source` property.

affects: >=5.0.0

gotchaThe 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.

fix

Implement the `/sprites` API endpoint in your application that returns a reference to a single image based on `name` and `baseurl` query parameters.

affects: >=4.0.0

gotchaTo 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.

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.

affects: >=4.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Attempting to use ES6 `import` syntax in a CommonJS environment or without proper module configuration in Node.js after v6.0.0.

fix

Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) or use a bundler to transpile.

TypeError: GeoStylerMapboxParser.MapboxStyleParser is not a constructor

Attempting to instantiate `MapboxParser` incorrectly in a browser environment, or the script for the library was not loaded.

fix

Ensure the library is loaded via a `<script>` tag and then instantiate `new GeoStylerMapboxParser.MapboxStyleParser()`.

Property 'source' is missing in type '{ ... }' but required in type 'MbStyle'.

Passing a Mapbox style object to the parser that lacks the mandatory `source` property, enforced since v5.0.0.

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).

Upgrade

Version history

6.2.0latest on npm

Audit

Dependencies

geostyler-stylerequiredCore dependency for the abstract GeoStyler style definition and utilities.

@types/mapbox-gloptionalTypeScript type definitions for Mapbox GL JS styles.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/geostyler/geostyler-mapbox-parser ↗

packagehttps://www.npmjs.com/package/geostyler-mapbox-parser ↗

homepagehttps://geostyler.org ↗