Lo que el 90% de Devs Hace Mal al Conectar Next.js, Node.js y Git

Y varios de esos devs hicieron push a producción. Esa es la parte que asusta.

Hay una historia que no puedo sacarme de la cabeza. Un desarrollador junior — chico inteligente, portafolio decente — construyó una app full-stack para su cliente freelance. Frontend Next.js, backend Node.js, todo cableado. Hizo push a GitHub. El competidor del cliente encontró el repo tres semanas después porque era público y el archivo .env estaba ahí, intacto. Contraseña de base de datos. Secret keys de Stripe. Todo.

Ese proyecto no fue solo una falla técnica. Fue una falla de confianza.

Y aquí viene lo brutal: no fue un error estúpido de una persona incompetente. Fue un error normal de un desarrollador que nunca aprendió la mecánica real de conectar estas tres herramientas. Sabía programar. No sabía cómo se enlazan.

La mayoría de desarrolladores están en ese mismo barco en 2026, y ninguno lo admitiría.

Por qué este stack es tan dominante (y por qué eso crea un problema)

Next.js, Node.js y Git. Este es prácticamente el stack por defecto de desarrollo web para una porción enorme del internet. Next.js superó los 6 millones de descargas semanales en npm a finales de 2024 y se ha mantenido en ese rango hasta 2026. Node.js impulsa aproximadamente el 6.3% de todos los sitios web directamente y una porción mucho mayor indirectamente a través de frameworks server-rendered. Git lo usa el 97.8% de los desarrolladores profesionales según la Stack Overflow Developer Survey 2025.

Tienes tres herramientas masivamente dominantes que se espera que todo desarrollador simplemente… sepa. Y como todo el mundo asume que los demás ya lo saben, nadie enseña realmente cómo interactúan entre sí.

La documentación las cubre por separado. Los tutoriales las cubren en aislamiento. Y luego un desarrollador tiene que conectarlas en un proyecto real y de repente nada tiene sentido.

Este es ese artículo. El que nadie quería escribir porque es admitir que el ecosistema tiene huecos de los que nadie habla.

Los errores reales (y qué tan graves pueden ser)

Voy a recorrerlos con honestidad. No en orden de frecuencia sino en orden de cuánto te pueden destruir.

1. Tu archivo .env probablemente ya está en GitHub

Lo voy a decir lo más directo posible.

Si iniciaste un proyecto Next.js o Node.js en los últimos tres años y no configuraste .gitignore antes de tu primer git init o git add ., hay una probabilidad real de que tus secretos estén en el historial de tu repositorio. Incluso si borraste el archivo después. Git no funciona como un sistema de archivos normal. Recuerda.

El equipo de seguridad de GitHub reportó que solo en 2024 se expusieron más de 12.8 millones de secretos en repositorios públicos. API keys, credenciales de bases de datos, tokens, llaves privadas. La cifra en 2025 no fue menor.

Y la cosa es que .env está listado en el .gitignore por defecto que genera create-next-app. Entonces, ¿por qué sigue pasando?

Porque los desarrolladores clonan repos starter. Arman setups personalizados. Copian estructuras de carpetas de tutoriales de YouTube de hace seis meses que nunca muestran la configuración del .gitignore. Ejecutan git add . por costumbre.

Así se ve un .gitignore correcto para un proyecto Next.js + Node.js:

# Node
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.pnpm-debug.log*

# Next.js
.next/
out/
build/
dist/

# Variables de entorno — ESTA ES LA CLAVE
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
.env*.local

# Vercel
.vercel

# TypeScript
*.tsbuildinfo
next-env.d.ts

# OS
.DS_Store
*.pem
Thumbs.db

# Debug
.npm
.eslintcache

Y si ya subiste secretos, esta es la verdad dolorosa: borrar el archivo y hacer push de nuevo NO lo elimina del historial. Necesitas hacer esto:

# Instalar git-filter-repo (mejor que BFG para 2025+)
pip install git-filter-repo

# Eliminar .env de todo el historial
git filter-repo --path .env --invert-paths

# Luego force push (necesitarás coordinar con tu equipo)
git push origin --force --all

Pero honestamente, ¿si el secreto estuvo expuesto más de unas horas? Rota las credenciales. Asume que fueron tomadas. Esa es la respuesta real.

2. La trampa de NEXT_PUBLIC_ que nadie explica bien

Esta es sutil y atrapa incluso a desarrolladores con experiencia.

Next.js tiene dos entornos: servidor y cliente. Las variables de entorno funcionan distinto en cada uno. Las variables que empiezan con NEXT_PUBLIC_ se empaquetan en el JavaScript del lado del cliente. Todo lo demás se queda en el servidor.

Suena simple. Pero aquí es donde la gente se equivoca.

// Esto se ejecuta en el SERVIDOR (API route, Server Component)
// Funciona bien
const dbPassword = process.env.DB_PASSWORD;

// Esto se ejecuta en el CLIENTE (navegador)
// process.env.DB_PASSWORD es undefined aquí
// porque no tiene el prefijo NEXT_PUBLIC_
const something = process.env.DB_PASSWORD; // undefined, sin error, solo silenciosamente roto

La parte aterradora no es el error. Es el silencio. En muchos casos no tendrás un crash. Solo obtendrás undefined y luego una falla críptica más adelante que te tomará una hora debuggear.

Y el error opuesto es todavía peor:

// NO HAGAS ESTO
// Esto expone tu secreto al navegador de cada usuario
NEXT_PUBLIC_DB_PASSWORD=supersecret123
NEXT_PUBLIC_STRIPE_SECRET_KEY=sk_live_...

Cualquier cosa con NEXT_PUBLIC_ es visible para cualquiera que abra tu sitio. Se incrusta en el bundle de JavaScript. DevTools. View Source. Todo está ahí.

Tipo de Variable	Accesible En	¿Expuesta al navegador?	Usar Para
`NEXT_PUBLIC_*`	Cliente + Servidor	SÍ	URLs base de API, llaves públicas, IDs de analytics
`ENV_VAR` normal	Solo servidor	NO	Contraseñas de BD, secret keys, tokens
`process.env.NODE_ENV`	Ambos	NO (built-in)	Detección de entorno

La regla es simple: si es un secreto, nunca lleva NEXT_PUBLIC_. Si tiene que estar en el cliente, mejor que no sea un secreto.

3. CORS no es un bug. Eres tú.

Tienes Next.js corriendo en el puerto 3000. Tu backend Node.js/Express en el puerto 3001. Haces una petición fetch. Error de CORS. Buscas en Google. Encuentras una respuesta de Stack Overflow de 2019 que te dice que hagas esto:

// El "fix" perezoso que todos copian
app.use(cors());

Y funciona localmente. Así que haces push a producción.

Y luego en producción se rompe de nuevo porque el origin es diferente, o peor: funciona pero ahora le has permitido a cada origin del planeta hacer peticiones a tu backend. Incluyendo gente que no quieres.

Así se ve una configuración de CORS correcta para un setup Next.js + Node.js:

// Backend Express - cors.config.js
const allowedOrigins = [
  'http://localhost:3000',
  'https://tu-dominio-real.com',
  process.env.FRONTEND_URL // dinámico, configurado en .env
].filter(Boolean);

app.use(cors({
  origin: function(origin, callback) {
    // Permitir peticiones sin origin (apps móviles, Postman, curl)
    if (!origin) return callback(null, true);

    if (allowedOrigins.indexOf(origin) === -1) {
      const msg = 'Política CORS bloqueó este origin: ' + origin;
      return callback(new Error(msg), false);
    }
    return callback(null, true);
  },
  credentials: true, // si usas cookies/sessions
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization'],
}));

Y honestamente, ¿si ya estás usando Next.js, pregúntate si necesitas un servidor Express separado. Las API routes de Next.js manejan una cantidad enorme de lógica de backend sin este lío de CORS.

4. No sabes cuándo usar API Routes vs Express

Esta es la confusión arquitectónica que le cuesta semanas a los equipos.

Next.js tiene API routes incorporadas (en pages/api/ o app/api/route.ts). Corren sobre Node.js. Son serverless por defecto cuando se despliegan en Vercel. Funcionan bien para la mayoría de las cosas.

Pero muchos desarrolladores:

a) Construyen un servidor Express completo para cosas que las API routes de Next.js manejarían perfectamente, creando complejidad innecesaria y problemas de CORS.

b) Meten todo en API routes de Next.js cuando realmente necesitan conexiones persistentes, WebSockets, trabajos pesados en background o algo que Vercel no soporta bien.

Esta es la comparación honesta:

Caso de Uso	API Routes de Next.js	Node.js/Express separado
CRUD para los datos de tu app	Perfecto	Exagerado
Autenticación (JWT, sesiones)	Bien	Complejidad innecesaria
Tiempo real (WebSockets)	No soportado nativamente	Requerido
Procesamiento pesado de archivos	Cold starts son un problema	Mejor
API compartida entre múltiples frontends	Incómodo	La opción correcta
Arquitectura de microservicios	Herramienta equivocada	Herramienta correcta
Background jobs / cron	Limitado (Vercel Cron tiene límites)	Mejor
Procesos de larga duración	Límites duros de timeout	Requerido
Pool de conexiones de BD a escala	Funciona pero es delicado	Más control

Si estás construyendo una app web estándar con base de datos, auth y CRUD — usa las API routes de Next.js. No necesitas Express. Estás agregando complejidad sin razón.

Si estás construyendo algo que necesita conexiones persistentes, sirve a múltiples clientes, ejecuta trabajos pesados en background o vive en un VPS que controlas — un servidor Node.js separado tiene sentido.

La mayoría de desarrolladores que he visto eligen el incorrecto porque aprendieron Express primero y no lo pueden soltar.

5. URLs hardcodeadas que mueren en producción

Esta es tan común que es casi un rito de iniciación.

// Funciona en tu laptop, se rompe en todos lados
const response = await fetch('http://localhost:3001/api/users');

Esto está hardcodeado a localhost. Cuando despliegas en Vercel o cualquier servidor, localhost:3001 no significa nada. No hay una máquina llamada localhost en producción. La petición no va a ningún lado.

La solución no es complicada. Pero tienes que implementarla.

// En .env.local (para desarrollo)
NEXT_PUBLIC_API_BASE_URL=http://localhost:3001

// En .env.production
NEXT_PUBLIC_API_BASE_URL=https://api.tudominio.com

// En tu código
const API_BASE = process.env.NEXT_PUBLIC_API_BASE_URL;

const response = await fetch(`${API_BASE}/api/users`);

Y si estás usando las API routes de Next.js como tu backend (misma app), ni siquiera necesitas una URL absoluta:

// Esto funciona tanto en dev como en producción cuando backend = misma app Next.js
const response = await fetch('/api/users');

URLs relativas. Infravaloradas. La gente sobrecomplica esto.

6. El workflow de Git para proyectos full-stack es diferente y nadie habla de eso

En un proyecto típico de una sola tecnología, el workflow de Git es directo. Rama de feature, PR, merge. Pero en un proyecto Next.js + Node.js donde el frontend y backend a veces están en el mismo repo y a veces en repos diferentes, las cosas se complican rápido.

Los dos patrones principales:

Monorepo (mismo repo, ambas apps)

mi-proyecto/
  ├── apps/
  │   ├── web/          (Next.js)
  │   └── api/          (Express.js)
  ├── packages/
  │   └── shared/       (tipos y utilidades compartidas)
  └── package.json      (raíz, con workspaces)

Polyrepo (repos separados)

mi-proyecto-frontend/    (Next.js)
mi-proyecto-backend/     (Express.js)

El error que la mayoría de desarrolladores junior comete es ninguno de los anteriores. Ponen todo en una carpeta plana y commitean todo junto, así que un cambio de frontend y uno de backend siempre quedan enredados en el mismo commit. Hace el code review un desastre. Hace los rollbacks una pesadilla.

Y luego está el branching. Esto es lo que realmente funciona para full-stack:

# Nunca commits directos a main
git checkout -b feature/autenticacion-usuarios

# Commits frecuentes con mensajes significativos
# Mal mensaje de commit:
git commit -m "arreglar cosas"

# Buen mensaje de commit:
git commit -m "feat(auth): agregar middleware de validación JWT a /api/auth/verify

- Valida expiración del token
- Retorna 401 en token inválido
- Loggea intentos fallidos a consola (temporal)"

El estándar de conventional commits (feat:, fix:, chore:, docs:, refactor:) no es solo cosmético. Herramientas como semantic-release y generadores automáticos de changelog dependen de él. En 2026, con herramientas de code review con IA integradas en GitHub, los commits estructurados también le dan mejor contexto a la IA sobre qué cambió.

7. La guerra civil del package-lock.json

Todo equipo eventualmente tiene esta pelea.

Un desarrollador usa npm install. Otro usa yarn add. Un tercero usó pnpm porque vio un video de YouTube. Ahora tienes package-lock.json, yarn.lock y pnpm-lock.yaml todos en el mismo repo. Tres lockfiles diferentes, tres algoritmos de resolución de dependencias diferentes, y producción podría estar corriendo una versión completamente distinta de un paquete que la que tienes en tu laptop.

Esto no es un problema menor. El ecosistema de paquetes de Node.js ha tenido ataques de supply chain donde código malicioso terminó en paquetes populares. Los lockfiles son tu mecanismo de defensa. Si cada persona en el equipo genera lockfiles diferentes, el lockfile no sirve para nada.

Elige un solo package manager. Imponlo. Elimina los demás.

// package.json — agrega esto
{
  "engines": {
    "node": ">=22.0.0",
    "npm": ">=10.0.0"
  },
  "packageManager": "npm@10.8.0"
}

# .npmrc — para forzar que no se usen otros package managers
engine-strict=true

Y commitea tu package-lock.json. Sé que es grande. Sé que crea conflictos de merge. Commitéalo igual. En el momento que lo agregas a .gitignore tiraste a la basura los builds reproducibles.

8. La carpeta .next no es código fuente

Este es un error más pequeño pero es de esas cosas que se acumulan.

.next/ es la carpeta de output de build de Next.js. Se genera fresca cada vez que ejecutas next build o next dev. Es específica de tu máquina, tu versión de Node.js y tu configuración de build.

Algunos desarrolladores la commitean porque creen que es necesaria. No lo es. Debería estar en .gitignore.

Carpeta	¿Commitear a Git?	Por qué
`.next/`	No	Output de build, específico de máquina
`node_modules/`	Nunca	Instalable desde package.json
`out/`	Generalmente no	Output de export estático
`public/`	Sí	Assets estáticos servidos por la app
`src/`	Sí	Tu código fuente real
`.env.local`	Nunca	Secretos locales
`next.config.js`	Sí	Configuración, no secretos

Commitea node_modules es la versión clásica de este error. Todos lo aprenden eventualmente. Pero .next/ y out/ atrapan a más gente de la que crees.

9. Nadie configura next.config.js para entornos reales

El archivo next.config.js es donde vive mucho del comportamiento importante en producción y la mayoría de tutoriales simplemente lo saltan.

Aquí un ejemplo real de cosas que se rompen en producción porque no fueron configuradas:

// next.config.js — cómo se ve una configuración real de producción

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Decirle a Next.js dónde vive tu API externa (para rewrites/proxying)
  async rewrites() {
    return [
      {
        source: '/api/backend/:path*',
        destination: `${process.env.BACKEND_URL}/api/:path*`,
      },
    ];
  },

  // Dominios de imágenes (o recibes errores 400 en imágenes externas)
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'tu-cdn-de-imagenes.com',
        port: '',
        pathname: '/images/**',
      },
    ],
  },

  // Variables de entorno que quieres exponer a través de next.config
  env: {
    APP_VERSION: process.env.npm_package_version,
  },

  // Strict mode — detecta más issues de React en dev
  reactStrictMode: true,

  // Modo de output para despliegue
  // 'standalone' es lo que quieres para despliegue en Docker/VPS
  output: process.env.NEXT_OUTPUT_MODE || undefined,
};

module.exports = nextConfig;

Una que mata a mucha gente: Next.js 15 (con App Router) maneja los rewrites de forma diferente al Pages Router en ciertos edge cases. Si estás proxyando peticiones a tu backend Node.js a través de rewrites de Next.js, prueba esto en un entorno de staging que coincida con producción. El entorno serverless de Vercel no es lo mismo que next start en un VPS.

10. La separación de despliegue que nadie planea

Este es el último y es el error más caro en proyectos reales.

Construyes tu app localmente. Next.js y Node.js ambos corren en tu máquina, se comunican bien, todo funciona. Luego vas a desplegar. Y alguien (probablemente tú) toma una decisión sin pensarlo:

“Pongo la app Next.js en Vercel porque es gratis y fácil.”

Tu app Next.js está en Vercel, que es serverless, auto-escalable, edge-deployed. Tu backend Node.js está en… un droplet de $5 en DigitalOcean. O Railway. O el tier gratuito de Render que se apaga después de 15 minutos de inactividad.

Ahora tienes:

Diferentes cadencias de despliegue
Diferentes sistemas de manejo de variables de entorno
Latencia de cold start en un lado pero no en el otro
Configuración de CORS que hay que actualizar cada vez que cambia el dominio
Dos pipelines de CI/CD separados que mantener
Tu backend Node.js pegando cold starts en el tier gratuito, haciendo que tu frontend de Vercel se vea lento

Nadie planeó esto. Pasó por accidente. Y ahora estás refactorizando tres meses después de empezar el proyecto.

La pregunta de planificación que tienes que responder antes de escribir una línea de código:

Escenario	Frontend	Backend	Notas
Proyecto hobby, bajo tráfico	Vercel	Vercel (solo API Routes)	Un solo despliegue, sin CORS
App mediana, presupuesto importa	Vercel	Railway / Render	Planear para cold starts
App seria de producción	Vercel	VPS (DigitalOcean, Hetzner)	Más control, más trabajo
Control total / enterprise	VPS (Docker)	VPS (mismo o diferente)	Tú manejas todo
Monorepo, full stack	Vercel	Vercel (ambos)	Funciona si serverless es suficiente

Lo que los desarrolladores buenos realmente hacen y nadie publica

He trabajado con y observado suficientes codebases para notar la diferencia. Esto es lo que separa a los desarrolladores que lo hacen bien:

Configuran la estructura del proyecto antes de escribir el primer componente. .gitignore, schema de variables de entorno, configuración de URL base de API — todo antes de git init.

Prueban la carga de variables de entorno en aislamiento. Antes de conectar cualquier llamada a API, hacen console.log(process.env.WHATEVER) en el contexto real de runtime donde se usará. ¿Server component? ¿Client component? ¿API route? Lo verifican.

Usan un archivo .env.example commiteado al repo que muestra cada variable necesaria sin los valores. Así le dices a tu equipo qué configurar sin filtrar nada.

# .env.example (COMMITEA ESTO)
DATABASE_URL=postgresql://user:***@host:port/database
NEXTAUTH_SECRET=generate-with-openssl-rand-base64-32
NEXTAUTH_URL=http://localhost:3000
BACKEND_URL=http://localhost:3001
NEXT_PUBLIC_API_BASE_URL=http://localhost:3001

# Los valores de producción van en la configuración de variables de entorno de tu plataforma
# NUNCA commitees .env.local o .env.production

Tratan el historial de Git como documentación. No solo para code review. Cuando algo se rompe en producción seis meses después, un buen historial de commits te permite hacer bisect del problema en minutos en vez de horas.

# Búsqueda binaria entre commits para encontrar cuándo se introdujo un bug
git bisect start
git bisect bad HEAD
git bisect good v1.0.0
# Git hace checkout del commit del medio, lo pruebas
# Luego marcas good o bad hasta encontrar el commit exacto
git bisect good  # o git bisect bad

Nunca debaten si usar App Router o Pages Router en 2026. El App Router es el default, es estable, React Server Components son el futuro de este ecosistema. Si estás empezando un proyecto nuevo hoy y usas Pages Router estás eligiendo activamente trabajar con un patrón deprecado. Es una elección que tienes permitido hacer, pero sé honesto de que es una elección.

Opinión polémica: el problema real son los tutoriales, no los desarrolladores

Voy a decir esto y la gente va a discrepar conmigo.

La razón por la que el 90% de los desarrolladores se equivoca no es estupidez ni pereza. Es la industria de los tutoriales.

Un tutorial de YouTube sobre “Construye una App Full Stack con Next.js y Node.js” dura 43 minutos. Los primeros 38 minutos son funcionalidades. Los últimos 5 minutos son “y ahora despliega en Vercel”. La configuración del .gitignore toma 30 segundos y se hace fuera de cámara o se copia de un template sin explicación. Las variables de entorno están hardcodeadas para simplificar. CORS se arregla con app.use(cors()) y nadie explica por qué.

Millones de desarrolladores aprendieron de esos tutoriales. Y luego fueron a construir cosas reales con esos patrones y se toparon con problemas reales.

“La documentación te dice qué hacen las herramientas. Rara vez te dice qué pasa cuando las usas mal en combinación.”

Esa brecha entre “terminé el tutorial” y “puedo construir software real de producción” es donde la mayoría de desarrolladores están atrapados. Y la combinación de Next.js, Node.js y Git es exactamente donde esa brecha se muestra más violentamente.

Lo único que arreglaría el 80% de estos problemas

Es vergonzosamente simple.

Empieza cada proyecto con esto:

# 1. Inicializa git PRIMERO, antes que cualquier otra cosa
git init mi-proyecto
cd mi-proyecto

# 2. Crea .gitignore ANTES de agregar cualquier archivo
# Copia el de la sección Node + Next.js de arriba

# 3. Crea .env.example
touch .env.example
# Escribe todas las variables que tu app necesitará (valores vacíos)

# 4. Crea .env.local para tus valores locales reales
# (Esto ya está en .gitignore así que no se committeará)

# 5. ENTONCES crea el scaffold de tu app Next.js
npx create-next-app@latest . --typescript

# 6. El primer commit debe ser: gitignore + env.example + nada más
git add .gitignore .env.example README.md
git commit -m "chore: inicialización del proyecto con gitignore y template de env"

Esa secuencia. En ese orden. Si cada desarrollador nuevo empezando un proyecto Next.js siguiera esos seis pasos en ese orden, el número de exposiciones accidentales de secretos caería drásticamente.

El orden importa porque una vez que ejecutas create-next-app, estás tentado a empezar a construir inmediatamente. Y en esa emoción, olvidas revisar qué se está staged cuando haces git add ..

Datos: dónde está este stack en 2026

Algunos números que dan contexto de por qué esto importa a escala:

Next.js sigue siendo el meta-framework de React dominante por descargas semanales de npm (consistentemente arriba de 5.8M por semana durante Q1 2026)
Node.js 22 LTS es la versión recomendada actual a inicios de 2026; Node.js 24 lanzado en abril 2025 va camino a LTS en octubre 2026
Git lo usa el 97.8% de desarrolladores en la Stack Overflow Developer Survey 2025 — efectivamente universal
La encuesta State of JavaScript 2024 mostró a Next.js con 81% de retención (desarrolladores que lo usaron y lo volverían a usar) y adopción creciente año tras año
El reporte de transparencia de GitHub de 2024 indicó que el escaneo de secretos bloqueó millones de exposiciones antes de que se hicieran públicas — la funcionalidad de push-protection está atrapando exactamente los errores descritos en este artículo

La escala de adopción significa que estos errores no le están pasando a unos pocos desarrolladores. Están pasando decenas de miles de veces al día, globalmente, en personas de todos los niveles de experiencia.

Preguntas comunes que no tienen buenas respuestas online

“¿Debería usar API routes de Next.js o un servidor Express separado para una startup?”

Si estás construyendo un MVP de startup, usa API routes de Next.js. Vas a entregar más rápido y tienes un despliegue menos que manejar. Cuando tengas problemas reales de escala, migra. No vas a tener esos problemas tan pronto como crees.

“¿Importa si commiteo node_modules una vez?”

Sí. node_modules puede pesar cientos de megabytes. Infla tu repositorio permanentemente (recuerda, Git guarda el historial). Y crea problemas de reproducibilidad. Elimínalo del historial usando git filter-repo de la misma forma que eliminarías un secreto.

“¿Cuál es la versión correcta de Node.js para usar con Next.js 15?”

Node.js 18 es el mínimo para Next.js 15. Node.js 22 LTS es lo que deberías estar usando en producción a inicios de 2026. La tabla de compatibilidad en los docs de Next.js está actualizada y debería ser tu fuente de verdad.

“¿Por qué mi app Next.js funciona en Vercel pero mis variables de entorno son undefined?”

Porque las configuraste en .env.local en tu máquina pero olvidaste agregarlas en la configuración de variables de entorno de Vercel en el dashboard. Vercel no lee tu .env.local. Tienes que configurar cada variable manualmente en los settings del proyecto en Vercel. Esto le pasa a todos una vez.

Reflexión final

La combinación de Next.js, Node.js y Git es genuinamente poderosa. El ecosistema en 2026 es suficientemente maduro para que puedas construir aplicaciones serias de producción y competir con equipos del doble de tu tamaño.

Pero “poderoso” y “perdonador” son cosas diferentes. Este stack no es perdonador. Te va a dejar hacer push de tu .env a GitHub. Te va a dar silenciosamente undefined en vez de tu secret key. Va a desplegar con variables de entorno rotas y no te va a dar ningún mensaje de error útil a las 2am.

Los desarrolladores que lo hacen bien no son necesariamente más talentosos. Simplemente ya se quemaron una vez y aprendieron, o tuvieron la suerte de aprender de alguien que se quemó.

Ahora lo leíste en vez de tener que vivirlo.

Aprovéchalo.

Referencias

GitHub Security: “Detected and Prevented Secrets in 2024” — GitHub Blog, Enero 2025
Stack Overflow Developer Survey 2025 — Datos de uso de sistemas de control de versiones
State of JavaScript 2024 — Sección Meta-Frameworks, retención y uso de Next.js
Next.js 15 Release Notes y Changelog — Repositorio Vercel/Next.js en GitHub
Node.js Release Schedule — Node.js Foundation
Estadísticas de descargas npm para next — npmjs.com
Documentación de Next.js: Variables de Entorno
Documentación de Next.js: API Routes
Conventional Commits Specification v1.0.0 — conventionalcommits.org
Documentación de git-filter-repo — GitHub
OWASP Secrets Management Cheat Sheet
Guía de Variables de Entorno en Vercel

Este artículo refleja mi experiencia real debuggeando estos problemas en codebases reales. Los errores descritos son patrones que he visto repetidamente, no edge cases. Si algo aquí contradice lo que has estado haciendo, no es un accidente.