{"id":16610515,"url":"https://github.com/kanahiro/chiitiler","last_synced_at":"2026-04-21T13:05:29.876Z","repository":{"id":193885962,"uuid":"689648474","full_name":"Kanahiro/chiitiler","owner":"Kanahiro","description":"Lightweight Raster Tile Server for MapLibre Style Specification","archived":false,"fork":false,"pushed_at":"2025-02-20T00:06:10.000Z","size":19417,"stargazers_count":63,"open_issues_count":5,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-16T06:05:57.472Z","etag":null,"topics":["foss4g","maplibre","nodejs","raster-tiles","serverless","typescript","vector-tiles"],"latest_commit_sha":null,"homepage":"https://spatialty-io.github.io/chiitiler-demo","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kanahiro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["Kanahiro"]}},"created_at":"2023-09-10T13:33:11.000Z","updated_at":"2025-03-11T21:55:21.000Z","dependencies_parsed_at":"2024-05-23T09:40:33.311Z","dependency_job_id":"bc0f8755-be39-4601-9cc5-13091c1ea204","html_url":"https://github.com/Kanahiro/chiitiler","commit_stats":null,"previous_names":["kanahiro/chiitiler"],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanahiro%2Fchiitiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanahiro%2Fchiitiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanahiro%2Fchiitiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanahiro%2Fchiitiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kanahiro","download_url":"https://codeload.github.com/Kanahiro/chiitiler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243936475,"owners_count":20371520,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["foss4g","maplibre","nodejs","raster-tiles","serverless","typescript","vector-tiles"],"created_at":"2024-10-12T01:30:34.497Z","updated_at":"2026-04-21T13:05:29.868Z","avatar_url":"https://github.com/Kanahiro.png","language":"TypeScript","funding_links":["https://github.com/sponsors/Kanahiro"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./logo.svg\" alt=\"chiitiler\" width=\"200\" /\u003e\n\n# chiitiler\n\n**A tiny raster tile server for MapLibre styles.**\n\nPoint it at any `style.json` and get back PNG / WebP / JPEG tiles, static images, or map cut-outs.\n\n[![Release](https://img.shields.io/github/v/release/Kanahiro/chiitiler?label=ghcr.io%2Fkanahiro%2Fchiitiler\u0026color=0ea5e9)](https://github.com/Kanahiro/chiitiler/pkgs/container/chiitiler)\n[![Unit Tests](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:unit.yml?label=unit)](https://github.com/Kanahiro/chiitiler/actions)\n[![Integration](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:integration.yml?label=integration)](https://github.com/Kanahiro/chiitiler/actions)\n[![codecov](https://codecov.io/gh/Kanahiro/chiitiler/graph/badge.svg?token=9RVLAJG126)](https://codecov.io/gh/Kanahiro/chiitiler)\n[![License](https://img.shields.io/github/license/Kanahiro/chiitiler?color=blue)](./LICENSE)\n\n[Quickstart](#quickstart) · [HTTP API](#http-api) · [Library](#library-usage) · [Deployment](#deployment)\n\n\u003c/div\u003e\n\n---\n\n## From zero to a rendered tile in 30 seconds\n\n**1. Run the server** — one command, no config file, no database, no API key.\n\n```bash\ndocker run --rm -p 3000:3000 ghcr.io/kanahiro/chiitiler:latest\n```\n\n**2. Open a tile in your browser** — pass any MapLibre style URL as `?url=`.\n\n```\nhttp://localhost:3000/tiles/0/0/0.png?url=https://tile.openstreetmap.jp/styles/osm-bright/style.json\n```\n\nYou'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}`.\n\n\u003e **No Docker?** `npx tsx` works too:\n\u003e ```bash\n\u003e git clone https://github.com/Kanahiro/chiitiler \u0026\u0026 cd chiitiler \u0026\u0026 npm i\n\u003e npx tsx src/main.ts tile-server --debug\n\u003e ```\n\u003e Then visit `http://localhost:3000/debug` to preview styles interactively.\n\n## Features\n\n- **Zero-config** — no config file, no YAML, no database. Just a style URL.\n- **Works with any MapLibre style** — remote URL or `POST` the JSON inline\n- **Multiple outputs** — slippy tiles (`/tiles`), bounding-box clips (`/clip`), free-form camera shots (`/camera`)\n- **Serverless-friendly** — small footprint, runs on AWS Lambda via Web Adapter (see [`cdk/`](./cdk))\n- **Pluggable caching** — `memory` · `file` · `s3` · `gcs` backends for shared source assets\n- **Many protocols** — `http(s)` · `s3` · `gs` · `file` · `mbtiles` · `pmtiles` · `cog`\n- **Library or server** — import the renderer directly into your Node.js pipeline\n- **Built-in debug UI** — `/debug` and `/editor` for live style preview\n\n## In Production\n\n- **[MIERUNE/tiles](https://github.com/MIERUNE/tiles)** — [live example](https://mierune.github.io/tiles/color.html#11.62/43.064/141.3375)\n- **[PLATEAU VIEW](https://plateauview.mlit.go.jp/)** — Cesium.js imagery via `/tiles`\n- **[qgis-amazonlocationservice-plugin](https://github.com/dayjournal/qgis-amazonlocationservice-plugin)** — QGIS integration\n- **[Allmaps Latest](https://bsky.app/profile/latest.allmaps.org)** — Bluesky bot\n\n## HTTP API\n\n| Method | Endpoint | Description |\n| --- | --- | --- |\n| `GET` / `POST` | `/tiles/{z}/{x}/{y}.{ext}` | Slippy-map raster tile |\n| `GET` / `POST` | `/clip.{ext}` | Bounding-box cut-out |\n| `GET` / `POST` | `/camera/{zoom}/{lat}/{lon}/{bearing}/{pitch}/{width}x{height}.{ext}` | Free-form camera shot |\n| `GET` | `/debug`, `/editor` | Debug UI (requires `--debug`) |\n\n`ext` is one of `png`, `jpeg`, `jpg`, `webp`.\n\n**Query parameters**\n\n| Name | Default | Notes |\n| --- | --- | --- |\n| `url` | — | Style JSON URL (required for `GET`) |\n| `tileSize` | `512` | Tile size in pixels |\n| `quality` | `100` | JPEG / WebP quality |\n| `margin` | `0` | Tile edge margin |\n| `bbox` | — | `/clip` bounding box: `minLon,minLat,maxLon,maxLat` |\n| `size` | `1024` | `/clip` longest edge in pixels |\n\nFor `POST`, send the style object as JSON body: `{ \"style\": { ... } }`.\n\n## Library Usage\n\nChiitiler is also published to npm. Returns `Buffer` or `Sharp` streams.\n\n```ts\nimport { getRenderedTileBuffer, ChiitilerCache } from 'chiitiler';\n\nconst cache = ChiitilerCache.fileCache({ dir: './.cache', ttl: 3600 });\n\nconst png = await getRenderedTileBuffer({\n    stylejson: 'https://tile.openstreetmap.jp/styles/osm-bright/style.json',\n    z: 5, x: 27, y: 12,\n    tileSize: 512,\n    ext: 'png',\n    quality: 100,\n    margin: 0,\n    cache,\n});\n```\n\nAvailable renderers: `getRenderedTileBuffer`, `getRenderedClipBuffer`, `getRenderedCameraBuffer`, and their `*Stream` variants (`Sharp` instances for further piping).\n\n## Configuration\n\nAll options can be set via CLI flag or environment variable.\n\n### Server\n\n| Flag | Env | Default |\n| --- | --- | --- |\n| `--port \u003cn\u003e` | `CHIITILER_PORT` | `3000` |\n| `--debug` | `CHIITILER_DEBUG` | `false` |\n| — | `CHIITILER_PROCESSES` | `1` (set `0` for all CPUs) |\n\n### Cache\n\n| Flag | Env | Default |\n| --- | --- | --- |\n| `--cache \u003cnone\\|memory\\|file\\|s3\\|gcs\u003e` | `CHIITILER_CACHE_METHOD` | `none` |\n| `--cache-ttl \u003cseconds\u003e` | `CHIITILER_CACHE_TTL_SEC` | `3600` |\n| `--memory-cache-max-item-count \u003cn\u003e` | `CHIITILER_MEMORYCACHE_MAXITEMCOUNT` | `1000` |\n| `--file-cache-dir \u003cdir\u003e` | `CHIITILER_FILECACHE_DIR` | `./.cache` |\n| `--s3-cache-bucket \u003cname\u003e` | `CHIITILER_S3CACHE_BUCKET` | — |\n| `--s3-region \u003cregion\u003e` | `CHIITILER_S3_REGION` | `us-east-1` |\n| `--s3-endpoint \u003curl\u003e` | `CHIITILER_S3_ENDPOINT` | — |\n| `--s3-force-path-style` | `CHIITILER_S3_FORCE_PATH_STYLE` | `false` |\n| `--gcs-cache-bucket \u003cname\u003e` | `CHIITILER_GCS_CACHE_BUCKET` | — |\n| `--gcs-project-id \u003cid\u003e` | `CHIITILER_GCS_PROJECT_ID` | — |\n| `--gcs-key-filename \u003cpath\u003e` | `CHIITILER_GCS_KEY_FILENAME` | — |\n| `--gcs-cache-prefix \u003cprefix\u003e` | `CHIITILER_GCS_CACHE_PREFIX` | — |\n| `--gcs-api-endpoint \u003curl\u003e` | `CHIITILER_GCS_API_ENDPOINT` | — |\n\nChiitiler 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.\n\n## Deployment\n\n- **Docker** — `ghcr.io/kanahiro/chiitiler:latest` (entrypoint: `tile-server`)\n- **Docker Compose** — see [`docker-compose.yml`](./docker-compose.yml) (includes MinIO + fake-gcs-server for local testing)\n- **AWS Lambda** — ready-to-deploy CDK app in [`cdk/`](./cdk)\n\n## Develop\n\nRequires Node.js 24.12+ and `sharp` system deps (see [Dockerfile](./Dockerfile)).\n\n```bash\ngit clone https://github.com/Kanahiro/chiitiler.git\ncd chiitiler\nnpm install\nnpm run dev              # tsx watch mode\nnpm run test:unit        # vitest\nnpm run test:integration # end-to-end\nnpm run test:benchmark   # see BENCHMARK.md\nnpm run build            # bundle to build/main.cjs\n```\n\n## Architecture\n\n```mermaid\ngraph LR\n    subgraph sources\n        direction LR\n        A[style.json]\n        B[z/x/y.pbf]\n        C[z/x/y.png/webp/jpg]\n        D[sprite]\n        E[glyphs]\n    end\n\n    subgraph chiitiler\n        cache\n        render\n        server\n    end\n\n    sources --\u003e cache --\u003e render --\u003e server --/tiles/z/x/y--\u003e png/webp/jpg\n    cache \u003c--get/set--\u003e memory/file/s3/gcs\n```\n\n## Credits\n\nInspired by [`maptiler/tileserver-gl`](https://github.com/maptiler/tileserver-gl) and [`developmentseed/titiler`](https://github.com/developmentseed/titiler).\n\n## License\n\n[MIT](./LICENSE) © Kanahiro Iguchi\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanahiro%2Fchiitiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkanahiro%2Fchiitiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanahiro%2Fchiitiler/lists"}