styled-map-package

CLI for creating, viewing, and converting Styled Map Package (.smp) files.

An .smp file is a ZIP archive containing all the resources needed to serve a MapLibre vector styled map offline: style JSON, vector and raster tiles, glyphs (fonts), sprites, and metadata.

Installation

Requires Node.js >= 22.

npm install --global styled-map-package

Commands

smp download

Download an online map style to a .smp file for offline use.

smp download https://demotiles.maplibre.org/style.json \
  --bbox '-180,-80,180,80' \
  --zoom 5 \
  --output demotiles.smp

Options:

| Option | Description | | ---------------------- | ---------------------------------------------------------------------- | | -o, --output <file> | Output file (writes to stdout if omitted) | | -b, --bbox <w,s,e,n> | Bounding box (west, south, east, north) | | -z, --zoom <number> | Max zoom level (0-22) | | -t, --token <token> | Mapbox access token (required for Mapbox styles) | | -d, --dedupe | Deduplicate tiles with identical content to reduce file size | | --skip-local-glyphs | Skip CJK/Hangul/Kana glyph ranges rendered locally by MapLibre GL | | --all-glyph-ranges | Download every glyph range, not only those used by downloaded labels | | --buffer-tiles | Download an extra tile ring around the bbox at each zoom below maxzoom |

When run interactively, missing options are prompted for.

The --buffer-tiles flag downloads one extra tile ring around the bbox at every zoom level below maxzoom, so the map is not clipped at the edges of the downloaded area when zooming out. The buffer is not added at maxzoom. smp view automatically renders these buffer tiles.

smp view

Preview a .smp file in a web browser.

smp view demotiles.smp --open

Options:

| Option | Description | | --------------------- | -------------------------------------------------------------------------- | | -o, --open | Open in the default web browser | | -p, --port <number> | Port to serve on (default: 3000) | | --no-fallback | Return 404 for missing tiles and glyphs instead of serving empty fallbacks |

By default the viewer serves empty tiles and Noto Sans glyphs for any resource not present in the file, so incomplete packages (those covering a partial area or zoom range) preview without 404 errors. Missing vector tiles are served as empty MVTs, missing raster tiles as transparent pixels. Missing glyph ranges are served using bundled Noto Sans glyphs (via GoNotoKurrent, covering 80+ scripts including Latin, Cyrillic, Greek, Arabic, Hebrew, Devanagari, Thai, and more). CJK and Hangul ranges are not bundled since MapLibre renders these client-side via localIdeographFontFamily. Pass --no-fallback to return 404s instead.

For packages downloaded with buffer tiles (recorded as smp:bufferTiles in the style metadata), the viewer also widens each source's bounds so the lower-zoom buffer tiles that extend beyond the data area are rendered rather than clipped. Combined with the empty-tile fallback, panning beyond the downloaded area shows blank tiles instead of console errors.

smp mbtiles

Convert an MBTiles file to a .smp file.

smp mbtiles tiles.mbtiles --output map.smp

Options:

| Option | Description | | --------------------- | ------------------------------------------------ | | -o, --output <file> | Output .smp file (writes to stdout if omitted) |

smp validate

Validate a .smp file against the SMP specification.

smp validate map.smp

Reports errors (spec MUST violations) and warnings (SHOULD/RECOMMENDED), each annotated with a severity level:

• fatal — the file cannot be opened by the reader
• rendering — the map opens but content will be visibly broken (missing tiles, glyphs, sprites)
• spec — non-compliance that doesn't affect practical use

Glyph coverage is checked by reading the vector tiles and requiring every glyph range their labels use. Pass --no-glyph-coverage to skip reading tiles and only require range 0-255.

Exits with code 0 if valid, 1 if errors are found.

License

MIT