shikiji-twoslash

A Shikiji transformer for Twoslash, provide inline type hover inside code blocks.

TwoSlash Notation Reference.

Install

npm i -D shikiji-twoslash

This package is a transformer addon to Shikiji. This means that for every integration that supports passing Shikiji transformers, you can use this package.

import {
  codeToHtml,
} from 'shikiji'
import {
  transformerTwoslash,
} from 'shikiji-twoslash'

const html = await codeToHtml(`console.log()`, {
  lang: 'ts',
  theme: 'vitesse-dark',
  transformers: [
    transformerTwoslash(), // <-- here
    // ...
  ],
})

The default output is unstyled. You need to add some extra CSS to make them look good.

If you want to run Twoslash on browsers or workers, reference to the CDN Usage section.

Renderers

Thanks to the flexibility of hast, this transformer allows customizing how each piece of information is rendered in the output HTML with ASTs.

We provide two renderers built-in, and you can also create your own:

---

rendererRich

Source code

TIP

This is the default renderer since v0.10.0.

This renderer provides a more explicit class name is prefixed with twoslash- for better scoping. In addition, it runs syntax highlighting on the hover information.

import { rendererRich, transformerTwoslash } from 'shikiji-twoslash'

transformerTwoslash({
  renderer: rendererRich() // <--
})

Here are a few examples with the built-in style-rich.css:

interface Todo {
  title: string
}

const todo: Readonly<Todo> = {
  title: 'Delete inactive users'.toUpperCase(),
}

todo.title = 'Hello'
Cannot assign to 'title' because it is a read-only property.

Number.p
arseInt('123', 10)

               //
               //

import { getHighlighterCore } from 'shikiji/core'

const highlighter = await getHighlighterCore({})
const a = 1
Custom log message
const b = 1
Custom error message
const c = 1
Custom warning message
Custom annotation message

---

rendererClassic

Source code

This renderer aligns with the output of shiki-twoslash.

import { rendererClassic, transformerTwoslash } from 'shikiji-twoslash'

transformerTwoslash({
  renderer: rendererClassic() // <--
})

You might need to reference shiki-twoslash's CSS to make it look good. Here we also copied the CSS from shiki-twoslash but it might need some cleanup.

rendererFloatingVue

Source code

This renderer outputs Vue template syntax that using Floating Vue as the popup component (to render it outside the containers). This renderer is NOT directly usable but an internal renderer for the VitePress integration. Listing it here for reference if you want to create your own renderer.

Options

Explicit Trigger

When integrating with markdown-it-shikiji or rehype-shikiji, we may not want Twoslash to run on every code block. In this case, we can set explicitTrigger to true to only run on code blocks with twoslash presented in the codeframe.

import { transformerTwoslash } from 'shikiji-twoslash'

transformerTwoslash({
  explicitTrigger: true // <--
})

In markdown, you can use the following syntax to trigger Twoslash:

```ts
// this is a normal code block
```

```ts twoslash
// this will run Twoslash
```

Integrations

While you can set up Twoslash with Shikiji on your own with the instructions above, you can also find high-level integrations with frameworks and tools here:

• VitePress - A plugin to enable Twoslash support in VitePress.
• Vocs - Vocs has TwoSlash support built-in.
• Slidev - Slidev has TwoSlash support built-in.

Recipes

CDN Usage

By default @typescript/twoslash runs on Node.js and relies on your local system to resolve TypeScript and types for the imports. Import it directly in non-Node.js environments would not work.

Luckily, Twoslash implemented a virtual file system, which allow you to provide your own files for TypeScript to resolve in memory. However, loading these files in the browser is still a challenge. Thanks to the work on the TypeScript WebSite, the TypeScript team has provided some utilities to fetch types on demand through CDN, they call it Automatic Type Acquisition (ATA).

We make tiny wrappers around the building blocks and provide an easy-to-use API in twoslash-cdn. For example:

// TODO: Replace with explicit versions in production
import { createTransformerFactory, rendererRich } from 'https://esm.sh/shikiji-twoslash@latest/core'
import { codeToHtml } from 'https://esm.sh/shikiji@latest'
import { createStorage } from 'https://esm.sh/unstorage@latest'
import indexedDbDriver from 'https://esm.sh/unstorage@latest/drivers/indexedb'
import { createTwoslashFromCDN } from 'https://esm.sh/twoslash-cdn@latest'

// ============= Initialization =============

// An example using unstorage with IndexedDB to cache the virtual file system
const storage = createStorage({
  driver: indexedDbDriver({ base: 'twoslash-cdn' }),
})

const twoslash = createTwoslashFromCDN({
  storage,
  compilerOptions: {
    lib: ['esnext', 'dom'],
  },
})

const transformerTwoslash = createTransformerFactory(twoslash.runSync)({
  renderer: rendererRich(),
})

// ============= Execution =============

const app = document.getElementById('app')

const source = `
import { ref } from 'vue'

console.log("Hi! Shikiji + Twoslash on CDN :)")

const count = ref(0)
//     ^?
`.trim()

// Before rendering, we need to prepare the types, so that the rendering can happen synchronously
await twoslash.prepareTypes(source)

// Then we can render the code
app.innerHTML = await codeToHtml(source, {
  lang: 'ts',
  theme: 'vitesse-dark',
  transformers: [transformerTwoslash],
})