# Shiki: TextMate-Grammar Syntax Highlighter for the Web

> Shiki is a TypeScript syntax highlighter that uses TextMate grammars and VS Code themes to produce accurate, token-level highlighted output. Version 4 is the current branch, organized as a monorepo with separate packages for engines, language grammars, themes, and framework integrations.

**shikijs/shiki** — A beautiful yet powerful syntax highlighter

- Repository: https://github.com/shikijs/shiki
- Website: http://shiki.style/
- Stars: 13,841 · Forks: 607
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/shikijs-shiki

## What Shiki Does and Why TextMate Grammars

Shiki is a syntax highlighter that produces token-level colored output from source code. The README describes it as a beautiful syntax highlighter based on TextMate grammar, accurate and powerful. TextMate grammars define how a language's tokens are parsed into semantic categories, the same grammar format used by VS Code and most other modern code editors. Using the same grammar means Shiki's output matches what a developer sees in their editor.

Syntax highlighters that use regular expression rules written specifically for the highlighter library (such as Prism or highlight.js) produce results that differ from editor highlighting because they use independently maintained grammar definitions. Shiki avoids this divergence by reusing the actual TextMate grammars.

Shiki is MIT-licensed and requires Node.js 20 or later, as specified in the engines field of the root package.json. The npm package name is shiki, as shown by the npm badge in the README. The current release is v4.4.3, published on 2026-08-10.

## Repository Layout: Engines, Languages, and Themes

Shiki v4 is organized as a pnpm monorepo built with Turborepo. The packages directory contains the core packages distributed to npm. The root package.json lists the following workspace packages among the devDependencies, which reveals the full scope of the published surface:

@shikijs/engine-javascript provides a pure-JavaScript implementation of the TextMate grammar engine. @shikijs/engine-oniguruma provides the Oniguruma-based engine, which uses a WebAssembly build of the original Oniguruma regular expression library for broader grammar compatibility. These two engines are interchangeable at configuration time.

@shikijs/langs and @shikijs/langs-precompiled hold the language grammar definitions. @shikijs/themes holds the available themes, which include VS Code's built-in themes. @shikijs/types provides the TypeScript type definitions shared across packages. @shikijs/transformers holds transformation utilities for post-processing highlighted output.

Framework integrations are packaged separately: @shikijs/markdown-it integrates with the markdown-it parser, @shikijs/rehype integrates with the Rehype pipeline used by unified and MDX, @shikijs/monaco integrates with the Monaco editor, @shikijs/twoslash provides TypeScript annotation support, and @shikijs/vitepress-twoslash combines VitePress with Twoslash for documentation sites.

## Version History: From v0 to v4

The README documents the branch history for Shiki explicitly, which matters because older versions remain in use across documentation sites. The table in the README lists:

- v4 (current main branch): the version at v4.4.3
- v3: frozen at v3.23
- v2: frozen at v2.5
- v1: frozen at v1.29
- v0: frozen at v0.14, described as the legacy version

Each version corresponds to a separate git branch. The jump from v1 to v2 and from v2 to v3 involved API changes that required code updates in consuming projects. Documentation for older APIs is on the respective branches rather than the main branch or the shiki.style documentation site.

The package.json shows that the packageManager is pnpm@12.3.4 and the project uses Turborepo for its build pipeline. The vitest.config.ts and bench/ directory indicate a test and benchmark suite that covers highlighter output correctness and performance.

## The Two-Engine Design and Compatibility

Shiki's engine separation between @shikijs/engine-javascript and @shikijs/engine-oniguruma reflects a real technical trade-off. Oniguruma is the regular expression engine that TextMate grammars were originally written for. Its regex syntax includes constructs that are not available in JavaScript's built-in regex engine, such as certain lookahead and lookbehind patterns. The Oniguruma engine loads a compiled WebAssembly binary to run those patterns exactly.

The JavaScript engine avoids the WebAssembly dependency at the cost of reduced grammar compatibility. Grammars that use Oniguruma-specific regex syntax may produce incorrect or degraded highlighting when run through the JavaScript engine. For most common programming languages this difference is not visible, but for languages with complex grammar definitions it can matter.

The trade-off maps to deployment constraints: edge functions and environments that restrict WebAssembly need the JavaScript engine, while standard Node.js and browser environments can use either.

## Integration Packages and the Rehype Pipeline

Shiki's integration packages make it usable within the documentation and site generation tools that most developers actually run rather than requiring them to call the highlighter API directly. The @shikijs/rehype package integrates Shiki into the unified/rehype processing pipeline, which underlies MDX, Astro's content layer, and several other documentation frameworks.

The @shikijs/markdown-it package targets markdown-it, the parser used by VitePress and many other tools. @shikijs/vitepress-twoslash combines Shiki, VitePress, and Twoslash in a single package for TypeScript documentation with inline type information and compiler output. @shikijs/monaco provides Shiki theme synchronization for the Monaco editor, which powers VS Code's embedded editor and web-based code editors.

The @shikijs/colorized-brackets package handles bracket pair colorization, a feature that VS Code users may expect to carry over to highlighted documentation output.

## Limitations: Bundle Size, Grammar Coverage, and SSR

Shiki's language grammar and theme bundles are large. TextMate grammars for a full set of languages and all VS Code themes can add hundreds of kilobytes to a bundle. The langs and themes packages are designed to be tree-shakeable so that only the grammars and themes actually used are included. However, even a small set of languages has a non-trivial bundle size compared to lightweight highlighters like Prism.

The Oniguruma engine requires loading a WebAssembly binary, which adds an initialization step. In server-side rendering scenarios where highlighting happens at build time this cost is paid once, but in client-side scenarios it requires the WebAssembly binary to be loaded before any highlighting can proceed.

The README does not document supported grammars or themes; that documentation is on shiki.style. Projects that need a grammar for a niche language must verify that it is included in @shikijs/langs before committing to Shiki rather than a library where custom grammars can be added as plain JavaScript objects.

## Alternatives: Prism and highlight.js

Prism is a lightweight syntax highlighter that uses regular expression rules written in JavaScript. It has a small core bundle and loads language definitions on demand. Prism's grammar definitions are independent of TextMate, so the output can differ from what VS Code shows for the same code. For simple documentation sites where exact editor-fidelity is not a requirement and bundle size is a priority, Prism is smaller and requires no WebAssembly.

highlight.js is another browser-oriented syntax highlighter that uses its own grammar format and auto-detects languages from code blocks without an explicit language annotation. It does not use TextMate grammars. Shiki requires an explicit language to be specified for each code block, which gives more predictable results but requires every code block in a document to be annotated.

## Conclusion

Shiki suits documentation sites, code playgrounds, and static site generators that need accurate, VS Code-quality syntax highlighting without a client-side JavaScript bundle. The two-engine design (JavaScript and Oniguruma) lets a project pick the engine that best fits its deployment: a pure-JS engine for environments where WebAssembly is constrained, and the Oniguruma engine for maximum grammar compatibility. The shikijs GitHub organization maintains the repository, with the last push on 2026-09-11 and the current release at v4.4.3.

## FAQ

### What is Shiki and what does it do?

Shiki is a TypeScript syntax highlighter that uses TextMate grammars, the same grammar format as VS Code, to produce accurate token-level highlighted output. It is available as the shiki npm package and supports two interchangeable highlight engines.

### What is the difference between the Shiki JavaScript engine and the Oniguruma engine?

The Oniguruma engine loads a WebAssembly binary to support the full Oniguruma regex syntax that TextMate grammars were written for, giving maximum grammar compatibility. The JavaScript engine avoids WebAssembly but may produce degraded highlighting for grammars that use Oniguruma-specific regex constructs.

### Which framework integrations does Shiki provide?

Shiki ships separate integration packages for markdown-it, Rehype (used by MDX and Astro), Monaco editor, VitePress with Twoslash, and standalone Twoslash for TypeScript annotation support. Each is an independently installable package from the shikijs npm scope.

## Sources

- [License: MIT](https://github.com/shikijs/shiki/blob/main/LICENSE)
- [Project website](http://shiki.style/)
- [README](https://github.com/shikijs/shiki/blob/main/README.md)
- [Releases](https://github.com/shikijs/shiki/releases)
- [shikijs/shiki on GitHub](https://github.com/shikijs/shiki)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/shikijs-shiki