# Un Worker. Tous les clients.

Un starter full-stack pour le web. TanStack Start et une API typée sur Cloudflare.

## Déjà en marche.

Tâches, fichiers, sécurité et agents connectés. Les vrais écrans du template avec des données de démonstration.

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

## Les pièces en place.

Gardez ce dont votre produit a besoin. Toutes les intégrations sont incluses ; les services optionnels restent inactifs avant leur configuration.

### Produit

- Authentification (Prêt): E-mail et mot de passe, passkeys, codes à deux facteurs, vérification de l'e-mail et gestion des sessions.
- Organisations (Prêt): Membres, invitations et rôles. Les todos et les fichiers appartiennent à l'organisation active.
- Fichiers (Prêt): Envois multipart vers R2, aperçus, liens de partage et corbeille.
- Admin (Prêt): Gestion des utilisateurs, usurpation d'identité, feature flags et journal d'audit.
- Exemple de todos (Prêt): Tableau, kanban et calendrier, avec files d’import à baux et brouillons proposés par les agents IA.
- Paiements (Désactivé par défaut): Stripe et Polar sur le web. Inactifs avant la configuration des fournisseurs et des flags de paiement.

### Plateforme

- Base de données (Prêt): Drizzle sur Neon Postgres, atteint via Hyperdrive.
- E-mail (Prêt): E-mails transactionnels via Cloudflare Email, affichés dans la console en développement.
- i18n et SEO (Prêt): Anglais, allemand et français, hreflang, sitemap et images OG générées avec Takumi.
- Assistant intégré (Désactivé par défaut): Chat en streaming avec TanStack AI et des outils MCP communs. Désactivé tant qu'un fournisseur n'est pas configuré et que le flag de l'assistant n'est pas activé.
- Tâches planifiées (Prêt): Effect aux interfaces externes : cron et envois, avec des baux Postgres pour les tâches en file.
- Consentement aux cookies (Prêt): Une bannière de consentement qui retient les scripts d'analyse et de marketing.

## Un seul contrat.

Le navigateur appelle le routeur oRPC. Le Worker vérifie la session avant tout accès à Postgres ou R2.

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

- API: oRPC, Zod, Effect

- Auth: Better Auth

- Données et fichiers: Drizzle ORM, Neon Postgres, Hyperdrive, R2

- Plateforme et outillage: 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());
```

Extrait de la route d’accueil. Le client généré conserve le typage de la requête.

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

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

Une vérification publique. Les procédures protégées exigent aussi une session.

## Le serveur reste à part.

Partagez les contrats avec vos clients. Trois contrôles indépendants protègent connexions, secrets et code serveur.

- oxlint: Les imports de valeurs depuis des modules serveur font échouer le lint dans apps/web et packages/ui. Les imports de types sont autorisés.

- Exports explicites: Chaque package liste ses points d'entrée publics. Pas de jokers, donc un nouvel import entre packages est un choix délibéré.

- Scan du bundle client: Le build web lit les assets client et échoue sur des chaînes qui n'existent que dans le code serveur.

## Un aperçu par PR.

Chaque pull request reçoit un Worker de preview et une branche Neon. Testez son URL avant de fusionner.

- Le merge part en production: Un push sur main lance le workflow de production séparé, avec les secrets et la base de données de production.

- Un nettoyage exact: Il vérifie le projet, la pull request et la branche parente, supprime d'abord le Worker et accepte les ressources déjà supprimées.

## Un catalogue d’outils.

TanStack AI et le serveur MCP utilisent les mêmes outils autorisés. Les agents de code disposent des règles du dépôt et des décisions d’architecture.

- AGENTS.md: Les règles que tout agent de code lit en premier : la frontière client et serveur, Effect côté serveur, l'i18n.

- docs/adr: Les décisions d'architecture avec leur contexte, pour qu'un agent ne les défasse pas.

- .agents/skills: Setup, démarrage, déploiement et vérifications navigateur sous forme de skills pas à pas.

- /api/mcp: Les agents lisent vos données et proposent des brouillons via OAuth. Les brouillons attendent que vous les appliquiez.

- /llms.txt: Du Markdown public sur /index.md et un annuaire /llms.txt à lire avant de connecter un agent.

## À vous de construire.

Clonez votre copie du dépôt. Installez, configurez et lancez l'app web.

### Cloner

Partez de votre copie du dépôt du template.

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

### Installer

Installe chaque workspace du monorepo.

```sh
pnpm install
```

### Configurer

Nomme le projet et écrit les fichiers d'env, Wrangler, la base de données, l'e-mail et le stockage.

```sh
pnpm setup
```

### Lancer

Le web sur localhost:3005.

```sh
pnpm run dev
```

## Avant de cloner.

### Que puis-je essayer dans la démo ?

Créez un compte et utilisez la vraie app : todos, fichiers, organisations, passkeys, double authentification et réglages. Elle tourne sur le même Worker que cette page.

### Pourquoi Cloudflare Workers ?

Un seul déploiement sert les pages, l'API, l'auth et les tâches planifiées. Chaque pull request a son propre Worker, donc la revue se fait sur une vraie URL.

### Pourquoi Neon Postgres plutôt que D1 ?

L'auth, les organisations et les files de tâches s'appuient sur les transactions et les verrous de Postgres. Hyperdrive mutualise la connexion, et chaque pull request a sa propre branche Neon.

### Puis-je retirer les paiements ou d'autres fonctions optionnelles ?

Oui. optional-features.json liste chaque package optionnel et ses points d'entrée, et docs/optional-features.md explique comment les retirer.

### Comment changer l'identité visuelle ?

Les couleurs, les rayons et les polices vivent dans un seul fichier de tokens. Les noms et les textes vivent dans les fichiers de langue. Les écrans n'utilisent que des tokens, donc changer la palette change toutes les pages.

### Dois-je connaître Effect ?

Seulement pour modifier les tâches serveur. Effect coordonne l'exécution dans le Worker ; les contrats utilisent Zod, les requêtes oRPC, l'auth Better Auth et l'accès aux données Drizzle.

### Comment connecter un agent IA ?

Pointez n'importe quel client MCP vers /api/mcp. Vous accordez l'accès via OAuth, la lecture et l'écriture sont des scopes séparés, et l'écriture ne crée que des brouillons que vous confirmez dans l'app.

### Le template inclut-il un assistant IA ?

Oui. L'assistant et MCP partagent un catalogue d'outils limité à votre organisation. Les modifications nécessitent une approbation. Configurez Anthropic, OpenAI ou Gemini et activez le flag de l'assistant pour afficher le chat. Il est désactivé par défaut.