TypeScript 7: qué se rompe de verdad al actualizar (y por qué tu build puede seguir en la 6)

El 8 de julio de 2026 TypeScript 7 pasó a estable, y hoy npm install typescript te instala la 7. No es una beta que tengas que pedir: es lo que hay detrás de la etiqueta latest.

Eso significa que puedes acabar en TypeScript 7 sin haberlo decidido — un npm install en un proyecto sin lockfile, un Dependabot que sube el rango, un compañero que clona el repo. Y a diferencia de casi todas las majors anteriores de TypeScript, esta elimina opciones de configuración en vez de solo avisar de que las va a eliminar.

La cabecera es real: el compilador está reescrito en Go y es unas diez veces más rápido. Lo he medido en este mismo sitio y sale 11,1×, con la mitad de memoria. Pero el titular tapa lo importante, que es qué te deja de funcionar el día que subas.

Este artículo es esa lista, con los mensajes de error tal cual los escupe el compilador. Si lo que buscas es qué es TypeScript y por qué usarlo, eso está en la introducción a TypeScript y el tipado estático; aquí vamos directos a lo que se rompe.

Primero: ¿ya te afecta?

Comprueba qué tienes delante:

npx tsc --version
npm view typescript dist-tags

A día de hoy latest es 7.0.2. Si tu package.json dice "typescript": "^6.0.0", estás a salvo: el ^ no salta de major. Si dice "typescript": "*", ">=6" o no fija nada, la próxima instalación limpia te sube.

La distinción que importa: TypeScript 7 no es un compilador nuevo al lado del viejo. Durante la fase de vista previa convivían, y el compilador en Go se instalaba aparte como @typescript/native-preview con el binario tsgo. Desde la RC eso se plegó: el paquete typescript de siempre y el comando tsc de siempre son ya el compilador en Go. No hay que cambiar de comando; hay que cambiar de configuración.

Lo que gana: medido, no copiado del anuncio

Las cifras oficiales son de repositorios enormes — vscode baja de 125,7 s a 10,6 s (11,9×), sentry de 139,8 s a 15,7 s (8,9×), bluesky de 24,3 s a 2,8 s (8,7×). Está muy bien, pero deja la duda obvia: ¿y en un proyecto normal, que no tiene 1,5 millones de líneas?

Lo medí en el código de este sitio: 162 archivos .ts/.tsx, 32 791 líneas, Node 24.16.0 sobre WSL2, mismo tsconfig, mismo hardware, tres corridas y me quedo con la mejor tras un calentamiento.

Dos cosas que conviene decir con honestidad. La primera: la ganancia no depende de tener un monorepo gigante. Un proyecto de 33 000 líneas saca el mismo múltiplo que vscode.

La segunda es la comprobación que hace que la cifra valga algo: los dos compiladores reportaron 305 errores, exactamente los mismos códigos y repartidos en los mismos 76 archivos. Si TypeScript 7 hubiera sido rápido por rendirse antes, se vería aquí. No se rinde antes: hace el mismo trabajo en la undécima parte del tiempo.

En memoria mi caída (−55 %) es bastante mayor que la oficial de vscode (−18 %). No tengo explicación sólida para esa diferencia y no me la voy a inventar; lo dejo como dato medido en un proyecto, no como promesa.

Lo que desaparece del tsconfig.json

Aquí está el grueso de la migración. Estas opciones no están deprecadas: están eliminadas, y el compilador se niega a arrancar.

1. baseUrl — la que te va a tocar a ti

Es, con diferencia, la más extendida. Cualquier proyecto con imports tipo @/components/... la tiene.

{ "compilerOptions": { "baseUrl": "./src", "paths": { "@/*": ["*"] } } }

error TS5102: Option 'baseUrl' has been removed. Please remove it from your configuration.
  Use '"paths": {"*": ["./src/*"]}' instead.
error TS5090: Non-relative paths are not allowed. Did you forget a leading './'?

La solución es reescribir paths relativo a la raíz del proyecto, con ./ delante, y borrar baseUrl:

{ "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }

Ojo con el segundo error, el TS5090: no basta con quitar baseUrl. Si dejas las rutas como ["*"] sin el ./, sigue fallando. Son dos cambios, no uno.

2. target: "es5"

error TS5108: Option 'target=ES5' has been removed. Please remove it from your configuration.

No hay sustituto: si de verdad necesitas salida ES5, ese trabajo pasa a tu bundler o a Babel. El mínimo del compilador ahora es ES2015.

3. downlevelIteration

error TS5102: Option 'downlevelIteration' has been removed. Please remove it from your configuration.

Es la consecuencia natural de lo anterior: solo tenía sentido para bajar iteradores a ES5.

4. moduleResolution: "node" y "classic"

error TS5108: Option 'moduleResolution=node10' has been removed. Please remove it from your configuration.

Fíjate en el detalle: escribes "node" y el error habla de node10. Es el mismo valor con su nombre moderno, así que no te vuelvas loco buscando dónde pusiste node10. Los sustitutos recomendados son nodenext (si resuelves como Node) o bundler (si empaquetas con Vite, esbuild o similar).

5. module: "amd", "umd", "systemjs" y "none"

Este caso merece aviso aparte porque el mensaje despista:

error TS5095: Option 'bundler' can only be used when 'module' is set to 'preserve', 'commonjs', or 'es2015' or later.
error TS5108: Option 'module=AMD' has been removed. Please remove it from your configuration.

El primer error menciona bundler, una opción que tú no escribiste. Aparece porque bundler es ahora la resolución por defecto y choca con el module heredado. El error real es el segundo. Cambia module a esnext o preserve y los dos desaparecen a la vez.

6. Las que ya no pueden valer false

esModuleInterop, allowSyntheticDefaultImports y alwaysStrict siguen existiendo, pero solo en true. Ponerlas en false es error:

error TS5108: Option 'esModuleInterop=false' has been removed. Please remove it from your configuration.
error TS5108: Option 'alwaysStrict=false' has been removed. Please remove it from your configuration.

En la práctica esto solo muerde a proyectos viejos que arrastraban esModuleInterop: false para no tocar imports de CommonJS. Si es tu caso, el trabajo real no es el tsconfig: es cambiar los import * as x from 'y' por import x from 'y'.

Lo que se rompe fuera del tsconfig: la API que no existe

Esta es la parte que hunde más migraciones que todas las opciones anteriores juntas, y no sale en ningún mensaje de error del compilador.

TypeScript 7.0 no publica API programática. El anuncio lo dice sin rodeos: “TypeScript 7.0 does not ship with an API”, y sitúa la nueva —distinta de la actual— en la 7.1.

Cualquier herramienta que no se limite a ejecutar tsc, sino que importe TypeScript para recorrer el AST o pedirle tipos, se queda fuera. Y no falla de forma elegante: el npm install entero aborta.

npm error code ERESOLVE
npm error Found: [email protected]
npm error Could not resolve dependency:
npm error peer typescript@">=4.8.4 <6.1.0" from [email protected]

Ese rango >=4.8.4 <6.1.0 es el que typescript-eslint tiene publicado hoy: excluye la 7 por diseño. Y como npm falla la resolución completa, no se instala nada — ni siquiera TypeScript. No es que se te quede el linter cojo: es que el proyecto no instala.

La lista de afectados por el mismo motivo:

• typescript-eslint — el caso de arriba.
• ts-jest — aquí es peor, porque no falla al instalar sino en tiempo de ejecución, con trazas sobre internos del compilador que ya no existen.
• ts-morph y cualquier generador de código o codemod que manipule el AST.
• Vue, Svelte, MDX y Astro — sus verificadores de tipos de plantilla usan la API. El propio anuncio avisa de que “workflows that use Vue, MDX, Astro, Svelte, and others will likely not yet be able to leverage TypeScript 7”.

Ese último punto no es teórico para mí: este sitio corre Astro 7 y sigue en TypeScript 6.0.3 justamente por esto. @astrojs/check depende de la API. Puedo usar el compilador en Go para medir, pero no puedo poner la 7 en el package.json sin quedarme sin verificación de tipos en los .astro. Si vienes de la guía para actualizar a Astro 7, esta es la pieza que todavía falta.

La trampa del paquete de compatibilidad

Microsoft publicó @typescript/typescript6 para el periodo intermedio: instala TypeScript 6 al lado de la 7 y expone el binario tsc6, para que tus herramientas viejas sigan teniendo su API mientras el build usa la 7.

Funciona. Pero tiene un efecto secundario que no está documentado y que te deja creyendo que migraste cuando no lo hiciste.

Instalé exactamente lo que dice el manual:

{ "devDependencies": { "typescript": "^7.0.2", "@typescript/typescript6": "^6.0.2" } }

Y esto es lo que sale:

$ npm ls typescript
└── [email protected]          # dice que estás en la 7

$ npx tsc --version
Version 6.0.3                 # pero tu build corre la 6

$ node node_modules/typescript/bin/tsc --version
Version 7.0.2                 # la 7 está ahí, solo que nadie la llama

La causa está en cómo se empaqueta la compatibilidad: @typescript/typescript6 depende de "@typescript/old": "npm:typescript@^6" —un alias— y el bin llamado tsc de esa dependencia se queda con el enlace node_modules/.bin/tsc, tapando el de TypeScript 7.

La prueba funcional, con el mismo tsconfig que lleva baseUrl:

# npx tsc  (el que usaría tu script de build)
error TS5101: Option 'baseUrl' is deprecated and will stop functioning in TypeScript 7.0.
              Specify compilerOption '"ignoreDeprecations": "6.0"' to silence this error.

# el binario real de TypeScript 7
error TS5102: Option 'baseUrl' has been removed. Please remove it from your configuration.

Un aviso de deprecación contra un error de eliminación. Si en tu CI ves TS5101, no estás compilando con TypeScript 7, digan lo que digan npm ls y tu package.json.

Cómo asegurarte de cuál corres:

node node_modules/typescript/bin/tsc --version   # la verdad, siempre
npx tsc --version                                # lo que ejecuta tu build

Si no coinciden, apunta tus scripts al binario explícito o quita el paquete de compatibilidad.

Dos detalles pequeños que muerden en CI

El código de salida cambió. Con errores de tipos, TypeScript 6 sale con 2 y TypeScript 7 con 1. Lo comprobé tres veces seguidas y es determinista; sin errores los dos salen 0. Si tienes un script que hace if [ $? -eq 2 ] para distinguir “hay errores de tipos” de “el compilador reventó”, deja de funcionar en silencio.

Ya no hay tsserver. Una instalación limpia de typescript@7 deja únicamente tsc en node_modules/.bin. TypeScript 7 habla LSP, y por eso los editores necesitan soporte propio: VS Code lo trae por extensión y Visual Studio lo activa solo, pero cualquier herramienta que lanzara tsserver a mano hay que revisarla.

Cómo adoptarlo hoy sin romper nada

El consejo que casi nadie está dando bien es que esto no es una decisión de todo o nada. Puedes cobrar el 11× donde vale la pena y dejar el resto quieto hasta la 7.1.

Capa 1 — el chequeo de tipos, ya. Un script separado que use el binario de TypeScript 7 explícitamente, para el npm run typecheck local y para CI. Es donde el 11× se nota de verdad, porque es lo que esperas mirando la terminal.

Capa 2 — el linter y los tests, quietos en TypeScript 6. typescript-eslint, ts-jest y lo que toque el AST siguen en la 6 hasta que publiquen soporte para la API de la 7.1.

El orden de trabajo que menos duele:

1. Limpia el tsconfig primero, aún en TypeScript 6. Quita baseUrl, sube moduleResolution a bundler o nodenext, saca target: es5. Todo eso es válido en la 6, así que puedes hacerlo y desplegarlo sin subir de major. Cuando lo tengas verde, la migración se queda en cambiar un número.
2. Fija la versión. Pon "typescript": "6.0.3" exacto, sin ^, mientras dure la transición. No quieres descubrir el cambio en un npm install de un viernes.
3. Prueba la 7 en una rama, con el binario explícito, y compara la salida de errores contra la 6. Deberían coincidir; si no coinciden, ahí tienes tu lista de trabajo real.
4. Espera a la 7.1 para el resto. Hasta que exista la API nueva y las herramientas la adopten, subir del todo es cambiar 11× de velocidad por quedarte sin linter y sin tests.

Checklist antes de subir

• baseUrl fuera, y paths reescrito con ./ delante.
• moduleResolution en bundler o nodenext (nunca node, node10 ni classic).
• module en esnext o preserve (nunca amd, umd, systemjs ni none).
• target en ES2015 o superior.
• esModuleInterop, allowSyntheticDefaultImports y alwaysStrict sin false.
• Comprobado si tu stack (Vue, Svelte, MDX, Astro) ya soporta la 7.
• Comprobado que npx tsc --version coincide con node node_modules/typescript/bin/tsc --version.
• Revisados los scripts de CI que dependan del código de salida 2.

Conclusión

TypeScript 7 es la mejor actualización de rendimiento que ha tenido el lenguaje: 11× medido en un proyecto pequeño, con la mitad de memoria y sin cambiar una línea de código de aplicación. Eso es real y está al alcance hoy.

Lo que no está al alcance hoy es todo el ecosistema. La API llega en la 7.1, y hasta entonces typescript-eslint, ts-jest y los verificadores de plantillas de Vue, Svelte, MDX y Astro se quedan en la 6.

Así que la respuesta sensata a “¿me actualizo?” es: limpia el tsconfig ya, cobra la velocidad en el chequeo de tipos, y deja el linter y los tests donde están. Y sobre todo, comprueba qué binario corre de verdad tu build — porque la trampa del paquete de compatibilidad hace que muchos proyectos que creen estar en TypeScript 7 sigan compilando con la 6.