TileflowDocs

Concepts

How Tileflow works

Tileflow keeps the source of truth in your repo. A small config becomes MapLibre style JSON, local preview assets, hosted delivery routes, and a manifest that maps names likemadrid to URLs.

Pipeline
tileflow.config.ts
  -> @tileflow/core
  -> MapLibre style JSON
  -> local manifest during dev
  -> deployed style URL in production
  -> React, MapLibre, or static maps
1

Config is the product contract

tileflow.config.ts names the maps your app uses. Product code refers to a map name, while the compiler handles OpenMapTiles layers, glyphs, sprites, and source URLs.

2

The compiler builds MapLibre styles

@tileflow/core validates fields such as basemap, theme, and view, then emits a MapLibre style document with Tileflow delivery URLs.

3

Delivery routes serve the map primitives

The hosted API serves style JSON, TileJSON, vector tiles, glyphs, sprites, authenticated static map renders, and immutable generated PNGs. Tilesets are backed by PMTiles archives in R2.

4

Apps consume names or URLs

React, Vue, and Svelte apps can resolve a name such as madrid through the manifest. Plain MapLibre apps can load the deployed style URL directly; Leaflet and OpenLayers require a compatible MapLibre-style adapter.

Assets

Anatomy of a deployed map

A hosted map is not a single file. It is a style URL that points MapLibre at the tile, font, sprite, and static image assets it needs.

Style JSON/maps/:mapId/style.json

The MapLibre document that your app loads first.

TileJSON/tiles/:tilesetId/tiles.json

Metadata and tile URL templates for a vector tileset.

Vector tiles/tiles/:tilesetId/:z/:x/:y.pbf

PMTiles-backed vector tile responses served from R2 range reads.

Glyphs/fonts/:fontstack/:range.pbf

Font ranges used by labels in the generated style.

Sprites/sprites/:spriteId/sprite.json

Icon metadata and PNG sheets referenced by MapLibre layers.

Manifest

The manifest keeps local and production names aligned

Framework adapters serve /tileflow/manifest.json in local development. Deploy writes a compatible local production manifest containing hosted URLs, so runtime code can keep using the same map names while URLs change behind the scenes.

public/tileflow/manifest.json
{
  "version": 1,
  "apiUrl": "https://api.tileflow.dev",
  "maps": {
    "madrid": {
      "environment": "madrid",
      "mapId": "map_1234567890abcdef",
      "styleId": "sty_456",
      "styleUrl": "https://api.tileflow.dev/maps/map_1234567890abcdef/style.json",
      "tilesetId": "world"
    }
  },
  "styles": {
    "madrid": "https://api.tileflow.dev/maps/map_1234567890abcdef/style.json"
  }
}
ConfigSmall typed source of truth reviewed like product code.
StyleGenerated MapLibre document with tiles, labels, terrain, sprites, and glyphs.
DeliveryCloudflare Workers routes backed by R2 and PMTiles range reads.
Static outputDeterministic PNG images share the same deployed map and style revision.
Statustileflow status shows deployed styles, registered tilesets, and archives.