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.

Sowie ein TypeScript-Plugin für Ihren Editor.

🎥 Ansehen: Lernen Sie mehr über das integrierte TypeScript-Plugin → YouTube (3 Minuten)

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.

TypeScript-Plugin

Next.js enthält ein benutzerdefiniertes TypeScript-Plugin und einen Typprüfer, die VSCode und andere Code-Editoren für erweiterte Typenüberprüfung und Autovervollständigung verwenden können.

Sie können das Plugin in VS Code aktivieren durch:

1. Öffnen der Befehlspalette (Strg/⌘ + Umschalt + P)
2. Suchen nach "TypeScript: TypeScript-Version auswählen"
3. Auswählen von "Arbeitsbereichsversion verwenden"

Wenn Sie jetzt Dateien bearbeiten, wird das benutzerdefinierte Plugin aktiviert. Bei Ausführung von next build wird der benutzerdefinierte Typprüfer verwendet.

Plugin-Funktionen

Das TypeScript-Plugin kann helfen bei:

• Warnung, wenn ungültige Werte für Segmentkonfigurationsoptionen übergeben werden.
• Anzeigen verfügbarer Optionen und kontextbezogener Dokumentation.
• Sicherstellen, dass die use client-Direktive korrekt verwendet wird.
• Sicherstellen, dass Client-Hooks (wie useState) nur in Client-Komponenten verwendet werden.

Hinweis: In Zukunft werden weitere Funktionen hinzugefügt.

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.

Statisch typisierte Links

Next.js kann Links statisch typisieren, um Tippfehler und andere Fehler bei der Verwendung von next/link zu verhindern und die Typsicherheit beim Navigieren zwischen Seiten zu verbessern.

Um diese Funktion zu aktivieren, müssen experimental.typedRoutes aktiviert und das Projekt TypeScript verwenden.

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    typedRoutes: true,
  },
}
 
export default nextConfig

Next.js generiert eine Linkdefinition in .next/types, die Informationen über alle vorhandenen Routen in Ihrer Anwendung enthält, die TypeScript dann zur Bereitstellung von Feedback in Ihrem Editor über ungültige Links verwenden kann.

Aktuell umfasst die experimentelle Unterstützung beliebige Zeichenfolgenliterale, einschließlich dynamischer Segmente. Für Nicht-Literalzeichenfolgen müssen Sie derzeit href manuell mit as Route umwandeln:

import type { Route } from 'next';
import Link from 'next/link'
 
// Keine TypeScript-Fehler, wenn href eine gültige Route ist
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />
 
// TypeScript-Fehler, wenn href keine gültige Route ist
<Link href="/aboot" />

Um href in einer benutzerdefinierten Komponente zu akzeptieren, die next/link umschließt, verwenden Sie einen generischen Typ:

import type { Route } from 'next'
import Link from 'next/link'
 
function Card<T extends string>({ href }: { href: Route<T> | URL }) {
  return (
    <Link href={href}>
      <div>Meine Karte</div>
    </Link>
  )
}

Wie funktioniert es?

Bei Ausführung von next dev oder next build generiert Next.js eine versteckte .d.ts-Datei innerhalb von .next, die Informationen über alle vorhandenen Routen in Ihrer Anwendung (alle gültigen Routen als href-Typ von Link) enthält. Diese .d.ts-Datei wird in tsconfig.json einbezogen, und der TypeScript-Compiler prüft diese .d.ts und liefert Feedback in Ihrem Editor über ungültige Links.

End-to-End-Typsicherheit

Der Next.js App Router bietet verbesserte Typsicherheit. Dies umfasst:

1. Keine Serialisierung von Daten zwischen Abruffunktion und Seite: Sie können direkt in Komponenten, Layouts und Seiten auf dem Server fetchen. Diese Daten müssen nicht serialisiert (in einen String umgewandelt) werden, um sie auf der Clientseite zu nutzen. Da app standardmäßig Server-Komponenten verwendet, können wir Werte wie Date, Map, Set und mehr ohne zusätzliche Schritte verwenden. Zuvor mussten Sie die Grenze zwischen Server und Client manuell mit Next.js-spezifischen Typen typisieren.
2. Optimierter Datenfluss zwischen Komponenten: Mit der Entfernung von _app zugunsten von Root-Layouts ist es jetzt einfacher, den Datenfluss zwischen Komponenten und Seiten zu visualisieren. Zuvor waren Daten, die zwischen einzelnen pages und _app flossen, schwierig zu typisieren und konnten verwirrende Fehler einführen. Mit kocolokierter Datenabfrage im App Router ist dies nicht mehr ein Problem.

Datenabfrage in Next.js bietet jetzt so etwas wie End-to-End-Typsicherheit, ohne bei der Auswahl Ihrer Datenbank oder Ihres Inhaltsanbieters vorschreibend zu sein.

Wir können die Antwortdaten wie mit normalem TypeScript erwarten typisieren. Zum Beispiel:

async function getData() {
  const res = await fetch('https://api.example.com/...')
  // Der Rückgabewert wird *nicht* serialisiert
  // Sie können Date, Map, Set usw. zurückgeben
  return res.json()
}
 
export default async function Page() {
  const name = await getData()
 
  return '...'
}

Für eine vollständige End-to-End-Typsicherheit erfordert dies auch, dass Ihre Datenbank oder Ihr Inhaltsanbieter TypeScript unterstützt. Dies könnte durch Verwendung eines ORM oder eines typsicheren Abfragegenerators erfolgen.

Async Server Component TypeScript-Fehler

Um eine async Server-Komponente mit TypeScript zu verwenden, stellen Sie sicher, dass Sie TypeScript 5.1.3 oder höher und @types/react 18.2.8 oder höher verwenden.

Wenn Sie eine ältere Version von TypeScript verwenden, erhalten Sie möglicherweise einen Typfehler 'Promise<Element>' ist kein gültiges JSX-Element. Die Aktualisierung auf die neueste Version von TypeScript und @types/react sollte dieses Problem beheben.

Datenaustausch zwischen Server- und Client-Komponenten

Beim Übergeben von Daten zwischen einer Server- und einer Client-Komponente über Props werden die Daten weiterhin serialisiert (in einen String umgewandelt), um sie im Browser zu verwenden. Dabei ist jedoch kein spezieller Typ erforderlich. Die Typisierung erfolgt genauso wie beim Übergeben anderer Props zwischen Komponenten.

Darüber hinaus gibt es weniger zu serialisierende Daten, da nicht gerenderte Daten nicht zwischen Server und Client wechseln (sie verbleiben auf dem Server). Dies ist nur durch die Unterstützung von Server-Komponenten möglich.

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