feat(shiki): add twoslash support

Author: avivkeller

apps/site/next.config.mjs

@@ -96,6 +96,8 @@ const nextConfig = {
       'shiki',
     ],
   },
+  // TODO(@avivkeller): Why can't this be used without this config?
+  serverExternalPackages: ['twoslash'],
   // If we're building for the Cloudflare deployment we want to set
   // an appropriate deploymentId (needed for skew protection)
   // TODO: The `OPEN_NEXT_CLOUDFLARE` environment variable is being

apps/site/package.json

@@ -73,6 +73,7 @@
     "semver": "~7.7.2",
     "sval": "^0.6.3",
     "tailwindcss": "catalog:",
+    "twoslash": "^0.3.4",
     "vfile": "~6.0.3",
     "vfile-matter": "~5.0.1"
   },

apps/site/pages/en/about/index.mdx

@@ -10,7 +10,7 @@ scalable network applications. In the following "hello world" example, many
 connections can be handled concurrently. Upon each connection, the callback is
 fired, but if there is no work to be done, Node.js will sleep.
 
-```cjs
+```cjs twoslash
 const { createServer } = require('node:http');
 
 const hostname = '127.0.0.1';

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

@@ -22,7 +22,7 @@ Take a look at this code snippet and then we can unpack it together:
   Maintainers note: this code is duplicated in the next article, please keep them in sync
 -->
 
-```ts
+```ts twoslash
 type User = {
   name: string;
   age: number;

apps/site/styles/index.css

@@ -7,4 +7,5 @@
 */
 
 @import '@node-core/ui-components/styles/index.css';
+@import '@node-core/rehype-shiki/styles.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",
+    "./styles.css": "./src/styles.css",
     "./*": "./src/*.mjs"
   },
   "repository": {
@@ -23,6 +24,7 @@
     "@shikijs/core": "^3.8.1",
     "@shikijs/engine-javascript": "^3.8.1",
     "@shikijs/engine-oniguruma": "^3.8.1",
+    "@shikijs/twoslash": "^3.12.1",
     "classnames": "catalog:",
     "hast-util-to-string": "^3.0.1",
     "shiki": "~3.8.1",

packages/rehype-shiki/src/highlighter.mjs

@@ -13,7 +13,7 @@ const DEFAULT_THEME = {
  * Creates a syntax highlighter with utility functions
  * @param {import('@shikijs/core').HighlighterCoreOptions} options - Configuration options for the highlighter
  */
-export const createHighlighter = options => {
+export const createHighlighter = ({ transformers, ...options }) => {
   const shiki = createHighlighterCoreSync({
     themes: [DEFAULT_THEME],
     ...options,
@@ -37,11 +37,12 @@ export const createHighlighter = options => {
    *
    * @param {string} code - The code to highlight
    * @param {string} lang - The programming language to use for highlighting
+   * @param {Record<string, any>} meta - Metadata
    * @returns {string} The inner HTML of the highlighted code
    */
-  const highlightToHtml = (code, lang) =>
+  const highlightToHtml = (code, lang, meta = {}) =>
     shiki
-      .codeToHtml(code, { lang, theme })
+      .codeToHtml(code, { lang, theme, meta, transformers })
       // Shiki will always return the Highlighted code encapsulated in a <pre> and <code> tag
       // since our own CodeBox component handles the <code> tag, we just want to extract
       // the inner highlighted code to the CodeBox
@@ -52,9 +53,10 @@ export const createHighlighter = options => {
    *
    * @param {string} code - The code to highlight
    * @param {string} lang - The programming language to use for highlighting
+   * @param {Record<string, any>} meta - Metadata
    */
-  const highlightToHast = (code, lang) =>
-    shiki.codeToHast(code, { lang, theme });
+  const highlightToHast = (code, lang, meta = {}) =>
+    shiki.codeToHast(code, { lang, theme, meta, transformers });
 
   return {
     shiki,

packages/rehype-shiki/src/index.mjs

@@ -1,5 +1,6 @@
 import { createJavaScriptRegexEngine } from '@shikijs/engine-javascript';
 import { createOnigurumaEngine } from '@shikijs/engine-oniguruma';
+import { transformerTwoslash } from '@shikijs/twoslash';
 import cLanguage from 'shiki/langs/c.mjs';
 import coffeeScriptLanguage from 'shiki/langs/coffeescript.mjs';
 import cPlusPlusLanguage from 'shiki/langs/cpp.mjs';
@@ -19,6 +20,11 @@ import { createHighlighter } from './highlighter.mjs';
 
 const { shiki, getLanguageDisplayName, highlightToHast, highlightToHtml } =
   createHighlighter({
+    transformers: [
+      transformerTwoslash({
+        explicitTrigger: true,
+      }),
+    ],
     // We use the faster WASM engine on the server instead of the web-optimized version.
     //
     // Currently we fall back to the JavaScript RegEx engine

packages/rehype-shiki/src/plugin.mjs

@@ -10,28 +10,28 @@ import { highlightToHast } from './index.mjs';
 // to attribute the current language of the <pre> element
 const languagePrefix = 'language-';
 
+// The regex to match metadata
+const rMeta = /(\w+)(?:=(?:"([^"]+)"|(\S+)))?/g;
+
 /**
- * Retrieve the value for the given meta key.
- *
- * @example - Returns "CommonJS"
- * getMetaParameter('displayName="CommonJS"', 'displayName');
- *
- * @param {any} meta - The meta parameter.
- * @param {string} key - The key to retrieve the value.
- *
- * @return {string | undefined} - The value related to the given key.
+ * Parses a fenced code block metadata string into a JavaScript object.
+ * @param {string} meta - The metadata string from a Markdown code fence.
+ * @returns {Record<string, string|boolean>} An object representing the metadata.
  */
-function getMetaParameter(meta, key) {
-  if (typeof meta !== 'string') {
-    return;
+function parseMeta(meta) {
+  const obj = { __raw: meta };
+
+  if (!meta) {
+    return obj;
   }
 
-  const matches = meta.match(new RegExp(`${key}="(?<parameter>[^"]*)"`));
-  const parameter = matches?.groups.parameter;
+  let match;
+
+  while ((match = rMeta.exec(meta)) !== null) {
+    obj[match[1]] = match[2] ?? match[3] ?? true;
+  }
 
-  return parameter !== undefined && parameter.length > 0
-    ? parameter
-    : undefined;
+  return obj;
 }
 
 /**
@@ -65,11 +65,7 @@ export default function rehypeShikiji() {
 
       while (isCodeBlock(parent?.children[currentIndex])) {
         const codeElement = parent?.children[currentIndex].children[0];
-
-        const displayName = getMetaParameter(
-          codeElement.data?.meta,
-          'displayName'
-        );
+        const meta = parseMeta(codeElement.data?.meta);
 
         // We should get the language name from the class name
         if (codeElement.properties.className?.length) {
@@ -80,18 +76,13 @@ export default function rehypeShikiji() {
         }
 
         // Map the display names of each variant for the CodeTab
-        displayNames.push(displayName?.replaceAll('|', '') ?? '');
+        displayNames.push(meta.displayName?.replaceAll('|', '') ?? '');
 
         codeTabsChildren.push(parent?.children[currentIndex]);
 
         // If `active="true"` is provided in a CodeBox
         // then the default selected entry of the CodeTabs will be the desired entry
-        const specificActive = getMetaParameter(
-          codeElement.data?.meta,
-          'active'
-        );
-
-        if (specificActive === 'true') {
+        if (meta.active === 'true') {
           defaultTab = String(codeTabsChildren.length - 1);
         }
 
@@ -162,30 +153,35 @@ export default function rehypeShikiji() {
         return;
       }
 
+      // Get the metadata
+      const meta = parseMeta(preElement.data?.meta);
+
       // Retrieve the whole <pre> contents as a parsed DOM string
       const preElementContents = toString(preElement);
 
       // Grabs the relevant alias/name of the language
       const languageId = codeLanguage.slice(languagePrefix.length);
 
       // Parses the <pre> contents and returns a HAST tree with the highlighted code
-      const { children } = highlightToHast(preElementContents, languageId);
+      const { children } = highlightToHast(
+        preElementContents,
+        languageId,
+        meta
+      );
 
       // Adds the original language back to the <pre> element
       children[0].properties.class = classNames(
         children[0].properties.class,
         codeLanguage
       );
 
-      const showCopyButton = getMetaParameter(
-        preElement.data?.meta,
-        'showCopyButton'
-      );
-
       // Adds a Copy Button to the CodeBox if requested as an additional parameter
       // And avoids setting the property (overriding) if undefined or invalid value
-      if (showCopyButton && ['true', 'false'].includes(showCopyButton)) {
-        children[0].properties.showCopyButton = showCopyButton;
+      if (
+        meta.showCopyButton &&
+        ['true', 'false'].includes(meta.showCopyButton)
+      ) {
+        children[0].properties.showCopyButton = meta.showCopyButton;
       }
 
       // Replaces the <pre> element with the updated one

packages/rehype-shiki/src/styles.css

@@ -0,0 +1 @@
+@import "@shikijs/twoslash/style-rich.css"