Next.js Compiler

Der Next.js Compiler, geschrieben in Rust mit SWC, ermöglicht es Next.js, Ihren JavaScript-Code für die Produktion zu transformieren und zu minimieren. Dies ersetzt Babel für einzelne Dateien und Terser für die Minimierung von Ausgabebündeln.

Die Kompilierung mit dem Next.js Compiler ist 17x schneller als mit Babel und seit Next.js Version 12 standardmäßig aktiviert. Wenn Sie eine bestehende Babel-Konfiguration haben oder nicht unterstützte Funktionen verwenden, wird Ihre Anwendung den Next.js Compiler nicht nutzen und weiterhin Babel verwenden.

Warum SWC?

SWC ist eine erweiterbare, auf Rust basierende Plattform für die nächste Generation schneller Entwicklerwerkzeuge.

SWC kann für Kompilierung, Minimierung, Bundling und mehr verwendet werden – und ist für Erweiterungen konzipiert. Es ist etwas, das Sie aufrufen können, um Code-Transformationen (entweder eingebaut oder benutzerdefiniert) durchzuführen. Die Ausführung dieser Transformationen erfolgt über höhere Tools wie Next.js.

Wir haben uns aus mehreren Gründen für SWC entschieden:

• Erweiterbarkeit: SWC kann als Crate innerhalb von Next.js verwendet werden, ohne die Bibliothek forken oder Designbeschränkungen umgehen zu müssen.
• Leistung: Durch den Wechsel zu SWC konnten wir ~3x schnelleres Fast Refresh und ~5x schnellere Builds in Next.js erreichen, mit weiterem Optimierungspotenzial.
• WebAssembly: Rusts Unterstützung für WASM ist entscheidend, um alle möglichen Plattformen zu unterstützen und Next.js-Entwicklung überall hin zu bringen.
• Community: Die Rust-Community und das Ökosystem sind hervorragend und wachsen weiter.

Unterstützte Funktionen

Styled Components

Wir arbeiten daran, babel-plugin-styled-components auf den Next.js Compiler zu portieren.

Aktualisieren Sie zunächst auf die neueste Version von Next.js: npm install next@latest. Aktualisieren Sie dann Ihre next.config.js-Datei:

module.exports = {
  compiler: {
    styledComponents: true,
  },
}

Für erweiterte Anwendungsfälle können Sie einzelne Eigenschaften für die styled-components-Kompilierung konfigurieren.

Hinweis: minify, transpileTemplateLiterals und pure sind noch nicht implementiert. Sie können den Fortschritt hier verfolgen. ssr und displayName-Transformationen sind die Hauptvoraussetzung für die Verwendung von styled-components in Next.js.

module.exports = {
  compiler: {
    // Weitere Informationen zu den Optionen finden Sie unter https://styled-components.com/docs/tooling#babel-plugin.
    styledComponents: {
      // Standardmäßig in der Entwicklung aktiviert, in der Produktion deaktiviert, um die Dateigröße zu reduzieren.
      // Das Setzen dieser Option überschreibt den Standard für alle Umgebungen.
      displayName?: boolean,
      // Standardmäßig aktiviert.
      ssr?: boolean,
      // Standardmäßig aktiviert.
      fileName?: boolean,
      // Standardmäßig leer.
      topLevelImportPaths?: string[],
      // Standardmäßig ["index"].
      meaninglessFileNames?: string[],
      // Standardmäßig aktiviert.
      cssProp?: boolean,
      // Standardmäßig leer.
      namespace?: string,
      // Noch nicht unterstützt.
      minify?: boolean,
      // Noch nicht unterstützt.
      transpileTemplateLiterals?: boolean,
      // Noch nicht unterstützt.
      pure?: boolean,
    },
  },
}

Jest

Der Next.js Compiler transpiliert Ihre Tests und vereinfacht die Konfiguration von Jest mit Next.js, einschließlich:

• Automatisches Mocking von .css, .module.css (und ihren .scss-Varianten) sowie Bildimporten
• Automatische Einrichtung von transform mit SWC
• Laden von .env (und allen Varianten) in process.env
• Ignorieren von node_modules bei der Testauflösung und Transformation
• Ignorieren von .next bei der Testauflösung
• Laden von next.config.js für Flags, die experimentelle SWC-Transformationen ermöglichen

Aktualisieren Sie zunächst auf die neueste Version von Next.js: npm install next@latest. Aktualisieren Sie dann Ihre jest.config.js-Datei:

const nextJest = require('next/jest')

// Bereitstellung des Pfads zu Ihrer Next.js-App, der das Laden von next.config.js und .env-Dateien ermöglicht
const createJestConfig = nextJest({ dir: './' })

// Benutzerdefinierte Konfiguration, die Sie an Jest übergeben möchten
const customJestConfig = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
}

// createJestConfig wird auf diese Weise exportiert, um sicherzustellen, dass next/jest die Next.js-Konfiguration laden kann, die asynchron ist
module.exports = createJestConfig(customJestConfig)

Relay

Um Relay-Unterstützung zu aktivieren:

module.exports = {
  compiler: {
    relay: {
      // Dies sollte mit relay.config.js übereinstimmen
      src: './',
      artifactDirectory: './__generated__',
      language: 'typescript',
      eagerEsModules: false,
    },
  },
}

Gut zu wissen: In Next.js werden alle JavaScript-Dateien im pages-Verzeichnis als Routen betrachtet. Für relay-compiler müssen Sie daher die artifactDirectory-Konfiguration außerhalb von pages angeben, da relay-compiler sonst Dateien neben der Quelldatei im __generated__-Verzeichnis generiert, was als Route betrachtet wird und Produktionsbuilds zerstört.

React Properties entfernen

Ermöglicht das Entfernen von JSX-Properties. Dies wird oft für Tests verwendet. Ähnlich wie babel-plugin-react-remove-properties.

Um Properties zu entfernen, die auf die Standard-Regex ^data-test passen:

module.exports = {
  compiler: {
    reactRemoveProperties: true,
  },
}

Um benutzerdefinierte Properties zu entfernen:

module.exports = {
  compiler: {
    // Die hier definierten Regex werden in Rust verarbeitet, daher unterscheidet sich die Syntax von
    // JavaScript `RegExp`s. Siehe https://docs.rs/regex.
    reactRemoveProperties: { properties: ['^data-custom$'] },
  },
}

Console entfernen

Diese Transformation ermöglicht das Entfernen aller console.*-Aufrufe im Anwendungscode (nicht in node_modules). Ähnlich wie babel-plugin-transform-remove-console.

Entfernt alle console.*-Aufrufe:

module.exports = {
  compiler: {
    removeConsole: true,
  },
}

Entfernt console.*-Ausgaben außer console.error:

module.exports = {
  compiler: {
    removeConsole: {
      exclude: ['error'],
    },
  },
}

Legacy Decorators

Next.js erkennt automatisch experimentalDecorators in jsconfig.json oder tsconfig.json. Legacy Decorators werden häufig mit älteren Versionen von Bibliotheken wie mobx verwendet.

Dieses Flag wird nur für die Kompatibilität mit bestehenden Anwendungen unterstützt. Wir empfehlen nicht, Legacy Decorators in neuen Anwendungen zu verwenden.

Aktualisieren Sie zunächst auf die neueste Version von Next.js: npm install next@latest. Aktualisieren Sie dann Ihre jsconfig.json oder tsconfig.json-Datei:

{
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

importSource

Next.js erkennt automatisch jsxImportSource in jsconfig.json oder tsconfig.json und wendet diese an. Dies wird häufig mit Bibliotheken wie Theme UI verwendet.

Aktualisieren Sie zunächst auf die neueste Version von Next.js: npm install next@latest. Aktualisieren Sie dann Ihre jsconfig.json oder tsconfig.json-Datei:

{
  "compilerOptions": {
    "jsxImportSource": "theme-ui"
  }
}

Emotion

Wir arbeiten daran, @emotion/babel-plugin auf den Next.js Compiler zu portieren.

Aktualisieren Sie zunächst auf die neueste Version von Next.js: npm install next@latest. Aktualisieren Sie dann Ihre next.config.js-Datei:

module.exports = {
  compiler: {
    emotion: boolean | {
      // Standard ist true. Wird deaktiviert, wenn der Build-Typ production ist.
      sourceMap?: boolean,
      // Standard ist 'dev-only'.
      autoLabel?: 'never' | 'dev-only' | 'always',
      // Standard ist '[local]'.
      // Erlaubte Werte: `[local]` `[filename]` und `[dirname]`
      // Diese Option funktioniert nur, wenn autoLabel auf 'dev-only' oder 'always' gesetzt ist.
      // Sie ermöglicht die Definition des Formats des resultierenden Labels.
      // Das Format wird über einen String definiert, bei dem variable Teile in eckige Klammern [] eingeschlossen sind.
      // Beispiel: labelFormat: "my-classname--[local]", wobei [local] durch den Namen der Variable ersetzt wird, der das Ergebnis zugewiesen wird.
      labelFormat?: string,
      // Standard ist undefined.
      // Diese Option ermöglicht es Ihnen, dem Compiler mitzuteilen, welche Importe er
      // betrachten soll, um zu bestimmen, was er transformieren soll, sodass Sie bei erneuten Exporten
      // von Emotion-Exporten weiterhin Transformationen verwenden können.
      importMap?: {
        [packageName: string]: {
          [exportName: string]: {
            canonicalImport?: [string, string],
            styledBaseImport?: [string, string],
          }
        }
      },
    },
  },
}

Minimierung

Der SWC-Compiler von Next.js wird seit v13 standardmäßig für die Minimierung verwendet. Dies ist 7x schneller als Terser.

Falls Terser aus irgendeinem Grund noch benötigt wird, kann dies konfiguriert werden.

module.exports = {
  swcMinify: false,
}

Modultranspilierung

Next.js kann Abhängigkeiten aus lokalen Paketen (wie Monorepos) oder externen Abhängigkeiten (node_modules) automatisch transpilieren und bündeln. Dies ersetzt das Paket next-transpile-modules.

module.exports = {
  transpilePackages: ['@acme/ui', 'lodash-es'],
}

Modularisierte Imports

Diese Option wurde in Next.js 13.5 durch optimizePackageImports ersetzt. Wir empfehlen ein Upgrade, um die neue Option zu nutzen, die keine manuelle Konfiguration von Importpfaden erfordert.

Experimentelle Funktionen

SWC Trace Profiling

Sie können SWCs interne Transformations-Traces im Trace Event Format von Chromium generieren.

module.exports = {
  experimental: {
    swcTraceProfiling: true,
  },
}

Nach der Aktivierung generiert SWC Traces mit dem Namen swc-trace-profile-${timestamp}.json unter .next/. Chromiums Trace Viewer (chrome://tracing/, https://ui.perfetto.dev/) oder kompatible Flamegraph-Viewer (https://www.speedscope.app/) können die generierten Traces laden und visualisieren.

SWC Plugins (Experimentell)

Sie können die SWC-Transformation konfigurieren, um SWCs experimentelle Plugin-Unterstützung in wasm zu nutzen und das Transformationsverhalten anzupassen.

module.exports = {
  experimental: {
    swcPlugins: [
      [
        'plugin',
        {
          ...pluginOptions,
        },
      ],
    ],
  },
}

swcPlugins akzeptiert ein Array von Tupeln zur Konfiguration von Plugins. Ein Tupel für das Plugin enthält den Pfad zum Plugin und ein Objekt für die Plugin-Konfiguration. Der Pfad zum Plugin kann ein npm-Modul-Paketname oder ein absoluter Pfad zur .wasm-Binärdatei selbst sein.

Nicht unterstützte Funktionen

Wenn Ihre Anwendung eine .babelrc-Datei hat, wird Next.js automatisch auf Babel für die Transformation einzelner Dateien zurückgreifen. Dies gewährleistet Abwärtskompatibilität mit bestehenden Anwendungen, die benutzerdefinierte Babel-Plugins nutzen.

Wenn Sie ein benutzerdefiniertes Babel-Setup verwenden, teilen Sie uns bitte Ihre Konfiguration mit. Wir arbeiten daran, so viele häufig verwendete Babel-Transformationen wie möglich zu portieren sowie zukünftig Plugins zu unterstützen.

Versionsverlauf