TypeScript

Next.js bietet eine TypeScript-orientierte Entwicklungserfahrung für den Aufbau Ihrer React-Anwendung.

Es verfügt über eine integrierte TypeScript-Unterstützung zum automatischen Installieren der erforderlichen Pakete und Konfigurieren der richtigen Einstellungen.

Neue Projekte

create-next-app wird jetzt standardmäßig mit TypeScript ausgeliefert.

npx create-next-app@latest

Bestehende Projekte

Fügen Sie Ihrem Projekt TypeScript hinzu, indem Sie eine Datei in .ts / .tsx umbenennen. Führen Sie next dev und next build aus, um automatisch die erforderlichen Abhängigkeiten zu installieren und eine tsconfig.json-Datei mit den empfohlenen Konfigurationsoptionen hinzuzufügen.

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

Wir empfehlen Ihnen auch, next.config.ts anstelle von next.config.js für eine bessere Typrückschlussermittlung zu verwenden.

Minimale TypeScript-Version

Es wird dringend empfohlen, mindestens die Version v4.5.2 von TypeScript zu verwenden, um Syntaxfunktionen wie Typmodifikatoren bei Importnamen und Leistungsverbesserungen zu erhalten.

Typenüberprüfung in der Next.js-Konfiguration

Typenüberprüfung von next.config.js

Bei Verwendung der next.config.js-Datei können Sie einige Typenüberprüfungen in Ihrer IDE mithilfe von JSDoc wie folgt hinzufügen:

// @ts-check
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* Konfigurationsoptionen hier */
}
 
module.exports = nextConfig

Typenüberprüfung von next.config.ts

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

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  /* Konfigurationsoptionen hier */
}
 
export default nextConfig

Hinweis: 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.

Statische Generierung und serverseitiges Rendering

Bei 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

Hinweis: satisfies wurde in TypeScript 4.9 hinzugefügt. Wir empfehlen, auf die neueste Version von TypeScript zu aktualisieren.

API-Routen

Das Folgende ist ein Beispiel, wie Sie die integrierten Typen für API-Routen verwenden:

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

Benutzerdefinierte 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} />
}

Pfadalias und baseUrl

Next.js unterstützt automatisch die "paths" und "baseUrl" Optionen aus der tsconfig.json.

Sie können mehr über diese Funktion in der Dokumentation zu Modul-Pfadaliasen erfahren.

Inkrementelle Typprüfung

Seit v10.2.1 unterstützt Next.js inkrementelle Typprüfung, wenn diese in Ihrer tsconfig.json aktiviert ist. Dies kann helfen, die Typprüfung in größeren Anwendungen zu beschleunigen.

TypeScript-Fehler ignorieren

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

Wenn Sie möchten, dass Next.js gefährlich Produktionscode erstellt, auch wenn Ihre Anwendung Fehler enthält, können Sie den integrierten Typprüfungsschritt deaktivieren.

Stellen Sie bei Deaktivierung sicher, dass Sie Typprüfungen als Teil Ihres Build- oder Bereitstellungsprozesses durchführen, da dies andernfalls sehr gefährlich sein kann.

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

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  typescript: {
    // !! WARNUNG !!
    // Erlaubt gefährlich Produktionsbuilds, auch wenn
    // Ihr Projekt Typfehler enthält.
    // !! WARNUNG !!
    ignoreBuildErrors: true,
  },
}
 
export default nextConfig

Hinweis: Sie können tsc --noEmit ausführen, um TypeScript-Fehler selbst zu prüfen, bevor Sie bauen. Dies ist nützlich für CI/CD-Pipelines, in denen Sie TypeScript-Fehler vor der Bereitstellung prü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 überschrieben werden. Erstellen Sie stattdessen eine neue Datei, nennen wir sie new-types.d.ts, und referenzieren Sie diese in Ihrer tsconfig.json:

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

Versionsänderungen