chiitiler

A tiny raster tile server for MapLibre styles.

Point it at any style.json and get back PNG / WebP / JPEG tiles, static images, or map cut-outs.

Quickstart · HTTP API · Library · Deployment

---

From zero to a rendered tile in 30 seconds

1. Run the server — one command, no config file, no database, no API key.

docker run --rm -p 3000:3000 ghcr.io/kanahiro/chiitiler:latest

2. Open a tile in your browser — pass any MapLibre style URL as ?url=.

http://localhost:3000/tiles/0/0/0.png?url=https://tile.openstreetmap.jp/styles/osm-bright/style.json

You're done. That same endpoint works as an XYZ tile source for Leaflet, MapLibre, OpenLayers, QGIS, Cesium, or anywhere else that speaks {z}/{x}/{y}.

No Docker? npx tsx works too:

git clone https://github.com/Kanahiro/chiitiler && cd chiitiler && npm i
npx tsx src/main.ts tile-server --debug

Then visit http://localhost:3000/debug to preview styles interactively.

Features

• Zero-config — no config file, no YAML, no database. Just a style URL.
• Works with any MapLibre style — remote URL or POST the JSON inline
• Multiple outputs — slippy tiles (/tiles), bounding-box clips (/clip), free-form camera shots (/camera)
• Serverless-friendly — small footprint, runs on AWS Lambda via Web Adapter (see cdk/)
• Pluggable caching — memory · file · s3 · gcs backends for shared source assets
• Many protocols — http(s) · s3 · gs · file · mbtiles · pmtiles · cog
• Library or server — import the renderer directly into your Node.js pipeline
• Built-in debug UI — /debug and /editor for live style preview

In Production

• MIERUNE/tiles — live example
• PLATEAU VIEW — Cesium.js imagery via /tiles
• qgis-amazonlocationservice-plugin — QGIS integration
• Allmaps Latest — Bluesky bot

HTTP API

Method	Endpoint	Description
GET / POST	/tiles/{z}/{x}/{y}.{ext}	Slippy-map raster tile
GET / POST	/clip.{ext}	Bounding-box cut-out
GET / POST	/camera/{zoom}/{lat}/{lon}/{bearing}/{pitch}/{width}x{height}.{ext}	Free-form camera shot
GET	/debug, /editor	Debug UI (requires --debug)

ext is one of png, jpeg, jpg, webp.

Query parameters

Name	Default	Notes
url	—	Style JSON URL (required for GET)
tileSize	512	Tile size in pixels
quality	100	JPEG / WebP quality
margin	0	Tile edge margin
bbox	—	/clip bounding box: minLon,minLat,maxLon,maxLat
size	1024	/clip longest edge in pixels

For POST, send the style object as JSON body: { "style": { ... } }.

Library Usage

Chiitiler is also published to npm. Returns Buffer or Sharp streams.

import { getRenderedTileBuffer, ChiitilerCache } from 'chiitiler';

const cache = ChiitilerCache.fileCache({ dir: './.cache', ttl: 3600 });

const png = await getRenderedTileBuffer({
    stylejson: 'https://tile.openstreetmap.jp/styles/osm-bright/style.json',
    z: 5, x: 27, y: 12,
    tileSize: 512,
    ext: 'png',
    quality: 100,
    margin: 0,
    cache,
});

Available renderers: getRenderedTileBuffer, getRenderedClipBuffer, getRenderedCameraBuffer, and their *Stream variants (Sharp instances for further piping).

Configuration

All options can be set via CLI flag or environment variable.

Server

Flag	Env	Default
--port <n>	CHIITILER_PORT	3000
--debug	CHIITILER_DEBUG	false
—	CHIITILER_PROCESSES	1 (set 0 for all CPUs)

Cache

Flag	Env	Default
--cache <none|memory|file|s3|gcs>	CHIITILER_CACHE_METHOD	none
--cache-ttl <seconds>	CHIITILER_CACHE_TTL_SEC	3600
--memory-cache-max-item-count <n>	CHIITILER_MEMORYCACHE_MAXITEMCOUNT	1000
--file-cache-dir <dir>	CHIITILER_FILECACHE_DIR	./.cache
--s3-cache-bucket <name>	CHIITILER_S3CACHE_BUCKET	—
--s3-region <region>	CHIITILER_S3_REGION	us-east-1
--s3-endpoint <url>	CHIITILER_S3_ENDPOINT	—
--s3-force-path-style	CHIITILER_S3_FORCE_PATH_STYLE	false
--gcs-cache-bucket <name>	CHIITILER_GCS_CACHE_BUCKET	—
--gcs-project-id <id>	CHIITILER_GCS_PROJECT_ID	—
--gcs-key-filename <path>	CHIITILER_GCS_KEY_FILENAME	—
--gcs-cache-prefix <prefix>	CHIITILER_GCS_CACHE_PREFIX	—
--gcs-api-endpoint <url>	CHIITILER_GCS_API_ENDPOINT	—

Chiitiler caches source assets (vector tiles, glyphs, sprites) — not final rasters — so cached data is reused across requests. Standard AWS / GCP credentials (AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS, etc.) are respected.

Deployment

• Docker — ghcr.io/kanahiro/chiitiler:latest (entrypoint: tile-server)
• Docker Compose — see docker-compose.yml (includes RustFS + fake-gcs-server for local testing)
• AWS Lambda — ready-to-deploy CDK app in cdk/

Develop

Requires Node.js 24.12+ and sharp system deps (see Dockerfile).

git clone https://github.com/Kanahiro/chiitiler.git
cd chiitiler
npm install
npm run dev              # tsx watch mode
npm run test:unit        # vitest
npm run test:integration # end-to-end
npm run test:benchmark   # see BENCHMARK.md
npm run build            # bundle to build/main.cjs

Architecture

graph LR
    subgraph sources
        direction LR
        A[style.json]
        B[z/x/y.pbf]
        C[z/x/y.png/webp/jpg]
        D[sprite]
        E[glyphs]
    end

    subgraph chiitiler
        cache
        render
        server
    end

    sources --> cache --> render --> server --/tiles/z/x/y--> png/webp/jpg
    cache <--get/set--> memory/file/s3/gcs

Loading

Credits

Inspired by maptiler/tileserver-gl and developmentseed/titiler.

License

MIT © Kanahiro Iguchi