Hacer tu primer deploy a producción implica cinco pasos: preparar el proyecto para producción, configurar variables de entorno, elegir plataforma y desplegar, conectar un dominio y verificar logs. Esta guía recorre el flujo completo en Vercel, Railway y Render, con el checklist previo y los errores más frecuentes que frenan a los developers junior.

Tu proyecto funciona perfecto en localhost:3000. Le pasás el link a alguien y no puede abrirlo. Ese es el momento en que muchos developers junior descubren que hacer que algo funcione en tu máquina y hacer que funcione para el mundo son dos problemas distintos.

El deploy es el primer obstáculo técnico real después de aprender a programar, y es también el que más frustra, porque los errores no aparecen mientras desarrollás: aparecen recién cuando subís. Esta guía cubre el flujo completo, en el orden en que conviene hacerlo.

Qué significa realmente "poner en producción"

En desarrollo, tu código corre en tu computadora, con tus archivos, tus variables y tu base de datos local. En producción corre en un servidor que no controlás, sin tus archivos, sin tus variables y con una base de datos distinta. Todo lo que rompe el deploy sale de esa diferencia.

Los tres puntos donde falla:

• Configuración: credenciales y URLs que estaban en tu máquina y no existen en el servidor.

• Dependencias: paquetes instalados globalmente en tu equipo que no están declarados en el proyecto.

• Rutas y assets: referencias a archivos con rutas absolutas locales.

Paso 1: preparar el proyecto (checklist previo al deploy)

Antes de tocar ninguna plataforma, resolvé esto. Ahorra el ochenta por ciento de los errores.

• Todas las dependencias declaradas. Borrá node_modules, corré la instalación limpia y verificá que el proyecto arranque. Si falla, tenés una dependencia sin declarar.

• Ninguna credencial en el código. Buscá claves de API, contraseñas y tokens escritos directamente en archivos. Todo eso va a variables de entorno.

• .gitignore correcto. Debe incluir .env, node_modules y archivos de build. Subir un .env a un repositorio público es el error más costoso de esta lista.

• Script de build y de start definidos. La plataforma necesita saber cómo construir y cómo arrancar tu app.

• Puerto dinámico. No fijes el puerto: leelo de la variable de entorno que provee la plataforma, con un valor por defecto para desarrollo local.

• Versión de runtime especificada. Declarar la versión de Node o Python evita que el servidor use una distinta a la tuya.

Este último punto es el que genera los errores más confusos: código que funciona local y falla en el servidor porque el runtime remoto es dos versiones mayores.

Paso 2: variables de entorno

Una variable de entorno es un valor de configuración que vive fuera del código. En local está en un archivo .env; en producción se carga en el panel de la plataforma.

Las que casi siempre necesitás:

Regla práctica: mantené un archivo .env.example en el repositorio con los nombres de las variables y sin valores. Es documentación y te salva cuando volvés al proyecto tres meses después.

Paso 3: elegir plataforma y desplegar

Las tres opciones más razonables para un primer deploy, con capa gratuita y sin necesidad de administrar servidores:

Flujo genérico de deploy

1. Subí el proyecto a Git. Todas estas plataformas despliegan desde un repositorio.

2. Conectá el repositorio. Autorizás la plataforma y elegís el repo y la rama.

3. Configurá build y start. Suelen detectarse automáticamente; verificá que sean correctos.

4. Cargá las variables de entorno. Antes del primer deploy, no después.

5. Desplegá y mirá los logs de build. El primer intento falla seguido; el log dice exactamente por qué.

La documentación oficial de Vercel, Railway y Render cubre las particularidades de cada stack y conviene tenerla abierta durante el primer intento.

Un punto que confunde: build time vs. runtime

Hay dos momentos distintos. El build es cuando se compila el proyecto; el runtime es cuando corre. Algunas variables se necesitan en build (por ejemplo las que se inyectan en el bundle del frontend) y otras en runtime. Si una variable de frontend no aparece en producción, casi siempre es porque se cargó como variable de runtime cuando se necesitaba en build.

Paso 4: dominio propio y HTTPS

Todas las plataformas te dan una URL propia del tipo tu-proyecto.vercel.app. Para conectar un dominio propio:

1. Comprá el dominio en un registrador.

2. Agregalo en el panel de la plataforma, que te va a indicar qué registros DNS crear.

3. Creá los registros en el panel de tu registrador: un CNAME para subdominios como www, o un registro A apuntando a la IP indicada para el dominio raíz.

4. Esperá la propagación. Puede tardar de minutos a algunas horas.

El certificado HTTPS se emite automáticamente en las tres plataformas una vez que el DNS resuelve. No hace falta configurarlo a mano.

Paso 5: logs, monitoreo y qué hacer cuando falla

Después del deploy, el trabajo recién empieza. Hay dos tipos de log que tenés que saber leer:

• Logs de build: dicen si el proyecto se compiló. Los errores acá son de dependencias, versiones o scripts mal definidos.

• Logs de runtime: dicen qué pasa mientras la app corre. Los errores acá son de conexión a base de datos, variables faltantes o excepciones no manejadas.

Los cinco errores más frecuentes en un primer deploy

Una práctica que ahorra mucho tiempo: probá el build de producción en tu máquina antes de subir. Correr el comando de build local y luego el de start replica la mayoría de los errores de producción sin esperar el ciclo de deploy. Es el mismo principio de anticipación que se aplica en testing y debugging de flujos automatizados.

Buenas prácticas desde el primer deploy

• Rama de producción separada. Desplegá desde main y trabajá en ramas. Nunca desarrolles sobre la rama que está en producción.

• Preview deploys. Vercel y Render generan un entorno por pull request. Es la forma más simple de probar sin romper producción.

• Base de datos de producción separada de la de desarrollo. Parece obvio y es el error que más datos destruye.

• Rollback identificado. Sabé de antemano cómo volver al deploy anterior. Las tres plataformas lo permiten con un clic.

• Un healthcheck simple. Un endpoint que devuelva estado alcanza para saber si la app está viva sin abrir el navegador.

Cursos y carreras recomendados de Coderhouse

Según el nivel desde el que llegues a esta etapa:

• Curso de JavaScript — el nivel inicial. Antes de preocuparse por producción conviene tener sólidos los fundamentos del lenguaje, el manejo de asincronismo y el consumo de APIs.

• Carrera de Desarrollo Backend — el nivel intermedio, donde el deploy deja de ser un paso final y se convierte en parte del diseño: servidores, bases de datos, autenticación y APIs pensadas para producción.

• Curso de DevOps y Cloud — el nivel avanzado y el más específico para este tema: CI/CD, contenedores, infraestructura como código y monitoreo. Es lo que convierte el deploy manual en un pipeline automático.

Si además querés automatizar tareas alrededor del deploy —notificaciones, chequeos, reportes—, el Curso de AI Automation cubre cómo orquestar esos flujos sin escribir infraestructura desde cero.

Preguntas frecuentes

¿Cuál es la mejor plataforma para un primer deploy?

Para un frontend o una app de Next.js, Vercel es la opción más directa: detecta la configuración sola y el deploy toma minutos. Para un backend con base de datos, Railway es más simple porque provee la base en el mismo proyecto. Render es una buena alternativa si necesitás workers o tareas programadas, con la salvedad de que los servicios gratuitos se suspenden por inactividad.

¿Necesito saber Docker para desplegar a producción?

No para un primer deploy. Las tres plataformas mencionadas detectan el tipo de proyecto y construyen la imagen por vos. Docker se vuelve necesario cuando necesitás replicar un entorno exacto, cuando el stack tiene dependencias del sistema poco comunes, o cuando el proyecto va a correr en infraestructura propia.

¿Por qué mi app funciona en local y falla en producción?

En el orden de frecuencia: falta una variable de entorno, hay una dependencia que tenías instalada globalmente, la versión del runtime del servidor es distinta a la tuya, o la cadena de conexión a la base de datos sigue apuntando a localhost. Los logs de build y de runtime identifican cuál de las cuatro es en casi todos los casos.

¿Cuánto cuesta mantener un proyecto en producción?

Un proyecto personal o de portfolio puede sostenerse en la capa gratuita de estas plataformas, con las limitaciones de suspensión por inactividad y cuotas de uso. Los costos reales aparecen con la base de datos persistente y el tráfico: un stack chico con base gestionada suele arrancar en el orden de los cinco a veinte dólares mensuales. El dominio propio se suma aparte, con costo anual.

¿Qué hago si rompí producción con un deploy?

Primero rollback al deploy anterior, que en Vercel, Railway y Render se hace desde el historial de despliegues en pocos clics. Recién después investigá la causa con calma sobre el entorno de preview. El orden importa: arreglar en caliente sobre producción es cómo un problema chico se convierte en uno grande.