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: 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.
• Anzeigen verfügbarer Optionen und Kontextdokumentation.
• Sicherstellen, dass die use client-Direktive korrekt verwendet wird.
• Sicherstellen, 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 Syntaxfunktionen wie Typmodifikatoren bei 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 in Ihrem Editor Feedback ü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 es?

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 wird diese .d.ts überprüfen und Feedback in Ihrem Editor über ungültige Links geben.

End-to-End-Typsicherheit

Next.js 13 bietet verbesserte Typsicherheit. Dazu gehören:

1. Keine Serialisierung von Daten zwischen Fetch-Funktion 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 Bugs einführen. Mit colocated data fetching in Next.js 13 ist dies kein Problem mehr.

Data Fetching in Next.js bietet nun eine so nahe an End-to-End-Typsicherheit wie möglich, ohne vorschreibend in Bezug auf Ihre Datenbank- oder Content-Provider-Auswahl 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 ebenfalls 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, sehen Sie möglicherweise einen Typfehler 'Promise<Element>' is not a valid JSX element. 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 immer noch 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 gibt es weniger Code, der serialisiert werden muss, da nicht gerenderte Daten nicht zwischen Server und Client übertragen werden (sie bleiben auf dem Server). Dies ist erst jetzt durch die Unterstützung für 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-Aliassen.

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 sie in Ihrer tsconfig.json aktiviert ist. Dies kann die Typüberprüfung in größeren Anwendungen beschleunigen.

Ignorieren von TypeScript-Fehlern

Next.js lässt Ihren Produktions-Build (next build) fehlschlagen, wenn TypeScript-Fehler in Ihrem Projekt vorhanden sind.

Wenn Sie möchten, dass Next.js gefährlicherweise Produktionscode erzeugt, auch 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 Deploy-Prozesses durchführen, da dies sonst sehr gefährlich sein kann.

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

module.exports = {
  typescript: {
    // !! WARNUNG !!
    // Erlaubt gefährlicherweise, dass Produktions-Builds erfolgreich abgeschlossen werden,
    // auch wenn Ihr Projekt Typfehler enthält.
    // !! WARNUNG !!
    ignoreBuildErrors: true,
  },
}

Versionsänderungen