Si desarrollas interfaces en Vue 3 con TypeScript, seguro que recuerdas el suplicio que ha sido durante años comprobar los tipos dentro de los Single File Components (.vue).
Como el compilador oficial tsc de Microsoft no sabía nada de archivos .vue y solo entendía .ts y .tsx, la comunidad tuvo que ingeniárselas por su cuenta. Así nació vue-tsc, una capa ingeniosa creada por Johnson Chu, autor de Volar. La utilidad tiraba de un monkey-patching sofisticado: interceptaba al vuelo métodos internos del runtime en Node.js del compilador de TypeScript, le colaba archivos virtuales y sacaba los errores hacia fuera.
Funcionaba lento, se rompía cada dos por tres con actualizaciones menores del lenguaje y mantenía un ecosistema frágil de forks. Pero la verdadera crisis estalló cuando Microsoft reescribió por completo el compilador TypeScript 7 en Go para multiplicar por diez la velocidad de compilación. El viejo truco de parchear métodos en el runtime JavaScript del compilador pasó a ser técnicamente imposible de la noche a la mañana.
La respuesta a ese callejón sin salida es el mecanismo oficial TypeScript 7.1 Content Mappers, cuyo análisis detallado ha publicado el desarrollador Alex Opa en VueDigest. Este sistema abre soporte nativo directo para formatos de archivo externos dentro del propio compilador tsc.
Un callejón histórico sin salida: cómo vue-tsc forzaba el compilador y por qué Go lo cambió todo
Para valorar la magnitud del salto, miremos bajo el capó del viejo esquema con vue-tsc.
Al lanzar vue-tsc --noEmit, el comando arrancaba su propia instancia de Node.js. Leía cada archivo .vue, lo dividía en sus tres bloques (<template>, <script> y <style>), generaba a partir de la plantilla un código TypeScript virtual de la función de renderizado con sus sourcemaps y, usando APIs privadas no documentadas del compilador, inyectaba ese código virtual en el árbol de dependencias.
El peaje era enorme:
- El consumo de memoria RAM en monorepos grandes superaba con facilidad los 4–8 GB.
- En pipelines de CI/CD, el chequeo de tipos tardaba 3–5 minutos, por lo que muchos equipos acababan desactivando el
typechecken los hooks de pre-commit y dejaban pasar errores tontos a producción. - Desfase de versiones: podías actualizar
typescripten tu proyecto, perovue-tscseguía arrastrando un motor anterior y las novedades sintácticas de TS no funcionaban en las plantillas.
El salto de TypeScript 7 a un binario nativo en Go puso a la comunidad ante una disyuntiva clara: o tsc ofrecía una API oficial de plugins, o Vue se quedaba sin verificación de tipos en el nuevo compilador. El equipo de TypeScript recogió el guante e introdujo los Content Mappers.
Anatomía de Content Mappers: código virtual y llamada nativa a tsc
¿Cómo funciona el nuevo mecanismo? Ahora el propio compilador tsc sabe delegar la lectura de archivos no estándar a mapeadores externos a través de la sección plugins de tsconfig.json.
Cuando tsc encuentra un archivo MyComponent.vue, entrega su contenido al plugin registrado @vue/language-plugin-content-mapper. El plugin transforma la plantilla y el bloque <script setup lang="ts"> en un archivo TypeScript virtual dentro de la memoria del compilador, manteniendo mapeadas con exactitud todas las posiciones de caracteres y números de línea respecto al .vue original.
El resultado es que la comprobación de tipos se ejecuta directamente con el compilador oficial:
# Comprobación de tipos nativa directa en un proyecto Vue con el tsc oficial
tsc --noEmit --runExternalCode
Sin binarios paralelos ni forks del compilador. Si la verificación pasa, tienes la certeza al 100 % de que tu código cumple con la especificación oficial de TypeScript.
El parámetro --runExternalCode es obligatorio: el compilador de TypeScript exige confirmación explícita del desarrollador para ejecutar código JavaScript externo de un plugin mapeador durante la compilación.
Benchmark sobre Directus: 4.6 veces más rápido y 1100 errores estrictos detectados
El desarrollador Alex Opa realizó una prueba a gran escala migrando a TypeScript 7.1 Content Mappers la base de código del popular CMS headless Directus, un proyecto con cientos de componentes Vue complejos, directivas personalizadas y módulos de servicio.
Los resultados del benchmark hablan por sí solos:
- Velocidad de verificación: el tiempo total del chequeo de tipos cayó 4.6 veces frente a
vue-tsc. Lo que antes dejaba la consola bloqueada un par de minutos ahora termina en segundos. - Rigor del tipado: el nuevo pipeline detectó más de 1 100 errores, frente a los 445 que encontraba el antiguo
vue-tsc.
¿Por qué afloraron tantos fallos ocultos? Por las limitaciones del monkey-patching, vue-tsc hacía numerosas concesiones heurísticas y pasaba por alto desajustes de tipos en casos límite de las plantillas. El compilador nativo tsc valida props, eventos $emit y slots sin hacer excepciones.
Configuración paso a paso de tsconfig.json y salto al nuevo estándar
Para migrar un proyecto existente de Vue 3 bastan tres pasos sencillos:
- Desinstalamos
vue-tsce instalamos el nuevo TypeScript junto al plugin de lenguaje:
npm uninstall vue-tsc
npm install -D typescript@^7.1.0 @vue/language-plugin-content-mapper@next
- Registramos el plugin de mapeo de contenido en la sección
compilerOptionsdetsconfig.json:
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"noEmit": true,
"plugins": [
{
"name": "@vue/language-plugin-content-mapper",
"extensions": [".vue"]
}
]
},
"include": [
"src/**/*.ts",
"src/**/*.d.ts",
"src/**/*.vue"
]
}
- Actualizamos el comando en la sección
scriptsdepackage.json:
{
"scripts": {
"typecheck": "tsc --noEmit --runExternalCode"
}
}
La llegada de Content Mappers marca un antes y un después para todo el ecosistema Vue. Los archivos .vue pasan a ser ciudadanos de pleno derecho dentro de TypeScript, dejando atrás parches frágiles y regalando tiempos de verificación fulgurantes en CI/CD.

