Twoslash

How to add interactive TypeScript type tooltips and error annotations to code blocks using @shikijs/twoslash with Comark.

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/twoslash

Server

In Node.js (SSR, static builds, or server routes), TypeScript reads type definitions from disk, so pass transformerTwoslash() directly:

parse.ts
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()],
    }),
  ],
})
In Nuxt, parse on the server with 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:

App.ts
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>:

App.vue
<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:

AnnotationWhereEffect
^?After a symbolShow inferred type in a hover popup
// @errors: N ...Top of blockExpect TypeScript error codes; mark others as unexpected
// @noErrorsTop of blockSuppress all type errors
// ---cut---Any lineCompile lines above and hide them from output
// ---cut-after---Any lineCompile lines below and hide them from output
// @filename: foo.tsTop of blockTreat 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:

main.ts
import '@shikijs/twoslash/style-rich.css'

To style popups in dark mode, override the popup selectors (shown here with Nuxt UI CSS variables):

styles.css
.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; }

Live example

Vue and Vite Twoslash

Browser-side Twoslash with CDN-fetched TypeScript types, a dark mode toggle, and hover type popups.
© 2026 Vercel, Inc.