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.

IDE-Plugin

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

Sie können das Plugin in VS Code aktivieren, indem Sie:

1. Die Befehlspalette öffnen (Strg/⌘ + Umschalt + P)
2. Nach "TypeScript: Select TypeScript Version" suchen
3. "Use Workspace Version" auswählen

Nun wird beim Bearbeiten von Dateien das benutzerdefinierte Plugin aktiviert. Beim Ausführen von next build wird der benutzerdefinierte Type-Checker verwendet.

Das TypeScript-Plugin kann bei folgenden Punkten helfen:

• Warnung, 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.

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

End-to-End-Type-Sicherheit

Der Next.js App Router bietet verbesserte Type-Sicherheit. 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 nun 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 kolokalisiertem Data Fetching im App-Router ist dies kein Problem mehr.

Data Fetching in Next.js bietet nun eine möglichst nahe End-to-End-Type-Sicherheit, ohne dabei Ihre Auswahl an Datenbank oder Content-Provider vorzuschreiben.

Wir können die Antwortdaten so typisieren, wie Sie es mit normalem TypeScript erwarten würden. 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-Type-Sicherheit muss auch Ihre Datenbank oder Ihr Content-Provider TypeScript unterstützen. Dies kann durch die Verwendung eines ORM oder eines type-sicheren Query-Builders erfolgen.

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

Statisch typisierte Links

Next.js kann Links statisch typisieren, um Tippfehler und andere Fehler bei der Verwendung von next/link zu verhindern und so die Type-Sicherheit bei der Navigation zwischen Seiten zu verbessern.

Um diese Funktion zu nutzen, muss experimental.typedRoutes aktiviert werden und das Projekt muss TypeScript verwenden.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

export default nextConfig

Next.js generiert eine Link-Definition in .next/types, die Informationen über alle vorhandenen Routen in Ihrer Anwendung enthält. TypeScript kann diese dann nutzen, 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 typisieren:

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?

Wenn Sie next dev oder next build ausführen, generiert Next.js eine versteckte .d.ts-Datei in .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 wird in tsconfig.json eingebunden und der TypeScript-Compiler überprüft diese .d.ts und gibt Feedback in Ihrem Editor über ungültige Links.

Mit Async Server Components

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, könnte ein 'Promise<Element>' is not a valid JSX element-Type-Fehler auftreten. Ein Update auf die neueste Version von TypeScript und @types/react sollte dieses Problem beheben.

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