TypeScript

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

Il inclut un support natif de TypeScript pour installer automatiquement les paquets 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 fichier 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 avancée des types 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. Cherchant "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é.

Fonctionnalités du plugin

Le plugin TypeScript peut aider avec :

• L'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.

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 performances.

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 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 contenant 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 n'importe quel 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

Next.js 13 a amélioré la sécurité des types. 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 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 serveur et client avec des types spécifiques à Next.js.
2. Flux de données simplifié entre les composants : Avec la suppression de _app en faveur 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 Next.js 13, ce n'est plus un problème.

La Récupération de données dans Next.js fournit désormais une sécurité des types aussi proche que possible de bout en bout sans être prescriptif quant au choix de votre base de données ou 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 async

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 ancienne version 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, cela ne nécessite pas de type spécial. C'est typé 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 traversent pas entre le serveur et le client (elles restent sur le serveur). Ceci n'est maintenant possible que grâce au support des composants serveur.

Alias de chemins 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 modules 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 parsé par Babel ou TypeScript, cependant 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 volumineuses.

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ée, 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,
  },
}

Historique des changements