feat(shiki): add twoslash support

[avivkeller]

Fixes#7932

---

Introduces @shikijs/twoslash support in @node-core/rehype-shiki. Since twoslash depends on TypeScript declaration files, it cannot be bundled and must instead be listed under serverExternalPackages.

Because TypeScript declarations aren’t imported like regular files (they’re loaded through a TSVFS), they need to be explicitly included in the output bundle.

Because Cloudflare doesn't support WASM or Top-Level awaits, rehype-shiki has been rewritten to not rely on them.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
nodejs-org	Ready	Preview	Oct 11, 2025 1:26pm

[codecov]

Codecov Report

❌ Patch coverage is 45.56962% with 86 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.39%. Comparing base (11fa0e5) to head (b1e201d).
⚠️ Report is 7 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/rehype-shiki/src/index.mjs	11.39%	70 Missing ⚠️
packages/rehype-shiki/src/plugin.mjs	76.74%	10 Missing ⚠️
packages/rehype-shiki/src/highlighter.mjs	80.00%	6 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #8132 +/- ##
==========================================
- Coverage 76.64% 76.39% -0.26% 
==========================================
Files 115 115 Lines 9623 9643 +20 Branches 322 317 -5 ==========================================
- Hits 7376 7367 -9 - Misses 2246 2275 +29 
Partials 1 1 

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[AugustinMauroy]

Hype 😁 !

[avivkeller]

Locally:

[Copilot]

Pull Request Overview

This PR adds TypeScript TwoSlash support to the syntax highlighting system, enabling interactive TypeScript error displays and type information tooltips in code blocks.

Key Changes:

• Integrated TwoSlash transformer for TypeScript/JavaScript code highlighting
• Refactored metadata parsing system from string-based to object-based approach
• Added CSS styling for TwoSlash popup containers and error displays

Reviewed Changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/rehype-shiki/src/index.mjs	Added TwoSlash transformer import and configuration
packages/rehype-shiki/src/highlighter.mjs	Updated functions to accept metadata parameter and pass transformers
packages/rehype-shiki/src/plugin.mjs	Replaced string-based metadata parsing with comprehensive object-based system
packages/rehype-shiki/src/twoslash.css	Added CSS styling for TwoSlash popup containers
packages/rehype-shiki/package.json	Added TwoSlash dependency and exported CSS file
packages/ui-components/src/Common/BaseCodeBox/index.module.css	Added CSS transforms for proper positioning
apps/site/next.config.mjs	Configured external packages and file tracing for TwoSlash
apps/site/package.json	Added twoslash dependency
apps/site/styles/index.css	Imported TwoSlash CSS styles
apps/site/pages/en/learn/typescript/transpile.md	Updated TypeScript example to use TwoSlash error annotations

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[jakebailey]

Is this all server side?

I'm asking because given the TS port to Go, I'm not sure what the deal will be for shiki on the web; probably having to include a large Go binary in Wasm to work with all of the fancy stuff if not prerendered...

[avivkeller]

@nodejs/nodejs-website @nodejs/web-infra for reviews. Currently, this is disabled on CF, but there's a TODO to enable it.

[AugustinMauroy]

Light/dark theme didn't work well but I didn't see why

[avivkeller]

I'll get to Augustin's review today, @nodejs/web any other comments / concerns

[flakey5]

thank you!

[avivkeller]

I need an @nodejs/nodejs-website approval, and then I'll rebase

[ovflowd]

This feels like some voodoo wizardry and so prone of going wrong I guess

[avivkeller]

How so? The RegEx (AFAICT) is pretty robust.

[ovflowd]

This regex pattern seems to be vulnerable to ReDoS.

[avivkeller]

I don't think it is:

[ovflowd]

Does this need to be on the same file?

[avivkeller]

Ideally yes, the index.mjsLANGS and the minimal.mjsLANGS

[ovflowd]

IDK, feels like this should have a dedicated langs.mjs file tho

[avivkeller]

I don't think so. The index.mjs exports all of the highlighting utilities needed for our server, and the minimal.mjs exports all for our client. A langs.mjs file for index.mjs doesn't make sense to me.

WDYT @nodejs/nodejs-website

[ovflowd]

These should all be separated files

[ovflowd]

Also are these client components? This file should only contain server components. There's another file for client components no?

[avivkeller]

No, we merged them into a single file in #8167

[ovflowd]

I have a few reservations, would love some comments to be addressed and some benchmark images of build times / bundle sizes with this addition.

This is a cool visual addition but if it's to heavy, might not be worth it.

[avivkeller]

I have a few reservations, would love some comments to be addressed and some benchmark images of build times / bundle sizes with this addition.

The bundle is a bit bigger, since it needs to load the extra JS (See #8160). The most recent Twoslash build took ~1:33, almost identical to the most recent main build (~1:29)

[ovflowd]

Bypassing ownership from typescript team as it is a false positive.