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.

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.

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.

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 changer le nom du 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 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