Errores de dependencias npm en Bolt: causas y soluciones

Casi todos los errores de npm en un proyecto de Bolt.new salen de cuatro lugares: paquetes cuyas versiones no se ponen de acuerdo (ERESOLVE), un paquete que necesita código nativo que el entorno del navegador no puede ejecutar, un paquete o versión que no existe, o un lockfile que ya no coincide con package.json. Lee la primera línea del error, corrige la versión o cambia el paquete y vuelve a instalar desde la terminal de Bolt. Forzar la instalación con banderas esconde el problema, no lo arregla.

En esta guía verás dónde aparecen estos errores, qué quiere decir cada mensaje, cómo se corrige y qué hábitos evitan que las dependencias se desordenen a medida que la IA va sumando paquetes.

¿Dónde aparecen los errores de npm en Bolt?

Bolt corre tu proyecto dentro de los WebContainers de StackBlitz, un entorno de Node.js que funciona en tu navegador. Los errores de instalación y arranque se ven en tres lugares:

• En la vista previa, como un aviso superpuesto o una página que nunca termina de cargar.
• En la pestaña Bolt de la terminal (vista de código), donde Bolt ejecuta sus propios comandos de instalación y desarrollo.
• En la pestaña Publish Output, cuando el error solo ocurre al compilar para producción.

Copia el error desde la terminal y no desde el aviso de la vista previa: ahí está el mensaje completo con los nombres de los paquetes.

¿Qué significa cada error?

¿Cómo resuelvo un conflicto de peer dependencies?

El mensaje nombra a los dos lados. Suele decir algo como "el paquete A necesita React 18, pero el proyecto tiene React 19".

1. Averigua quién pide qué. En la terminal de Bolt:

   npm ls react
   npm view <paquete-a> peerDependencies

2. Mueve al que está desfasado. Normalmente un paquete quedó atrás. Revisa si hay una versión más nueva compatible (npm view <paquete-a> versions), instálala y prueba. Si ninguna versión sirve, reemplaza el paquete.
3. Reinstala limpio. La guía de problemas de WebContainers de StackBlitz sugiere borrar package-lock.json, volver a correr npm install y guardar el proyecto.

4. Deja las salidas de emergencia para el final. npm install --legacy-peer-deps o --force pasan por encima del error, y StackBlitz puede reintentar solo con --legacy-peer-deps. Las dos dejan versiones desparejas que pueden fallar después, en ejecución o en otro hosting. Si necesitas fijar una dependencia anidada, el campo overrides de package.json lo hace en un lugar visible:

   {
    "overrides": {
      "some-library": {
        "react": "$react"
      }
    }
   }

¿Por qué un paquete funciona en mi computadora y en Bolt no?

Porque algunos paquetes incluyen código nativo compilado (C o C++ para tu sistema operativo) y los WebContainers no pueden cargarlo. Verás Cannot load native addon because loading addons is disabled. Librerías para cifrar contraseñas, algunos procesadores de imágenes y drivers de bases de datos locales son los casos típicos.

La salida es una alternativa escrita en JavaScript o compilada a WebAssembly, por ejemplo bcryptjs en lugar de bcrypt. Muchas veces lo mejor es no necesitar ese paquete en el proyecto del navegador: que tu proveedor de autenticación se ocupe de las contraseñas y que el procesamiento pesado de imágenes ocurra en una función de servidor o en un servicio de almacenamiento.

¿Y si la IA instaló un paquete que no existe?

Las herramientas de IA a veces inventan nombres de paquetes que suenan creíbles. npm responde con un 404 y la instalación se detiene. Quita el paquete de package.json y pregúntale a Bolt qué librería real quiso usar.

Ten más cuidado cuando el nombre sí existe pero nunca lo habías visto. Hay atacantes que registran paquetes con los nombres que las IA suelen inventar. Antes de quedarte con un paquete desconocido, búscalo en npmjs.com: que tenga un repositorio de código enlazado, versiones recientes y descargas reales. Si falta algo de eso, pide una alternativa conocida.

¿Y el código escrito para otra versión?

Este no da error al instalar. El paquete se instala bien, pero la IA escribió código para otra versión mayor, así que faltan funciones o la configuración se ignora. Las librerías que cambiaron su forma de configurarse entre versiones, como Tailwind CSS, los enrutadores y los SDK de autenticación, son las sospechosas de siempre.

Revisa la versión instalada con npm ls <paquete> y díselo a Bolt en el prompt: "El proyecto usa Tailwind CSS 3.4; escribe código para esa versión". Mejor aún, deja las versiones clave en Project settings > Knowledge para no repetirlas.

¿Cómo evito que las dependencias se desordenen?

• Conserva el lockfile. package-lock.json es lo que hace que cada instalación sea idéntica. No lo borres como solución de rutina y asegúrate de que esté en GitHub.
• Actualiza a propósito. Corre npm outdated una vez al mes, sube una versión mayor por vez y prueba después de cada una.
• Limpia. npx depcheck muestra paquetes que nadie importa y npm dedupe elimina copias duplicadas. Menos paquetes también es menos para que Bolt lea.
• Cuidado con npm audit fix --force. Puede saltar a versiones mayores que rompen cosas. Lee el reporte y actualiza a mano los paquetes señalados.
• Compila antes de publicar. npm run build en la terminal muestra errores que el servidor de desarrollo deja pasar. Qué ocurre si te lo saltas lo cuenta error al publicar Bolt en Netlify, y el otro bloqueo frecuente está en errores de TypeScript que rompen el build.

Respuestas rápidas

¿Es seguro usar --legacy-peer-deps? Es un atajo, no una solución. Instala versiones desparejas que pueden romperse en ejecución. Úsalo para destrabar y después alinea las versiones.

¿Borro node_modules y empiezo de cero? Ayuda si la instalación se corrompió, pero no resuelve un conflicto de versiones: el conflicto está en package.json.

¿Por qué los errores aparecen solo al publicar? Porque el build de producción es más estricto que el servidor de desarrollo y pasa el verificador de tipos y el empaquetador por todos los archivos.

¿Puedo trabajar en local para evitar los límites de WebContainers? Sí. En tu computadora los paquetes nativos se instalan normal; mira descargar el código de Bolt y correrlo en local. Eso sí, la vista previa de Bolt seguirá fallando con ellos.

¿Las dependencias se enredaron más de la cuenta?

Cuando los conflictos vuelven una y otra vez, el árbol de dependencias suele necesitar una limpieza a conciencia. Nuestro servicio para arreglar apps de Bolt empieza con una revisión del código y un precio cerrado por arreglo, y el mantenimiento continuo deja las actualizaciones al día. Empieza con la revisión gratuita o mándanos el error.