|
| 1 | +# Shiki v2.0.0 |
| 2 | + |
| 3 | +Shiki v2.0.0 itself is a **boring** release. |
| 4 | + |
| 5 | +In case you missed them, here are quote some cool new features we have landed in minor releases progressively: |
| 6 | + |
| 7 | +| Version | Noteable New Features | |
| 8 | +| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 9 | +| [v1.1.0](https://github.com/shikijs/shiki/releases/tag/v1.1.0) | Better Twoslash support | |
| 10 | +| [v1.3.0](https://github.com/shikijs/shiki/releases/tag/v1.3.0) | New `structure: inline` option | |
| 11 | +| [v1.6.0](https://github.com/shikijs/shiki/releases/tag/v1.6.0) | Scoped color replacement, thanks to [@QuentinRoy](https://github.com/QuentinRoy) | |
| 12 | +| [v1.8.0](https://github.com/shikijs/shiki/releases/tag/v1.8.0) | Expose `.dispose()` method for explicit resource cleanup | |
| 13 | +| [v1.10.0](https://github.com/shikijs/shiki/releases/tag/v1.10.0) | Introduced [Grammar State](https://github.com/shikijs/shiki/pull/712) for partial code highlighting | |
| 14 | +| [v1.15.0](https://github.com/shikijs/shiki/releases/tag/v1.15.0) | Introduced [JavaScript Engine](/guide/regex-engines#javascript-engine) with better portability and bundle size | |
| 15 | +| [v1.16.0](https://github.com/shikijs/shiki/releases/tag/v1.16.0) | Support [Synchronous Usage](/guide/sync-usage) | |
| 16 | +| [v1.19.0](https://github.com/shikijs/shiki/releases/tag/v1.19.0) | Introduced `enableDeprecationWarnings()` function for easier migration. Support object-style `htmlStyle` and new `htmlAttrs` on themed tokens. | |
| 17 | +| [v1.23.0](https://github.com/shikijs/shiki/releases/tag/v1.23.0) | New [`@shikijs/colorized-brackets`](/packages/colorized-brackets) package, thanks to [@MichaelMakesGames](https://github.com/MichaelMakesGames) | |
| 18 | +| [v1.24.0](https://github.com/shikijs/shiki/releases/tag/v1.24.0) | Improved performance and accuracy for the JavaScript engine, thanks to [@slevithan](https://github.com/slevithan) | |
| 19 | +| [v1.25.0](https://github.com/shikijs/shiki/releases/tag/v1.25.0) | Separated themes and languages into `@shikijs/themes` and `@shikijs/languages` packages | |
| 20 | +| [v1.26.0](https://github.com/shikijs/shiki/releases/tag/v1.26.0) | Introduced [pre-compiled languages](https://shiki.style/guide/regex-engines#pre-compiled-languages) package for smaller bundle and better performance | |
| 21 | +| [v1.27.0](https://github.com/shikijs/shiki/releases/tag/v1.27.0) | New [`shiki-codegen`](/packages/codegen) package for easier fine-grained bundle creation | |
| 22 | +| [v1.29.0](https://github.com/shikijs/shiki/releases/tag/v1.28.0) | Improved the transformer matching algorithm, introduce `matchAlgorithm` option. Thanks to [@fuma-nama](https://github.com/fuma-nama) | |
| 23 | + |
| 24 | +Among all these new features, we also includes a lot of new languages support and new themes. Check out [languages](/languages) and [themes](/themes) list for the full list. |
| 25 | + |
| 26 | +Meanwhile, huge thanks to [@slevithan](https://github.com/slevithan)'s great work on [`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es) that make the [JavaScript engine supports 97.2% of all the languages](/references/engine-js-compat). |
| 27 | + |
| 28 | +## Breaking Changes |
| 29 | + |
| 30 | +There are **NO** hard breaking changes in v2.0.0. It serves as a stepping stone for the upcoming v3.0.0. |
| 31 | + |
| 32 | +The only change in v2 is that Shiki will now **emit warnings when you are using APIs that are deprecated** and planned to be removed in v3. As this might affect the end users, we make a major version bump so you can opt-in to the warnings and prepare for the future removal. |
| 33 | + |
| 34 | +- `v1.x`: Deprecated APIs are still supported, marked on type level only. With optional runtime warnings to opt-in. |
| 35 | +- 👉 `v2.0`: No breaking changes, but enable runtime deprecated warnings by default. |
| 36 | +- `v3.0`: Remove deprecated APIs, breaking changes. |
| 37 | + |
| 38 | +Expect v3.0.0 to be released soon after v2.0.0. |
| 39 | + |
| 40 | +## Deprecations |
| 41 | + |
| 42 | +We highly recommend you to migrate them sooner. |
| 43 | + |
| 44 | +### `getHighlighter` -> `createHighlighter` |
| 45 | + |
| 46 | +There is no functional changes, but more like correcting the naming to avoid confusion. It should be a straightforward find-and-replace. |
| 47 | + |
| 48 | +### WASM Related APIs |
| 49 | + |
| 50 | +Since the introduce of the [engine system](/guide/regex-engines) in v0.16, the WebAssembly related dependencies are no longer a hard requirement. To make tree-shaking easier and decoupled the engines with the core, two packages are extracted `@shikijs/engine-oniguruma` and `@shikijs/engine-javascript`. They are also re-exported from the main package's `shiki/engine/oniguruma` and `shiki/engine/javascript` respectively. |
| 51 | + |
| 52 | +You might need to change your import path: |
| 53 | + |
| 54 | +```ts |
| 55 | +import { loadWasm } from 'shiki' // [!code --] |
| 56 | +import { loadWasm } from 'shiki/engine/oniguruma' // [!code ++] |
| 57 | +``` |
| 58 | +
|
| 59 | +`loadWasm` field in `createHighlighterCore` is replaced with `engine` field: |
| 60 | +
|
| 61 | +```ts |
| 62 | +import { createHighlighter } from 'shiki' |
| 63 | +import { createOnigurumaEngine } from 'shiki/engine/oniguruma' // [!code ++] |
| 64 | +
|
| 65 | +const shiki = await createHighlighter({ |
| 66 | + // ... |
| 67 | + loadWasm: () => import('shiki/wasm'), // [!code --] |
| 68 | + engine: createOnigurumaEngine(() => import('shiki/wasm')), // [!code ++] |
| 69 | +}) |
| 70 | +``` |
| 71 | + |
| 72 | +### Shiki Compat |
| 73 | + |
| 74 | +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. |
| 75 | + |
| 76 | +### Transformers Matching Algorithm |
| 77 | + |
| 78 | +The `matchAlgorithm` option for transformers is introduced in v1.29.0 to allow users to choose the matching algorithm. The default value will be changed from `v1` to `v3` in v3.0.0. We recommend you to set the `matchAlgorithm` option explicitly to avoid breaking changes in the future. |
| 79 | + |
| 80 | +[Learn more](/packages/transformers#matching-algorithm). |
| 81 | + |
| 82 | +### Other Deprecations |
| 83 | + |
| 84 | +- `createdBundledHighlighter` requires a single object-style argument |
| 85 | +- `@shikijs/core` |
| 86 | + - The regex engines `createJavaScriptRegexEngine` `createOnigurumaEngine` are no longer included, import them from `@shikijs/engine-oniguruma` and `@shikijs/engine-javascript` respectively |
| 87 | + - `createHighlighterCore` now explicits requires an `engine` field to be passed |
| 88 | + - `loadWasm` field in `createHighlighterCore` is replaced with `engine` field |
| 89 | + - `@shikijs/core/wasm-inline` is replaced with `@shikijs/engine-oniguruma/wasm-inline` |
| 90 | + - Import `FontStyle` and `StackElementMetadata` from `@shikijs/vscode-textmate` instead of `@shikijs/core` |
| 91 | + |
| 92 | +## Tweaking Warnings |
| 93 | + |
| 94 | +If you prepre 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: |
| 95 | + |
| 96 | +```ts |
| 97 | +import { enableDeprecationWarnings } from 'shiki/core' |
| 98 | + |
| 99 | +enableDeprecationWarnings(true, true) // enable warnings and throw errors |
| 100 | + |
| 101 | +// use crateHighlighter(...) etc. after that |
| 102 | +``` |
| 103 | + |
| 104 | +### Disable Warnings |
| 105 | + |
| 106 | +If you want to disable the warnings: |
| 107 | + |
| 108 | +```ts |
| 109 | +import { enableDeprecationWarnings } from 'shiki/core' |
| 110 | + |
| 111 | +enableDeprecationWarnings(false) |
| 112 | +``` |
| 113 | + |
| 114 | +## Feedback |
| 115 | + |
| 116 | +Any feedbacks are welcome! Feel free to open an issue on [GitHub](https://github.com/shikijs/shiki) and let us know your thoughts. |
0 commit comments