Cours Vibe coding avec Claude Code · Module 2: Un projet Next.js avec Claude Code

TypeScript : les types comme contrôle pour Claude

14 min de lecture ·
Dans cette leçon16

Ohé ! Kraken's Call a déjà sa section hero. Tu vas maintenant découvrir l'outil qui contrôle le code de Claude avant même qu'un seul joueur ne le voie : TypeScript et son compilateur.

Problème : Claude écrit avec assurance, et c'est le joueur qui voit l'erreur

Claude écrit vite et avec assurance, mais il lui arrive de noter le niveau d'un pirate comme le texte "5" au lieu du nombre 5, ou d'aller chercher un champ que l'objet n'a pas. En JavaScript ordinaire, une telle erreur n'apparaît que dans le navigateur, chez le joueur. TypeScript l'attrape plus tôt, pendant un contrôle que Claude peut lancer lui-même avant d'annoncer « terminé ». Tu n'écris pas les types à la main : tu dois savoir les lire et exiger que le contrôle passe pour de bon.

TypeScript en un paragraphe

TypeScript est du JavaScript avec un système de types. Un type dit quelle valeur peut se trouver à un endroit donné : un texte, un nombre ou un objet avec des champs précis. Les fichiers .ts et .tsx sont compilés en JavaScript ordinaire, donc le navigateur ne voit pas les types. Voici une fonction qui attend un texte :

function greet(name: string) {
  return "Ohé, " + name;
}

greet(5);

L'écriture name: string dit que le paramètre doit être un texte, donc pour greet(5) le compilateur signalera une erreur avant même que le code ne démarre. Ce que les types ne feront pas : ils disparaissent après la compilation, donc ils ne vérifieront pas les données que la page reçoit pendant son exécution, par exemple depuis internet.

Le contrôle : le compilateur comme maître d'équipage

tsc est le compilateur de TypeScript. Dans un projet Next.js, il sert surtout à vérifier les types dans tout le projet avec une seule commande :

npx tsc --noEmit

npx de la leçon 1_1 lance le tsc installé dans le projet, et --noEmit veut dire : contrôle seulement, n'écris pas de fichiers JavaScript. Quand les types concordent, la commande n'affiche rien, donc le silence est bon signe. La documentation de Next.js la recommande pour vérifier les types avant le build.

Le second contrôle, tu le connais de la leçon 1_2 : npm run build vérifie aussi les types (la ligne « Running TypeScript ») et s'arrête en cas d'erreur. Un piège : le type LayoutProps de app/layout.tsx n'est généré par Next.js qu'avec npm run dev ou npm run build, donc dans un projet tout juste téléchargé, tsc signalera « Cannot find name 'LayoutProps' » tant que tu ne l'auras pas construit une fois. Conseil du capitaine : demande les deux contrôles, le tsc rapide entre les étapes et le build à la fin.

Types de base

Les types les plus simples sont string (texte), number (nombre) et boolean (vrai ou faux). On écrit le type après les deux-points, juste derrière le nom de la variable :

const shipName: string = "Black Pearl";
const crewCount: number = 3;
const isSailing: boolean = true;
const ports: string[] = ["Tortuga", "Nassau"];

La dernière ligne est un tableau : string[] signifie « liste de textes ». Dans le code de Claude, le type n'est souvent pas écrit, car TypeScript le déduit de la valeur : après let crewSize = 3, essayer d'y mettre un texte se terminera aussi par une erreur.

Interface : le contrat sur la forme d'un objet

La section « Équipage » de la future landing page affichera des cartes de pirates. Chaque pirate est un objet avec quelques champs, et une interface est un contrat qui dit quels champs un tel objet doit avoir et de quel type ils sont :

interface CrewMember {
  name: string;
  role: string;
  level: number;
}

Désormais, tout objet décrit comme CrewMember doit avoir un nom et un rôle sous forme de texte et un niveau sous forme de nombre. Une interface n'affiche ni ne crée rien : c'est une forme dont le compilateur surveille le respect.

Champ optionnel et union

Tous les pirates n'ont pas de perroquet, donc ce champ sera optionnel : on le marque d'un point d'interrogation après son nom. Le rôle, lui, ne devrait pas être un texte quelconque, mais l'un de quelques rôles connus. Pour cela, il y a l'union (union type), un type composé de plusieurs possibilités reliées par le signe |, que tu lis comme « ou » :

type CrewRole = "capitaine" | "timonier" | "cuisinier" | "bosco";

interface CrewMember {
  name: string;
  role: CrewRole;
  level: number;
  parrot?: string;
}

Le mot type donne un nom à n'importe quel type, ici à une union de quatre textes. Le rôle "capitaine" passera, mais "capitane" avec une faute de frappe, non : le compilateur répondra « Type '"capitane"' is not assignable to type 'CrewRole' » et te soufflera même la valeur correcte. Le champ parrot? peut être omis, mais le code doit vérifier que le perroquet existe avant de s'en servir.

type ou interface ?

Les deux formes décrivent la forme d'un objet et sont en général interchangeables, mais une union ne s'écrit qu'avec type. La documentation de TypeScript conseille : utilise interface tant que tu n'as pas besoin de quelque chose que seul type offre. Je m'y tiens mais si Claude décrit un objet avec type, ne lui demande pas de le changer : ce n'est pas une erreur.

Demande pour Claude Code

Il est temps que Claude construise la page de l'équipage avec des types et la vérifie lui-même. Dans la session, dans le dossier krakens-call, toujours en mode Manual, donne cette demande :

Demande pour Claude Code :

Ajoute une page app/crew/page.tsx avec une section « Équipage » pour
Kraken's Call : trois cartes de pirates (nom, rôle, niveau,
éventuellement le nom du perroquet). Dans ce fichier, définis une
interface CrewMember, le rôle sous forme d'union de quelques textes
et un composant CrewCard avec des props typées. Sans any, sans as,
sans @ts-ignore et sans modifier tsconfig.json ni next.config.ts.
Classes Tailwind dans le style de @app/page.tsx. À la fin, lance
npx tsc --noEmit et npm run build et montre les deux résultats.

Les interdictions de la quatrième phrase ferment les raccourcis dont nous parlerons dans un instant, et la dernière phrase exige une preuve : deux résultats au lieu du mot « terminé ».

Ce que Claude a écrit

Ouvre dans Cursor app/crew/page.tsx. En haut se trouvent CrewRole et CrewMember, que tu connais déjà, et en dessous les données de l'équipage :

const crew: CrewMember[] = [
  { name: "Anne Bonny", role: "capitaine", level: 10, parrot: "Capitaine Plume" },
  { name: "Jack Rackham", role: "timonier", level: 7 },
  { name: "Mary Read", role: "cuisinier", level: 5 },
];

CrewMember[] est un tableau d'objets conformes au contrat. Seule la première pirate a un perroquet, car le champ est optionnel. Les données sont écrites dans le fichier : la page ne télécharge rien depuis internet.

Ensuite vient le composant d'une seule carte. Les props sont les données que le composant reçoit de son parent, comme une fonction reçoit des arguments, et leur forme se décrit elle aussi avec une interface :

interface CrewCardProps {
  member: CrewMember;
}

function CrewCard({ member }: CrewCardProps) {
  return (
    <article className="rounded-lg border border-yellow-500 bg-gray-900 p-6 text-white">
      <h3 className="text-xl font-bold">{member.name}</h3>
      <p className="mt-2 text-gray-300">
        {member.role}, niveau {member.level}
      </p>
      {member.parrot && (
        <p className="mt-2 text-yellow-400">Perroquet : {member.parrot}</p>
      )}
    </article>
  );
}

{ member }: CrewCardProps dit que la carte reçoit une seule prop member de type CrewMember. L'écriture member.parrot && (...) n'affiche le paragraphe du perroquet que si le champ existe : voilà à quoi ressemble la vérification d'un champ optionnel. Si Claude avait écrit member.ship, le compilateur aurait signalé que ce champ n'existe pas dans le contrat.

À la fin du fichier, la page qui range les cartes dans une grille :

export default function CrewPage() {
  return (
    <main className="min-h-screen bg-black px-6 py-16">
      <h1 className="text-center text-3xl font-bold text-red-600">Équipage</h1>
      <div className="mx-auto mt-8 grid max-w-4xl grid-cols-1 gap-4 md:grid-cols-3">
        {crew.map((member) => (
          <CrewCard key={member.name} member={member} />
        ))}
      </div>
    </main>
  );
}

crew.map crée une carte pour chaque pirate, et key donne à React une étiquette unique pour l'élément de la liste. La grille, tu la connais depuis la leçon 1_3. Le fichier se trouve dans le dossier app/crew/, donc la page sera à l'adresse /crew.

La preuve : deux résultats

Claude montrera le résultat des deux commandes. Après npx tsc --noEmit, il n'y a aucun texte, et le build se termine ainsi :

✓ Compiled successfully in 1523ms
  Running TypeScript ...
  Finished TypeScript in 745ms ...

Route (app)
┌ ○ /
├ ○ /_not-found
└ ○ /crew

La ligne /crew confirme que la page existe, et les lignes sur TypeScript que les types concordent. Ouvre encore http://localhost:3000/crew : le build vérifie le code, mais il n'évaluera pas à ta place la lisibilité des cartes.

À quoi ressemble une erreur de types

Regarde ce qui se passerait si Claude notait le niveau de Mary Read comme le texte "5". npx tsc --noEmit afficherait une seule ligne :

app/crew/page.tsx(13,43): error TS2322: Type 'string' is not assignable to type 'number'.

Tu lis de gauche à droite : le fichier, la ligne et la colonne, le code de l'erreur et sa description : dans le champ level se trouve un texte, alors que le contrat exige un nombre. npm run build affichera le même message et se terminera par les mots « Failed to type check. », donc la version cassée ne verra pas le jour.

Cette même erreur, tu la vois dans Cursor sans commande. Cursor est construit sur le code de VS Code, donc ce que la documentation de VS Code décrit pour TypeScript y fonctionne : les erreurs sont soulignées dans le texte du fichier, et en passant le curseur sur un nom, tu vois son type, par exemple CrewMember pour member. La liste des erreurs, c'est le panneau Problems (Cmd+Shift+M sur Mac, Ctrl+Shift+M sous Windows et Linux).

Erreur typique de l'agent : réduire au silence au lieu de réparer

Quand le contrôle ne passe pas, l'agent est parfois tenté de le faire taire au lieu de réparer la cause. Le contrôle passe alors, parce qu'il a cessé de regarder. Tu reconnaîtras quatre astuces :

  • as any : as est une assertion de type, c'est-à-dire « je sais mieux », et any désactive la vérification ;
  • // @ts-ignore ou // @ts-expect-error au-dessus de la ligne fautive : le compilateur saute cette ligne ;
  • "strict": false dans tsconfig.json : les contrôles stricts disparaissent, par exemple l'avertissement « 'captain' is possibly 'undefined' », disant que le pirate cherché peut ne pas exister ;
  • ignoreBuildErrors: true dans next.config.ts : le build ne vérifie plus du tout les types, ce que la documentation de Next.js qualifie ouvertement de dangereux.

Voici à quoi ressemble la première astuce dans le diff de Source Control :

-  { name: "Mary Read", role: "cuisinier", level: "5" },
+  { name: "Mary Read", role: "cuisinier", level: "5" as any },

La vraie correction changerait "5" en 5, alors que celle-ci laisse un texte là où le contrat exige un nombre. L'assertion disparaît après la compilation comme tout type, donc elle ne répare rien : l'erreur s'est seulement cachée du compilateur.

Comment l'attraper : dans le diff, cherche any, as et @ts-, et dans Source Control, vérifie que tsconfig.json et next.config.ts n'ont pas changé. Le linter aide aussi : dans un projet issu de create-next-app, la commande npm run lint signale as any comme l'erreur « Unexpected any » et rejette @ts-ignore. Quand tu trouves une telle astuce, réponds :

Supprime as any de app/crew/page.tsx et répare la cause : level doit
être un nombre conforme à CrewMember. Ne modifie pas tsconfig.json.
Ensuite lance npx tsc --noEmit et npm run lint et montre les deux
résultats.

La réponse nomme la cause, ferme le raccourci et exige de nouveau une preuve.

Tu les croiseras dans le code de Claude

Ces écritures, tu n'as pas à les écrire : il suffit que tu les reconnaisses dans le code de Claude.

Les génériques sont des types avec un paramètre entre chevrons : Array<CrewMember> veut dire la même chose que CrewMember[]. C'est ainsi qu'on décrit par exemple la réponse d'un serveur au contenu variable :

interface ApiResponse<T> {
  data: T;
  status: number;
}

const answer: ApiResponse<CrewMember[]> = { data: crew, status: 200 };

T est la place d'un type que tu indiques à l'usage, ici la liste des pirates. Le préfixe Api est voulu : Response dans un fichier sans imports ni exports entre en collision avec le type intégré du navigateur, et tsc signale « All declarations of 'Response' must have identical type parameters ».

Les types utilitaires (utility types) construisent un nouveau type à partir d'un type existant. Partial rend tous les champs optionnels, Pick en choisit quelques-uns, et Omit en omet quelques-uns :

type CrewDraft = Partial<CrewMember>;
type CrewBadge = Pick<CrewMember, "name" | "role">;
type CrewWithoutParrot = Omit<CrewMember, "parrot">;

CrewBadge n'a que le nom et le rôle, juste ce qu'il faut pour un petit badge, et Required fait l'inverse de Partial. Aucune de ces écritures ne modifie CrewMember lui-même : de nouveaux noms naissent à côté.

unknown au lieu de any. Les deux types acceptent toute valeur, mais unknown ne te laisse pas l'utiliser tant que tu n'as pas vérifié ce que c'est :

function shout(value: unknown) {
  if (typeof value === "string") {
    return value.toUpperCase();
  }
  return "???";
}

À l'intérieur du if, TypeScript sait déjà que value est un texte, donc toUpperCase() est permis, alors qu'avec any il aurait laissé passer l'appel de n'importe quelle méthode. Plus rarement, tu verras never, le type d'une valeur qui ne naîtra jamais, par exemple le résultat d'une fonction qui lance toujours une erreur.

tsconfig.json : les réglages du compilateur

Les réglages de TypeScript se trouvent dans le fichier tsconfig.json, créé par l'assistant. Pour toi, la ligne la plus importante est celle-ci :

"strict": true,

strict active toute une famille de contrôles stricts, entre autres noImplicitAny, qui signale les endroits où un type deviendrait silencieusement any, et strictNullChecks, qui surveille les valeurs null et undefined. Toute proposition de modifier cette ligne est un signal pour arrêter Claude.

La revue du capitaine

Avant d'approuver la page de l'équipage, vérifie :

  1. Un contrôle honnête : dans le diff, il n'y a ni any, ni as, ni @ts-, et dans la liste des modifications, ni tsconfig.json ni next.config.ts.
  2. Une preuve, pas un compte rendu : tu as vu le résultat vide de npx tsc --noEmit et le tableau du build avec /crew.
  3. Des types qui décrivent les données : CrewMember contient les champs visibles sur les cartes, sans champs inventés d'avance.
  4. La page : sous /crew se trouvent trois cartes, et sur un écran étroit l'une sous l'autre.

L'erreur typique de l'agent, tu la connais déjà : faire taire l'erreur de types au lieu de la réparer. Tu l'attraperas à coup sûr en ajoutant aux deux contrôles de la demande un troisième, npm run lint.

Étape suivante

Attends pour le commit : dans la leçon suivante, tu le feras après avoir relu les changements, et tu enverras le projet sur GitHub. Dans l'éditeur ci-dessous se trouve la même page de l'équipage avec des types : ajoute un bosco avec un perroquet et regarde-le dans l'aperçu.

Retiens : les types sont une carte avec les écueils marqués, et le compilateur est le maître d'équipage qui vérifie le cap avant que le navire ne largue les amarres.

Code de cette leçon : App.tsx
// Kraken's Call - page de l'équipage décrite avec des types TypeScript

type CrewRole = "capitaine" | "timonier" | "cuisinier" | "bosco";

interface CrewMember {
  name: string;
  role: CrewRole;
  level: number;
  parrot?: string; // champ optionnel : tous les pirates n'ont pas de perroquet
}

interface CrewCardProps {
  member: CrewMember;
}

const crew: CrewMember[] = [
  { name: "Anne Bonny", role: "capitaine", level: 10, parrot: "Capitaine Plume" },
  { name: "Jack Rackham", role: "timonier", level: 7 },
  { name: "Mary Read", role: "cuisinier", level: 5 },
  // Essaie : ajoute un bosco avec un perroquet, par exemple { name: "Israel Hands", role: "bosco", level: 6, parrot: "Rafale" }
];

function CrewCard({ member }: CrewCardProps) {
  return (
    <article style={{ background: "#111827", color: "white", padding: 16, borderRadius: 8, border: "1px solid #eab308" }}>
      <h3 style={{ margin: "0 0 8px" }}>{member.name}</h3>
      <p style={{ margin: 0, color: "#d1d5db" }}>
        {member.role}, niveau {member.level}
      </p>
      {member.parrot && (
        <p style={{ margin: "8px 0 0", color: "#facc15" }}>Perroquet : {member.parrot}</p>
      )}
    </article>
  );
}

export default function App() {
  return (
    <main style={{ minHeight: "100vh", background: "black", padding: 32, fontFamily: "system-ui, sans-serif" }}>
      <h1 style={{ color: "#dc2626", textAlign: "center", marginTop: 0 }}>Équipage</h1>
      <div style={{ display: "grid", gap: 16, gridTemplateColumns: "repeat(auto-fit, minmax(200px, 1fr))" }}>
        {crew.map((member) => (
          <CrewCard key={member.name} member={member} />
        ))}
      </div>
    </main>
  );
}

Tu as repéré une erreur dans cette leçon ?

Teste tes connaissances

Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.

  1. 1. Qu'est-ce que TypeScript ?

  2. 2. À quoi sert une interface en TypeScript ?

  3. 3. Claude a « réparé » une erreur de types en ajoutant as any, et npx tsc --noEmit passe. Que fais-tu ?

Tâches pratiques dans le jeu

  • Tri horizontal

    Ordonne la déclaration d'une variable de type string en TypeScript (de gauche à droite) :

  • Clique dans l'ordre

    Construis un champ 'parrot' optionnel de type string dans l'interface CrewMember :

  1. QuestionQuiz : qu'est-ce que TypeScript
  2. Remets dans l'ordreOrdre : une variable typée en TypeScript
  3. QuestionQuiz : les interfaces en TypeScript
  4. Clique dans l'ordreOrdre : un champ optionnel dans une interface
  5. QuestionQuiz : Claude fait taire une erreur de types

Articles utiles