Domina next.config.js y variables de entorno en Next.js 15: Configuración esencial

Guía Definitiva: Configuración de next.config.js en Next.js

El archivo next.config.ts es el centro de control de cualquier aplicación Next.js 15. Este archivo de configuración, ahora con mejor soporte para TypeScript, te permite personalizar el framework para tus necesidades específicas.

¿Qué es next.config.js / next.config.ts?

next.config es un archivo que no es parseado por Webpack/Babel como el código de tu app, se ejecuta en el entorno de Node.js durante la fase de build y al iniciar el servidor de desarrollo y permite personalizar el comportamiento por defecto de Next.js.

• Si usas TypeScript, puedes nombrarlo next.config.ts para tener autocompletado y chequeo de tipos.
• Importante: Cada vez que modificas next.config.js o next.config.ts, debes reiniciar el servidor de desarrollo (npm run dev, yarn dev) para que los cambios surtan efecto.

Formato Básico (TypeScript):

// Importación del tipo NextConfig para autocompletado y validación
import type { NextConfig } from 'next'

/**
 * Configuración principal de Next.js
 * @type {NextConfig}
 */
const nextConfig: NextConfig = {
  // ... tus configuraciones aquí
}

export default nextConfig

Configuraciones Principales next.config.js / next.config.ts

env (Variables de Entorno)

• Propósito: Permite definir variables de entorno que estarán disponibles durante el proceso de build, estas variables se incrustan en el código JavaScript final.
• Uso: Son útiles para configurar valores que no cambian después del build, como identificadores de servicios o configuraciones específicas del entorno de build.
• Para variables que necesiten estar disponibles también en el lado del cliente (navegador), deben tener el prefijo NEXT_PUBLIC_ y definirse en archivos .env o en el entorno del sistema, no necesariamente aquí (aunque puedes mapearlas si quieres). Variables sin ese prefijo solo están disponibles en el servidor (Node.js).

const nextConfig: NextConfig = {
  env: {
    CUSTOM_VAR: 'mi-valor-personalizado', // Solo disponible en Node.js (build/server)
    // NEXT_PUBLIC_API_ENDPOINT se definiría mejor en .env.local
  },
};

basePath (Ruta Base)

• Propósito: Permite desplegar tu aplicación Next.js bajo un subdirectorio en tu dominio (ej: midominio.com/mi-app/).
• Uso: Útil cuando alojas múltiples aplicaciones en el mismo dominio. Todos los enlaces (<Link>, router.push) y assets se servirán relativos a esta ruta base.

const nextConfig: NextConfig = {
  basePath: '/ewebik',
};
// Ahora tu app vive por ejemplo en ewebik.com/ewebik

reactStrictMode (Modo Estricto de React)

• Propósito: Habilita el StrictMode de React, que ayuda a identificar potenciales problemas en la aplicación ejecutando ciertas comprobaciones y advertencias en desarrollo.
• Uso: Recomendado para detectar prácticas inseguras, efectos secundarios inesperados y APIs obsoletas. Viene habilitado (true) por defecto en nuevas apps Next.js.

const nextConfig: NextConfig = {
  reactStrictMode: true, // Valor por defecto
};

images (Optimización de Imágenes)

• Propósito: Configura el componente next/image y la optimización automática de imágenes de Next.js.
• Uso: Para definir desde qué dominios externos se pueden cargar y optimizar imágenes, especificar tamaños de dispositivo, formatos de imagen permitidos, etc.

const nextConfig: NextConfig = {
  images: {
    // Dominios externos permitidos (¡Necesario para <Image> con src externo!)
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'images.ewebik.com',
        port: '',
        pathname: '/**', // Permite cualquier path dentro de ese hostname
      },
      {
        protocol: 'https',
        hostname: 'cdn.ewebik.com',
      }
    ],
    // domains: ['images.unsplash.com', 'cdn.example.com'], // Forma anterior, ahora se prefiere remotePatterns
    // Tamaños de imagen a generar
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
    formats: ['image/avif', 'image/webp'], // Formatos a intentar servir (además del original)
  },
};

headers (Cabeceras HTTP Personalizadas)

• Propósito: Permite añadir cabeceras HTTP personalizadas a las rutas especificadas.
• Uso: Para configurar políticas de seguridad (CSP, HSTS, X-Frame-Options), CORS, cabeceras de caché personalizadas.

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)', // Aplicar a todas las rutas
        headers: [
          {
            key: 'X-Frame-Options', //se utiliza para controlar si una página web puede ser renderizada dentro de un marco (iframe), <frame>, <embed> o <object>
            value: 'SAMEORIGIN', //Permite la incrustación de la página solo dentro de su propio dominio. 
          },
          {
            key: 'Content-Security-Policy', //ayuda a prevenir o minimizar el riesgo de ciertos tipos de amenazas a la seguridad.
            value: "default-src 'self'; img-src 'self' data: https://images.unsplash.com;",
          },
          {
            key: 'X-Content-Type-Options', //util para evitar que los navegadores web realicen un "rastreo de MIME o rastreo de tipos de contenidos" (MIME sniffing) 
            value: 'nosniff', //indica que el navegador no debe realizar el rastreo MIME
          },
        ],
      },
      {
         source: '/api/(.*)', // Cabeceras específicas para la API
         headers: [
            { key: 'Access-Control-Allow-Origin', value: '*' }, // se utiliza en las respuestas HTTP para indicar qué origen (dominio, protocolo y puerto) puede acceder a los recursos de un servidor
         ]
      }
    ];
  },
};

output (Modo de Salida)

• Propósito: Controla cómo se genera la salida de la compilación (next build).
• Uso:
  • standalone: Genera una carpeta standalone con solo los archivos necesarios para desplegar (incluyendo node_modules mínimos), ideal para contenedores Docker optimizados.
  • export: Genera una salida HTML/CSS/JS estática (como next export anteriormente). Requiere que no uses funcionalidades dinámicas del servidor (como getServerSideProps en modo Node.js).

const nextConfig: NextConfig = {
  output: 'standalone',
};

Configuración de Redirecciones en next.config.ts

Next.js permite configurar redirecciones directamente en el archivo de configuración. Aquí te muestro cómo implementarlas correctamente:

redirects (Redirecciones)

• Propósito: Permite definir redirecciones del lado del servidor, util para redirigir rutas antiguas a nuevas, imponer HTTPS o www, etc.
• Uso: SEO, cambios de estructura del sitio, mantenimiento de enlaces se ejecutan antes de comprobar el sistema de archivos o las páginas dinámicas.

const nextConfig: NextConfig = {
  async redirects() {
    return [
      {
        source: '/antigua-pagina', // La ruta entrante
        destination: '/nueva-pagina', // La ruta a la que se redirige
        permanent: true, // true = 308 (permanente), false = 307 (temporal)
      },
      {
        // Redirección con parámetros
        source: '/blog/:slug/viejo',
        destination: '/articulos/:slug',
        permanent: true,
      },
      {
        // Condicional (ej: solo redirigir si hay una cookie específica)
        source: '/privado',
        has: [
          {
            type: 'cookie',
            key: 'NoAutenticado',
          },
        ],
        destination: '/login',
        permanent: false,
      },
    ];
  },
};

Recuerda que debes considerar

• Usar permanent: true para cambios definitivos (mejor para SEO)
• Prueba todas las redirecciones en entorno de desarrollo
• Documenta cada redirección con comentarios
• Combina con otros headers de seguridad

Variables de Entorno en Next.js 15

Gestionar correctamente las variables de entorno en Next.js 15 es fundamental para desarrollar aplicaciones seguras y fáciles de configurar. Este sistema te permite manejar diferentes configuraciones entre entornos de desarrollo y producción sin comprometer información sensible.

Tipos de Variables de Entorno

Next.js 15 clasifica las variables en dos grupos principales:

// .env.local
NEXT_PUBLIC_API_URL=https://api.midominio.com  # Accesible en cliente
DATABASE_PASSWORD=supersecret123               # Solo en servidor

• Variables públicas: Prefijadas con NEXT_PUBLIC_ (accesibles en cliente)
• Variables privadas: Sin prefijo (solo disponibles en el servidor)

Configuración Básica

Crea tus archivos .env según cada entorno:

# Estructura recomendada
.env.local          	  # Valores locales (ignorado por git)
.env.development.local    # Desarrollo
.env.test.local           # Testing 
.env.production.local     # Producción

Uso en la Aplicación

Variables Públicas

// Acceso directo en componentes
export function ApiComponent() {
  return (
    <div>
      <p>Endpoint API: {process.env.NEXT_PUBLIC_API_URL}</p>
    </div>
  )
}

Variables Privadas

// Solo accesible en Server Components, API Routes o getServerSideProps
export async function getServerSideProps() {
  const dbPassword = process.env.DATABASE_PASSWORD
  
  return {
    props: { 
      data: await fetchData(dbPassword) 
    }
  }
}

Configuración Avanzada

Validación de Variables

// lib/env.ts
import { z } from 'zod'

const envSchema = z.object({
  NEXT_PUBLIC_API_URL: z.string().url(),
  DATABASE_PASSWORD: z.string().min(8),
})

export const env = envSchema.parse(process.env)

Ejercicio Práctico

Revisemos como podemos definir nuestras variables de entorno publicas y privadas para que solo sean accedidas desde el servidor.

Definición de variables de enotrno

// .env.local
NEXT_PUBLIC_API_URL=http://localhost:3000            # URL de nuestra API accesible en cliente
DATABASE_USER=userdb                      	         # Usuario DB, accesible solo en servidor
DATABASE_PASSWORD=supersecret123               	     # Contraseña DB, accesible solo en servidor

Accedemos a nuestra variable de entorno desde el navegador del usuario

Desde el usuario hacemos un fetch a nuestra API pero la URL de la API la obtenemos de nuestra variable de entorno:

// app/blog/page.tsx

import Link from "next/link";

interface Posts {
  id: string;
  title: string;
  slug: string;
  createdAt: string;
}

export default async function BlogPage() {
  const posts: Posts[] = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/posts`, {
    next: { tags: ["posts"], revalidate: 3600 },
  }).then((res) => res.json());

  return (
    <div className="max-w-4xl mx-auto py-8">
      <h1 className="text-3xl font-bold mb-8">Blog</h1>
      <div className="grid gap-8">
        {posts.map((post) => (
          <article key={post.id} className="border-b pb-6">
            <h2 className="text-2xl font-semibold">{post.title}</h2>
            <p className="text-gray-600 mt-2">{post.createdAt}</p>
            <Link href={post.slug} className="text-xl font-bold text-red-400">
              Ver mas
            </Link>
          </article>
        ))}
      </div>
    </div>
  );
}

Acceder a variables de entorno de lado del servidor

Ahora, en nuestra API recibimos el request y consultamos el usuario contraseña de nuestra base de datos desde nuestras variables de entorno.

// app/api/posts/route.ts
import { NextResponse } from "next/server";
//import db from "@/lib/db";

export async function GET() {
  try {
    
    const posts = await db.post.findMany({
      select: {
        id: true,
        title: true,
        slug: true,
        createdAt: true,
      },
      orderBy: { createdAt: "desc" },
      db:{
       user: process.env.DATABASE_USER,
       password: process.env.DATABASE_PASSWORD
      }
    });
    return NextResponse.json(posts);
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to fetch posts" },
      { status: 500 }
    );
  }
}

Recuerda siempre

• Nunca commits archivos .env: Añádelos a .gitignore
• Usa diferentes archivos para cada entorno
• Valida tus variables al iniciar la aplicación
• Minimiza las variables públicas por seguridad
• Documenta todas las variables necesarias en un .env.example

7. Solución de Problemas

Si las variables no se cargan:

# Verifica que estás usando el archivo correcto
echo $NODE_ENV

# Reinicia el servidor después de cambios
npm run dev

Dominar la gestión de variables de entorno en Next.js 15 te permitirá construir aplicaciones más seguras, fáciles de configurar y preparadas para despliegues en múltiples entornos.