# Ein Worker. Alle Clients.

Ein Full-Stack-Starter für Web und Mobile. TanStack Start, Expo und eine typisierte API auf Cloudflare.

## Läuft schon.

Aufgaben, Dateien, Sicherheit und Agenten. Echte Ansichten des Templates mit Beispieldaten.

[Docs](/docs) · [Changelog](/docs/changelog)

## Die fertigen Teile.

Behalte, was dein Produkt braucht. Alle Integrationen sind enthalten; optionale Dienste bleiben bis zur Konfiguration aus.

### Produkt

- Authentifizierung (Fertig): E-Mail und Passwort, Passkeys, Zwei-Faktor-Codes, E-Mail-Bestätigung und Sitzungsverwaltung.
- Organisationen (Fertig): Mitglieder, Einladungen und Rollen. Todos und Dateien gehören zur aktiven Organisation.
- Dateien (Fertig): Multipart-Uploads zu R2, Vorschauen, Freigabelinks und ein Papierkorb.
- Admin (Fertig): Benutzerverwaltung, Impersonation, Feature-Flags und ein Audit-Log.
- Todo-Beispiel (Fertig): Tabelle, Board und Kalender, mit Import-Queues mit Leases und Entwürfen von KI-Agenten.
- Zahlungen (Standardmäßig aus): Stripe und Polar im Web, RevenueCat auf Mobile. Aus, bis Anbieter und Billing-Flags konfiguriert sind.

### Plattform

- Datenbank (Fertig): Drizzle auf Neon Postgres, erreichbar über Hyperdrive.
- E-Mail (Fertig): Transaktionale E-Mails über Cloudflare Email, in der Entwicklung in der Konsole ausgegeben.
- i18n und SEO (Fertig): Englisch, Deutsch und Französisch, hreflang, Sitemap und mit Takumi erzeugte OG-Bilder.
- Assistent in der App (Standardmäßig aus): Streaming-Chat mit TanStack AI und gemeinsamen MCP-Tools. Aus, bis ein Anbieter konfiguriert und die Assistenten-Flag aktiviert ist.
- Geplante Jobs (Fertig): Effect an den Rändern: Cron-Jobs und ausgehende Zustellung, mit Postgres-Leases für Warteschlangen.
- Cookie-Einwilligung (Fertig): Ein Consent-Banner, das Analyse- und Marketing-Skripte zurückhält.

### Mobile

- Expo-App (Fertig): iOS und Android mit demselben API-Client, derselben Sitzung und Passkeys.
- Push-Benachrichtigungen (In Arbeit): Expo-Push-Registrierung und eine Zustell-Queue. Aus, bis Zugangsdaten gesetzt sind.
- Homescreen-Widgets (Standardmäßig aus): Todo-Widgets für iOS und Android hinter einer nativen Build-Option.
- Werbung (Standardmäßig aus): AdMob-Helfer als eigenständige Bibliothek, von der App nicht importiert.

## Ein gemeinsamer Vertrag.

Browser und Expo nutzen denselben oRPC-Router. Der Worker prüft die Sitzung vor dem Zugriff auf Postgres oder R2.

- Web: TanStack Start, React, Tailwind CSS, shadcn/ui

- Mobile: Expo, Expo Router, React Native

- API: oRPC, Zod, Effect

- Auth: Better Auth

- Daten und Dateien: Drizzle ORM, Neon Postgres, Hyperdrive, R2

- Plattform und Tooling: Cloudflare Workers, GitHub Actions, Turborepo, pnpm

### apps/web/src/routes/index.tsx

```ts
import { useQuery } from "@tanstack/react-query";
import { orpc } from "@/utils/orpc";

const { data: apiOk, isLoading: apiLoading } =
  useQuery(orpc.healthCheck.queryOptions());
```

Auszug aus der Landing-Route. Der generierte Client hält die Abfrage typisiert.

### apps/mobile/src/app/(tabs)/(home)/index.tsx

```ts
import { useQuery } from "@tanstack/react-query";
import { orpc } from "@/lib/orpc";

const healthCheck = useQuery(
  orpc.healthCheck.queryOptions(),
);
```

Der Expo-Startbildschirm ruft dieselbe Health-Check-Prozedur auf.

### packages/api/src/routers/index.ts

```ts
healthCheck: publicProcedure.handler(() => {
  return "OK";
}),
```

Ein öffentlicher Health-Check. Geschützte Prozeduren benötigen zusätzlich eine Sitzung.

## Server bleibt Server.

Teile Verträge mit den Clients. Drei unabhängige Prüfungen schützen Datenbankverbindungen, Secrets und Servercode.

- oxlint: Wert-Importe von Server-Modulen lassen den Lint in apps/web, apps/mobile und packages/ui scheitern. Typ-Importe sind erlaubt.

- Explizite Exports: Jedes Package listet seine öffentlichen Einstiegspunkte. Keine Wildcards, also ist ein neuer Import zwischen Packages eine bewusste Änderung.

- Scan des Client-Bundles: Der Web-Build liest die Client-Assets und schlägt bei Strings fehl, die nur im Server-Code existieren.

## Eine Vorschau pro PR.

Jeder Pull Request erhält einen Preview-Worker und einen Neon-Branch. Prüfe die echte URL vor dem Merge.

- Ein Merge geht in Produktion: Ein Push auf main startet den separaten Produktions-Workflow mit Produktions-Secrets und -Datenbank.

- Aufräumen ist exakt: Es prüft Projekt, Pull Request und Eltern-Branch, löscht zuerst den Worker und akzeptiert bereits entfernte Ressourcen.

## Ein Werkzeugkatalog.

TanStack AI und der MCP-Server nutzen dieselben autorisierten Werkzeuge. Coding-Agenten erhalten Repo-Regeln und Architekturentscheidungen.

- AGENTS.md: Regeln, die jeder Coding-Agent zuerst liest: die Client-Server-Grenze, Effect auf dem Server, i18n.

- docs/adr: Architekturentscheidungen mit Kontext, damit ein Agent sie nicht rückgängig macht.

- .agents/skills: Setup, Start, Deployment und Browser-Checks als Schritt-für-Schritt-Skills.

- /api/mcp: Agenten lesen deine Daten und schlagen per OAuth Entwürfe vor. Entwürfe warten, bis du sie übernimmst.

- /llms.txt: Öffentliches Markdown unter /index.md und ein /llms.txt-Verzeichnis, das Agenten vor dem Verbinden lesen können.

## Mach es zu deinem.

Klone deine Kopie des Repositorys. Installiere, konfiguriere und starte Web und Mobile gemeinsam.

### Klonen

Starte mit deiner Kopie des Template-Repositorys.

```sh
git clone <your-repo-url> my-app
```

### Installieren

Installiert jeden Workspace im Monorepo.

```sh
pnpm install
```

### Konfigurieren

Benennt das Projekt und schreibt Env-Dateien, Wrangler, Datenbank, E-Mail und Speicher.

```sh
pnpm setup
```

### Starten

Web auf localhost:3005, dazu der Expo-Dev-Server für Mobile.

```sh
pnpm run dev
```

## Vor dem Klonen.

### Was kann ich in der Demo ausprobieren?

Leg ein Konto an und nutze die echte App: Todos, Dateien, Organisationen, Passkeys, Zwei-Faktor und Einstellungen. Sie läuft auf demselben Worker wie diese Seite.

### Warum Cloudflare Workers?

Ein Deployment liefert Seiten, API, Auth und geplante Jobs. Jeder Pull Request bekommt seinen eigenen Worker, das Review findet also auf einer echten URL statt.

### Warum Neon Postgres statt D1?

Auth, Organisationen und die Job-Queues brauchen Transaktionen und Locks von Postgres. Hyperdrive bündelt die Verbindung, und jeder Pull Request bekommt seinen eigenen Neon-Branch.

### Kann ich Mobile, Zahlungen oder Werbung entfernen?

Ja. optional-features.json listet jedes optionale Package mit seinen Einstiegspunkten, und docs/optional-features.md beschreibt, wie du sie entfernst.

### Wie passe ich das Branding an?

Farben, Radius und Schriften stehen in einer Token-Datei. Namen und Texte stehen in den Locale-Dateien. Die Screens nutzen nur Tokens, also ändert ein Palettenwechsel jede Seite.

### Muss ich Effect kennen?

Nur um Server-Jobs zu ändern. Effect koordiniert die Ausführung im Worker; Verträge nutzen Zod, Requests oRPC, Auth Better Auth und Abfragen Drizzle.

### Wie verbinde ich einen KI-Agenten?

Richte einen beliebigen MCP-Client auf /api/mcp. Du gibst den Zugriff per OAuth frei, Lesen und Schreiben sind getrennte Scopes, und Schreiben erzeugt nur Entwürfe, die du in der App bestätigst.

### Enthält das Template einen KI-Assistenten?

Ja. Der Assistent und MCP nutzen denselben Tool-Katalog, beschränkt auf deine Organisation. Änderungen brauchen eine Freigabe. Konfiguriere Anthropic, OpenAI oder Gemini und aktiviere die Assistenten-Flag, um den Chat anzuzeigen. Er ist standardmäßig aus.