next.config.js

Next.js можно настроить через файл next.config.js в корневой директории вашего проекта (например, рядом с package.json) с помощью экспорта по умолчанию.

// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* здесь указываются параметры конфигурации */
}

module.exports = nextConfig

Модули ECMAScript

next.config.js — это обычный модуль Node.js, а не JSON-файл. Он используется сервером Next.js на этапах сборки и разработки и не включается в сборку для браузера.

Если вам нужны модули ECMAScript, вы можете использовать next.config.mjs:

// @ts-check

/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  /* здесь указываются параметры конфигурации */
}

export default nextConfig

Важно знать: расширения .cjs, .cts или .mts для next.config в настоящее время не поддерживаются.

Конфигурация как функция

Вы также можете использовать функцию:

// @ts-check

export default (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* здесь указываются параметры конфигурации */
  }
  return nextConfig
}

Асинхронная конфигурация

Начиная с Next.js 12.1.0, можно использовать асинхронную функцию:

// @ts-check

module.exports = async (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* здесь указываются параметры конфигурации */
  }
  return nextConfig
}

Фаза (phase)

phase — это текущий контекст, в котором загружается конфигурация. Вы можете увидеть доступные фазы. Фазы можно импортировать из next/constants:

// @ts-check

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

module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* здесь указываются параметры конфигурации только для разработки */
    }
  }

  return {
    /* здесь указываются параметры конфигурации для всех фаз, кроме разработки */
  }
}

TypeScript

Если вы используете TypeScript в своем проекте, вы можете использовать next.config.ts для работы с TypeScript в конфигурации:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* здесь указываются параметры конфигурации */
}

export default nextConfig

Закомментированные строки — это место, где вы можете указать параметры, разрешенные в next.config.js, которые определены в этом файле.

Однако ни один из параметров не является обязательным, и нет необходимости понимать, что делает каждый из них. Вместо этого найдите функции, которые вам нужно включить или изменить, в этом разделе, и они покажут вам, что делать.

Избегайте использования новых функций JavaScript, недоступных в вашей целевой версии Node.js. next.config.js не будет обрабатываться Webpack или Babel.

На этой странице документированы все доступные параметры конфигурации:

Юнит-тестирование (экспериментальное)

Начиная с Next.js 15.1, пакет next/experimental/testing/server содержит утилиты для юнит-тестирования файлов next.config.js.

Функция unstable_getResponseFromNextConfig запускает функции headers, redirects и rewrites из next.config.js с предоставленной информацией о запросе и возвращает NextResponse с результатами маршрутизации.

Ответ от unstable_getResponseFromNextConfig учитывает только поля next.config.js и не учитывает middleware или маршруты файловой системы, поэтому результат в продакшене может отличаться от юнит-теста.

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')