TypeScript

Next.js bietet eine TypeScript-first-Entwicklungsumgebung für den Aufbau Ihrer React-Anwendung.

Es verfügt über integrierte TypeScript-Unterstützung für die automatische Installation der erforderlichen Pakete und die Konfiguration der richtigen Einstellungen.

Sowie ein TypeScript-Plugin für Ihren Editor.

🎥 Video ansehen: Erfahren Sie mehr über das integrierte TypeScript-Plugin → YouTube (3 Minuten)

Neue Projekte

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

npx create-next-app@latest

Bestehende Projekte

Fügen Sie TypeScript zu Ihrem Projekt 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 paths-Compiler-Option aus der alten jsconfig.json in die neue tsconfig.json-Datei und löschen Sie die alte jsconfig.json-Datei.

TypeScript-Plugin

Next.js enthält ein benutzerdefiniertes TypeScript-Plugin und einen Type-Checker, die von VSCode und anderen Code-Editoren für erweiterte Typüberprüfung und Auto-Vervollständigung verwendet werden können.

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

1. Öffnen der Befehlspalette (Strg/⌘ + Umschalt + P)
2. Suchen nach "TypeScript: Select TypeScript Version"
3. Auswählen von "Use Workspace Version"

Beim Bearbeiten von Dateien wird nun das benutzerdefinierte Plugin aktiviert. Bei der Ausführung von next build wird der benutzerdefinierte Type-Checker verwendet.

Plugin-Funktionen

Das TypeScript-Plugin kann helfen bei:

• Warnungen, wenn ungültige Werte für Segment-Konfigurationsoptionen übergeben werden.
• Anzeige verfügbarer Optionen und Kontextdokumentation.
• Sicherstellung, dass die use client-Direktive korrekt verwendet wird.
• Sicherstellung, dass Client-Hooks (wie useState) nur in Client-Komponenten verwendet werden.

Gut zu wissen: Weitere Funktionen werden in Zukunft hinzugefügt.

Minimale TypeScript-Version

Es wird dringend empfohlen, mindestens TypeScript v4.5.2 zu verwenden, um Syntax-Funktionen wie Typmodifikatoren für Importnamen und Leistungsverbesserungen zu erhalten.

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 bei der Navigation zwischen Seiten zu verbessern.

Um diese Funktion zu aktivieren, muss experimental.typedRoutes aktiviert sein und das Projekt muss TypeScript verwenden.

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

module.exports = nextConfig

Next.js generiert eine Link-Definition in .next/types, die Informationen über alle vorhandenen Routen in Ihrer Anwendung enthält, die TypeScript dann verwenden kann, um Feedback in Ihrem Editor über ungültige Links zu geben.

Derzeit umfasst die experimentelle Unterstützung alle String-Literale, einschließlich dynamischer Segmente. Für nicht-literale Strings müssen Sie derzeit den href manuell mit as Route casten:

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, die next/link umschließt, zu akzeptieren, verwenden Sie ein Generic:

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 das?

Bei der 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 enthält (alle gültigen Routen als href-Typ von Link). Diese .d.ts-Datei ist in tsconfig.json enthalten und der TypeScript-Compiler überprüft diese .d.ts-Datei und gibt 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 fetch direkt in Komponenten, Layouts und Seiten auf dem Server verwenden. Diese Daten müssen nicht serialisiert (in einen String umgewandelt) werden, um an die Client-Seite zur Verwendung in React übergeben zu werden. Da app standardmäßig Server-Komponenten verwendet, können wir Werte wie Date, Map, Set und mehr ohne zusätzliche Schritte verwenden. Früher 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. Früher waren Datenflüsse zwischen einzelnen pages und _app schwer zu typisieren und konnten verwirrende Fehler verursachen. Mit colocated data fetching im App Router ist dies kein Problem mehr.

Data Fetching in Next.js bietet nun eine möglichst nahe End-to-End-Typsicherheit, ohne bei der Auswahl Ihrer Datenbank oder Ihres Content-Providers vorschreibend zu sein.

Wir können die Antwortdaten so typisieren, wie Sie es mit normalem TypeScript erwarten würden. 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 vollständige End-to-End-Typsicherheit muss Ihre Datenbank oder Ihr Content-Provider auch TypeScript unterstützen. Dies könnte durch die Verwendung eines ORM oder eines typsicheren Query-Builders erfolgen.

TypeScript-Fehler bei Async-Server-Komponenten

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 'Promise<Element>' is not a valid JSX element-Typfehler. Ein Update auf die neueste Version von TypeScript und @types/react sollte dieses Problem beheben.

Datenübergabe zwischen Server- und Client-Komponenten

Bei der Übergabe von Daten zwischen einer Server- und einer Client-Komponente über Props werden die Daten für die Verwendung im Browser weiterhin serialisiert (in einen String umgewandelt). Es ist jedoch kein spezieller Typ erforderlich. Die Typisierung erfolgt genauso wie bei der Übergabe anderer Props zwischen Komponenten.

Darüber hinaus muss weniger Code serialisiert werden, da nicht gerenderte Daten nicht zwischen Server und Client übertragen werden (sie bleiben auf dem Server). Dies ist jetzt erst durch die Unterstützung von Server-Komponenten möglich.

Pfad-Aliase und baseUrl

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

Weitere Informationen zu dieser Funktion finden Sie in der Dokumentation zu Modulpfad-Aliasen.

Typüberprüfung von next.config.js

Die next.config.js-Datei muss eine JavaScript-Datei sein, da sie nicht von Babel oder TypeScript geparst wird. Sie können jedoch mit JSDoc eine Typüberprüfung in Ihrer IDE hinzufügen:

// @ts-check

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

module.exports = nextConfig

Inkrementelle Typüberprüfung

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

Ignorieren von TypeScript-Fehlern

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 Typüberprüfungsschritt deaktivieren.

Wenn dies deaktiviert ist, stellen Sie sicher, dass Sie Typüberprüfungen als Teil Ihres Build- oder Bereitstellungsprozesses durchführen, da dies sonst sehr gefährlich sein kann.

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

module.exports = {
  typescript: {
    // !! WARNUNG !!
    // Erlaubt gefährlicherweise die erfolgreiche Fertigstellung von Produktionsbuilds, auch wenn
    // Ihr Projekt Typfehler enthält.
    // !! WARNUNG !!
    ignoreBuildErrors: true,
  },
}

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 in Ihrer tsconfig.json darauf verweisen:

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

Versionsänderungen