shiki-skilld

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-10

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