🦄 Next.js 16.3 — the upgrade we took, and the one we didn't

Hey everyone 👋

Both of our Mantine documentation starters are now on Next.js 16.3 — the Nextra one and the Fumadocs one, shipped together today. Dependency-only patches, nothing to migrate.

What actually got better

• Repeat builds are roughly 2.8× faster — 17.8s cold against 8.0s warm on our Nextra template. Turbopack's FileSystem Cache now covers next build, not just next dev, and it's on by default.

• Long dev sessions use dramatically less RAM.

• The App Router renders through native Node streams instead of web streams.

The part I actually want to talk about

We tried to take TypeScript 7 in the same pass, and reverted it. Not because it's slow — it type-checked an entire template in about a second, zero errors. Because it isn't a version bump at all: it's a different package. TypeScript 7 no longer ships the JavaScript compiler API. The typescript package now exports only version metadata, and the whole API moved to typescript/unstable/* subpaths.

So every tool doing import ts from 'typescript' receives a two-key object. For a documentation toolchain that's most of it. Ours died on twoslash, pulled in by Nextra, which calls the removed API at module load — so it throws even on a site with zero twoslash code blocks, and there's no flag to turn it off.

The dritta, if you're about to try it

A permissive peer range hides this completely. @shikijs/twoslash declares typescript: >=5.5.0 with no upper bound, so your install won't warn you at all — it's the underlying twoslash that says ^5.5.0 || ^6.0.0. And you'll need Yarn 4.18 just to install TS 7, because Yarn's builtin compatibility patch looks for a file the new package no longer contains.

There's a second lesson we paid for. Turbopack's build cache is on by default now and does not invalidate when node_modules changes. After swapping a dependency back to a working version, our build kept failing with the old error, pointing at a line that no longer existed on disk. It was replaying a cached result. The passing direction is the scary one: a build that goes green in CI without reflecting what's installed.

Curious about two things

Has anyone got TypeScript 7 working in a docs toolchain yet, or is everyone waiting on the ecosystem to move to the unstable/* API? And is anyone leaning on Turbopack's build cache in CI — how are you keying it?

Nextra template · Fumadocs template · Next.js 16.3 release notes · twoslash tracking issue