TypeScript

Next.js intègre nativement TypeScript, installant automatiquement les packages nécessaires et configurant les paramètres appropriés lorsque vous créez un nouveau projet avec create-next-app.

Pour ajouter TypeScript à un projet existant, renommez un fichier en .ts / .tsx. Exécutez next dev et next build pour installer automatiquement les dépendances requises et ajouter un fichier tsconfig.json avec les options de configuration recommandées.

Bon à savoir : Si vous avez déjà un fichier jsconfig.json, copiez l'option paths du compilateur depuis l'ancien jsconfig.json vers le nouveau fichier tsconfig.json, puis supprimez l'ancien jsconfig.json.

Plugin IDE

Next.js inclut un plugin TypeScript personnalisé et un vérificateur de types, que VSCode et d'autres éditeurs de code peuvent utiliser pour une vérification de types avancée et de l'auto-complétion.

Vous pouvez activer le plugin dans VS Code en :

1. Ouvrant la palette de commandes (Ctrl/⌘ + Shift + P)
2. Recherchant "TypeScript: Select TypeScript Version"
3. Sélectionnant "Use Workspace Version"

Maintenant, lors de l'édition des fichiers, le plugin personnalisé sera activé. Lors de l'exécution de next build, le vérificateur de types personnalisé sera utilisé.

Le plugin TypeScript peut aider avec :

• Un avertissement si des valeurs invalides pour les options de configuration des segments sont passées.
• L'affichage des options disponibles et de la documentation contextuelle.
• La vérification que la directive 'use client' est utilisée correctement.
• La vérification que les hooks clients (comme useState) ne sont utilisés que dans les composants clients.

🎥 Regarder : Découvrez le plugin TypeScript intégré → YouTube (3 minutes)

Sécurité de type de bout en bout

Le routeur App de Next.js offre une sécurité de type améliorée. Cela inclut :

1. Aucune sérialisation des données entre la fonction de récupération et la page : Vous pouvez utiliser fetch directement dans les composants, layouts et pages côté serveur. Ces données n'ont pas besoin d'être sérialisées (converties en chaîne) pour être passées côté client et consommées dans React. Au lieu de cela, puisque app utilise par défaut des composants serveur, nous pouvons utiliser des valeurs comme Date, Map, Set, et plus encore sans étapes supplémentaires. Auparavant, vous deviez typer manuellement la frontière entre le serveur et le client avec des types spécifiques à Next.js.
2. Flux de données simplifié entre les composants : Avec la suppression de _app au profit des layouts racine, il est maintenant plus facile de visualiser le flux de données entre les composants et les pages. Auparavant, les données circulant entre les pages individuelles et _app étaient difficiles à typer et pouvaient introduire des bugs déroutants. Avec la récupération de données colocalisée dans le routeur App, ce n'est plus un problème.

La récupération de données dans Next.js offre désormais une sécurité de type aussi proche que possible du bout en bout sans être prescriptif quant à votre choix de base de données ou de fournisseur de contenu.

Nous pouvons typer les données de réponse comme vous vous y attendriez avec TypeScript normal. Par exemple :

async function getData() {
  const res = await fetch('https://api.example.com/...')
  // La valeur de retour n'est *pas* sérialisée
  // Vous pouvez retourner Date, Map, Set, etc.
  return res.json()
}

export default async function Page() {
  const name = await getData()

  return '...'
}

Pour une sécurité de type complète de bout en bout, cela nécessite également que votre base de données ou fournisseur de contenu prenne en charge TypeScript. Cela peut être via l'utilisation d'un ORM ou d'un constructeur de requêtes type-safe.

Exemples

Vérification de type de next.config.ts

Vous pouvez utiliser TypeScript et importer des types dans votre configuration Next.js en utilisant next.config.ts.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* options de configuration ici */
}

export default nextConfig

Bon à savoir : La résolution des modules dans next.config.ts est actuellement limitée à CommonJS. Cela peut causer des incompatibilités avec les packages ESM uniquement chargés dans next.config.ts.

Lors de l'utilisation du fichier next.config.js, vous pouvez ajouter une vérification de type dans votre IDE en utilisant JSDoc comme ci-dessous :

// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* options de configuration ici */
}

module.exports = nextConfig

Liens statiquement typés

Next.js peut typer statiquement les liens pour prévenir les fautes de frappe et autres erreurs lors de l'utilisation de next/link, améliorant la sécurité de type lors de la navigation entre les pages.

Pour activer cette fonctionnalité, experimental.typedRoutes doit être activé et le projet doit utiliser TypeScript.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

export default nextConfig

Next.js générera une définition de lien dans .next/types qui contient des informations sur toutes les routes existantes dans votre application, que TypeScript peut ensuite utiliser pour fournir des retours dans votre éditeur sur les liens invalides.

Actuellement, le support expérimental inclut tout littéral de chaîne, y compris les segments dynamiques. Pour les chaînes non littérales, vous devez actuellement caster manuellement le href avec as Route :

import type { Route } from 'next';
import Link from 'next/link'

// Aucune erreur TypeScript si href est une route valide
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />

// Erreurs TypeScript si href n'est pas une route valide
<Link href="/aboot" />

Pour accepter href dans un composant personnalisé encapsulant next/link, utilisez un générique :

import type { Route } from 'next'
import Link from 'next/link'

function Card<T extends string>({ href }: { href: Route<T> | URL }) {
  return (
    <Link href={href}>
      <div>Ma Carte</div>
    </Link>
  )
}

Comment ça marche ?

Lors de l'exécution de next dev ou next build, Next.js génère un fichier .d.ts caché dans .next qui contient des informations sur toutes les routes existantes dans votre application (toutes les routes valides comme type href de Link). Ce fichier .d.ts est inclus dans tsconfig.json et le compilateur TypeScript vérifiera ce .d.ts et fournira des retours dans votre éditeur sur les liens invalides.

Avec les composants serveur asynchrones

Pour utiliser un composant serveur async avec TypeScript, assurez-vous d'utiliser TypeScript 5.1.3 ou supérieur et @types/react 18.2.8 ou supérieur.

Si vous utilisez une version plus ancienne de TypeScript, vous pourriez voir une erreur de type 'Promise<Element>' is not a valid JSX element. Mettre à jour vers la dernière version de TypeScript et @types/react devrait résoudre ce problème.

Vérification de type incrémentielle

Depuis la version v10.2.1, Next.js prend en charge la vérification de type incrémentielle lorsqu'elle est activée dans votre tsconfig.json, ce qui peut aider à accélérer la vérification de type dans les applications plus grandes.

Désactivation des erreurs TypeScript en production

Next.js échoue votre build de production (next build) lorsque des erreurs TypeScript sont présentes dans votre projet.

Si vous souhaitez que Next.js produise dangereusement du code de production même lorsque votre application contient des erreurs, vous pouvez désactiver l'étape de vérification de type intégrée.

Si désactivée, assurez-vous d'exécuter des vérifications de type dans le cadre de votre processus de build ou de déploiement, sinon cela peut être très dangereux.

Ouvrez next.config.ts et activez l'option ignoreBuildErrors dans la configuration typescript :

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  typescript: {
    // !! ATTENTION !!
    // Permet dangereusement aux builds de production de se terminer avec succès même si
    // votre projet contient des erreurs de type.
    // !! ATTENTION !!
    ignoreBuildErrors: true,
  },
}

export default nextConfig

Bon à savoir : Vous pouvez exécuter tsc --noEmit pour vérifier les erreurs TypeScript vous-même avant de build. Ceci est utile pour les pipelines CI/CD où vous souhaitez vérifier les erreurs TypeScript avant le déploiement.

Déclarations de type personnalisées

Lorsque vous avez besoin de déclarer des types personnalisés, vous pourriez être tenté de modifier next-env.d.ts. Cependant, ce fichier est généré automatiquement, donc toute modification que vous apportez sera écrasée. À la place, vous devriez créer un nouveau fichier, appelons-le new-types.d.ts, et le référencer dans votre tsconfig.json :

{
  "compilerOptions": {
    "skipLibCheck": true
    //...tronqué...
  },
  "include": [
    "new-types.d.ts",
    "next-env.d.ts",
    ".next/types/**/*.ts",
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": ["node_modules"]
}

Changements de version