@geogdev/styles

MapLibre GL layer styles for OpenMapTiles-compatible vector tiles.

Installation

npm / pnpm / yarn

npm install @geogdev/styles

CDN (Browser)

<script src="https://unpkg.com/@geogdev/styles/dist/styles.js"></script>

Quick Start

ESM / TypeScript

import maplibregl from "maplibre-gl";
import { layers, LIGHT, DARK, GRAY, WARM } from "@geogdev/styles";

const map = new maplibregl.Map({
  container: "map",
  center: [-93.265, 44.977],
  zoom: 12,
  style: {
    version: 8,
    glyphs: "https://your-server.com/fonts/{fontstack}/{range}.pbf",
    sprite: "https://your-server.com/sprites/light",
    sources: {
      basemap: {
        type: "vector",
        url: "https://your-server.com/tiles.json"
      }
    },
    layers: layers("basemap", LIGHT, { lang: "en" })
  }
});

Browser (CDN)

<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>
<script src="https://unpkg.com/@geogdev/styles/dist/styles.js"></script>
<script>
  const mapLayers = styles.layers("basemap", styles.LIGHT, { lang: "en" });

  const map = new maplibregl.Map({
    container: "map",
    style: {
      version: 8,
      glyphs: "https://your-server.com/fonts/{fontstack}/{range}.pbf",
      sprite: "https://your-server.com/sprites/light",
      sources: {
        basemap: { type: "vector", url: "https://your-server.com/tiles.json" }
      },
      layers: mapLayers
    }
  });
</script>

Available Themes

| Theme | Description | |-------|-------------| | LIGHT | Natural colors, high contrast labels | | DARK | Subdued colors for dark mode | | GRAY | Monochrome, ideal for data viz overlays | | WARM | Earthy, sepia-toned palette |

API Reference

layers(source, style, options?)

Generates MapLibre GL layer specifications.

import { layers, LIGHT } from "@geogdev/styles";

// Generate all layers (base + labels)
layers("basemap", LIGHT, { lang: "en" });

// Generate base layers only (no labels)
layers("basemap", LIGHT);

// Generate labels only
layers("basemap", LIGHT, { labelsOnly: true, lang: "en" });

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | source | string | Source ID matching your MapLibre sources config | | style | Style | Theme preset (LIGHT, DARK, GRAY, WARM) | | options.lang | string | Language code for labels (e.g., "en", "de", "ja") | | options.labelsOnly | boolean | If true, only generate label layers |

namedStyle(name)

Get a style preset by string name.

import { namedStyle } from "@geogdev/styles";

const style = namedStyle("dark"); // Returns DARK

Style Presets

import { LIGHT, DARK, GRAY, WARM } from "@geogdev/styles";
import { STYLE_NAMES, isValidStyleName } from "@geogdev/styles";

// STYLE_NAMES = ["light", "dark", "gray", "warm"]
isValidStyleName("dark"); // true

TypeScript Types

import type { Style, StyleName } from "@geogdev/styles";

// StyleName = "light" | "dark" | "gray" | "warm"
// Style = interface with all color properties

Theme Switching

import { layers, LIGHT, DARK } from "@geogdev/styles";

function switchTheme(map, theme) {
  const newStyle = {
    version: 8,
    glyphs: "https://your-server.com/fonts/{fontstack}/{range}.pbf",
    sprite: `https://your-server.com/sprites/${theme === DARK ? "dark" : "light"}`,
    sources: {
      basemap: { type: "vector", url: "https://your-server.com/tiles.json" }
    },
    layers: layers("basemap", theme, { lang: "en" })
  };
  map.setStyle(newStyle);
}

// Usage
switchTheme(map, DARK);

Requirements

This package generates layer specifications only. You must provide:

1. Tile source - OpenMapTiles-compatible vector tiles (PMTiles, TileJSON, etc.)
2. Fonts (glyphs) - PBF font files for text rendering
3. Sprites - Icon sprite sheets (PNG + JSON)

Development

# Build the package
npm run build

# Run tests
npm test

# Type checking
npm run tsc

# Format code
npm run format

# Generate style JSON (via npm script)
npm run generate_style output.json https://example.com/tiles.json light en

# Or via the installed CLI
npx geog-generate-style output.json https://example.com/tiles.json light en

License

BSD-3-Clause