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.
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
andStackElementMetadata
from@shikijs/vscode-textmate
instead of@shikijs/core
- The regex engines
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.