name	shiki-skilld
description	ALWAYS use when writing code importing "shiki". Consult for debugging, best practices, or modifying shiki.
metadata	{"version":"4.0.2","generated_by":"Claude Code · Haiku 4.5","generated_at":"2026-03-10T00:00:00.000Z"}

shikijs/shiki `shiki`

Version: 4.0.2 (Mar 2026) Deps: @shikijs/vscode-textmate@^10.0.2, @types/hast@^3.0.4, @shikijs/core@4.0.2, @shikijs/themes@4.0.2, @shikijs/engine-oniguruma@4.0.2, @shikijs/langs@4.0.2, @shikijs/engine-javascript@4.0.2, @shikijs/types@4.0.2 Tags: next: 0.9.4 (May 2021), latest: 4.0.2 (Mar 2026)

References: package.json — exports, entry points • README — setup, basic usage • Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs

Search

Use skilld search instead of grepping .skilld/ directories — hybrid semantic + keyword search across all indexed docs, issues, and releases. If skilld is unavailable, use npx -y skilld search.

skilld search "query" -p shiki
skilld search "issues:error handling" -p shiki
skilld search "releases:deprecated" -p shiki

Filters: docs:, issues:, releases: prefix narrows by source type.

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

BREAKING: Node.js ≥ 20 required — Shiki v4 drops Node.js 18 support which reached EOL in April 2025 source
BREAKING: CreatedBundledHighlighterOptions type removed — renamed to CreateBundledHighlighterOptions (typo fix) source
BREAKING: createdBundledHighlighter function removed — renamed to createBundledHighlighter (typo fix) source
BREAKING: theme option removed in TwoslashFloatingVue — use themes object instead source
NEW: @shikijs/markdown-exit package — modern markdown parser with native async support, replaces markdown-it approach source
NEW: @shikijs/primitive package — leaner primitive package for core functionality source

Also changed: CSS class twoslash-query-presisted renamed to twoslash-query-persisted · rootStyle: false option added · transformerRemoveComments transformer added · classActiveCode option for notation transformers · zeroIndexed option for transformerMetaHighlight · leading position support in transformerRenderWhitespace

Best Practices

Cache the highlighter instance using singleton pattern to avoid recreating it for each call, as initialization is expensive. Reuse across requests and call dispose() when no longer needed to free memory source
Avoid importing full bundles like shiki or shiki/bundle/full in production applications. Instead use fine-grained modules such as shiki/core, @shikijs/langs/typescript, and @shikijs/themes/nord to reduce bundle size and memory usage source
Use shorthand functions like codeToHtml() for on-demand loading when highlighting can be asynchronous, as they maintain an internal highlighter and load only necessary themes and languages without upfront overhead source
Use the JavaScript regex engine instead of Oniguruma for web applications to avoid large WebAssembly files, faster startup, and better native performance — ensure language compatibility via the reference table source
Apply custom transformers with enforce: 'pre' or enforce: 'post' modifiers to control execution order relative to default transformers, ensuring dependencies are resolved correctly source
Use dual themes by passing themes object with light and dark keys, which generates CSS variables on each token for automatic theme switching via media queries or class selectors source
Load languages and themes dynamically after highlighter creation using loadLanguage() and loadTheme() methods to support runtime addition without recreating the highlighter instance source source
Use grammarState and getLastGrammarState() when highlighting code snippets to provide the correct parsing context, making inline type annotations and partial code blocks highlight correctly source
Pass highlighted hast nodes to getLastGrammarState() instead of code strings to retrieve cached grammar state, avoiding redundant highlighting execution in pausable or streaming scenarios source
Use createHighlighterCoreSync with explicit engine and resolved themes/languages for completely synchronous highlighting when necessary, requiring the JavaScript engine or pre-loaded Oniguruma source

shikijs/shiki shiki

skilld search "query" -p shiki skilld search "issues:error handling" -p shiki skilld search "releases:deprecated" -p shiki

Filters: docs:, issues:, releases: prefix narrows by source type.

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

BREAKING: Node.js ≥ 20 required — Shiki v4 drops Node.js 18 support which reached EOL in April 2025 source

BREAKING: CreatedBundledHighlighterOptions type removed — renamed to CreateBundledHighlighterOptions (typo fix) source

BREAKING: createdBundledHighlighter function removed — renamed to createBundledHighlighter (typo fix) source

BREAKING: theme option removed in TwoslashFloatingVue — use themes object instead source

NEW: @shikijs/markdown-exit package — modern markdown parser with native async support, replaces markdown-it approach source

NEW: @shikijs/primitive package — leaner primitive package for core functionality source

Best Practices

Cache the highlighter instance using singleton pattern to avoid recreating it for each call, as initialization is expensive. Reuse across requests and call dispose() when no longer needed to free memory source

Avoid importing full bundles like shiki or shiki/bundle/full in production applications. Instead use fine-grained modules such as shiki/core, @shikijs/langs/typescript, and @shikijs/themes/nord to reduce bundle size and memory usage source

Use shorthand functions like codeToHtml() for on-demand loading when highlighting can be asynchronous, as they maintain an internal highlighter and load only necessary themes and languages without upfront overhead source

Use the JavaScript regex engine instead of Oniguruma for web applications to avoid large WebAssembly files, faster startup, and better native performance — ensure language compatibility via the reference table source

Apply custom transformers with enforce: 'pre' or enforce: 'post' modifiers to control execution order relative to default transformers, ensuring dependencies are resolved correctly source

Use dual themes by passing themes object with light and dark keys, which generates CSS variables on each token for automatic theme switching via media queries or class selectors source

Load languages and themes dynamically after highlighter creation using loadLanguage() and loadTheme() methods to support runtime addition without recreating the highlighter instance source source

Use grammarState and getLastGrammarState() when highlighting code snippets to provide the correct parsing context, making inline type annotations and partial code blocks highlight correctly source

Pass highlighted hast nodes to getLastGrammarState() instead of code strings to retrieve cached grammar state, avoiding redundant highlighting execution in pausable or streaming scenarios source

Use createHighlighterCoreSync with explicit engine and resolved themes/languages for completely synchronous highlighting when necessary, requiring the JavaScript engine or pre-loaded Oniguruma source

shiki-skilld

shikijs/shiki shiki

Search

API Changes

Best Practices

shikijs/shiki shiki

Search

API Changes

Best Practices

shikijs/shiki `shiki`

shikijs/shiki `shiki`