Monorepo & Workflows¶

Das Repo ist ein Bun-Workspace. Die Pakete unter apps/* und packages/* sind in der Root-package.json registriert und referenzieren sich gegenseitig über workspace:*. Gemeinsame Abhängigkeitsversionen werden zentral über den Bun-Catalog in der Root-package.json gepflegt, damit alle Pakete dieselben Versionen nutzen.

Voraussetzungen¶

Nix mit aktivierten Flakes
Bun (wird auch von nix develop bereitgestellt)
Docker für die lokale Infrastruktur

NixOS

Auf NixOS solltest du Cypress, die Prisma-CLI und MkDocs innerhalb von nix develop ausführen – sonst fehlen statisch gelinkte Abhängigkeiten.

Erstes Setup¶

nix develop            # Toolchain-Shell betreten
bun install            # Workspace-Abhängigkeiten installieren
cp .env.example .env   # Konfiguration anlegen
bun run dev:infra:up   # Postgres, Keycloak, Mailpit, Geocoder starten
bun run db:generate    # Prisma-Client erzeugen
bun run db:migrate:deploy

Anschließend die beiden Apps in getrennten Terminals starten:

bun run dev:api        # API:  http://localhost:3100
bun run dev            # Web:  http://localhost:5174

Lokale Dev-Infrastruktur¶

bun run dev:infra:up startet den Docker-Stack aus docker-compose.dev.yml:

Dienst	Adresse	Hinweis
PostgreSQL	`localhost:5435`	Login `txride` / `txride`
Keycloak	`http://localhost:8180`	Admin `admin` / `admin`, Realm `txride`, User `dev` / `dev`
Mailpit (UI)	`http://localhost:8035`	abgefangene Test-Mails
Mailpit (SMTP)	`localhost:1035`
Nominatim	`http://localhost:8085`	OSM-Daten Sachsen
Photon	`http://localhost:2322`	Deutschland-Index, erster Start lädt ~5 GB

Den Fortschritt der Geocoder beobachten:

bun run dev:geocoders:watch   # Status alle 10 s
bun run dev:photon:logs       # Live-Logs des Photon-Downloads
bun run smoke:geocoders       # wartet, bis beide APIs antworten

Häufige Befehle¶

Befehl	Zweck
`bun run dev`	Vite-Dev-Server (Web)
`bun run dev:api`	Hono/oRPC-API-Server
`bun run dev:worker`	pg-boss-Worker für Benachrichtigungen
`bun run storybook`	Storybook für die UI-Komponenten
`bun run db:generate`	Prisma-Client generieren
`bun run db:migrate`	Migration in der Entwicklung erstellen/anwenden
`bun run db:migrate:deploy`	Migrationen anwenden (CI/Prod)
`bun run build`	Produktions-Build der Web-App
`bun run typecheck`	TypeScript-Check über das ganze Repo
`bun run test`	Bun-Unit-Tests
`bun run ci:local`	Typecheck + Tests + Build + Doku-Build

Pakete gemeinsam nutzen¶

Workspace-Pakete werden über ihren @txride/*-Namen importiert – Bun löst sie ohne Build-Schritt auf:

import { AppShell } from "@txride/ui";
import { contract } from "@txride/contract";

Der Vertrag (packages/contract) ist client-sicher und die gemeinsame Quelle der Wahrheit zwischen API, Web-App und CLI: Er definiert mit oRPC und Zod, welche Prozeduren es gibt und welche Typen sie erwarten und zurückgeben.