Shiki v2.0.0

Shiki v2.0.0 itself is a boring release.

In case you missed, there are quite some cool new features we have landed in minor releases progressively:

Version	Noteable New Features
v1.1.0	Better Twoslash support
v1.3.0	New structure: inline option
v1.6.0	Scoped color replacement, thanks to @QuentinRoy
v1.8.0	Expose .dispose() method for explicit resource cleanup
v1.10.0	Introduced Grammar State for partial code highlighting
v1.15.0	Introduced JavaScript Engine with better portability and bundle size
v1.16.0	Support Synchronous Usage
v1.19.0	Introduced enableDeprecationWarnings() function for easier migration. Support object-style htmlStyle and new htmlAttrs on themed tokens.
v1.23.0	New @shikijs/colorized-brackets package, thanks to @MichaelMakesGames
v1.24.0	Improved performance and accuracy for the JavaScript engine, thanks to @slevithan
v1.25.0	Separated themes and languages into @shikijs/themes and @shikijs/languages packages
v1.26.0	Introduced pre-compiled languages package for smaller bundle and better performance
v1.27.0	New shiki-codegen package for easier fine-grained bundle creation
v1.29.0	Improved the transformer matching algorithm, introduce matchAlgorithm option. Thanks to @fuma-nama

Among all these new features, we also includes a lot of new languages support and new themes. Check out languages and themes list for the full list.

Meanwhile, huge thanks to @slevithan's great work on oniguruma-to-es that make the JavaScript engine supports 97.2% of all the languages.

Breaking Changes

There are NO hard breaking changes in v2.0.0. It serves as a stepping stone for the upcoming v3.0.0.

The only change in v2 is that Shiki will now emit warnings when you use deprecated APIs that are planned to be removed in v3. Since this might affect end users, we have made a major version bump so you can opt-in to the warnings and prepare for the future removal.

• v1.x: Deprecated APIs are still supported, marked on type level only. With optional runtime warnings to opt-in.
• 👉 v2.0: No breaking changes, but enable runtime deprecated warnings by default.
• v3.0: Remove deprecated APIs, breaking changes.

Expect v3.0.0 to be released soon after v2.0.0.

Deprecations

We highly recommend you to migrate the depreactions as soon as possible, with the warning messages as a guide.

getHighlighter -> createHighlighter

There is no functional changes, but more like correcting the naming to avoid confusion. It should be a straightforward find-and-replace.

WASM Related APIs

Since the introduction of the engine system in v0.16, WebAssembly-related dependencies are no longer a hard requirement. To facilitate tree-shaking and decouple the engines from the core, two packages have been extracted: @shikijs/engine-oniguruma and @shikijs/engine-javascript. These are also re-exported from the main package as shiki/engine/oniguruma and shiki/engine/javascript, respectively.

You might need to change your import path:

import { loadWasm } from 'shiki'
import { loadWasm } from 'shiki/engine/oniguruma'

loadWasm field in createHighlighterCore is replaced with engine field:

import { createHighlighter } from 'shiki'
import { createOnigurumaEngine } from 'shiki/engine/oniguruma'

const shiki = await createHighlighter({
  // ...
  loadWasm: () => import('shiki/wasm'), 
  engine: createOnigurumaEngine(() => import('shiki/wasm')), 
})

Shiki Compat

The @shikijs/compat package that built for compatibility with v0.14 is now deprecated. Please migrate to the main package. This package will be removed in v3.0.

Transformers Matching Algorithm

The matchAlgorithm option for transformers was introduced in v1.29.0, allowing users to choose the matching algorithm. The default value will change from v1 to v3 in v3.0.0. We recommend explicitly setting the matchAlgorithm option to avoid future breaking changes.

Learn more.

Other Deprecations

• createdBundledHighlighter requires a single object-style argument
• @shikijs/core
  • The regex engines createJavaScriptRegexEngine createOnigurumaEngine are no longer included, import them from @shikijs/engine-oniguruma and @shikijs/engine-javascript respectively
  • createHighlighterCore now explicits requires an engine field to be passed
  • loadWasm field in createHighlighterCore is replaced with engine field
  • @shikijs/core/wasm-inline is replaced with @shikijs/engine-oniguruma/wasm-inline
  • Import FontStyle and StackElementMetadata from @shikijs/vscode-textmate instead of @shikijs/core

Tweaking Warnings

If you prefer hard errors instead of warnings, you can run the following code before using Shiki, the first argument decides if warnings should be enabled, the second argument decides if warnings should be thrown as errors:

import { enableDeprecationWarnings } from 'shiki/core'

enableDeprecationWarnings(true, true) // enable warnings and throw errors

// use crateHighlighter(...) etc. after that

Disable Warnings

If you want to disable the warnings:

import { enableDeprecationWarnings } from 'shiki/core'

enableDeprecationWarnings(false)

Try It as a User

If you are using Shiki indirectly via other packages, like vitepress or @nuxt/content, where you don't directly control the version of Shiki, you can try adding the following lines to your package.json to force the usage of Shiki v2.0.0. This will help you check if the frameworks/tools you are using rely on deprecated Shiki APIs. If they do, please report it to their repositories to raise awareness of the upcoming changes. Thanks!

{
  "resolutions": {
    "shiki": "^2",
    "@shikijs/core": "^2",
    "@shikijs/transformers": "^2",
    "@shikijs/markdown-it": "^2",
    "@shikijs/rehype": "^2"
  }
}

Feedback

Any feedbacks are welcome! Feel free to open an issue on GitHub and let us know your thoughts.