https://github.com/robbeverhelst/routess
Route-planning app for cyclists, runners, and hikers. Interactive map editor, GPX import/export, and a personal route library. Open source, self-hostable, and also available as a hosted service.
https://github.com/robbeverhelst/routess
bun mapbox react shadcn typescript
Last synced: 13 days ago
JSON representation
Route-planning app for cyclists, runners, and hikers. Interactive map editor, GPX import/export, and a personal route library. Open source, self-hostable, and also available as a hosted service.
- Host: GitHub
- URL: https://github.com/robbeverhelst/routess
- Owner: robbeverhelst
- License: mit
- Created: 2025-05-15T20:09:42.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-05-31T14:13:29.000Z (20 days ago)
- Last Synced: 2026-05-31T16:12:08.655Z (20 days ago)
- Topics: bun, mapbox, react, shadcn, typescript
- Language: TypeScript
- Homepage: https://routess.com
- Size: 13.3 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# routess
[](LICENSE)
[](https://github.com/robbeverhelst/routess/actions/workflows/ci.yml)
[](https://github.com/robbeverhelst/routess/releases)
[](https://docs.routess.com)
Route-planning app for cyclists, runners, and hikers. Interactive map editor, GPX import/export, and a personal route library. Open source, self-hostable, and also available as a hosted service.
📚 **Full documentation: [docs.routess.com](https://docs.routess.com)**
## Try it locally (self-host, 5 minutes)
```bash
git clone https://github.com/robbeverhelst/routess.git
cd routess
cp docker/.env.selfhost.example .env
# fill in JWT_SECRET, GOOGLE_CLIENT_ID/SECRET, VITE_MAPBOX_ACCESS_TOKEN
docker compose -f docker/compose.selfhost.yaml --project-directory . up -d
```
Then open .
See [`docs/operations/self-host`](https://docs.routess.com/docs/operations/self-host) for the full walkthrough (OAuth setup, optional services, Helm/Kubernetes path, TLS).
## What you need
Minimum to run routess:
- A **Google OAuth client** (the only login provider today)
- A **Mapbox access token** (free tier is fine)
- A **JWT secret** (any long random string)
Optional services degrade gracefully when unset: Resend (email), Stadia Maps (surface analysis), Sentry/GlitchTip (error reporting), Umami (product analytics), Prometheus (metrics).
## Develop on routess
```bash
bun install
cp .env.example .env
bun dev
```
Defaults: web `:5173`, API `:3000`, docs `:3001`, Postgres `:5432`, pgAdmin `:5050`. Ports auto-shift if taken. Full dev guide: [`docs/getting-started/local-setup`](https://docs.routess.com/docs/getting-started/local-setup).
```bash
bun run lint # biome check
bun run check-types # tsc across all workspaces
bun run test # all tests
bun run ci # full pipeline (postgres + format:check + lint + check-types + build + test)
```
Run `bun run` with no arguments to list every script.
## Project layout
```
routess/
├── apps/
│ ├── web/ # React + Vite + Tailwind + Mapbox
│ ├── api/ # NestJS + PostgreSQL + MikroORM
│ ├── cli/ # `routess` CLI (npm)
│ └── docs/ # Next.js (Fumadocs)
├── packages/
│ ├── core/ # @routess/core — shared business logic & state
│ ├── api-client/ # @routess/api-client — type-safe API client
│ ├── i18n/ # @routess/i18n — internationalization
│ └── design-tokens/ # @routess/design-tokens — design system
├── charts/routess/ # Helm chart
└── docker/ # buildx bake + dev/self-host compose files
```
## Tech stack
| Layer | Technology |
|----------|---------------------------------------------------------|
| Frontend | React, TypeScript, Vite, Tailwind, Mapbox GL |
| Backend | NestJS, PostgreSQL, MikroORM, OpenTelemetry |
| Docs | Next.js, Fumadocs |
| Build | Bun workspaces, Biome, Docker Buildx Bake |
| Deploy | Helm, Kubernetes, GitHub Actions, semantic-release |
## Contributing
PRs welcome. See [`CONTRIBUTING.md`](.github/CONTRIBUTING.md) for the short version and [`docs/contributing`](https://docs.routess.com/docs/contributing) for depth. Run `bun run ci` before submitting; CI enforces production-strict TypeScript and Biome rules.
Security issues: please follow [`SECURITY.md`](.github/SECURITY.md) — do not open public issues for vulnerabilities.
## License
[MIT](LICENSE) © Robbe Verhelst.