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.

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

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 type { 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.

Avec les 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' })
}

Avec un App personnalisé

Si vous avez une application 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} />
}

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