feat: enable Twoslash on Cloudflare

[dario-piotrowicz]

Description

Note

Disclaimer, This PR has been authored mostly by Claude Opus 4.6 with minor tweaks from me.
It does seem to work and the code makes sense to me.

Enables twoslash to work on Cloudflare (previously it would only work on the Vercel deployment):

Validation

See: https://nodejs-website.dario-test.workers.dev/en

Related Issues

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run pnpm format to ensure the code follows the style guide.
• I have run pnpm test to check if all tests are passing.
• I have run pnpm build to check if the website builds without errors.
• I've covered new added functionality with unit tests if necessary.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
nodejs-org	Ready	Preview	Apr 23, 2026 9:39am

[cursor]

PR Summary

Medium Risk
Introduces a new generated artifact and changes MDX syntax-highlighting/Twoslash execution paths across environments; risk is mainly build/runtime regressions on Cloudflare or mismatched TypeScript declaration bundling.

Overview
Enables Twoslash-powered code annotations during MDX rendering on Cloudflare Workers by switching to a virtual-filesystem-backed twoslasher instead of disabling Twoslash in that environment.

Adds a build-time script that bundles TypeScript lib.*.d.ts files and @types/node declarations into generated/twoslash-fsmap.json, wires it into prebuild/Turbo task dependencies (including Cloudflare build), and updates the Twoslash transformer to accept an injected twoslasher via createTransformerFactory to avoid Node filesystem assumptions. Also ignores apps/site/generated in git.

^{Reviewed by Cursor Bugbot for commit 841a898. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

👋 Codeowner Review Request

The following codeowners have been identified for the changed files:

Team reviewers: @nodejs/nodejs-website @nodejs/web-infra

Please review the changes when you have a chance. Thank you! 🙏

[dario-piotrowicz]

@avivkeller 🙂

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 73.85%. Comparing base (a26c508) to head (841a898).
⚠️ Report is 2 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8837      +/-   ##
==========================================
- Coverage   73.90%   73.85%   -0.05%     
==========================================
  Files         105      105              
  Lines        8889     8889              
  Branches      326      327       +1     
==========================================
- Hits         6569     6565       -4     
- Misses       2319     2323       +4     
  Partials        1        1              

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

[Copilot]

Pull request overview

Enables Twoslash-powered code annotations in the Cloudflare Workers deployment by providing a virtual filesystem (VFS) twoslasher and wiring in a build-time generated TypeScript/@types map, while updating the rehype-shiki Twoslash transformer to accept a custom twoslasher.

Changes:

• Add a VFS-backed Twoslash setup for Cloudflare that loads a pre-generated twoslash-fsmap.json.
• Introduce a build script (and Turbo task dependency) to generate the VFS map before Cloudflare worker builds.
• Update @node-core/rehype-shiki’s Twoslash transformer to support options.twoslasher via createTransformerFactory.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/rehype-shiki/src/transformers/twoslash/index.mjs	Adds support for passing a custom twoslasher (Cloudflare-compatible path).
apps/site/mdx/plugins.mjs	Enables Twoslash on Cloudflare by creating a VFS-based twoslasher and passing it through twoslashOptions.
apps/site/scripts/twoslash-fsmap/index.mjs	New script to write the generated VFS map JSON to apps/site/generated/.
apps/site/scripts/twoslash-fsmap/generate.mjs	New generator that builds a map of TS lib + @types/node declaration files.
apps/site/turbo.json	Adds build:twoslash-fsmap task and makes Cloudflare worker build depend on it.
apps/site/package.json	Adds build:twoslash-fsmap script entry.
.gitignore	Ignores apps/site/generated/ build artifacts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 841a898. Configure here.}

[ovflowd]

Not fan of this diff/approach. Let's keep Twoslash disabled for now in Cloudflare and discuss our options.