Set CHIITILER_PROCESSES to control clustering (0 uses all CPUs). When >1, the primary process forks workers that all share the same cache adapter.

Environment Variables

In addition to the CLI options above, the server respects:

| Variable | Default | Notes |
| -------- | ------- | ----- |
| CHIITILER_PROCESSES | 1 | Number of worker processes; 0 = availableParallelism(). |
| AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY | – | Used by the S3 cache adapter. |
| AWS_REGION | – | Overrides SDK default region if set. |
| GOOGLE_APPLICATION_CREDENTIALS | – | Path to a service account JSON used by the GCS adapter. |

Cache Backends

Chiitiler caches the source material required for rendering (vector tiles, glyphs, sprites, spritesheets), not the final raster outputs. These cached assets are reused across requests to avoid refetching upstream sources.

- none – No caching; every request renders from scratch.
- memory – In-memory LRU cache with configurable TTL and max entries.
- file – Stores fetched source assets under CHIITILER_FILECACHE_DIR.
- s3 – Uploads cached source assets to S3/MinIO; honors custom endpoint and path-style.
- gcs – Uploads cached source assets to Google Cloud Storage or fake-gcs-server.

Each adapter exposes the same get/set interface and can be reused when embedding Chiitiler as a library.

Debug Tools

Run with --debug or CHIITILER_DEBUG=true to unlock:

- /debug – Inspect styles, test queries, and view response metadata.
- /editor – Lightweight MapLibre style editor with live preview.

Development & Testing

`bash
npm run dev # Watch mode via tsx
npm run build # Bundle to build/main.cjs with esbuild
npm run test:unit # Vitest unit suite (src/*/.test.ts)
npm run test:integration # End-to-end scenarios in tests/
npm run test:coverage # Unit coverage with V8 provider
npm run test:benchmark # Performance tests (see BENCHMARK.md)
`

Benchmark scenarios and recent measurements live in BENCHMARK.md.

Library Usage

Chiitiler is also published as an npm library. Core helpers return Sharp instances or encoded buffers so you can integrate the renderer into other pipelines.

`ts
import {
getRenderedTileBuffer,
getRenderedClipBuffer,
getRenderedCameraBuffer,
getRenderedTileStream,
getRenderedClipStream,
getRenderedCameraStream,
ChiitilerCache,
} from 'chiitiler';

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

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

const clip = await getRenderedClipBuffer({
stylejson: 'file://localdata/style.json',
bbox: [123.4, 34.5, 124.5, 35.6],
size: 1024,
ext: 'png',
quality: 95,
cache: ChiitilerCache.noneCache(),
});

const camera = await getRenderedCameraBuffer({
stylejson: 'file://localdata/style.json',
center: [139.69, 35.68],
zoom: 10,
bearing: 180,
pitch: 60,
width: 1024,
height: 1024,
ext: 'png',
quality: 95,
cache,
});

// you can get Sharp streams directly
const tileStream = await getRenderedTileStream({
stylejson: 'https://tile.openstreetmap.jp/styles/osm-bright/style.json',
z: 5,
x: 27,
y: 12,
tileSize: 512,
margin: 0,
ext: 'png',
quality: 90,
cache,
});

const clipStream = await getRenderedClipStream({
stylejson: 'file://localdata/style.json',
bbox: [123.4, 34.5, 124.5, 35.6],
size: 1024,
ext: 'jpeg',
quality: 85,
cache,
});

const cameraStream = await getRenderedCameraStream({
stylejson: 'file://localdata/style.json',
center: [139.69, 35.68],
zoom: 10,
bearing: 180,
pitch: 60,
width: 1024,
height: 1024,
ext: 'png',
quality: 95,
cache,
})
`

Deployment

The cdk/ directory contains an AWS CDK app for running Chiitiler on Lambda with Web Adapter.

Architecture

`mermaid
graph LR
subgraph sources
direction LR
A[style.json]
z/x/y.pbf
z/x/y.png/webp/jpg
sprite
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
``