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.

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.

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.

Génération statique et rendu côté serveur

Pour getStaticProps, getStaticPaths, et getServerSideProps, vous pouvez utiliser respectivement les types GetStaticProps, GetStaticPaths, et GetServerSideProps :

import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next'

export const getStaticProps = (async (context) => {
  // ...
}) satisfies GetStaticProps

export const getStaticPaths = (async () => {
  // ...
}) satisfies GetStaticPaths

export const getServerSideProps = (async (context) => {
  // ...
}) satisfies GetServerSideProps

Bon à savoir : satisfies a été ajouté à TypeScript dans la version 4.9. Nous recommandons de mettre à jour vers la dernière version de TypeScript.

Routes API

Voici un exemple d'utilisation des types intégrés pour les routes API :

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ name: 'John Doe' })
}

Vous pouvez également typer les données de réponse :

import type { NextApiRequest, NextApiResponse } from 'next'

type Data = {
  name: string
}

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>
) {
  res.status(200).json({ name: 'John Doe' })
}

App personnalisé

Si vous avez une App personnalisée, vous pouvez utiliser le type intégré AppProps et renommer le fichier en ./pages/_app.tsx comme suit :

import type { AppProps } from 'next/app'

export default function MyApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

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