TypeScript

Next.js offre une expérience de développement axée sur TypeScript pour construire votre application React.

Il inclut un support intégré de TypeScript pour installer automatiquement les packages nécessaires et configurer les paramètres appropriés.

Ainsi qu'un Plugin TypeScript pour votre éditeur.

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

Nouveaux projets

create-next-app inclut désormais TypeScript par défaut.

npx create-next-app@latest

Projets existants

Ajoutez TypeScript à votre projet en renommant un fichier en .ts / .tsx. Exécutez next dev et next build pour installer automatiquement les dépendances nécessaires et ajouter un fichier tsconfig.json avec les options de configuration recommandées.

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

Plugin TypeScript

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 une auto-complétion.

Vous pouvez activer le plugin dans VS Code en :

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

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

Fonctionnalités du plugin

Le plugin TypeScript peut aider avec :

• Un avertissement si des valeurs invalides pour les options de configuration de segment sont passées.
• L'affichage des options disponibles et de la documentation en contexte.
• 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.

Bon à savoir : D'autres fonctionnalités seront ajoutées à l'avenir.

Version minimale de TypeScript

Il est fortement recommandé d'utiliser au moins la version v4.5.2 de TypeScript pour bénéficier de fonctionnalités syntaxiques comme les modificateurs de type sur les noms d'import et les améliorations de performance.

Liens typés statiquement

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 ainsi la sécurité des types lors de la navigation entre les pages.

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

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

module.exports = 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.

Sécurité des types de bout en bout

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

1. Aucune sérialisation des données entre la fonction de récupération et la page : Vous pouvez fetch directement dans les composants, layouts et pages sur le serveur. Ces données n'ont pas besoin d'être sérialisées (converties en chaîne) pour être passées côté client pour consommation dans React. Au lieu de cela, puisque app utilise des composants serveur par défaut, nous pouvons utiliser des valeurs comme Date, Map, Set, et plus sans étapes supplémentaires. Auparavant, vous deviez typer manuellement la frontière entre serveur et client avec des types spécifiques à Next.js.
2. Flux de données simplifié entre composants : Avec la suppression de _app en faveur des layouts racine, il est maintenant plus facile de visualiser le flux de données entre composants et 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é des types aussi proche que possible de 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é des types complète de bout en bout, cela nécessite également que votre base de données ou fournisseur de contenu supporte TypeScript. Cela peut être via l'utilisation d'un ORM ou d'un constructeur de requêtes typé.

Erreur TypeScript 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.

Passage de données entre composants serveur et client

Lors du passage de données entre un composant serveur et un composant client via les props, les données sont toujours sérialisées (converties en chaîne) pour utilisation dans le navigateur. Cependant, elles n'ont pas besoin d'un type spécial. Elles sont typées de la même manière que le passage de n'importe quelle autre prop entre composants.

De plus, il y a moins de code à sérialiser, car les données non rendues ne passent pas entre le serveur et le client (elles restent sur le serveur). Ceci n'est possible que grâce au support des composants serveur.

Alias de chemin et baseUrl

Next.js supporte automatiquement les options "paths" et "baseUrl" de tsconfig.json.

Vous pouvez en apprendre plus sur cette fonctionnalité dans la documentation Alias de module et imports absolus.

Vérification des types dans next.config.js

Le fichier next.config.js doit être un fichier JavaScript car il n'est pas analysé par Babel ou TypeScript, mais 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

Vérification incrémentale des types

Depuis la v10.2.1, Next.js supporte la vérification incrémentale des types lorsqu'elle est activée dans votre tsconfig.json, ce qui peut aider à accélérer la vérification des types dans les applications plus grandes.

Ignorer les erreurs TypeScript

Next.js fait échouer 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 des types intégrée.

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

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

module.exports = {
  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,
  },
}

Déclarations de types 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 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