# Tileflow

Tileflow is an agent-ready map platform for product teams. It turns map styling into code: edit `tileflow.config.ts`, validate it, preview through the app dev server, and deploy stable MapLibre style URLs.

## Core docs

- Documentation: https://tileflow.dev/docs
- How it works: https://tileflow.dev/docs/how-it-works
- Static maps: https://tileflow.dev/docs/static-maps
- Roads module: https://tileflow.dev/docs/roads
- Tilesets: https://tileflow.dev/docs/tilesets
- Auth and keys: https://tileflow.dev/docs/auth
- Recipes: https://tileflow.dev/docs/examples
- Agent workflow: https://tileflow.dev/docs/agent-workflow
- Full agent guide: https://tileflow.dev/llms-full.txt
- Hosted style URL shape: `https://api.tileflow.dev/maps/:mapId/style.json`
- Static map render endpoint: `POST https://api.tileflow.dev/v1/static/maps`

## Agent workflow

1. Install packages: `pnpm add @tileflow/core@alpha maplibre-gl` plus one runtime (`@tileflow/react@alpha`, `@tileflow/vue@alpha`, or `@tileflow/svelte@alpha`), then add `@tileflow/vite@alpha`, `@tileflow/next@alpha`, or `@tileflow/webpack@alpha`, plus `pnpm add -D @tileflow/cli@alpha`
2. Create config: `tileflow init`
3. Edit `tileflow.config.ts`
4. Validate: `tileflow validate`
5. Preview: `pnpm dev` or `tileflow dev`
6. Deploy with approved hosted access: `tileflow login` then `tileflow deploy`

## Prefer the semantic config

Use Tileflow fields such as `themes`, `colors`, `theme.modules`, `modules`, `layers`, `typography`, `labels`, `poi`, `tileset`, and `allowedOrigins`. Use `roads()` for road detail and hierarchy, while road colors stay in the theme. Prefer these over generating raw MapLibre layer JSON unless the user explicitly needs exact layer control. `allowedOrigins` reduces browser hotlinking; it is not authentication and does not make hosted map data private.

## Current agent surface

- Use the CLI and docs today: `tileflow init`, `tileflow validate`, `tileflow dev`, `tileflow deploy`, and `tileflow status`.
- Use `tileflow tileset register` and `tileflow tileset upload` for PMTiles-backed data workflows.
- Use `@tileflow/react`, `@tileflow/vue`, or `@tileflow/svelte` to render named maps from the same manifest.
- Runtime components accept `mapOptions` for native MapLibre constructor options except `container` and `style`; direct props such as `center`, `zoom`, and `interactive` take priority.
- Use `@tileflow/static` and `@tileflow/react/static` for deterministic PNG map images.
- Use `https://tileflow.dev/docs/agent-workflow` for starter agent rules.
- Tileflow does not yet publish a stable MCP server or OpenAPI contract. Prefer the CLI until those contracts are announced.
- Local config, validation, and preview require no account or API key. Hosted deploys currently require approved access and a pre-provisioned key.

## Minimal config

```ts
import {defineTileflow, osm, roads} from '@tileflow/core';

export default defineTileflow({
  themes: {
    light: {
      colors: {
        background: '#F6F7F3',
        land: '#F1F3ED',
        water: '#A9D3F5',
        park: '#CDE8B5',
        building: '#E6E3DA',
        road: '#FFFFFF',
        roadMajor: '#F4C95D',
        boundary: '#C9D1D9',
        text: '#3C4043',
        textMuted: '#727B84',
        textHalo: '#FFFFFF',
      },
    },
  },
  tilesets: {
    world: {
      id: 'world',
      name: 'World',
      attribution: 'OpenMapTiles and OpenStreetMap contributors',
    },
  },
  maps: {
    madrid: {
      basemap: osm(),
      name: 'Madrid',
      tileset: 'world',
      theme: 'light',
      density: 'balanced',
      modules: [roads({preset: 'standard'})],
      labels: 'balanced',
      poi: 'minimal',
    },
  },
});
```