Errores de TypeScript: el build falla en mi app hecha con IA
Por qué una app escrita con IA funciona en desarrollo y el build falla por TypeScript, cómo hallar y corregir el error real y por qué no apagar el chequeo.
Read in English →
Cuando una app escrita con IA funciona bien en desarrollo pero el build falla con errores de TypeScript, es porque la compilación de producción revisa los tipos y el servidor de desarrollo no se detiene por ellos. next build hace el chequeo de tipos por defecto, y los proyectos con Vite suelen correr tsc antes de vite build, mientras que el servidor de desarrollo de Vite solo quita los tipos y ejecuta el código. Reprodúcelo en tu equipo con npx tsc --noEmit, corrige los errores archivo por archivo empezando por el primero y regenera los tipos de la base de datos si están desactualizados. Apagar el chequeo hace que el build pase y les traslada los errores a tus usuarios.
En esta guía verás de dónde salen estos errores en el código escrito con IA, cómo leerlos, qué significan los más comunes y cómo corregirlos, y cómo evitar que vuelvan.
¿Por qué funciona en desarrollo y falla al compilar?
Hay dos programas distintos en juego. En desarrollo, Vite y herramientas parecidas convierten TypeScript en JavaScript lo más rápido posible y se saltan el chequeo de tipos, así que un desajuste que solo rompería en un caso raro nunca impide que cargue la página. La compilación de producción es más estricta:
- Next.js hace fallar
next buildsi hay errores de TypeScript, salvo que alguien lo haya desactivado. - Las plantillas de Vite para React con TypeScript usan un script de build como
tsc -b && vite build, así que el verificador de tipos corre primero y detiene todo si encuentra errores.
Tu proveedor de hosting ejecuta ese script, por eso el fallo suele aparecer primero en Vercel o Netlify, mucho después de que se escribió el código.
¿Cómo encuentro el error de verdad?
En el registro de compilación, pasa de largo los pasos de instalación hasta el primer error. Los errores de TypeScript indican un archivo, una línea y columna, y un código:
src/pages/Invoices.tsx(42,17): error TS2339: Property 'total' does not exist on type 'Invoice'.Después reprodúcelo en tu máquina para no depender de cada despliegue:
- Ejecuta
npm run buildpara hacer exactamente lo que hace el hosting. - Para ir más rápido, ejecuta
npx tsc --noEmit(onpx tsc -bsi tu proyecto usa referencias entretsconfig, como las plantillas de Vite). Muestra todos los errores de tipos sin generar archivos. - Corrige el primer error de cada archivo antes de mirar los demás. Un tipo equivocado suele provocar varios errores más abajo.
Si el build pasa en tu equipo pero falla en el hosting, mira la sección sobre mayúsculas en las importaciones más abajo, y nuestra guía para leer un error de build en Vercel.
¿Qué significan los errores más comunes?
Los mensajes de TypeScript salen en inglés; aquí van resumidos con lo que suelen significar.
| Código | Mensaje (resumido) | Qué suele significar en código escrito con IA | Arreglo habitual |
|---|---|---|---|
| TS2339 | Property 'x' does not exist on type 'Y' | El código usa un campo que el tipo no tiene: una columna renombrada o un campo que la IA supuso | Usa el nombre real del campo, o actualiza el tipo si el campo existe |
| TS2322 | Type 'X' is not assignable to type 'Y' | Un valor con la forma equivocada, a menudo un string donde se espera un número o un conjunto de valores concreto | Convierte el valor o corrige el tipo, que quedó muy estrecho o muy amplio |
| TS2345 | Argument of type 'X' is not assignable to parameter of type 'Y' | Se llamó a una función con el tipo de dato equivocado, muchas veces después de que cambió su firma | Ajusta la llamada o la función para que coincidan |
| TS18048 | 'x' is possibly 'undefined' | Datos que quizá todavía no cargaron, o un campo opcional, se usan como si siempre estuvieran | Maneja el caso vacío: un retorno anticipado, un valor por defecto o un estado de carga |
| TS7006 | Parameter 'x' implicitly has an 'any' type | Un parámetro sin tipo en modo estricto | Agrega el tipo |
| TS2307 | Cannot find module 'x' or its corresponding type declarations | Ruta de importación equivocada, paquete que falta o faltan sus tipos | Corrige la ruta, instala el paquete o instala sus tipos |
| TS6133 | 'x' is declared but its value is never read | Restos de intentos anteriores, cuando está activo el chequeo de variables sin usar | Borra el código que sobra |
Los cuatro primeros son los que más producen las herramientas de IA, porque el agente edita un archivo a la vez y no siempre actualiza los tipos y las llamadas que dependen de él.
¿Y si los errores vienen de los tipos de la base de datos?
Las apps con Supabase suelen tener un archivo generado que describe cada tabla y columna. Cuando el agente agrega una columna con una migración pero no regenera ese archivo, cada consulta que usa la columna nueva falla con TS2339 o TS2322. Regenera los tipos a partir del esquema real:
npx supabase login
npx supabase gen types typescript --project-id "$PROJECT_REF" --schema public > database.types.tsGuarda el resultado encima del archivo que ya usa tu proyecto, esté donde esté. La guía de Supabase para generar tipos explica las opciones. Si después de esto los errores desaparecen, el código estaba bien y los tipos estaban viejos.
¿Por qué no apago el chequeo y listo?
Porque los errores te están avisando de fallos reales. Next.js permite poner typescript.ignoreBuildErrors en true, y su propia documentación lo describe como producir código de producción de forma peligrosa aunque la aplicación tenga errores: se salta el chequeo de tipos por completo. Lo mismo vale para llenar el código de // @ts-ignore, as any o poner "strict": false en tsconfig.json. El build se pone en verde y el valor "posiblemente indefinido" rompe la página al primer usuario con una cuenta vacía.
Si un lanzamiento depende de esto, saltarse el chequeo por unos días, con la lista de errores por escrito y una fecha para corregirlos, es una decisión de negocio. Dejarlo así para siempre es como los errores pequeños se acumulan en deuda técnica.
¿Cómo hago que la IA los corrija sin empeorar las cosas?
- Pásale un error a la vez, con el archivo y la línea, en lugar del registro completo.
- Prohíbe los atajos en tus reglas: "Nunca uses
any,@ts-ignoreni@ts-expect-error, ni aflojestsconfig.json, para corregir un error de tipos. Corrige la causa." - Pídele que corra el verificador después de cada arreglo y que pegue el resultado.
- Lee los cambios. Si el arreglo de un error tocó diez archivos o el
tsconfig, detente y pregunta por qué.
¿Por qué pasa en mi Mac y falla en el servidor?
La causa clásica son las mayúsculas. macOS y Windows normalmente tratan Button.tsx y button.tsx como el mismo archivo; las máquinas Linux donde corren casi todos los builds, no. Si el agente cambió las mayúsculas de un archivo, o lo importa escrito de otra forma, el build falla con TS2307 solo en el hosting. Haz que la importación coincida exactamente con el nombre del archivo. Una versión distinta de Node.js o un paquete que falta en package.json causan fallos parecidos que solo aparecen en el servidor.
Respuestas rápidas
¿Es seguro ejecutar npx tsc --noEmit? Sí. Solo revisa; no cambia archivos ni genera nada.
Tengo 200 errores. ¿Por dónde empiezo? Corre el verificador, arregla el primer archivo y vuelve a correrlo. La cantidad suele bajar rápido porque los errores se encadenan.
¿Puedo evitar esto la próxima vez? Corre el chequeo de tipos en cada push y antes de que el agente dé una tarea por terminada. En pruebas para código generado con IA tienes un flujo sencillo.
¿Paso el proyecto de TypeScript a JavaScript? No. Te quedarías con los errores y perderías la herramienta que los encuentra.
¿El build sigue en rojo?
Si la lista de errores no deja de crecer o cada arreglo rompe otra pantalla, los tipos suelen estar señalando un desajuste más profundo entre el código y los datos. En nuestra página de ayuda con proyectos de Cursor explicamos cómo lo encaramos, la revisión gratuita muestra lo que se ve desde afuera, y puedes mandarnos el registro del build.
