TypeScript

Next.js bringt TypeScript mit sich und installiert automatisch die notwendigen Pakete sowie konfiguriert die richtigen Einstellungen, wenn Sie ein neues Projekt mit create-next-app erstellen.

Um TypeScript zu einem bestehenden Projekt hinzuzufügen, benennen Sie eine Datei in .ts / .tsx um. Führen Sie next dev und next build aus, um automatisch die notwendigen Abhängigkeiten zu installieren und eine tsconfig.json-Datei mit den empfohlenen Konfigurationsoptionen hinzuzufügen.

Gut zu wissen: Wenn Sie bereits eine jsconfig.json-Datei haben, kopieren Sie die paths-Compiler-Option aus der alten jsconfig.json in die neue tsconfig.json-Datei und löschen Sie die alte jsconfig.json-Datei.

Beispiele

Type-Checking für next.config.ts

Sie können TypeScript und importierte Typen in Ihrer Next.js-Konfiguration verwenden, indem Sie next.config.ts nutzen.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* Konfigurationsoptionen hier */
}

export default nextConfig

Gut zu wissen: Die Modulauflösung in next.config.ts ist derzeit auf CommonJS beschränkt. Dies kann zu Inkompatibilitäten mit ESM-only-Paketen führen, die in next.config.ts geladen werden.

Wenn Sie die next.config.js-Datei verwenden, können Sie in Ihrer IDE mit JSDoc eine Type-Checking-Funktionalität hinzufügen:

// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* Konfigurationsoptionen hier */
}

module.exports = nextConfig

Statische Generierung und Server-seitiges Rendering

Für getStaticProps, getStaticPaths und getServerSideProps können Sie die Typen GetStaticProps, GetStaticPaths bzw. GetServerSideProps verwenden:

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

Gut zu wissen: satisfies wurde in TypeScript 4.9 hinzugefügt. Wir empfehlen ein Upgrade auf die neueste Version von TypeScript.

Mit API-Routen

Das folgende Beispiel zeigt, wie Sie die integrierten Typen für API-Routen verwenden können:

import type { NextApiRequest, NextApiResponse } from 'next'

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

Sie können auch die Antwortdaten typisieren:

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

Mit benutzerdefinierter App

Wenn Sie eine benutzerdefinierte App haben, können Sie den integrierten Typ AppProps verwenden und den Dateinamen in ./pages/_app.tsx ändern:

import type { AppProps } from 'next/app'

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

Inkrementelles Type-Checking

Seit v10.2.1 unterstützt Next.js inkrementelles Type-Checking, wenn es in Ihrer tsconfig.json aktiviert ist. Dies kann die Type-Checking-Geschwindigkeit in größeren Anwendungen verbessern.

Deaktivieren von TypeScript-Fehlern in der Produktion

Next.js bricht Ihren Produktionsbuild (next build) ab, wenn TypeScript-Fehler in Ihrem Projekt vorhanden sind.

Wenn Sie möchten, dass Next.js gefährlicherweise Produktionscode erzeugt, selbst wenn Ihre Anwendung Fehler enthält, können Sie den integrierten Type-Checking-Schritt deaktivieren.

Wenn Sie dies deaktivieren, stellen Sie sicher, dass Sie Type-Checks als Teil Ihres Build- oder Deploy-Prozesses durchführen, da dies sonst sehr gefährlich sein kann.

Öffnen Sie next.config.ts und aktivieren Sie die ignoreBuildErrors-Option in der typescript-Konfiguration:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  typescript: {
    // !! WARNUNG !!
    // Erlaubt gefährlicherweise, dass Produktionsbuilds erfolgreich abgeschlossen werden,
    // selbst wenn Ihr Projekt Type-Fehler enthält.
    // !! WARNUNG !!
    ignoreBuildErrors: true,
  },
}

export default nextConfig

Gut zu wissen: Sie können tsc --noEmit ausführen, um selbst nach TypeScript-Fehlern zu suchen, bevor Sie den Build durchführen. Dies ist nützlich für CI/CD-Pipelines, in denen Sie TypeScript-Fehler vor dem Deployment überprüfen möchten.

Benutzerdefinierte Typdeklarationen

Wenn Sie benutzerdefinierte Typen deklarieren müssen, könnten Sie versucht sein, next-env.d.ts zu ändern. Diese Datei wird jedoch automatisch generiert, sodass alle Änderungen, die Sie vornehmen, überschrieben werden. Stattdessen sollten Sie eine neue Datei erstellen, z.B. new-types.d.ts, und diese in Ihrer tsconfig.json referenzieren:

{
  "compilerOptions": {
    "skipLibCheck": true
    //...gekürzt...
  },
  "include": [
    "new-types.d.ts",
    "next-env.d.ts",
    ".next/types/**/*.ts",
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": ["node_modules"]
}

Versionsänderungen