Installation & Usage

Installation

Install via npm, or see CDN Usage:

npmyarnpnpmbundeno

npm install -D shiki

yarn add -D shiki

pnpm add -D shiki

bun add -D shiki

deno add npm:shiki

Integrations

We also provide some integrations:

Usage

Shorthands

The quickest way to get started with shiki is to use the provided shorthand functions. These will load the necessary themes and languages on demand, and automatically cache them in memory.

Passing your code snippet to the codeToHtml function with the lang and theme specified, it will return a highlighted HTML string that you can embed in your page. The generated HTML contains inline style for each token, so you don't need extra CSS to style it.

import {codeToHtml } from 'shiki'

const code = 'const a = 1' // input code
const html = awaitcodeToHtml(code, {
lang: 'javascript',
theme: 'vitesse-dark'
})

console.log(html) // highlighted html string

Going a bit advanced, you can also use codeToTokens or codeToHast to get the intermediate data structure, and render them by yourself:

import { codeToTokens } from 'shiki'

const { tokens } = awaitcodeToTokens('<div class="foo">bar</div>', {
lang: 'html',
theme: 'min-dark'
})

import {codeToHast} from 'shiki'

consthast= awaitcodeToHast('.text-red { color: red; }', {
lang: 'css',
theme: 'catppuccin-mocha'
})

Highlighter Usage

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

import {createHighlighter } from 'shiki'

// `createHighlighter` is async, it initializes the internal and
// loads the themes and languages specified.
consthighlighter = awaitcreateHighlighter({
themes: ['nord'],
langs: ['javascript'],
})

// then later you can use `highlighter.codeToHtml` synchronously
// with the loaded themes and languages.
constcode =highlighter.codeToHtml('const a = 1', {
lang: 'javascript',
theme: 'nord'
})

Important Note

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

// load themes and languages after creation
awaithighlighter.loadTheme('vitesse-light')
awaithighlighter.loadLanguage('css')

Since Shiki v1.0, it requires all themes and languages to be loaded explicitly.

import { createHighlighter } from 'shiki'

consthighlighter = awaitcreateHighlighter({
themes: ['slack-dark'],
langs: ['css']
})

highlighter.codeToHtml(
 'const a = 1',
 { lang: 'javascript', theme: 'slack-dark' }
)
Throw error, `javascript` is not loaded
awaithighlighter.loadLanguage('javascript') // load the language

// now it works

If you want to load all themes and languages (not recommended), you can iterate over all keys from bundledLanguages and bundledThemes.

import {bundledLanguages,bundledThemes,createHighlighter } from 'shiki'

consthighlighter = awaitcreateHighlighter({
themes:Object.keys(bundledThemes),
langs:Object.keys(bundledLanguages),
})

highlighter.codeToHtml('const a = 1', {
lang: 'javascript',
theme: 'poimandres'
})

Fine-grained Bundle

When importing shiki, all the themes and languages are bundled as async chunks. Normally it won't be a concern to you as they are not being loaded if you don't use them. In some cases, if you want to control what to bundle, you can use the core and compose your own bundle.

Check out the Fine-grained Bundle section for more details.

Bundle Presets

We also provide some pre-composed bundles for you to use easily, you can learn more about them in the bundles section.

CJS Usage

shiki is published as ESM-only to reduce the package size. It's still possible to use it in CJS, as Node.js supports importing ESM modules dynamically in CJS.

For example, the following ESM code:

// ESM
import {createHighlighter } from 'shiki'

async functionmain() {
 const highlighter = awaitcreateHighlighter({
themes: ['vitesse-dark'],
langs: ['javascript'],
 })

 const code =highlighter.codeToHtml('const a = 1', {
theme: 'vitesse-dark',
lang: 'javascript',
 })
}

Can be written in CJS as:

// CJS
async functionmain() {
 const {createHighlighter } = await import('shiki')

 const highlighter = awaitcreateHighlighter({
themes: ['vitesse-dark'],
langs: ['javascript'],
 })

 const code =highlighter.codeToHtml('const a = 1', {
theme: 'vitesse-dark',
lang: 'javascript'
 })
}

CDN Usage

To use shiki in the browser via CDN, you can use esm.run or esm.sh.

html

<body>
 <div id="foo"></div>

 <script type="module">
 // be sure to specify the exact version
 import { codeToHtml } from 'https://esm.sh/shiki@3.0.0'
 // or
 // import { codeToHtml } from 'https://esm.run/shiki@3.0.0'

 const foo = document.getElementById('foo')
 foo.innerHTML = await codeToHtml('console.log("Hi, Shiki on CDN :)")', {
 lang: 'js',
 theme: 'rose-pine'
 })
 </script>
</body>

It's quite efficient as it will only load the languages and themes on demand. For the code snippet above, only four requests will be fired (shiki, @shikijs/themes/vitesse-light, @shikijs/langs/javascript, shiki/wasm.mjs), with around 200KB data transferred in total.

Demo

Cloudflare Workers

Cloudflare Workers does not support initializing WebAssembly from binary data, so the default wasm build won't work. You need to upload the wasm as assets and import it directly.

Meanwhile, it's also recommended to use the Fine-grained Bundle approach to reduce the bundle size.

importjs from '@shikijs/langs/javascript'
importnord from '@shikijs/themes/nord'
import {createHighlighterCore } from 'shiki/core'
import {loadWasm } from 'shiki/engine/oniguruma'

// import wasm as assets
awaitloadWasm(import('shiki/onig.wasm'))

export default {
 asyncfetch() {
 consthighlighter = awaitcreateHighlighterCore({
themes: [nord],
langs: [js],
 })

 return newResponse(highlighter.codeToHtml('console.log(\'shiki\');', {
theme: 'nord',
lang: 'js'
 }))
 },
}

Installation & Usage ​

Installation ​

Integrations ​

Usage ​

Shorthands ​

Highlighter Usage ​

Fine-grained Bundle ​

Bundle Presets ​

CJS Usage ​

CDN Usage ​

Cloudflare Workers ​