Twoslash
Twoslash runs the TypeScript compiler on fenced code blocks to generate inline type tooltips, expected error markers, and hidden setup lines. When you parse on the server or at build time, the output ships as HTML and CSS with no client JavaScript.
It runs as a Shiki transformer inside Comark's Shiki plugin.
Installation
pnpm add shiki @shikijs/twoslashnpm install shiki @shikijs/twoslashyarn add shiki @shikijs/twoslashbun add shiki @shikijs/twoslashpnpm add shiki @shikijs/twoslash twoslash-cdnnpm install shiki @shikijs/twoslash twoslash-cdnyarn add shiki @shikijs/twoslash twoslash-cdnbun add shiki @shikijs/twoslash twoslash-cdnServer
In Node.js (SSR, static builds, or server routes), TypeScript reads type definitions from disk, so pass transformerTwoslash() directly:
import { parseMarkdown } from 'comark'
import shiki from 'comark/plugins/shiki'
import { transformerTwoslash } from '@shikijs/twoslash'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'
const result = await parseMarkdown(content, {
plugins: [
shiki({
themes: { light: githubLight, dark: githubDark },
transformers: [transformerTwoslash()],
}),
],
})parseMarkdown() and render <MarkdownDocument> on the client so Twoslash runs on the server with no client JavaScript.Browser
The browser has no filesystem, so TypeScript cannot read local .d.ts files. Use twoslash-cdn to fetch type definitions over a CDN:
import { createTransformerFactory, rendererRich } from '@shikijs/twoslash/core'
import { createTwoslashFromCDN } from 'twoslash-cdn'
import shiki from 'comark/plugins/shiki'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'
const twoslash = createTwoslashFromCDN()
await twoslash.init()
const transformer = createTransformerFactory(twoslash.runSync)({
explicitTrigger: true,
renderer: rendererRich(),
})
const plugin = shiki({
themes: { light: githubLight, dark: githubDark },
transformers: [transformer],
})explicitTrigger: true limits compilation to code blocks tagged with twoslash in their info string and leaves plain ts blocks untouched. Import @shikijs/twoslash/style-rich.css for the default popup styles.Vue and Vite
Initialize twoslash-cdn after mount and pass the plugin array to <Markdown>:
<script setup lang="ts">
import { shallowRef, onMounted } from 'vue'
import { Markdown } from '@comark/vue'
import shiki from '@comark/vue/plugins/shiki'
import { createTransformerFactory, rendererRich } from '@shikijs/twoslash/core'
import { createTwoslashFromCDN } from 'twoslash-cdn'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'
import '@shikijs/twoslash/style-rich.css'
import type { ComarkPlugin } from 'comark'
const plugins = shallowRef<ComarkPlugin[] | null>(null)
onMounted(async () => {
const twoslash = createTwoslashFromCDN()
await twoslash.init()
const transformer = createTransformerFactory(twoslash.runSync)({
explicitTrigger: true,
renderer: rendererRich(),
})
plugins.value = [
shiki({
themes: { light: githubLight, dark: githubDark },
transformers: [transformer],
}),
]
})
</script>
<template>
<Suspense>
<Markdown v-if="plugins" :plugins="plugins">{{ content }}</Markdown>
</Suspense>
</template>Annotations
Add annotations directly inside a twoslash code block. Twoslash compiles the block and strips the comment directives from the rendered output:
| Annotation | Where | Effect |
|---|---|---|
^? | After a symbol | Show inferred type in a hover popup |
// @errors: N ... | Top of block | Expect TypeScript error codes; mark others as unexpected |
// @noErrors | Top of block | Suppress all type errors |
// ---cut--- | Any line | Compile lines above and hide them from output |
// ---cut-after--- | Any line | Compile lines below and hide them from output |
// @filename: foo.ts | Top of block | Treat block as a named virtual file for multi-file examples |
Type hover (^?)
Place ^? under an identifier to show its inferred type in a popup:
```ts twoslash
const message = "Hello from Twoslash"
// ^?
```Error annotations (@errors)
Declare expected TypeScript error codes so intentional type errors compile and render inline:
```ts twoslash
// @errors: 2322
let count: number = "not a number"
```Hide setup (// ---cut---)
Lines above // ---cut--- compile with the snippet and stay hidden in the rendered block:
```ts twoslash
interface User { id: number; name: string }
function getUser(id: number): User {
return { id, name: 'Alice' }
}
// ---cut---
const user = getUser(42)
// ^?
```Styling
Import the bundled stylesheet for popup styles, then override CSS variables to match your theme:
import '@shikijs/twoslash/style-rich.css'To style popups in dark mode, override the popup selectors (shown here with Nuxt UI CSS variables):
.dark .twoslash-popup-container {
background: var(--ui-bg-elevated) !important;
border-color: var(--ui-border) !important;
}
.dark .twoslash-popup-code span {
color: var(--shiki-dark) !important;
}
/* Prevent nested <pre> inside popup from inheriting block styles */
pre .twoslash-hover pre {
margin: 0;
padding: 0;
background: transparent !important;
border: none;
}
pre .twoslash-hover pre .line { display: inline; }