next.config.js

Next.js peut être configuré via un fichier next.config.js à la racine de votre répertoire de projet (par exemple, à côté de package.json) avec un export par défaut.

// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* options de configuration ici */
}

module.exports = nextConfig

Modules ECMAScript

next.config.js est un module Node.js standard, pas un fichier JSON. Il est utilisé par le serveur Next.js et les phases de build, et n'est pas inclus dans le build navigateur.

Si vous avez besoin de modules ECMAScript, vous pouvez utiliser next.config.mjs :

// @ts-check

/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  /* options de configuration ici */
}

export default nextConfig

Bon à savoir : les extensions .cjs, .cts ou .mts pour next.config ne sont pas supportées actuellement.

Configuration sous forme de fonction

Vous pouvez également utiliser une fonction :

// @ts-check

export default (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* options de configuration ici */
  }
  return nextConfig
}

Configuration asynchrone

Depuis Next.js 12.1.0, vous pouvez utiliser une fonction asynchrone :

// @ts-check

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

Phase

phase est le contexte actuel dans lequel la configuration est chargée. Vous pouvez voir les phases disponibles. Les phases peuvent être importées depuis next/constants :

// @ts-check

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

module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* options de configuration spécifiques au développement ici */
    }
  }

  return {
    /* options de configuration pour toutes les phases sauf le développement ici */
  }
}

TypeScript

Si vous utilisez TypeScript dans votre projet, vous pouvez utiliser next.config.ts pour utiliser TypeScript dans votre configuration :

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* options de configuration ici */
}

export default nextConfig

Les lignes commentées sont l'endroit où vous pouvez placer les configurations autorisées par next.config.js, qui sont définies dans ce fichier.

Cependant, aucune de ces configurations n'est obligatoire, et il n'est pas nécessaire de comprendre ce que fait chaque configuration. Cherchez plutôt les fonctionnalités que vous souhaitez activer ou modifier dans cette section et elles vous indiqueront quoi faire.

Évitez d'utiliser de nouvelles fonctionnalités JavaScript non disponibles dans votre version cible de Node.js. next.config.js ne sera pas parsé par Webpack ou Babel.

Cette page documente toutes les options de configuration disponibles :

Tests unitaires (expérimental)

Depuis Next.js 15.1, le package next/experimental/testing/server contient des utilitaires pour aider à tester unitairement les fichiers next.config.js.

La fonction unstable_getResponseFromNextConfig exécute les fonctions headers, redirects et rewrites de next.config.js avec les informations de requête fournies et renvoie un NextResponse avec les résultats du routage.

La réponse de unstable_getResponseFromNextConfig ne prend en compte que les champs de next.config.js et ne considère pas le middleware ou les routes du système de fichiers, donc le résultat en production peut différer du test unitaire.

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