next.config.js

Next.js kann über eine next.config.js-Datei im Stammverzeichnis Ihres Projekts (zum Beispiel neben package.json) mit einem Standard-Export konfiguriert werden.

// @ts-check

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

module.exports = nextConfig

ECMAScript-Module

next.config.js ist ein reguläres Node.js-Modul, keine JSON-Datei. Es wird von der Next.js-Server- und Build-Phase verwendet und ist nicht im Browser-Build enthalten.

Falls Sie ECMAScript-Module benötigen, können Sie next.config.mjs verwenden:

// @ts-check

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

export default nextConfig

Gut zu wissen: next.config mit den Erweiterungen .cjs, .cts oder .mts werden derzeit nicht unterstützt.

Konfiguration als Funktion

Sie können auch eine Funktion verwenden:

// @ts-check

export default (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* Konfigurationsoptionen hier */
  }
  return nextConfig
}

Asynchrone Konfiguration

Seit Next.js 12.1.0 können Sie eine asynchrone Funktion verwenden:

// @ts-check

module.exports = async (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* Konfigurationsoptionen hier */
  }
  return nextConfig
}

Phase

phase ist der aktuelle Kontext, in dem die Konfiguration geladen wird. Sie können die verfügbaren Phasen einsehen. Phasen können aus next/constants importiert werden:

// @ts-check

const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')

module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* Nur für die Entwicklung gültige Konfigurationsoptionen hier */
    }
  }

  return {
    /* Konfigurationsoptionen für alle Phasen außer Entwicklung hier */
  }
}

TypeScript

Wenn Sie TypeScript in Ihrem Projekt verwenden, können Sie next.config.ts nutzen, um TypeScript in Ihrer Konfiguration zu verwenden:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* Konfigurationsoptionen hier */
}

export default nextConfig

Die kommentierten Zeilen sind der Platz, an dem Sie die von next.config.js erlaubten Konfigurationen einfügen können, die in dieser Datei definiert sind.

Allerdings ist keine der Konfigurationen erforderlich, und es ist nicht notwendig zu verstehen, was jede Konfiguration bewirkt. Stattdessen können Sie nach den Funktionen suchen, die Sie aktivieren oder ändern möchten, und diese Abschnitte zeigen Ihnen, was zu tun ist.

Vermeiden Sie die Verwendung neuer JavaScript-Funktionen, die in Ihrer Ziel-Node.js-Version nicht verfügbar sind. next.config.js wird nicht von Webpack oder Babel geparsed.

Diese Seite dokumentiert alle verfügbaren Konfigurationsoptionen:

Unit-Tests (experimentell)

Ab Next.js 15.1 enthält das Paket next/experimental/testing/server Hilfsmittel, um Unit-Tests für next.config.js-Dateien durchzuführen.

Die Funktion unstable_getResponseFromNextConfig führt die Funktionen headers, redirects und rewrites aus next.config.js mit den bereitgestellten Anfrageinformationen aus und gibt eine NextResponse mit den Ergebnissen des Routings zurück.

Die Antwort von unstable_getResponseFromNextConfig berücksichtigt nur die Felder von next.config.js und beachtet weder Middleware noch Dateisystemrouten, sodass das Ergebnis in der Produktion anders ausfallen kann als im Unit-Test.

import {
  getRedirectUrl,
  unstable_getResponseFromNextConfig,
} from 'next/experimental/testing/server'

const response = await unstable_getResponseFromNextConfig({
  url: 'https://nextjs.org/test',
  nextConfig: {
    async redirects() {
      return [{ source: '/test', destination: '/test2', permanent: false }]
    },
  },
})
expect(response.status).toEqual(307)
expect(getRedirectUrl(response)).toEqual('https://nextjs.org/test2')