TerraInk

Note: TerraInk is still in development. Every feedback is appreciated. This is a for-fun, open-source project, and community contributions are very welcome.

Acknowledgment

This project is a JavaScript reimplementation inspired by the original MapToPoster originalankur/maptoposter by Ankur Gupta (MIT license). My app is built using Bun, React, and TypeScript. It allows users to create custom city map posters with various styling options, leveraging OpenStreetMap data rendered via MapLibre and OpenFreeMap vector tiles.

Features

• Custom city map posters for any location in the world, powered by real OpenStreetMap data
• Smart geocoding — search for any city or region by name, or enter coordinates manually
• Rich theme system — choose from dozens of curated themes or build your own custom color palette
• Detailed map layers — roads, water bodies, parks, and building footprints with per-layer styling
• Typography controls — set city/country display labels and load any Google Fonts family
• High-resolution PNG export — download a print-ready poster at any defined dimension

Data Providers and Mapping Stack

• Map data: OpenStreetMap contributors
• Tiles: OpenMapTiles
• Tile hosting: OpenFreeMap
• Geocoding: Nominatim
• Map renderer: MapLibre

User Interface

Showcase

All showcase images are stored in public/assets/showcase/.

Featured Examples

<p align="center"> <img src="./public/assets/showcase/showcase_1.png" alt="Featured showcase example 1" width="100%" /> <img src="./public/assets/showcase/showcase_2.png" alt="Featured showcase example 2" width="100%" /> </p>

Run

bun install
bun run dev

Environment

Check .env.example for available variables. They are optional for most local work and should not be set during testing unless a specific case requires them.

Build

bun run build

Deploy with Docker (Self-Hosting)

1) Build and run with Docker Compose

Create .env from .env.example (or set APP_PORT directly in your shell), then run:

docker compose up -d --build

This serves the app on http://localhost:7200 by default.

To change the exposed host port:

• Linux/macOS:

APP_PORT=80 docker compose up -d --build

• PowerShell:

$env:APP_PORT=80
docker compose up -d --build

2) Stop the deployment

docker compose down

3) Optional: build and run without Compose

docker build -t terraink:latest .
docker run -d --name terraink -p 7200:80 --restart unless-stopped terraink:latest

Contributing

The contribution guidelines are meant to keep TerraInk easy to extend, review, and maintain over time. They are here to support a durable architecture, not to add unnecessary friction.

Read CONTRIBUTING.md before opening a PR.

• Branch from dev and target dev only. Do not open PRs against main.
• Fill out the pull request template completely when you open a PR.
• Keep contributions clean, modular, and aligned with the existing architecture.
• Avoid hard-coded values when constants, configuration, or reusable abstractions are more appropriate.
• AI-assisted coding is allowed, but submissions must be reviewed, refined, and intentionally engineered before review.

Star History

License

This project is licensed under the MIT License - see the LICENSE file for details.

Trademark

The Terraink™ name, logo, and branding assets are trademarks of the project owner.</br> The MIT license grants you the right to use the code, but it does not grant any rights to use the project's name or branding for your own commercial purposes or hosted services.</br> See TRADEMARK.md for details.