Sebastian Gomez

Feb 21, 2022

Updated: Jun 24, 2026

Personalizando la configuración en Next.js

Next.js ofrece una facilidad enorme a la hora de modificar el comportamiento del flujo de ejecución. Por ejemplo, lo más común sería añadir variables de entorno a tu proyecto. En este artículo te mostraremos cómo hacerlo y cómo extender la funcionalidad de Next.js a través de diferentes fases y plugins.

Vigente en Next.js 16: todo lo que veremos, el archivo de configuración, las fases de compilación y el soporte de MDX, sigue plenamente vigente. Lo que cambió desde 2022 son algunos detalles: hoy se recomienda usar next.config.mjs (ESM) o next.config.ts (tipado) en lugar de next.config.js con module.exports, y Turbopack es el bundler por defecto. A lo largo del post te indico la forma moderna en cada caso.

Añadiendo variables de entorno

Aquí hay una gran simplificación respecto a 2022. Lo primero que debes saber es que ya casi nunca necesitas el archivo de configuración para esto. Desde la versión 9.4, Next.js carga automáticamente los archivos .env, así que basta con crearlos.

Crea un .env.local en la raíz de tu proyecto y añade tus variables:

# .env.local
NEXT_PUBLIC_APP_URL=https://www.sebastian-gomez.com
SECRET_API_KEY=NO_PONGAS_SECRETOS_EN_EL_CLIENTE

Tip importante: las variables que quieras usar en el navegador deben llevar el prefijo NEXT_PUBLIC_. Sin ese prefijo, la variable solo existe en el servidor y en el cliente llega como undefined. Y recuerda: nunca hagas commit de tu .env.local a GitHub, mantén tus secretos fuera del control de versiones.

Para leerlas, en cualquier página o componente basta con usar process.env:

// Esta variable lleva el prefijo NEXT_PUBLIC_, así que está disponible en el cliente
<a href={process.env.NEXT_PUBLIC_APP_URL}>Ir a la aplicación</a>

Si aun así necesitas inyectar valores en tiempo de compilación desde el archivo de configuración (por ejemplo, valores derivados), todavía existe la clave env. Funciona, pero hoy es la opción secundaria: prefiere .env.local para el caso común.

// next.config.mjs
// La clave 'env' inyecta valores en tiempo de compilación (opción secundaria; prefiere .env.local)
const nextConfig = {
  env: {
    // Establecemos la variable 'MY_ENV_VAR' con el valor 'HOLA'
    MY_ENV_VAR: "HOLA",
  },
};

export default nextConfig;

Exportando la configuración mediante una función

También podemos exportar la configuración mediante una función que recibe la fase actual de Next.js. Esto nos permite, por ejemplo, devolver una configuración distinta según el entorno:

// next.config.mjs
// Importamos la constante 'PHASE_DEVELOPMENT_SERVER' de Next.js
import { PHASE_DEVELOPMENT_SERVER } from "next/constants.js";

// Exportamos una función que recibe la fase y la configuración por defecto de Next.js
export default (phase, { defaultConfig }) => {
  // Si estamos en la fase de desarrollo, agregamos una variable de entorno
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      ...defaultConfig,
      env: {
        // En modo de desarrollo establecemos 'IS_THIS_A_FUNCTION' en 'TRUE'
        IS_THIS_A_FUNCTION: "TRUE",
      },
    };
  }

  // Si no estamos en desarrollo, devolvemos la configuración por defecto
  return defaultConfig;
};

Interviniendo fases de Next.js

Next.js trae varias constantes que nos sirven para intervenir ciertas fases, como desarrollo, producción o construcción. Un caso clásico es analizar el tamaño del bundle.

Lo importante aquí es entender que analizar el bundle es una tarea de tiempo de compilación, no de servidor. Por eso la fase correcta es PHASE_PRODUCTION_BUILD (la que corre cuando se construye el proyecto), y no PHASE_PRODUCTION_SERVER (que corre al servir, cuando el bundle ya existe).

Otra cosa clave: dentro de next.config, la clave webpack no es un objeto, es una función (config) => config que recibe la configuración, la muta y la devuelve. Asignarle un objeto plano no hace nada. Así se ve hecho correctamente:

// next.config.mjs
import { PHASE_PRODUCTION_BUILD } from "next/constants.js";
import pkg from "webpack-bundle-analyzer";
const { BundleAnalyzerPlugin } = pkg;

export default (phase, { defaultConfig }) => {
  // Solo en la fase de construcción de producción añadimos el analizador
  if (phase === PHASE_PRODUCTION_BUILD) {
    return {
      ...defaultConfig,
      // 'webpack' es una FUNCION: recibe el config, lo muta y lo devuelve
      webpack: (config) => {
        config.plugins.push(new BundleAnalyzerPlugin());
        return config;
      },
    };
  }

  return defaultConfig;
};

Tip: en la práctica, para analizar el bundle hoy lo más cómodo es usar el wrapper oficial y mantenido `@next/bundle-analyzer`, que se activa con la variable ANALYZE=true y funciona tanto con webpack como con Turbopack, sin que tengas que tocar la clave webpack a mano.

En la documentación de `next/constants` puedes ver las diferentes fases que tiene Next.js y todas sus constantes.

Extender la configuración para otros formatos de archivo

Si te preguntas cómo permitir que tus páginas no sean solo JavaScript sino también archivos markdown (.md) o markdown extendido (.mdx), Next.js ofrece el paquete @next/mdx.

Un detalle importante para 2026: como Turbopack es el bundler por defecto en Next.js 16, los remarkPlugins y rehypePlugins deben pasarse como referencias serializables (un string con el nombre del paquete, o [string, options]), no como instancias de funciones importadas. Aquí un ejemplo con createMDX:

// next.config.mjs
import createMDX from "@next/mdx";

const withMDX = createMDX({
  options: {
    // Plugins como referencias serializables (requerido bajo Turbopack)
    remarkPlugins: [["remark-gfm"], ["remark-emoji"]],
    rehypePlugins: [],
  },
});

const nextConfig = {
  // Indicamos qué extensiones deben tratarse como páginas
  pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"],
};

export default withMDX(nextConfig);

Nota: revisa qué plugins de remark/rehype necesitas realmente. El antiguo remark-images quedó esencialmente sin mantenimiento, así que aquí lo reemplazamos por remark-gfm, el más común hoy. Ajusta según tu caso.

En el siguiente post hablamos más sobre los Plugins que puedes usar en Next.js.

Conclusiones

La configuración original de Next.js puede modificarse fácilmente, y puedes extender la funcionalidad tanto como quieras.

No te sientas asustado de hacerlo: esto te permitirá sacarle mucho más provecho a Next.js. Conocer las diferentes fases y constantes te ayudará a personalizar aún más tus proyectos.

Ejercicios para practicar

1. Crea un proyecto básico de Next.js 16 y añade variables de entorno usando un archivo .env.local; expón una al cliente con NEXT_PUBLIC_ y comprueba que las demás solo existen en el servidor.
2. Interviene una fase del proyecto usando las constantes de next/constants (por ejemplo, integra @next/bundle-analyzer solo en la fase de construcción).
3. Extiende la configuración de tu proyecto para admitir archivos markdown (.md) y markdown extendido (.mdx) con @next/mdx.

Resumen en 3 puntos

1. Aprende a añadir variables de entorno a tu proyecto usando archivos .env (.env.local) y el prefijo NEXT_PUBLIC_, en lugar de la antigua clave env.
2. Descubre cómo intervenir diferentes fases de Next.js con sus constantes, recordando que webpack es una función y que analizar el bundle ocurre en PHASE_PRODUCTION_BUILD.
3. Extiende la configuración de tu proyecto para admitir otros formatos, como markdown y MDX, con createMDX.

Eso es todo, espero que este post te sea de utilidad y lo puedas aplicar a algún proyecto que tengas en mente, o que simplemente te haya ayudado a entender cómo funciona modificar la configuración de tus proyectos de Next.js.

Déjame un comentario si te sirvió, si quieres añadir alguna opinión o si tienes alguna duda, no dudes en dejarlo en la parte de abajo. Y recuerda que si te gustó, también puedes compartirlo usando los links a las redes sociales aquí abajo.