feat(shiki): add twoslash support

Author: avivkeller

apps/site/mdx/components.mjs

@@ -3,6 +3,11 @@
 import BadgeGroup from '@node-core/ui-components/Common/BadgeGroup';
 import Blockquote from '@node-core/ui-components/Common/Blockquote';
 import MDXCodeTabs from '@node-core/ui-components/MDX/CodeTabs';
+import {
+  MDXTooltip,
+  MDXTooltipContent,
+  MDXTooltipTrigger,
+} from '@node-core/ui-components/MDX/Tooltip';
 
 import Button from '#site/components/Common/Button';
 import LinkWithArrow from '#site/components/Common/LinkWithArrow';
@@ -48,6 +53,10 @@ export default {
   img: MDXImage,
   // Renders MDX CodeTabs
   CodeTabs: MDXCodeTabs,
+  // Renders Tooltips
+  MDXTooltip,
+  MDXTooltipContent,
+  MDXTooltipTrigger,
   // Renders a Download Button
   DownloadButton,
   // Renders a stateless Release Select Component

apps/site/mdx/plugins.mjs

@@ -9,6 +9,12 @@ import readingTime from 'remark-reading-time';
 
 import remarkTableTitles from '../util/table';
 
+// TODO(@avivkeller): When available, use `OPEN_NEXT_CLOUDFLARE` environment
+// variable for detection instead of current method, which will enable better
+// tree-shaking.
+// Reference: https://github.com/nodejs/nodejs.org/pull/7896#issuecomment-3009480615
+const OPEN_NEXT_CLOUDFLARE = 'Cloudflare' in global;
+
 /**
  * Provides all our Rehype Plugins that are used within MDX
  */
@@ -19,7 +25,21 @@ export const rehypePlugins = [
   [rehypeAutolinkHeadings, { behavior: 'wrap' }],
   // Transforms sequential code elements into code tabs and
   // adds our syntax highlighter (Shikiji) to Codeboxes
-  rehypeShikiji,
+  [
+    rehypeShikiji,
+    {
+      // We use the faster WASM engine on the server instead of the web-optimized version.
+      //
+      // Currently we fall back to the JavaScript RegEx engine
+      // on Cloudflare workers because `shiki/wasm` requires loading via
+      // `WebAssembly.instantiate` with custom imports, which Cloudflare doesn't support
+      // for security reasons.
+      wasm: !OPEN_NEXT_CLOUDFLARE,
+
+      // TODO(@avivkeller): Find a way to enable Twoslash w/ a VFS on Cloudflare
+      twoslash: !OPEN_NEXT_CLOUDFLARE,
+    },
+  ],
 ];
 
 /**

apps/site/next.config.mjs

@@ -51,6 +51,16 @@ const nextConfig = {
       },
     ],
   },
+  serverExternalPackages: ['twoslash'],
+  outputFileTracingIncludes: {
+    // Twoslash needs TypeScript declarations to function, and, by default,
+    // Next.js strips them for brevity. Therefore, they must be explicitly
+    // included.
+    '/*': [
+      '../../node_modules/.pnpm/typescript@*/node_modules/typescript/lib/*.d.ts',
+      './node_modules/@types/node/**/*',
+    ],
+  },
   // On static export builds we want the output directory to be "build"
   distDir: ENABLE_STATIC_EXPORT ? 'build' : undefined,
   // On static export builds we want to enable the export feature

apps/site/package.json

@@ -74,6 +74,7 @@
     "semver": "~7.7.2",
     "sval": "^0.6.3",
     "tailwindcss": "catalog:",
+    "twoslash": "^0.3.4",
     "unist-util-visit": "^5.0.0",
     "vfile": "~6.0.3",
     "vfile-matter": "~5.0.1"

apps/site/pages/en/learn/typescript/introduction.md

@@ -70,16 +70,15 @@ npm add --save-dev @types/node
 
 These type definitions allow TypeScript to understand Node.js APIs and provide proper type checking and autocompletion when you use functions like `fs.readFile` or `http.createServer`. For example:
 
-```js
-import * as fs from 'fs';
-
-fs.readFile('example.txt', 'foo', (err, data) => {
-  //                          ^^^ Argument of type '"foo"' is not assignable to parameter of type …
-  if (err) {
-    throw err;
-  }
-  console.log(data);
-});
+<!-- prettier-ignore -->
+```ts
+// @noErrors
+/* eslint-disable */
+// ---cut---
+import fs from 'fs';
+
+fs.read
+//     ^|
 ```
 
 Many popular JavaScript libraries have their type definitions available under the `@types` namespace, maintained by the DefinitelyTyped community. This enables seamless integration of existing JavaScript libraries with TypeScript projects.

apps/site/pages/en/learn/typescript/publishing-a-ts-package.md

@@ -126,9 +126,9 @@ A note about directory organisation: There are a few common practices for placin
 The purpose of types is to warn an implementation will not work:
 
 ```ts
+// @errors: 2322
 const foo = 'a';
 const bar: number = 1 + foo;
-//    ^^^ Type 'string' is not assignable to type 'number'.
 ```
 
 TypeScript has warned that the above code will not behave as intended, just like a unit test warns that code does not behave as intended. They are complementary and verify different things—you should have both.

apps/site/pages/en/learn/typescript/transpile.md

@@ -71,6 +71,7 @@ If you have type errors in your TypeScript code, the TypeScript compiler will ca
 We will modify our code like this, to voluntarily introduce a type error:
 
 ```ts
+// @errors: 2322 2554
 type User = {
   name: string;
   age: number;
@@ -88,31 +89,4 @@ const justine: User = {
 const isJustineAnAdult: string = isAdult(justine, "I shouldn't be here!");
 ```
 
-And this is what TypeScript has to say about this:
-
-```console
-example.ts:12:5 - error TS2322: Type 'string' is not assignable to type 'number'.
-
-12     age: 'Secret!',
-       ~~~
-
-  example.ts:3:5
-    3     age: number;
-          ~~~
-    The expected type comes from property 'age' which is declared here on type 'User'
-
-example.ts:15:7 - error TS2322: Type 'boolean' is not assignable to type 'string'.
-
-15 const isJustineAnAdult: string = isAdult(justine, "I shouldn't be here!");
-         ~~~~~~~~~~~~~~~~
-
-example.ts:15:51 - error TS2554: Expected 1 arguments, but got 2.
-
-15 const isJustineAnAdult: string = isAdult(justine, "I shouldn't be here!");
-                                                     ~~~~~~~~~~~~~~~~~~~~~~
-
-
-Found 3 errors in the same file, starting at: example.ts:12
-```
-
 As you can see, TypeScript is very helpful in catching bugs before they even happen. This is one of the reasons why TypeScript is so popular among developers.

apps/site/styles/index.css

@@ -7,4 +7,5 @@
 */
 
 @import '@node-core/ui-components/styles/index.css';
+@import '@node-core/rehype-shiki/index.css';
 @import './locales.css';

packages/rehype-shiki/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@node-core/rehype-shiki",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "exports": {
     ".": "./src/index.mjs",
+    "./index.css": "./src/index.css",
     "./*": "./src/*.mjs"
   },
   "repository": {
@@ -23,6 +24,7 @@
     "@shikijs/core": "^3.12.0",
     "@shikijs/engine-javascript": "^3.12.0",
     "@shikijs/engine-oniguruma": "^3.12.0",
+    "@shikijs/twoslash": "^3.12.2",
     "classnames": "catalog:",
     "hast-util-to-string": "^3.0.1",
     "shiki": "~3.12.0",

packages/rehype-shiki/src/__tests__/highlighter.test.mjs

@@ -20,33 +20,7 @@ mock.module('shiki/themes/nord.mjs', {
 });
 
 describe('createHighlighter', async () => {
-  const { createHighlighter } = await import('../highlighter.mjs');
-
-  describe('getLanguageDisplayName', () => {
-    it('returns display name for known languages', () => {
-      const langs = [
-        { name: 'javascript', displayName: 'JavaScript', aliases: ['js'] },
-      ];
-      const highlighter = createHighlighter({ langs });
-
-      assert.strictEqual(
-        highlighter.getLanguageDisplayName('javascript'),
-        'JavaScript'
-      );
-      assert.strictEqual(
-        highlighter.getLanguageDisplayName('js'),
-        'JavaScript'
-      );
-    });
-
-    it('returns original name for unknown languages', () => {
-      const highlighter = createHighlighter({ langs: [] });
-      assert.strictEqual(
-        highlighter.getLanguageDisplayName('unknown'),
-        'unknown'
-      );
-    });
-  });
+  const { default: createHighlighter } = await import('../highlighter.mjs');
 
   describe('highlightToHtml', () => {
     it('extracts inner HTML from code tag', () => {