Opciones de 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.

next.config.js
// @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:

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:

next.config.mjs
// @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:

next.config.js
// @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:

next.config.js
// @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:

next.config.ts
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')

allowedDevOrigins

Utilice `allowedDevOrigins` para configurar orígenes adicionales que puedan solicitar el servidor de desarrollo.

assetPrefix

Aprenda a utilizar la opción de configuración assetPrefix para configurar su CDN.

basePath

Utilice `basePath` para implementar una aplicación Next.js en un subdirectorio de un dominio.

bundlePagesRouterDependencies

Habilita el agrupamiento automático de dependencias para Pages Router

compresión

Next.js proporciona compresión gzip para comprimir el contenido renderizado y los archivos estáticos, pero solo funciona con el objetivo de servidor. Obtenga más información al respecto aquí.

crossOrigin

Utilice la opción `crossOrigin` para agregar una etiqueta crossOrigin en las etiquetas `script` generadas por `next/script` y `next/head`.

Indicadores de desarrollo (devIndicators)

Las páginas optimizadas incluyen un indicador para mostrar si están siendo optimizadas estáticamente. Puede desactivarlo aquí.

distDir

Configura un directorio de compilación personalizado para usar en lugar del directorio `.next` predeterminado.

env

Aprenda a agregar y acceder a variables de entorno en su aplicación Next.js durante el tiempo de compilación.

eslint

Por defecto, Next.js reporta errores y advertencias de ESLint durante las compilaciones. Aprende cómo desactivar este comportamiento aquí.

exportPathMap

Personaliza las páginas que se exportarán como archivos HTML al usar `next export`.

generateBuildId

Configura el ID de compilación, que se utiliza para identificar la compilación actual en la que se sirve tu aplicación.

generateEtags

Next.js generará etags para cada página de forma predeterminada. Aprenda cómo desactivar la generación de etags aquí.

headers

Agregue encabezados HTTP personalizados a su aplicación Next.js.

httpAgentOptions

Next.js utiliza automáticamente HTTP Keep-Alive de forma predeterminada. Aprenda cómo deshabilitar HTTP Keep-Alive aquí.

imágenes

Configuración personalizada para el cargador de next/image

onDemandEntries

Configura cómo Next.js eliminará y mantendrá en memoria las páginas creadas durante el desarrollo.

optimizePackageImports

Referencia de la API para la opción de configuración optimizePackageImports en Next.js

output

Next.js rastrea automáticamente los archivos necesarios para cada página, lo que facilita la implementación de tu aplicación. Aprende cómo funciona aquí.

pageExtensions

Extiende las extensiones de página predeterminadas que utiliza Next.js al resolver páginas en el Enrutador de Páginas (Pages Router).

poweredByHeader

Next.js añade el encabezado `x-powered-by` por defecto. Aprende cómo desactivarlo aquí.

productionBrowserSourceMaps

Habilita la generación de mapas de origen (source maps) del navegador durante la compilación de producción.

reactStrictMode

El runtime completo de Next.js ahora cumple con el Modo Estricto (Strict Mode), aprenda cómo activarlo

Redirecciones

Agregue redirecciones a su aplicación Next.js.

reescrituras (rewrites)

Agregue reescrituras (rewrites) a su aplicación Next.js.

Configuración en Tiempo de Ejecución (Runtime Config)

Agregue configuración en tiempo de ejecución para cliente y servidor a su aplicación Next.js.

serverExternalPackages

Excluir dependencias específicas del empaquetado habilitado por `bundlePagesRouterDependencies`.

trailingSlash

Configuración de páginas en Next.js para resolver con o sin barra diagonal al final.

transpilePackages

Transpila y empaqueta automáticamente dependencias de paquetes locales (como monorepos) o de dependencias externas (`node_modules`).

turbo

Configura Next.js con opciones específicas de Turbopack

TypeScript

Next.js reporta errores de TypeScript por defecto. Aprende cómo desactivar este comportamiento aquí.

urlImports

Configura Next.js para permitir la importación de módulos desde URLs externas.

useLightlightningcss

Habilita el soporte experimental para Lightning CSS.

webpack

Aprende cómo personalizar la configuración de webpack utilizada por Next.js

webVitalsAttribution

Aprenda a utilizar la opción webVitalsAttribution para identificar el origen de problemas con las métricas Web Vitals.