Installing

Twoslash Features

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

Installation

Install the package with your favorite package manager

npm i expressive-code-twoslash

pnpm add expressive-code-twoslash

yarn 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<const TLocales extends Locales = never, const TDriver extends SessionDriverName = never, const TFontProviders extends Array<FontProvider> = never>(config: AstroUserConfig<TLocales, TDriver, TFontProviders>): AstroUserConfig<TLocales, TDriver, TFontProviders>
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.
@see ― https://twoslash.studiocms.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash from "expressive-code-twoslash";

// https://astro.build/config
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/config
defineConfig({
  
AstroUserConfig<TLocales extends Locales = never, TSession extends SessionDriverName = never, TFontProviders extends Array<FontProvider> = never>.integrations?: (false | AstroIntegration | (false | AstroIntegration | null | undefined)[] | null | undefined)[] | undefined@docs
@name ― integrations
@typeraw ― {AstroIntegration[]}
@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 mdx from '@astrojs/mdx';
{
  // Example: Add React + MDX support to Astro
  integrations: [react(), mdx()]
}
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.
@see ― https://twoslash.studiocms.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.
@see ― https://twoslash.studiocms.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.
@see ― https://twoslash.studiocms.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash()],
});

astro.config.mjs
ec.config.mjs

import { 
function defineConfig<const TLocales extends Locales = never, const TDriver extends SessionDriverName = never, const TFontProviders extends Array<FontProvider> = never>(config: AstroUserConfig<TLocales, TDriver, TFontProviders>): AstroUserConfig<TLocales, TDriver, TFontProviders>
See the full Astro Configuration API Documentation
https://astro.build/config
defineConfig } from "astro/config";
import 
function starlight(userOpts: 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.
@see ― https://twoslash.studiocms.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash from "expressive-code-twoslash";

// https://astro.build/config
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/config
defineConfig({
  
AstroUserConfig<TLocales extends Locales = never, TSession extends SessionDriverName = never, TFontProviders extends Array<FontProvider> = never>.integrations?: (false | AstroIntegration | (false | AstroIntegration | null | undefined)[] | null | undefined)[] | undefined@docs
@name ― integrations
@typeraw ― {AstroIntegration[]}
@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 mdx from '@astrojs/mdx';
{
  // Example: Add React + MDX support to Astro
  integrations: [react(), mdx()]
}
integrations: [
    
function starlight(userOpts: 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.
@see ― https://twoslash.studiocms.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.
@see ― https://twoslash.studiocms.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.
@see ― https://twoslash.studiocms.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.
@see ― https://twoslash.studiocms.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.
@see ― https://twoslash.studiocms.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.
@see ― https://twoslash.studiocms.dev for the full documentation.
@returns ― A plugin object with the specified configuration.
ecTwoSlash({
  
PluginTwoslashOptions.instanceConfigs?: {
    twoslash?: {
        explicitTrigger?: boolean | RegExp;
        languages?: ReadonlyArray<string>;
    };
    eslint?: {
        explicitTrigger?: boolean | RegExp;
        languages?: ReadonlyArray<string>;
    };
} | undefined
Allows for configuring the included twoslasher instances and their triggers.
instanceConfigs: {
    
twoslash?: {
    explicitTrigger?: boolean | RegExp;
    languages?: ReadonlyArray<string>;
} | undefined
Standard Twoslash instance configuration.
twoslash: {
      
explicitTrigger?: boolean | RegExp | undefined
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,
      
languages?: readonly string[] | undefined
The languages to apply this transformer to.
@default ― ["ts", "tsx", "vue"]
languages: ["ts", "tsx", "vue"],
    },
    
eslint?: {
    explicitTrigger?: boolean | RegExp;
    languages?: ReadonlyArray<string>;
} | undefined
ESLint Twoslash instance configuration.
Unlike the standard Twoslash instance, the ESLint Twoslash instance uses eslint as its meta trigger for code blocks, and it is designed to work with JavaScript and TypeScript code blocks that contain ESLint errors. When a code block is annotated with eslint, the ESLint Twoslash instance will parse the code and display any ESLint errors as annotations in the code block.
eslint: {
      
explicitTrigger?: boolean | RegExp | undefined
If true, requires eslint 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.
explicitTrigger: true,
      
languages?: readonly string[] | undefined
The languages to apply this transformer to.
@default ― ["ts", "tsx"]
languages: ["ts", "tsx"],
    }
  },
  
PluginTwoslashOptions.includeJsDoc?: boolean | undefined
If true, includes JSDoc comments in the hover popup.
@default ― true
includeJsDoc: true,
Message: allowNonStandardJsDocTags is required for like this to work
  
PluginTwoslashOptions.allowNonStandardJsDocTags?: boolean | undefined
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 ― true
allowNonStandardJsDocTags: true,
  
PluginTwoslashOptions.twoslashOptions?: TwoslashOptions | undefined
Options to forward to twoslash.
@default ― {}
twoslashOptions: {
    
TwoslashExecuteOptions.compilerOptions?: ts.CompilerOptions | undefined
Allows setting any of the compiler options from outside the function
compilerOptions: {
      
ts.CompilerOptions.moduleResolution?: ts.ModuleResolutionKind | undefined
moduleResolution: 100 satisfies 
(alias) namespace ts
import ts
ts.
enum ts.ModuleResolutionKind
ModuleResolutionKind.
function (enum member) ts.ModuleResolutionKind.Bundler = 100
Bundler,
      
ts.CompilerOptions.lib?: string[] | undefined
lib: ["lib.es2022.d.ts", "lib.dom.d.ts", "lib.dom.iterable.d.ts"],
    }
  },
})