Construire votre première fonctionnalité

Parcours pas à pas pour débuter

Prérequis : Lisez les deux guides pour débutants ci-dessous, terminez la configuration locale du Web et ouvrez ce monorepo à sa racine dans votre éditeur. Les paramètres Web appartiennent à apps/web-tanstack/.env.local ; TanStack Start ne lit pas la racine .env. /dashboard dans le mode faux par défaut est une démo sans base de données ; /auth nécessite une base de données migrée.

Termes rapides : un espace de travail est constitué des utilisateurs, des données et des paramètres distincts d'une équipe. Le serveur est le backend de confiance ; gardez les clés du fournisseur hors du code du navigateur et du téléphone. Une migration est une modification de base de données versionnée qui crée ou met à jour des tables. Un modèle d'IA est le moteur qui répond ; le catalogue de modèles est la liste du serveur des identifiants de modèles et des prix disponibles. Un fournisseur est un service externe tel qu'un service d'IA, de messagerie ou de facturation. Un droit est une subvention qui permet à un espace de travail d'utiliser une fonctionnalité. Un webhook est un message qu'un service envoie au URL d'un autre service.

1. Ouvrez VS Code à la racine du référentiel et demandez à votre agent de codage de créer apps/web-tanstack/src/routes/reports.tsx et packages/web-core/src/reports.ts. Donnez-lui les champs de rapport et les rôles autorisés ; nécessitent des vérifications d’adhésion côté serveur et une requête filtrée par workspaceId.

2. Ouvrez /reports en tant que membre connecté et confirmez que seuls les enregistrements de cet espace de travail apparaissent.

3. Essayez un compte déconnecté et un deuxième compte d'espace de travail ; si l'un ou l'autre peut lire les enregistrements, arrêtez et corrigez la vérification du serveur.

Pour le code personnalisé, commencez par le prompts/README.md fourni et copiez l'invite la plus proche : prompts/new-app-screen.md pour un écran d'application ou prompts/new-landing-page.md pour une page publique. Pour le travail sur un serveur, une base de données ou un fournisseur, confiez à votre agent de codage la tâche de ce guide et demandez-lui de lire les miroirs AGENTS.md, .ai/PROJECT_CONTEXT.md et .ai/ correspondants ; inspectez les fichiers sources exacts nommés ici ; lister les fichiers et les vérifications avant de les modifier ; préserver la propriété de l'espace de travail et les secrets du serveur ; et je vous montre la différence. Indiquez-lui le comportement souhaité, les champs d'entrée et de sortie, les rôles autorisés, les succès et erreurs attendus, ainsi que le compte, le fournisseur ou l'appareil de test. Utilisez des exemples de valeurs ; ne collez jamais un vrai secret.

• Avant de commencer
• Bases du terminal
• Configuration locale Web
• Invites de l'agent et mémoire du projet

Créer la route

Ajoutez un fichier de route sous apps/web-tanstack/src/routes/ — il appelle createFileRoute pour publier la page. Partez du tableau de bord ou d'une route de contenu afin de réutiliser la session et la résolution de l'espace de travail actif ; les sources de page partagées (page.load.ts et page.view.tsx) vivent sous packages/web-core/src/pages/ et se montent via des bindings générés. Utilisez le loader de la route pour les lectures protégées.

apps/web-tanstack/src/routes/reports.tsx
packages/web-core/src/reports.ts
.ai/apps/web-tanstack/src/routes/reports.md
.ai/packages/web-core/src/reports.md

Résoudre les droits côté serveur

Lisez l’identité de la session et l’espace de travail actif avec les assistants d’authentification et d’espace de travail existants. Vérifiez l’adhésion avant de charger les enregistrements. Filtrez chaque requête avec le workspaceId résolu ; ne prenez jamais l’identifiant d’un propriétaire depuis un formulaire ou la sortie d’un modèle.

Vérifiez les droits de propriétaire ou d’administrateur pour les actions de gestion. Si une fonctionnalité est payante, contrôlez son droit d’accès à la frontière de lecture ou d’action avant de renvoyer des données protégées ; masquer un bouton ne contrôle pas l’accès.

Vérifier les accès et la récupération

Testez l’accès anonyme, un membre valide, un membre d’un autre espace de travail, une session révoquée et le rôle requis. Prévoyez des états vides et des erreurs de chargement avec une action de récupération. Gardez la route hors du sitemap public et ajoutez son préfixe aux exclusions de robots.

• Isolement de l'espace de travail
• Contrôle des droits

Modéliser l'enregistrement

Chaque enregistrement produit commence dans le schéma de base. Ajoutez une table dans packages/db avec une colonne workspaceId, générez la migration et écrivez les helpers de repository qui résolvent le workspace avant de lire ou d'écrire.

// packages/db/src/schema.ts
export const ideas = pgTable("idea", {
  id: uuid().primaryKey(),
  workspaceId: uuid().notNull().references(() => workspaces.id),
  title: text().notNull(),
  createdAt: timestamp().defaultNow(),
});

corepack pnpm --filter @supastack/db db:generate

Autoriser l'action

Créez une fonction serveur qui résout la session, le workspace puis l'entitlement, dans cet ordre — le handler vit dans packages/web-core et atteint l'app via un binding createServerFn sous apps/web-tanstack/src/actions/ (régénérez avec corepack pnpm gen:actions). Validez l'entrée avec un schéma zod, exécutez la mutation via le repository et renvoyez un résultat typé que l'interface peut rendre.

L'ordre compte : une mutation qui écrit avant de vérifier l'appartenance au workspace a déjà franchi la frontière. Dérivez l'appartenance côté serveur — ne faites jamais confiance à un id de workspace envoyé par le navigateur.

Composer la surface

Construisez la page à partir des composants partagés et des tokens — les blocks et primitives ui-web du kit couvrent les motifs courants. Gérez les états de chargement, d'erreur et de vide ; une fonctionnalité qui ne rend que son chemin nominal n'est pas terminée.