TypeScript 7.1's Content Mappers Actually Work — I Type-Checked a Real .vue File in 3 Tries

TypeScript 7.1 is supposed to land its release candidate today, November 10. The headline feature for anyone who writes Vue, Svelte, Astro, or MDX is content mappers: a plug-in point that lets TypeScript understand files that embed TypeScript inside another format, and map errors back to the right line in the original file.

The announcement post from October 20 says the example mapper package, @vue/content-mapper, is "not currently on npm." So I went to find out what's actually true on the morning of the RC: install the beta, write a real .vue file with a real type error in it, and see what happens.

Try 1: install the beta, check what version that even is

npm install -D typescript@beta
./node_modules/.bin/tsc --version
# Version 7.1.0-beta

That was the first surprise. On the morning of November 10, typescript@beta still resolves to 7.1.0-beta — the same beta from October 20. I checked the dist-tags: latest is 7.0.2, beta is 7.1.0-beta, rc still points at 7.0.1-rc, and next is a dev build dated November 9. So the 7.1 RC the iteration plan promised for today hasn't landed on npm yet, at least not by the time I ran this (around 12:15 Dhaka time). Everything below is the beta, not the RC. If you try this after the RC drops, your version string will differ.

Node 24.22.1, npm 10.9.4, on a small Linux VM. That's the whole machine context; nothing here needed more than that.

Try 2: the config from the announcement, verbatim

The announcement's example config looks like this:

{
  "compilerOptions": { "strict": true },
  "contentMappers": [
    { "package": "@vue/content-mapper", "extensions": [".vue"] }
  ]
}

I wrote a Counter.vue with a deliberate mistake buried in the script block — const label: string = 42 — and a tsconfig.json following that example, then ran tsc:

error TS18003: No inputs were found in config file 'tsconfig.json'.
tsconfig.json(8,3): error TS18068: Content mappers require the
'--runExternalCode' command line flag to be enabled.

Two errors, and both are doing exactly what the announcement says they should. Content mappers are effectively arbitrary executables that TypeScript dispatches to, so tsc refuses to run them without an explicit opt-in. The flag is --runExternalCode, and you have to pass it on the command line — it can't live in the tsconfig. Without it, TypeScript doesn't even see the .vue file as an input, which is why TS18003 shows up alongside it.

So I ran it again with the flag:

error TS18003: No inputs were found in config file 'tsconfig.json'.
tsconfig.json(9,18): error TS18075: The content mapper package
'@vue/content-mapper' could not be resolved.

TS18075. The package wasn't installed, and tsc tells you so instead of silently skipping your Vue files. That's the correct failure mode — a silent skip would be far worse — but it also confirmed the announcement's warning: the mapper is a separate package, and nothing ships it for you.

Try 3: the package that "isn't on npm" is on npm

Here's where the announcement is out of date. I ran npm view @vue/content-mapper version expecting a 404. It returned 4.0.0-alpha.0.

So I installed it, plus Vue itself for the ref import:

npm install -D @vue/[email protected] vue@3
./node_modules/.bin/tsc -p tsconfig.json --runExternalCode

And this time:

Counter.vue(8,7): error TS2322: Type 'number' is not assignable to type 'string'.

That's the planted error, caught, with the position mapped back to line 8, column 7 of the .vue file — the exact line where const label: string = 42 sits inside the <script setup> block. The mapper extracted the script, TypeScript checked it, and the diagnostic landed on the original file. No vue-tsc, no separate binary.

To make sure it wasn't just erroring on everything, I fixed the line to const label: string = "forty-two" and ran it again. Exit code 0. Clean pass.

What this actually means, and what it doesn't

What works, today, on the beta: the contentMappers key in tsconfig, the --runExternalCode gate, the Vue mapper package at 4.0.0-alpha.0, and real type errors mapped back to the right line in a .vue file. That's the whole loop, and it took three tries and about ten minutes, most of it waiting on npm.

What it doesn't mean: this is alpha software on a beta compiler. The mapper package is version 4.0.0-alpha.0 — Vue Language Tools territory, and the announcement itself says prototypes exist for Astro, CSS Modules, Ember, MDX, Svelte, and Vue, with the Vue one as the example. If your framework's mapper isn't published yet, the config will fail with TS18075 and your files won't be checked at all. Don't adopt contentMappers until the package for your framework exists, and when you do, add --runExternalCode to CI explicitly — the compiler will not run mappers without it, by design.

Two practical notes from the announcement worth repeating. In VS Code, mappers need workspace trust and mapper permissions, and they can be switched off with js/ts.contentMappers.enabled. And there's a known workflow wrinkle where saving a mapper config can leave types stale until the language server restarts — tracked on GitHub, not something I hit in a one-file test.

The bigger picture is the one the TypeScript team keeps coming back to: 7.0 shipped the Go-based native compiler without a programmatic API, and 7.1 is the release that gives tool authors their hooks back. Content mappers are the framework-facing half of that. Volar's model — extract the embedded code, check it, map diagnostics back — is now a first-class citizen instead of a separate toolchain bolted on the side.

I'll keep the test project around and re-run it when the RC actually lands. If the version string changes or the alpha mapper breaks, that's a follow-up post. For now: the feature works, the docs were honest about the sharp edges, and the one claim that turned out wrong — "not on npm" — turned out wrong in the good direction.

Versions and outputs above are from my own machine, November 10, 2026: typescript@beta = 7.1.0-beta, @vue/content-mapper = 4.0.0-alpha.0, Node 24.22.1, npm 10.9.4. The config shape and the --runExternalCode requirement are from the TypeScript 7.1 Beta announcement (October 20, 2026).