Installing

Twoslash Features

Feature	Supported Status
JSDocs and Type Hover boxes	✅
Error Handling/Messages	✅
Type Extraction	✅
Code Completions	✅
Code Highlighting	✅
Code Cutting	✅
Callouts	✅
TSComiler Overrides	✅
Show Emitted Files	⛔️

Installation

Install the package with your favorite package manager

npm i expressive-code-twoslash

yarn add expressive-code-twoslash

pnpm add expressive-code-twoslash

Add to EC Config

Add ecTwoSlash to your Expressive Code plugin list

astro.config.mjs
ec.config.mjs

import { 
function defineConfig(config: AstroUserConfig): AstroUserConfig
See the full Astro Configuration API Documentation
https://astro.build/config
defineConfig } from "astro/config";
import 
function astroExpressiveCode(integrationOptions?: AstroExpressiveCodeOptions): {
    name: string;
    hooks: {
        "astro:config:setup": (args: unknown) => Promise<void>;
    };
}
Astro integration that adds Expressive Code support to code blocks in Markdown & MDX documents.
astroExpressiveCode from 'astro-expressive-code'
import 
function ecTwoSlash(options?: PluginTwoslashOptions): ExpressiveCodePlugin
Add Twoslash support to your Expressive Code TypeScript code blocks.
@param ― options - Configuration options for the plugin.
@param ― options.explicitTrigger - Settings for the explicit trigger.
@param ― options.languages - The languages to apply this transformer to.
@param ― options.includeJsDoc - If true, includes JSDoc comments in the hover popup.
@param ― options.twoslashOptions - Options to forward to twoslash.
@see ― https://twoslash.matthiesen.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash from "expressive-code-twoslash";

// https://astro.build/config
export default 
function defineConfig(config: AstroUserConfig): AstroUserConfig
See the full Astro Configuration API Documentation
https://astro.build/config
defineConfig({
  
AstroUserConfig.integrations?: (false | AstroIntegration | (false | AstroIntegration | null | undefined)[] | null | undefined)[]@name ― integrations
@description 
Extend Astro with custom integrations. Integrations are your one-stop-shop for adding framework support (like Solid.js), new features (like sitemaps), and new libraries (like Partytown).
Read our Integrations Guide for help getting started with Astro Integrations.
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
{
  // Example: Add React + Tailwind support to Astro
  integrations: [react(), tailwind()]
}
integrations: [
    
function astroExpressiveCode(integrationOptions?: AstroExpressiveCodeOptions): {
    name: string;
    hooks: {
        "astro:config:setup": (args: unknown) => Promise<void>;
    };
}
Astro integration that adds Expressive Code support to code blocks in Markdown & MDX documents.
astroExpressiveCode({
      
plugins?: (ExpressiveCodePlugin | ExpressiveCodePlugin[])[] | undefined
An optional array of plugins that should be used when rendering code blocks.
To add a plugin, import its initialization function and call it inside this array.
If the plugin has any configuration options, you can pass them to the initialization
function as an object containing your desired property values.
If any nested arrays are found inside the plugins array, they will be flattened
before processing.
plugins: [
function ecTwoSlash(options?: PluginTwoslashOptions): ExpressiveCodePlugin
Add Twoslash support to your Expressive Code TypeScript code blocks.
@param ― options - Configuration options for the plugin.
@param ― options.explicitTrigger - Settings for the explicit trigger.
@param ― options.languages - The languages to apply this transformer to.
@param ― options.includeJsDoc - If true, includes JSDoc comments in the hover popup.
@param ― options.twoslashOptions - Options to forward to twoslash.
@see ― https://twoslash.matthiesen.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash()],
    }),
  ],
});

import { 
function defineEcConfig(config: AstroExpressiveCodeOptions): AstroExpressiveCodeOptions
A utility function that helps you define an Expressive Code configuration object. It is meant
to be used inside the optional config file ec.config.mjs located in the root directory
of your Astro project, and its return value to be exported as the default export.
Expressive Code will automatically detect this file and use the exported configuration object
to override its own default settings.
Using this function is recommended, but not required. It just passes through the given object,
but it also provides type information for your editor's auto-completion and type checking.
@example 
// ec.config.mjs
import { defineEcConfig } from 'astro-expressive-code'

export default defineEcConfig({
  themes: ['dracula', 'github-light'],
  styleOverrides: {
    borderRadius: '0.5rem',
  },
})
defineEcConfig } from 'astro-expressive-code'
import 
function ecTwoSlash(options?: PluginTwoslashOptions): ExpressiveCodePlugin
Add Twoslash support to your Expressive Code TypeScript code blocks.
@param ― options - Configuration options for the plugin.
@param ― options.explicitTrigger - Settings for the explicit trigger.
@param ― options.languages - The languages to apply this transformer to.
@param ― options.includeJsDoc - If true, includes JSDoc comments in the hover popup.
@param ― options.twoslashOptions - Options to forward to twoslash.
@see ― https://twoslash.matthiesen.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash from "expressive-code-twoslash";

export default 
function defineEcConfig(config: AstroExpressiveCodeOptions): AstroExpressiveCodeOptions
A utility function that helps you define an Expressive Code configuration object. It is meant
to be used inside the optional config file ec.config.mjs located in the root directory
of your Astro project, and its return value to be exported as the default export.
Expressive Code will automatically detect this file and use the exported configuration object
to override its own default settings.
Using this function is recommended, but not required. It just passes through the given object,
but it also provides type information for your editor's auto-completion and type checking.
@example 
// ec.config.mjs
import { defineEcConfig } from 'astro-expressive-code'

export default defineEcConfig({
  themes: ['dracula', 'github-light'],
  styleOverrides: {
    borderRadius: '0.5rem',
  },
})
defineEcConfig({
  
plugins?: (ExpressiveCodePlugin | ExpressiveCodePlugin[])[] | undefined
An optional array of plugins that should be used when rendering code blocks.
To add a plugin, import its initialization function and call it inside this array.
If the plugin has any configuration options, you can pass them to the initialization
function as an object containing your desired property values.
If any nested arrays are found inside the plugins array, they will be flattened
before processing.
plugins: [
function ecTwoSlash(options?: PluginTwoslashOptions): ExpressiveCodePlugin
Add Twoslash support to your Expressive Code TypeScript code blocks.
@param ― options - Configuration options for the plugin.
@param ― options.explicitTrigger - Settings for the explicit trigger.
@param ― options.languages - The languages to apply this transformer to.
@param ― options.includeJsDoc - If true, includes JSDoc comments in the hover popup.
@param ― options.twoslashOptions - Options to forward to twoslash.
@see ― https://twoslash.matthiesen.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash()],
});

astro.config.mjs
ec.config.mjs

import { 
function defineConfig(config: AstroUserConfig): AstroUserConfig
See the full Astro Configuration API Documentation
https://astro.build/config
defineConfig } from "astro/config";
import 
function starlight({ plugins, ...opts }: StarlightUserConfigWithPlugins): AstroIntegration
starlight from "@astrojs/starlight";
import 
function ecTwoSlash(options?: PluginTwoslashOptions): ExpressiveCodePlugin
Add Twoslash support to your Expressive Code TypeScript code blocks.
@param ― options - Configuration options for the plugin.
@param ― options.explicitTrigger - Settings for the explicit trigger.
@param ― options.languages - The languages to apply this transformer to.
@param ― options.includeJsDoc - If true, includes JSDoc comments in the hover popup.
@param ― options.twoslashOptions - Options to forward to twoslash.
@see ― https://twoslash.matthiesen.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash from "expressive-code-twoslash";

// https://astro.build/config
export default 
function defineConfig(config: AstroUserConfig): AstroUserConfig
See the full Astro Configuration API Documentation
https://astro.build/config
defineConfig({
  
AstroUserConfig.integrations?: (false | AstroIntegration | (false | AstroIntegration | null | undefined)[] | null | undefined)[]@name ― integrations
@description 
Extend Astro with custom integrations. Integrations are your one-stop-shop for adding framework support (like Solid.js), new features (like sitemaps), and new libraries (like Partytown).
Read our Integrations Guide for help getting started with Astro Integrations.
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
{
  // Example: Add React + Tailwind support to Astro
  integrations: [react(), tailwind()]
}
integrations: [
    
function starlight({ plugins, ...opts }: StarlightUserConfigWithPlugins): AstroIntegration
starlight({
      
title: string | Record<string, string>
Title for your website. Will be used in metadata and as browser tab title.
title: "Starlight",
      
expressiveCode?: boolean | StarlightExpressiveCodeOptions | undefined
Define how code blocks are rendered by passing options to Expressive Code,
or disable the integration by passing false.
expressiveCode: {
        
plugins?: (ExpressiveCodePlugin | ExpressiveCodePlugin[])[] | undefined
An optional array of plugins that should be used when rendering code blocks.
To add a plugin, import its initialization function and call it inside this array.
If the plugin has any configuration options, you can pass them to the initialization
function as an object containing your desired property values.
If any nested arrays are found inside the plugins array, they will be flattened
before processing.
plugins: [
function ecTwoSlash(options?: PluginTwoslashOptions): ExpressiveCodePlugin
Add Twoslash support to your Expressive Code TypeScript code blocks.
@param ― options - Configuration options for the plugin.
@param ― options.explicitTrigger - Settings for the explicit trigger.
@param ― options.languages - The languages to apply this transformer to.
@param ― options.includeJsDoc - If true, includes JSDoc comments in the hover popup.
@param ― options.twoslashOptions - Options to forward to twoslash.
@see ― https://twoslash.matthiesen.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash()],
      },
    }),
  ],
});

import { 
function defineEcConfig(config: StarlightExpressiveCodeOptions): StarlightExpressiveCodeOptions
A utility function that helps you define an Expressive Code configuration object. It is meant
to be used inside the optional config file ec.config.mjs located in the root directory
of your Starlight project, and its return value to be exported as the default export.
Expressive Code will automatically detect this file and use the exported configuration object
to override its own default settings.
Using this function is recommended, but not required. It just passes through the given object,
but it also provides type information for your editor's auto-completion and type checking.
@example 
// ec.config.mjs
import { defineEcConfig } from '@astrojs/starlight/expressive-code'

export default defineEcConfig({
  themes: ['starlight-dark', 'github-light'],
  styleOverrides: {
    borderRadius: '0.5rem',
  },
})
defineEcConfig } from "@astrojs/starlight/expressive-code";
import 
function ecTwoSlash(options?: PluginTwoslashOptions): ExpressiveCodePlugin
Add Twoslash support to your Expressive Code TypeScript code blocks.
@param ― options - Configuration options for the plugin.
@param ― options.explicitTrigger - Settings for the explicit trigger.
@param ― options.languages - The languages to apply this transformer to.
@param ― options.includeJsDoc - If true, includes JSDoc comments in the hover popup.
@param ― options.twoslashOptions - Options to forward to twoslash.
@see ― https://twoslash.matthiesen.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash from "expressive-code-twoslash";

export default 
function defineEcConfig(config: StarlightExpressiveCodeOptions): StarlightExpressiveCodeOptions
A utility function that helps you define an Expressive Code configuration object. It is meant
to be used inside the optional config file ec.config.mjs located in the root directory
of your Starlight project, and its return value to be exported as the default export.
Expressive Code will automatically detect this file and use the exported configuration object
to override its own default settings.
Using this function is recommended, but not required. It just passes through the given object,
but it also provides type information for your editor's auto-completion and type checking.
@example 
// ec.config.mjs
import { defineEcConfig } from '@astrojs/starlight/expressive-code'

export default defineEcConfig({
  themes: ['starlight-dark', 'github-light'],
  styleOverrides: {
    borderRadius: '0.5rem',
  },
})
defineEcConfig({
  
plugins?: (ExpressiveCodePlugin | ExpressiveCodePlugin[])[] | undefined
An optional array of plugins that should be used when rendering code blocks.
To add a plugin, import its initialization function and call it inside this array.
If the plugin has any configuration options, you can pass them to the initialization
function as an object containing your desired property values.
If any nested arrays are found inside the plugins array, they will be flattened
before processing.
plugins: [
function ecTwoSlash(options?: PluginTwoslashOptions): ExpressiveCodePlugin
Add Twoslash support to your Expressive Code TypeScript code blocks.
@param ― options - Configuration options for the plugin.
@param ― options.explicitTrigger - Settings for the explicit trigger.
@param ― options.languages - The languages to apply this transformer to.
@param ― options.includeJsDoc - If true, includes JSDoc comments in the hover popup.
@param ― options.twoslashOptions - Options to forward to twoslash.
@see ― https://twoslash.matthiesen.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash()],
});

import 
function rehypeExpressiveCode(options?: RehypeExpressiveCodeOptions): (tree: Root, file: any) => Promise<void>
rehypeExpressiveCode from 'rehype-expressive-code'
import 
function ecTwoSlash(options?: PluginTwoslashOptions): ExpressiveCodePlugin
Add Twoslash support to your Expressive Code TypeScript code blocks.
@param ― options - Configuration options for the plugin.
@param ― options.explicitTrigger - Settings for the explicit trigger.
@param ― options.languages - The languages to apply this transformer to.
@param ― options.includeJsDoc - If true, includes JSDoc comments in the hover popup.
@param ― options.twoslashOptions - Options to forward to twoslash.
@see ― https://twoslash.matthiesen.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash from "expressive-code-twoslash";

/** @type {import('rehype-expressive-code').RehypeExpressiveCodeOptions} */
const 
const rehypeExpressiveCodeOptions: {
    plugins: ExpressiveCodePlugin[];
}@type ― {import('rehype-expressive-code').RehypeExpressiveCodeOptions}
rehypeExpressiveCodeOptions = {
  
plugins: ExpressiveCodePlugin[]
plugins: [
function ecTwoSlash(options?: PluginTwoslashOptions): ExpressiveCodePlugin
Add Twoslash support to your Expressive Code TypeScript code blocks.
@param ― options - Configuration options for the plugin.
@param ― options.explicitTrigger - Settings for the explicit trigger.
@param ― options.languages - The languages to apply this transformer to.
@param ― options.includeJsDoc - If true, includes JSDoc comments in the hover popup.
@param ― options.twoslashOptions - Options to forward to twoslash.
@see ― https://twoslash.matthiesen.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash()],
}

// Rest of your Next.js config

For more information on how to add to your Next.js config, see the Expressive Code documentation.

Config Options

Default config options shown.


function ecTwoSlash(options?: PluginTwoslashOptions): ExpressiveCodePlugin
Add Twoslash support to your Expressive Code TypeScript code blocks.
@param ― options - Configuration options for the plugin.
@param ― options.explicitTrigger - Settings for the explicit trigger.
@param ― options.languages - The languages to apply this transformer to.
@param ― options.includeJsDoc - If true, includes JSDoc comments in the hover popup.
@param ― options.twoslashOptions - Options to forward to twoslash.
@see ― https://twoslash.matthiesen.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash({
    
PluginTwoslashOptions.explicitTrigger?: boolean | RegExp
If true, requires twoslash to be present in the code block meta for
this transformer to be applied.
If a RegExp, requires the RegExp to match a directive in the code
block meta for this transformer to be applied.
If false, this transformer will be applied to all code blocks that match
the specified languages.
It is recommended to keep this as true to avoid unnecessary processing.
@default ― true
explicitTrigger: true,
    
PluginTwoslashOptions.includeJsDoc?: boolean
If true, includes JSDoc comments in the hover popup.
@default ― true
includeJsDoc: true,
    
PluginTwoslashOptions.allowNonStandardJsDocTags?: boolean
Allows non-standard JSDoc tags to be included in the hover popup.
Non-standard tags are tags that are not included in the default JSDoc tag list.
@example @customTag, @docs, @omglookatthis
@default ― false
allowNonStandardJsDocTags: false,
    
PluginTwoslashOptions.languages?: readonly string[]
The languages to apply this transformer to.
@default ― ["ts", "tsx"]
languages: ["ts", "tsx"],
    
PluginTwoslashOptions.twoslashOptions?: TwoslashOptions
Options to forward to twoslash.
@default ― {}
twoslashOptions: {},
})