feat!: rename getHighlighter to createHighlighter (#702)

docs/.vitepress/store/playground.ts

@@ -39,7 +39,7 @@ export const usePlayground = defineStore('playground', () => {
   }
 
   ;(async () => {
-    const { getHighlighter } = await import('shiki')
+    const { createHighlighter } = await import('shiki')
     const { bundledLanguagesInfo: bundleFull } = await import('shiki/bundle/full')
     const { bundledLanguagesInfo: bundleWeb } = await import('shiki/bundle/web')
     const { bundledThemesInfo } = await import('shiki/themes')
@@ -64,7 +64,7 @@ export const usePlayground = defineStore('playground', () => {
     bundledLangsWeb.value = bundleWeb
 
     if (typeof window !== 'undefined') {
-      const highlighter = await getHighlighter({
+      const highlighter = await createHighlighter({
         themes: [theme.value],
         langs: ['typescript', 'javascript', lang.value as any],
       })

docs/api.md

@@ -5,9 +5,9 @@
 You can also get the intermediate `hast` to do custom rendering without serializing them into HTML with `codeToHast`. You can also further integrate the AST with the [unified](https://github.com/unifiedjs) ecosystem.
 
 ```ts twoslash
-import { getHighlighter } from 'shiki'
+import { createHighlighter } from 'shiki'
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   themes: ['nord', 'min-light'],
   langs: ['javascript'],
 })

docs/guide/bundles.md

@@ -27,10 +27,10 @@ import {
   BundledLanguage,
   BundledTheme,
   codeToHtml,
-  getHighlighter
+  createHighlighter
 } from 'shiki/bundle/web' // [!code highlight]
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   langs: ['html', 'css', 'js'],
   themes: ['github-dark', 'github-light'],
 })

docs/guide/install.md

@@ -80,16 +80,16 @@ const hast = await codeToHast('.text-red { color: red; }', {
 
 ### Highlighter Usage
 
-The [shorthands](#shorthands) we provided are executed asynchronously as we use WASM and load themes and languages on demand internally. In some cases, you may need to highlight code synchronously, so we provide the `getHighlighter` function to create a highlighter instance that can later be used synchronously.
+The [shorthands](#shorthands) we provided are executed asynchronously as we use WASM and load themes and languages on demand internally. In some cases, you may need to highlight code synchronously, so we provide the `createHighlighter` function to create a highlighter instance that can later be used synchronously.
 
 The usage is pretty much the same as with `codeToHtml`, where each theme and language file is a dynamically imported ES module. It would be better to list the languages and themes **explicitly** to have the best performance.
 
 ```ts twoslash theme:nord
-import { getHighlighter } from 'shiki'
+import { createHighlighter } from 'shiki'
 
-// `getHighlighter` is async, it initializes the internal and
+// `createHighlighter` is async, it initializes the internal and
 // loads the themes and languages specified.
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   themes: ['nord'],
   langs: ['javascript'],
 })
@@ -103,16 +103,16 @@ const code = highlighter.codeToHtml('const a = 1', {
 ```
 
 :::info Important Note
-Highlighter instance should be **long-lived singleton**. You might need to cache it somewhere and reuse it across your application. Avoid calling `getHighlighter` in hot functions or loops.
+Highlighter instance should be **long-lived singleton**. You might need to cache it somewhere and reuse it across your application. Avoid calling `createHighlighter` in hot functions or loops.
 
 If running on Node.js, we recommend using the [Shorthands](#shorthands) which manages the highlighter instance and dynamic theme/language loading for you.
 :::
 
 Additionally, if you want to load themes and languages after the highlighter is created, you can use the `loadTheme` and `loadLanguage` methods.
 
 ```ts twoslash
-import { getHighlighter } from 'shiki'
-const highlighter = await getHighlighter({ themes: [], langs: [] })
+import { createHighlighter } from 'shiki'
+const highlighter = await createHighlighter({ themes: [], langs: [] })
 // ---cut---
 // load themes and languages after creation
 await highlighter.loadTheme('vitesse-light')
@@ -122,9 +122,9 @@ await highlighter.loadLanguage('css')
 Since Shiki v1.0, it requires all themes and languages to be loaded explicitly.
 
 ```ts theme:slack-dark twoslash
-import { getHighlighter } from 'shiki'
+import { createHighlighter } from 'shiki'
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   themes: ['slack-dark'],
   langs: ['css']
 })
@@ -143,9 +143,9 @@ await highlighter.loadLanguage('javascript') // load the language
 If you want to load all themes and languages (not recommended), you can iterate over all keys from `bundledLanguages` and `bundledThemes`.
 
 ```ts twoslash theme:poimandres
-import { bundledLanguages, bundledThemes, getHighlighter } from 'shiki'
+import { bundledLanguages, bundledThemes, createHighlighter } from 'shiki'
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   themes: Object.keys(bundledThemes),
   langs: Object.keys(bundledLanguages),
 })
@@ -163,15 +163,15 @@ When importing `shiki`, all the themes and languages are bundled as async chunks
 ```ts twoslash theme:material-theme-ocean
 // @noErrors
 // `shiki/core` entry does not include any themes or languages or the wasm binary.
-import { getHighlighterCore } from 'shiki/core'
+import { createHighlighterCore } from 'shiki/core'
 
 // `shiki/wasm` contains the wasm binary inlined as base64 string.
 import getWasm from 'shiki/wasm'
 
 // directly import the theme and language modules, only the ones you imported will be bundled.
 import nord from 'shiki/themes/nord.mjs'
 
-const highlighter = await getHighlighterCore({
+const highlighter = await createHighlighterCore({
   themes: [
     // instead of strings, you need to pass the imported module
     nord,
@@ -213,10 +213,10 @@ For example, the following ESM code:
 
 ```ts twoslash
 // ESM
-import { getHighlighter } from 'shiki'
+import { createHighlighter } from 'shiki'
 
 async function main() {
-  const highlighter = await getHighlighter({
+  const highlighter = await createHighlighter({
     themes: ['vitesse-dark'],
     langs: ['javascript'],
   })
@@ -233,9 +233,9 @@ Can be written in CJS as:
 ```ts twoslash
 // CJS
 async function main() {
-  const { getHighlighter } = await import('shiki')
+  const { createHighlighter } = await import('shiki')
 
-  const highlighter = await getHighlighter({
+  const highlighter = await createHighlighter({
     themes: ['vitesse-dark'],
     langs: ['javascript'],
   })
@@ -282,7 +282,7 @@ Meanwhile, it's also recommended to use the [Fine-grained Bundle](#fine-grained-
 
 ```ts twoslash theme:nord
 // @noErrors
-import { getHighlighterCore, loadWasm } from 'shiki/core'
+import { createHighlighterCore, loadWasm } from 'shiki/core'
 import nord from 'shiki/themes/nord.mjs'
 import js from 'shiki/langs/javascript.mjs'
 
@@ -291,7 +291,7 @@ await loadWasm(import('shiki/onig.wasm'))
 
 export default {
   async fetch() {
-    const highlighter = await getHighlighterCore({
+    const highlighter = await createHighlighterCore({
       themes: [nord],
       langs: [js],
     })

docs/guide/load-lang.md

@@ -6,11 +6,11 @@ You can load custom languages by passing a TextMate grammar object into the `lan
 
 ```ts twoslash
 // @noErrors
-import { getHighlighter } from 'shiki'
+import { createHighlighter } from 'shiki'
 
 const myLang = JSON.parse(fs.readFileSync('my-lang.json', 'utf8'))
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   langs: [myLang],
   themes: ['vitesse-light']
 })
@@ -25,11 +25,11 @@ You can also load languages after the highlighter has been created.
 
 ```ts twoslash
 // @noErrors
-import { getHighlighter } from 'shiki'
+import { createHighlighter } from 'shiki'
 
 const myLang = JSON.parse(fs.readFileSync('my-lang.json', 'utf8'))
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   langs: [],
   themes: ['vitesse-light'],
 })
@@ -49,7 +49,7 @@ Since v1.0, `shiki` now is environment agnostic, we don't have access to the fil
 For example, the following would not work:
 
 ```ts
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   langs: [
     {
       name: 'vue-vine',
@@ -75,7 +75,7 @@ Instead, load that file yourself (via `fs`, `import()`, `fetch()`, etc.):
 ```ts
 const vineGrammar = JSON.parse(fs.readFileSync(join(__dirname, './vine-ts.tmLanguage.json'), 'utf8'))
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   langs: [
     {
       name: 'vue-vine',
@@ -100,9 +100,9 @@ const highlighter = await getHighlighter({
 You can register custom language aliases with the `langAlias` option. For example:
 
 ```ts twoslash
-import { getHighlighter } from 'shiki'
+import { createHighlighter } from 'shiki'
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   langs: ['javascript'],
   langAlias: { // [!code hl:3]
     mylang: 'javascript',

docs/guide/load-theme.md

@@ -5,7 +5,7 @@ See [All Builtin Themes](/themes) first.
 You can load custom themes by passing a `Theme` object into the `themes` array.
 
 ```ts twoslash
-import { getHighlighter } from 'shiki'
+import { createHighlighter } from 'shiki'
 
 const myTheme = {
   name: 'my-theme',
@@ -20,7 +20,7 @@ const myTheme = {
   ]
 }
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   themes: [myTheme],
   langs: [],
 })
@@ -36,12 +36,12 @@ You can also load themes after the highlighter has been created.
 
 ```ts twoslash
 // @noErrors
-import { getHighlighter } from 'shiki'
+import { createHighlighter } from 'shiki'
 
 // Load the theme object from a file, a network request, or anywhere
 const myTheme = JSON.parse(fs.readFileSync('my-theme.json', 'utf8'))
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   langs: ['javascript'],
   themes: [],
 })

docs/guide/migrate.md

@@ -27,7 +27,7 @@ Breaking changes applies to main package `shiki`, but are shimmed by the [compat
 
 - Top-level named exports `setCDN`, `loadLanguage`, `loadTheme`, `setWasm` are dropped as they are not needed anymore.
 - `BUNDLED_LANGUAGES`, `BUNDLED_THEMES` are moved to `shiki/langs` and `shiki/themes` and renamed to `bundledLanguages` and `bundledThemes` respectively.
-- `theme` option for `getHighlighter` is dropped, use `themes` with an array instead.
+- `theme` option for `createHighlighter` is dropped, use `themes` with an array instead.
 - Highlighter does not maintain an internal default theme context. `theme` option is required for `codeToHtml` and `codeToTokens`.
 - `codeToThemedTokens` is renamed to `codeToTokensBase`, a higher level `codeToTokens` is added.
 - `codeToTokens` sets `includeExplanation` to `false` by default.

docs/guide/theme-colors.md

@@ -5,9 +5,9 @@
 Usually, TextMate themes expect the color values of each token to be a valid hex color value. This limitation is inherited from [`vscode-textmate`](https://github.com/microsoft/vscode-textmate). However, in Shiki v0.9.15 we introduced an automatic workaround by replacing non-hex color values with a placeholder and replacing them back on tokenization. This would allows you to use themes with arbitrary color values for rendering without worrying about the technical details:
 
 ```ts twoslash
-import { getHighlighter } from 'shiki'
+import { createHighlighter } from 'shiki'
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   langs: ['javascript'],
   themes: [
     {
@@ -99,7 +99,7 @@ Shiki provides a factory function helper `createCssVariablesTheme` for creating
 This theme is **not included by default** and must be registered explicitly:
 
 ```ts twoslash
-import { createCssVariablesTheme, getHighlighter } from 'shiki'
+import { createCssVariablesTheme, createHighlighter } from 'shiki'
 
 // Create a custom CSS variables theme, the following are the default values
 const myTheme = createCssVariablesTheme({ // [!code hl:6]
@@ -109,7 +109,7 @@ const myTheme = createCssVariablesTheme({ // [!code hl:6]
   fontStyle: true
 })
 
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   langs: ['javascript'],
   themes: [myTheme] // register the theme // [!code hl]
 })

docs/packages/markdown-it.md

@@ -34,9 +34,9 @@ By default, the full bundle of `shiki` will be imported. If you are using a [fin
 // @noErrors: true
 import MarkdownIt from 'markdown-it'
 import { fromHighlighter } from '@shikijs/markdown-it/core'
-import { getHighlighterCore } from 'shiki/core'
+import { createHighlighterCore } from 'shiki/core'
 
-const highlighter = await getHighlighterCore({
+const highlighter = await createHighlighterCore({
   themes: [
     import('shiki/themes/vitesse-light.mjs')
   ],

docs/packages/monaco.md

@@ -15,12 +15,12 @@ npm i -D @shikijs/monaco
 ```
 
 ```ts
-import { getHighlighter } from 'shiki'
+import { createHighlighter } from 'shiki'
 import { shikiToMonaco } from '@shikijs/monaco'
 import * as monaco from 'monaco-editor-core'
 
 // Create the highlighter, it can be reused
-const highlighter = await getHighlighter({
+const highlighter = await createHighlighter({
   themes: [
     'vitesse-dark',
     'vitesse-light',

docs/packages/rehype.md

@@ -50,9 +50,9 @@ import remarkRehype from 'remark-rehype'
 import rehypeStringify from 'rehype-stringify'
 import rehypeShikiFromHighlighter from '@shikijs/rehype/core'
 
-import { getHighlighterCore } from 'shiki/core'
+import { createHighlighterCore } from 'shiki/core'
 
-const highlighter = await getHighlighterCore({
+const highlighter = await createHighlighterCore({
   themes: [
     import('shiki/themes/vitesse-light.mjs')
   ],

docs/packages/twoslash.md

@@ -92,9 +92,9 @@ Number.parseInt('123', 10)
 ```
 
 ```ts twoslash
-import { getHighlighterCore } from 'shiki/core'
+import { createHighlighterCore } from 'shiki/core'
 
-const highlighter = await getHighlighterCore({})
+const highlighter = await createHighlighterCore({})
 // @log: Custom log message
 const a = 1
 // @error: Custom error message

packages/compat/index.cjs

@@ -1,13 +1,13 @@
-async function getHighlighter(...args) {
-  const { getHighlighter } = await import('./dist/index.mjs')
-  return getHighlighter(...args)
+async function createHighlighter(...args) {
+  const { createHighlighter } = await import('./dist/index.mjs')
+  return createHighlighter(...args)
 }
 
 async function loadTheme(...args) {
   const { loadTheme } = await import('./dist/index.mjs')
   return loadTheme(...args)
 }
 
-module.exports = getHighlighter
-module.exports.getHighlighter = getHighlighter
+module.exports = createHighlighter
+module.exports.createHighlighter = createHighlighter
 module.exports.loadTheme = loadTheme

packages/compat/src/index.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
 import type { BuiltinLanguage, BuiltinTheme, CodeToTokensBaseOptions, MaybeGetter, StringLiteralUnion, ThemeInput, ThemeRegistrationAny, ThemeRegistrationResolved, ThemedToken } from 'shiki'
-import { bundledLanguages, bundledThemes, getHighlighter as getShiki, normalizeTheme, tokenizeAnsiWithTheme } from 'shiki'
+import { bundledLanguages, bundledThemes, createHighlighter as getShiki, normalizeTheme, tokenizeAnsiWithTheme } from 'shiki'
 import { transformerCompactLineOptions } from '@shikijs/transformers'
 import type { AnsiToHtmlOptions, CodeToHtmlOptions, CodeToHtmlOptionsExtra, HighlighterOptions } from './types'
 import { ShikiCompatError } from './error'