Next.js: los cambios no se reflejan, borra .next/dev

Tu código parece correcto, pero el entorno de desarrollo de Next.js 16 se comporta como si no hubieras cambiado nada. Los síntomas más habituales son estos:

Después de un git checkout, o de editar un servicio o el CSS global, next dev sigue sirviendo el código o los estilos anteriores, incluso tras reiniciarlo.
Una ruta de API nueva responde con la página HTML de error 404.
tsc --noEmit falla dentro de archivos generados que tú no editaste, mientras la integración continua (CI) pasa sin problemas.

En el último caso, el error apunta a la carpeta de tipos generados, por ejemplo así:

.next/dev/types/validator.ts:78:39
Type error: Cannot find module '../../../app/mi-ruta/page.js'

También puede ser un error de sintaxis dentro de validator.ts o routes.d.ts, archivos que Next.js genera y que no tienen relación con tu cambio. Los tres síntomas comparten una causa: estado generado y guardado en disco que ya no corresponde a tu código.

Por qué pasa

En Next.js 16, la documentación de la CLI indica que las compilaciones de desarrollo se escriben en .next/dev en lugar de .next. Ahí viven dos cosas que importan en este problema:

La caché del sistema de archivos de Turbopack para desarrollo. Según la documentación, está activada por defecto desde la versión 16.1.0, se guarda en .next/dev/cache/turbopack y hace que, al reiniciar el servidor, se reutilice la compilación anterior. Por eso reiniciar next dev no basta cuando esa caché quedó desfasada: el servidor la vuelve a cargar.
Los tipos generados. Next.js escribe los tipos de rutas en <distDir>/types, que en desarrollo es .next/dev/types. Si tu tsconfig.json incluye esa carpeta, tsc revisa esos archivos como cualquier otro: la documentación de TypeScript de Next.js indica que la comprobación con la CLI de tsc cubre el proyecto completo que define tu tsconfig, incluida .next/dev/types cuando está incluida.

Con ese contexto, las dos variantes del error se explican así:

Cannot find module tras cambiar de rama o borrar una ruta. Un validator.ts antiguo sigue importando páginas que ya no existen. En el repositorio de Next.js se fusionó una corrección para next build (descarta .next/dev/types durante la comprobación de tipos de la compilación; no pude confirmar en qué versión llegó), pero un tsc --noEmit lanzado por separado sigue revisando lo que tu tsconfig incluya.
Errores de sintaxis en archivos generados. Apuntan a un archivo incompleto o dañado. No encontré documentación que explique cómo ocurre; las causas plausibles son una escritura interrumpida (proceso terminado a la fuerza, apagado del equipo) o dos procesos escribiendo la misma carpeta. En las versiones que separan .next/dev de .next, la documentación afirma que puedes ejecutar next dev y next build a la vez sin conflictos; antes de esa separación ambos usaban la misma carpeta .next.

El caso de la ruta de API que responde 404 encaja con el mismo patrón (estado desfasado), pero conviene descartar primero un error simple; se explica más abajo.

Solución

Detén todo lo que use la carpeta. Cierra el servidor de desarrollo y cualquier tsc --watch o proceso de compilación. En Windows, un proceso que mantiene archivos abiertos impide borrarlos.
Borra la carpeta de desarrollo. Contiene los tipos generados y la caché de Turbopack para desarrollo:
```
rm -rf .next/dev
```
```
Remove-Item -Recurse -Force .next\dev
```
Si el problema persiste o acabas de cambiar de rama o de versión de Next.js, borra toda la carpeta .next. Ten en cuenta que también elimina la caché de compilación de producción (.next/cache), así que el siguiente next build será más lento una vez:
```
rm -rf .next
```
```
Remove-Item -Recurse -Force .next
```
Vuelve a generar y arrancar. next dev recrea la carpeta. Si solo quieres comprobar tipos sin levantar el servidor, la documentación de la CLI muestra este patrón para CI:
```
npx next typegen && npx tsc --noEmit
```
Si cambiaste el esquema de Prisma, regenera el cliente. La documentación de Prisma indica ejecutar prisma generate después de cambiar el esquema; luego reinicia el servidor:
```
npx prisma generate
```
Evita que se repita. Mantén .next en .gitignore, no edites a mano los archivos generados y no ejecutes dos servidores de desarrollo sobre la misma carpeta de proyecto. Si usas una versión anterior a la separación de .next/dev o herramientas propias que escriben en .next, evita ejecutar next dev y next build al mismo tiempo, o separa las salidas con la opción distDir (usa una carpeta que solo ocupe Next.js, porque la documentación advierte que a veces borra su contenido).

Cómo verificar que quedó resuelto

npx tsc --noEmit
npx next build

El primer comando debe terminar sin errores en archivos generados, y el segundo debe compilar. En un caso real, después de borrar .next/dev la comprobación de tipos pasó de fallar a terminar con cero errores, la compilación terminó correctamente y la batería completa de pruebas automáticas pasó en verde. Con next dev en marcha, recarga la página: los cambios de CSS (por ejemplo, variables de color del modo oscuro) y la ruta de API nueva deben verse sin más pasos.

Para confirmar que la caché era la culpable, puedes desactivarla temporalmente. Es una opción experimental documentada y solo conviene para diagnosticar, porque el arranque se vuelve más lento:

// next.config.js
module.exports = {
  experimental: {
    turbopackFileSystemCacheForDev: false,
  },
}

Variantes y errores relacionados

La ruta de API nueva da 404

Antes de borrar nada, revisa lo básico. Según la documentación de Next.js, un controlador de ruta se define en un archivo llamado route.js o route.ts dentro de app, y exporta funciones con el nombre del método HTTP (GET, POST, etc.). Un archivo con otro nombre, una carpeta mal ubicada o un método no exportado también producen un 404 genuino. Si todo está bien y la ruta sigue sin aparecer, aplica la solución de este artículo.

Los errores no desaparecen tras borrar

Si tsc sigue fallando en archivos que no son generados, el error es real y está en tu código. No lo ocultes con typescript.ignoreBuildErrors: la documentación lo describe como una opción peligrosa, porque permite generar código de producción con errores de tipos.

No se puede borrar la carpeta en Windows

Si el borrado falla por archivos en uso, cierra el servidor, las ventanas de terminal que lo ejecutaban y cualquier proceso de comprobación de tipos, y vuelve a intentarlo.

El CSS global no cambia

Si solo un estilo no cambia y el resto se actualiza, comprueba primero que el archivo editado es el que se importa y que ninguna otra regla lo sobrescribe. Si el valor correcto aparece en una instalación limpia del repositorio (por ejemplo, en CI) pero no en tu equipo, sospecha del estado local y aplica la limpieza de este artículo.

Resumen

En Next.js 16, el desarrollo escribe en .next/dev: allí están los tipos generados y la caché de Turbopack que sobrevive a los reinicios.
Código viejo tras reiniciar, 404 en una ruta nueva o errores de tsc en .next/dev/types suelen indicar estado desfasado, no un fallo de tu cambio.
Detén los procesos y borra .next/dev (o .next completa si hace falta); no necesitas tocar el código.
Regenera el cliente de Prisma si cambió el esquema y revisa el nombre route.ts antes de culpar a la caché.
Verifica con tsc --noEmit y next build; no uses ignoreBuildErrors como parche.

Tutoriales Técnicos

Buscar este blog