feat(shiki): add twoslash support

Author: avivkeller

apps/site/next.config.mjs

@@ -51,6 +51,15 @@ 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
+    // incldued.
+    '/*': [
+      '../../node_modules/.pnpm/typescript@*/node_modules/typescript/lib/*.d.ts',
+    ],
+  },
   // 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

@@ -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/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/twoslash.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",
+    "./twoslash.css": "./src/twoslash.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/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,13 @@ import { createHighlighter } from './highlighter.mjs';
 
 const { shiki, getLanguageDisplayName, highlightToHast, highlightToHtml } =
   createHighlighter({
+    transformers: [
+      transformerTwoslash({
+        langs: ['ts', 'js', 'cjs', 'mjs'],
+        // Don't throw on errors on untype-able code
+        // throws: false,
+      }),
+    ],
     // 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/twoslash.css

@@ -0,0 +1,20 @@
+@import '@shikijs/twoslash/style-rich.css';
+
+.twoslash-popup-container {
+  > :not(.twoslash-popup-code) {
+    display: none !important;
+  }
+
+  .twoslash-popup-code {
+    >span {
+      display: inline-block !important;
+    }
+
+    display: flex !important;
+    flex-wrap: wrap !important;
+
+    font-size: small;
+  }
+
+  position: fixed !important;
+}

packages/ui-components/src/Common/BaseCodeBox/index.module.css

@@ -2,6 +2,9 @@
 
 .root {
   @apply w-full
+    translate-x-0
+    translate-y-0
+    transform
     rounded-sm
     border
     border-neutral-900