npm run build: qué hace y en qué se diferencia de npm run dev

npm run build convierte el código de tu proyecto en los archivos finales que se publican en internet: HTML, CSS y JavaScript optimizados, más pequeños y rápidos. Ejecuta el script llamado build de tu package.json; en un proyecto de Vite (lo que usan Lovable y Bolt) es vite build, y el resultado queda en la carpeta dist. No levanta ningún servidor: solo prepara los archivos.

Qué pasa cuando corres npm run build

Abre tu package.json. Verás algo así:

{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview"
  }
}

npm run build ejecuta lo que dice "build". En este ejemplo hace dos cosas:

1. tsc -b: revisa que el código TypeScript no tenga errores de tipos.
2. vite build: junta todos tus archivos, quita lo que no se usa, los comprime y genera la carpeta dist:

dist/
├── index.html
└── assets/
    ├── index-a1b2c3.js
    └── index-d4e5f6.css

Los nombres raros (a1b2c3) sirven para que el navegador descargue la versión nueva cada vez que publicas.

Esa carpeta es lo que Vercel, Netlify o cualquier hosting sirve a tus visitantes. Cuando Vercel “hace deploy”, en realidad corre npm install y npm run build, y publica lo que salió.

npm run build vs npm run dev

Concepto	npm run dev	npm run build
Para qué	Trabajar en tu computadora	Preparar la versión para publicar
Servidor	Sí, en localhost	No
Se actualiza al guardar	Sí	No; hay que volver a correrlo
Velocidad del sitio	Lenta (sin optimizar)	Rápida (optimizada y comprimida)
Revisión de errores	Permisiva	Más estricta
Resultado	Nada en disco	Carpeta dist (o build, .next)

Para ver localmente cómo quedará el sitio publicado:

npm run build
npm run preview

preview sirve la carpeta dist en tu computadora, igual que lo haría el hosting.

Qué carpeta genera según la herramienta

Herramienta	Carpeta	Comando típico
Vite (Lovable, Bolt, la mayoría)	dist	vite build
Create React App	build	react-scripts build
Next.js	.next	next build
Astro	dist	astro build

Esto importa al publicar: en Vercel o Netlify, el Output Directory debe coincidir con esta carpeta. Si no, verás un 404 en todo el sitio. Ver error 404 en Vercel.

Por qué npm run build falla si npm run dev funciona

Es la pregunta más común. El build es más estricto:

1. Errores de TypeScript. En desarrollo, Vite no detiene la app por errores de tipos; en el build, tsc sí.
2. Imports con mayúsculas distintas. import Header from './header' funciona en Windows o macOS aunque el archivo sea Header.tsx, pero falla al compilar en Linux (como en Vercel).
3. Variables de entorno. En el build, los valores de import.meta.env.VITE_... se escriben dentro del JavaScript final. Si no existen al momento del build, quedan vacíos. Ver variables de entorno en Vite.
4. Código que solo existe en desarrollo, como herramientas de depuración.

Para diagnosticar:

npm run build

Y lee el primer error que aparece, no el último. Si en Vercel ves “exited with 1”, ve a npm run build exited with 1.

Mensajes que verás al correr el build (y cuáles importan)

No todo lo que sale en la terminal es un error. Estos son los más frecuentes:

Una advertencia de tamaño:

(!) Some chunks are larger than 500 kB after minification.

Es una advertencia de Vite, no un error: el build sí terminó. Significa que un archivo JavaScript quedó grande y tu sitio tardará más en cargar la primera vez. No bloquea la publicación; si quieres mejorar velocidad, se resuelve cargando por partes las páginas que no se usan al inicio.

El script no existe:

npm error Missing script: "build"

Tu package.json no tiene un script build, o estás corriendo el comando en la carpeta equivocada. Revisa que estés en la carpeta donde está el package.json (la raíz del proyecto).

Falta la herramienta:

sh: vite: command not found

No se instalaron las dependencias. Corre npm install primero. Si ya lo hiciste, borra node_modules y vuelve a instalar.

Error de memoria en proyectos grandes: si el build se detiene con un mensaje que menciona heap out of memory, el proceso se quedó sin memoria. Pasa más en computadoras con poca RAM o en servidores pequeños; también puede ser señal de que el proyecto importa librerías enormes que no necesita.

En todos los casos, la regla es la misma: busca la primera línea que diga error y empieza por ahí.

Preguntas que suelen surgir

¿Tengo que subir la carpeta dist a GitHub? No. Se agrega al .gitignore; el hosting la genera en cada deploy.

¿Tengo que correr npm run build antes de publicar en Vercel? No es obligatorio (Vercel lo corre por ti), pero hacerlo antes te ahorra deploys fallidos.

¿Puedo subir dist a un hosting tradicional (como Hostinger)? Sí: subes el contenido de dist a la carpeta pública (public_html). Si tu app tiene rutas, necesitarás una regla de reescritura en el servidor. Ver cómo subir mi página web a internet.

¿Qué es npm install? Descarga las librerías que tu proyecto necesita (las guarda en node_modules). Se corre antes del build.

Errores comunes

• Editar archivos dentro de dist: se borran en el siguiente build.
• Subir node_modules o dist al repositorio.
• Probar solo con npm run dev y descubrir los errores hasta el deploy.
• Desactivar TypeScript en el build para que “pase”.

Si tu build falla y no entiendes el error, o tu app hecha con IA solo funciona en desarrollo, en Black Engine revisamos el log contigo por WhatsApp. Si quieres entender todo el proceso de publicar, lee qué es un deploy.