Configuration

Write the map as a small config file

A Tileflow project has named maps. Each map chooses a basemap, a theme, and an initial view. Your UI uses the map name instead of hard-coding generated style JSON.

tileflow.config.ts

import { defineTileflow, labels, osm, poi } from "@tileflow/core";
 
export default defineTileflow({
  icons: {
    brand: {
      sprite: "https://cdn.example.com/tileflow/brand/sprite",
    },
  },
  themes: {
    light: {
      colors: {
        background: "#f8f7f7",
        land: "#f4f2ed",
        water: "#8ed6e8",
        park: "#c3f1d5",
        building: "#eef0f2",
        road: "#ffffff",
        roadMajor: "#f5d58a",
        roadCasing: "#dde0e3",
        boundary: "#c9ced3",
        text: "#566371",
        textMuted: "#8a98a8",
        textHalo: "#ffffff",
      },
      modules: {
        labels: {
          road: "#7a8794",
          water: "#4b8fa8",
        },
        poi: {
          food: "#d97706",
          culture: "#7c3aed",
          transit: "#2563eb",
        },
        roads: {
          motorway: "#f7c56f",
        },
      },
      typography: {
        font: "Inter",
      },
    },
    dark: {
      colors: {
        background: "#161a1d",
        land: "#20262b",
        water: "#18384d",
        park: "#24442f",
        building: "#2b3339",
        road: "#38434c",
        roadMajor: "#6e7580",
        roadCasing: "#58636c",
        boundary: "#53606b",
        text: "#d9e2ea",
        textMuted: "#a3afba",
        textHalo: "#161a1d",
      },
      modules: {
        roads: {
          motorway: "#858c96",
        },
      },
      typography: {
        font: "Inter",
      },
    },
  },
  maps: {
    madrid: {
      basemap: osm(),
      theme: "light",
      icons: "brand",
      modules: [
        labels({ roads: "minimal" }),
        poi({
          preset: "minimal",
          categories: ["food", "coffee", "culture", "transit"],
          icons: "essential",
        }),
      ],
      view: {
        center: [-3.7038, 40.4168],
        zoom: 12,
      },
    },
  },
});

Shape

The important fields are deliberately boring

Keep the map readable. Use basemap for the data and style template, theme.colors for common visual decisions, theme.modules for granular module tokens, icons for POI/icon assets, modules for semantic behavior, layers for exact MapLibre patches, and view for the starting camera.

Basemaposm() gives the map its source, OpenMapTiles layers, glyphs, and sprites.

ThemesDefine named color systems such as light or dark, then add module tokens only when a map family needs more control.

ViewSet the initial center and zoom used by local previews and examples.

TilesUse tilesets only when you need custom PMTiles data instead of the default.

Reference

Fields you should reach for first

These fields are compact, typed, reviewable, and validated by tileflow validate. Use them before reaching for raw MapLibre layer JSON.

themes.lightNamed theme with basic colors, module tokens, optional layer overrides, and typography.themes.darkDark-mode theme with its own colors, module tokens, layer patches, and typography.themes.<name>.extendsCustom themes such as brand or highContrast can extend light or dark.themes.<name>.modulesGranular theme tokens consumed by basemaps or modules, for example roads.rail or labels.halo.themes.<name>.layersExact MapLibre layer patches shared by every map using that theme.mapsNamed map contracts such as madrid, checkout, or store-locator.maps.<name>.basemapThe base map source and layer template, usually osm().maps.<name>.themeSelect a named theme or provide an inline theme object for this map.maps.<name>.iconsOptional root icon set reference, hosted MapLibre sprite, or local icon folder for framework/build output.maps.<name>.viewInitial center, zoom, and bearing used by previews and examples.tilesetsOptional named PMTiles or TileJSON sources for custom data.maps.<name>.allowedOriginsBrowser-origin allowlist for reducing unauthorized embedding. It is not authentication and does not make map data private.maps.<name>.modulesOptional semantic modules such as labels(), poi(), and roads().maps.<name>.layersExact MapLibre layer patches for one map.maps.<name>.terrainOptional terrain or hillshade configuration; hosted production requires operator-preseeded terrain cache coverage.