next.config.js

Next.js se puede configurar mediante un archivo next.config.js en la raíz de su directorio de proyecto (por ejemplo, junto a package.json) con una exportación por defecto.

// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* opciones de configuración aquí */
}

module.exports = nextConfig

Módulos ECMAScript

next.config.js es un módulo normal de Node.js, no un archivo JSON. Es utilizado por el servidor y las fases de construcción de Next.js, y no se incluye en el build del navegador.

Si necesita módulos ECMAScript, puede usar next.config.mjs:

// @ts-check

/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  /* opciones de configuración aquí */
}

export default nextConfig

Es bueno saber: Actualmente no se admiten archivos next.config con extensiones .cjs, .cts o .mts.

Configuración como Función

También puede usar una función:

// @ts-check

export default (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* opciones de configuración aquí */
  }
  return nextConfig
}

Configuración Asíncrona

Desde Next.js 12.1.0, puede usar una función asíncrona:

// @ts-check

module.exports = async (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* opciones de configuración aquí */
  }
  return nextConfig
}

Fase

phase es el contexto actual en el que se carga la configuración. Puede ver las fases disponibles. Las fases se pueden importar desde next/constants:

// @ts-check

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

module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* opciones de configuración solo para desarrollo aquí */
    }
  }

  return {
    /* opciones de configuración para todas las fases excepto desarrollo aquí */
  }
}

TypeScript

Si está usando TypeScript en su proyecto, puede usar next.config.ts para utilizar TypeScript en su configuración:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* opciones de configuración aquí */
}

export default nextConfig

Las líneas comentadas son el lugar donde puede colocar las configuraciones permitidas por next.config.js, que están definidas en este archivo.

Sin embargo, ninguna de las configuraciones es obligatoria, y no es necesario entender qué hace cada una. En su lugar, busque las características que necesita habilitar o modificar en esta sección y le mostrarán qué hacer.

Evite usar nuevas características de JavaScript que no estén disponibles en su versión objetivo de Node.js. next.config.js no será analizado por Webpack o Babel.

Esta página documenta todas las opciones de configuración disponibles:

Pruebas Unitarias (experimental)

A partir de Next.js 15.1, el paquete next/experimental/testing/server contiene utilidades para ayudar a realizar pruebas unitarias en archivos next.config.js.

La función unstable_getResponseFromNextConfig ejecuta las funciones headers, redirects y rewrites de next.config.js con la información de solicitud proporcionada y devuelve NextResponse con los resultados del enrutamiento.

La respuesta de unstable_getResponseFromNextConfig solo considera campos de next.config.js y no tiene en cuenta middleware o rutas del sistema de archivos, por lo que el resultado en producción puede ser diferente al de la prueba unitaria.

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