TIL: Using Twoslash with Shiki and Astro

Do you want code snippets like below on your Astro site?

Note: you can hover over types to see their definitions.

function function createLabel<T extends number | string>(idOrName: T): NameOrId<T>createLabel<function (type parameter) T in createLabel<T extends number | string>(idOrName: T): NameOrId<T>T extends number | string>(idOrName: T extends number | stringidOrName: function (type parameter) T in createLabel<T extends number | string>(idOrName: T): NameOrId<T>T): type NameOrId<T extends number | string> = T extends number ? IdLabel : NameLabelNameOrId<function (type parameter) T in createLabel<T extends number | string>(idOrName: T): NameOrId<T>T> {
  throw "unimplemented";
}

let let a: NameLabela = function createLabel<"typescript">(idOrName: "typescript"): NameLabelcreateLabel("typescript");

It’s super easy. In your astro.config.ts file, add the following:

import { function rendererRich(options?: RendererRichOptions): TwoslashRenderer
An alternative renderer that providers better prefixed class names,
with syntax highlight for the info text.rendererRich, function transformerTwoslash(options?: TransformerTwoslashIndexOptions): ShikiTransformer
Factory function to create a Shiki transformer for twoslash integrations.transformerTwoslash } from "@shikijs/twoslash";

export default defineConfig<never, never, never>(config: AstroUserConfig<never, never, never>): AstroUserConfig<never, never, never>
See the full Astro Configuration API Documentation
https://astro.build/configdefineConfig({
  
AstroUserConfig<never, never, never>.markdown?: {
    shikiConfig?: Partial<ShikiConfig>;
    syntaxHighlight?: {
        type?: SyntaxHighlightConfigType;
        excludeLangs?: string[];
    } | SyntaxHighlightConfigType | false;
    ... 4 more ...;
    remarkRehype?: RemarkRehype;
} | undefined
@docs@kindheading@nameMarkdown Optionsmarkdown: {
    shikiConfig?: Partial<ShikiConfig> | undefined
@docs@namemarkdown.shikiConfig@typeraw{Partial<ShikiConfig>}@descriptionShiki is our default syntax highlighter. You can configure all options via the `markdown.shikiConfig` object:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      // Choose from Shiki's built-in themes (or add your own)
      // https://shiki.style/themes
      theme: 'dracula',
      // Alternatively, provide multiple themes
      // See note below for using dual light/dark themes
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
      // Disable the default colors
      // https://shiki.style/guide/dual-themes#without-default-color
      // (Added in v4.12.0)
      defaultColor: false,
      // Add custom languages
      // Note: Shiki has countless langs built-in, including .astro!
      // https://shiki.style/languages
      langs: [],
      // Add custom aliases for languages
      // Map an alias to a Shiki language ID: https://shiki.style/languages#bundled-languages
      // https://shiki.style/guide/load-lang#custom-language-aliases
      langAlias: {
        cjs: "javascript"
      },
      // Enable word wrap to prevent horizontal scrolling
      wrap: true,
      // Add custom transformers: https://shiki.style/guide/transformers
      // Find common transformers: https://shiki.style/packages/transformers
      transformers: [],
    },
  },
});
```

See the [code syntax highlighting guide](https://docs.astro.build/en/guides/syntax-highlighting/) for usage and examples.shikiConfig: {
      transformers?: ShikiTransformer[] | undefined
Shiki transformers to customize the generated HTML by manipulating the hast tree.transformers: [
        function transformerTwoslash(options?: TransformerTwoslashIndexOptions): ShikiTransformer
Factory function to create a Shiki transformer for twoslash integrations.transformerTwoslash({
          TransformerTwoslashOptions.renderer?: TwoslashRenderer | undefined
Custom renderers to decide how each info should be renderedrenderer: function rendererRich(options?: RendererRichOptions): TwoslashRenderer
An alternative renderer that providers better prefixed class names,
with syntax highlight for the info text.rendererRich(),
        }),
      ],
    },
  },
});

Import this CSS in your layout:

import "@shikijs/twoslash/style-rich.css";
Cannot find module or type declarations for side-effect import of '@shikijs/twoslash/style-rich.css'.

Add the following CSS and import it in your layout:

// fixes an issue where type popups are cut off
.astro-code {
  overflow: visible !important;
}

Bonus: enable an automatic light & dark mode. Add the following CSS from Shiki’s documentation:

@media (prefers-color-scheme: dark) {
  .shiki,
  .shiki span {
    color: var(--shiki-dark) !important;
    background-color: var(--shiki-dark-bg) !important;
    /* Optional, if you also want font styles */
    font-style: var(--shiki-dark-font-style) !important;
    font-weight: var(--shiki-dark-font-weight) !important;
    text-decoration: var(--shiki-dark-text-decoration) !important;
  }
}

Add the following to your astro.config.ts:

export default defineConfig<never, never, never>(config: AstroUserConfig<never, never, never>): AstroUserConfig<never, never, never>
See the full Astro Configuration API Documentation
https://astro.build/configdefineConfig({
  
AstroUserConfig<never, never, never>.markdown?: {
    shikiConfig?: Partial<ShikiConfig>;
    syntaxHighlight?: {
        type?: SyntaxHighlightConfigType;
        excludeLangs?: string[];
    } | SyntaxHighlightConfigType | false;
    ... 4 more ...;
    remarkRehype?: RemarkRehype;
} | undefined
@docs@kindheading@nameMarkdown Optionsmarkdown: {
    shikiConfig?: Partial<ShikiConfig> | undefined
@docs@namemarkdown.shikiConfig@typeraw{Partial<ShikiConfig>}@descriptionShiki is our default syntax highlighter. You can configure all options via the `markdown.shikiConfig` object:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      // Choose from Shiki's built-in themes (or add your own)
      // https://shiki.style/themes
      theme: 'dracula',
      // Alternatively, provide multiple themes
      // See note below for using dual light/dark themes
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
      // Disable the default colors
      // https://shiki.style/guide/dual-themes#without-default-color
      // (Added in v4.12.0)
      defaultColor: false,
      // Add custom languages
      // Note: Shiki has countless langs built-in, including .astro!
      // https://shiki.style/languages
      langs: [],
      // Add custom aliases for languages
      // Map an alias to a Shiki language ID: https://shiki.style/languages#bundled-languages
      // https://shiki.style/guide/load-lang#custom-language-aliases
      langAlias: {
        cjs: "javascript"
      },
      // Enable word wrap to prevent horizontal scrolling
      wrap: true,
      // Add custom transformers: https://shiki.style/guide/transformers
      // Find common transformers: https://shiki.style/packages/transformers
      transformers: [],
    },
  },
});
```

See the [code syntax highlighting guide](https://docs.astro.build/en/guides/syntax-highlighting/) for usage and examples.shikiConfig: {
      theme?: ThemePresets | ThemeRegistration | ThemeRegistrationRaw | undefinedtheme: "github-dark",
      themes?: Record<string, ThemePresets | ThemeRegistration | ThemeRegistrationRaw> | undefinedthemes: {
        light: "github-light"light: "github-light",
        dark: "github-dark"dark: "github-dark",
      },
    },
  },
});

You can try it on this site by toggling your browser’s or operating system’s dark mode.

Check out Shiki’s Twoslash documentation for details.