Shiki v3.0.0

Shiki v3.0.0 is another boring release that removes deprecated APIs that have been marked since v1.x and explicitly warned in v2.x.

In Shiki, new features are shipped in minor releases progressively, while the major releases is for cleaning up and removing deprecated APIs.

If you are still on v1.x, please migrate to v2.x first. It should provides you a smooth transition path to v3.0.0.

Breaking Changes

• 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.

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 v1.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')), 
})

Meanwhile, @shikijs/core package no longer includes the engines or wasm binaries. You need to import them from the @shikijs/engine-oniguruma and @shikijs/engine-javascript packages.

Shiki Compat

The @shikijs/compat package that built for compatibility with v0.14 is now discontinued. Please migrate to the main package.

Transformers Matching Algorithm

The matchAlgorithm option for transformers was introduced in v1.29.0, allowing users to choose the matching algorithm. The default value is change from v1 to v3 in v3.0.0.

Learn more.

Other Breaking Changes

• 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
  • @shikijs/core/wasm-inline is replaced with @shikijs/engine-oniguruma/wasm-inline
  • Import FontStyle and StackElementMetadata from @shikijs/vscode-textmate instead of @shikijs/core

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 first.

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

Then run the tool to see if it emits any warnings. If they do, please report it to their repositories to raise awareness of the upcoming changes. And if not, the tool should work as expected with Shiki v3.0.0, where you can then further migrate to v3 as:

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

Feedback

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