# shikijs/shiki architecture

> Architecture diagram of the GitHub repository shikijs/shiki, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shikijs/shiki
- Repository: https://github.com/shikijs/shiki

## Overview

Shiki is a TextMate-grammar-based syntax highlighter. Its main workflow is to accept code and language/theme configuration, match grammar patterns with a regex engine, then produce highlighted output for consumers. The workspace also provides editor and Markdown adapters, token transformers, and framework-specific rendering products. The source index supports several internal links, but many package implementations were not sampled; uncertain connections are therefore omitted or marked dashed.

Main entry points: [`packages/shiki/src/core.ts`](https://github.com/shikijs/shiki/blob/main/packages/shiki/src/core.ts) (Shiki API), [`packages/core/src/highlight/code-to-hast.ts`](https://github.com/shikijs/shiki/blob/main/packages/core/src/highlight/code-to-hast.ts) (Highlight conversion), [`packages/engine-javascript/src/engine-compile.ts`](https://github.com/shikijs/shiki/blob/main/packages/engine-javascript/src/engine-compile.ts) (JavaScript regex), [`packages/engine-javascript/src/scanner.ts`](https://github.com/shikijs/shiki/blob/main/packages/engine-javascript/src/scanner.ts) (Regex scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_highlighting["Highlighting runtime"]
  node_api["Shiki API<br/>[core.ts]"]
  node_highlight["Highlight conversion<br/>[code-to-hast.ts]"]
  node_html["HTML output<br/>[code-to-html.ts]"]
  node_tokens["Token output<br/>[code-to-tokens.ts]"]
end

subgraph group_engines["Grammar and engines"]
  node_textmate["TextMate runtime<br/>[grammar-state.ts]"]
  node_primitive["Primitive tokenizer"]
  node_jsengine["JavaScript regex<br/>[engine-compile.ts]"]
  node_scanner["Regex scanner<br/>[scanner.ts]"]
  node_onig["Oniguruma engine<br/>[index.ts]"]
  node_bundles["Languages and themes<br/>[langs.ts]"]
  node_packages_engine_javascript_string["String adapter<br/>[string.ts]"]
end

subgraph group_integrations["Consumer integrations"]
  node_cli["Terminal CLI<br/>[cli.ts]"]
  node_ansi["ANSI conversion<br/>[code-to-ansi.ts]"]
  node_monaco["Monaco adapter<br/>[index.ts]"]
  node_rehype["Rehype adapter<br/>[core.ts]"]
  node_markdownit["Markdown-it adapter<br/>[core.ts]"]
end

subgraph group_extensions["Highlighting extensions"]
  node_transformers["Token transformers"]
  node_brackets["Bracket coloring"]
  node_twoslash["Rich Twoslash renderer<br/>[renderer-rich.ts]"]
end

subgraph group_rendering["Framework rendering"]
  node_magicmove["Magic Move<br/>[renderer.ts]"]
  node_stream["Streaming highlighter<br/>[stream.ts]"]
end

node_user(("Application"))

node_user -.->|"configures and highlights"| node_api
node_api -.->|"uses"| node_highlight
node_highlight -.->|"renders HTML"| node_html
node_highlight -.->|"produces tokens"| node_tokens
node_primitive -->|"uses grammar state"| node_textmate
node_jsengine -->|"constructs scanner"| node_scanner
node_scanner -->|"uses string adapter"| node_packages_engine_javascript_string
node_api -->|"re-exports engine"| node_jsengine
node_api -->|"re-exports engine"| node_onig
node_api -.->|"uses bundled assets"| node_bundles
node_cli -->|"formats terminal output"| node_ansi
node_monaco -->|"integrates highlighter"| node_api
node_rehype -.->|"adapts code blocks"| node_highlight
node_markdownit -.->|"adapts Markdown"| node_highlight
node_transformers -.->|"transforms output"| node_highlight
node_brackets -->|"colors tokens"| node_tokens
node_twoslash -.->|"highlights popup code"| node_api
node_magicmove -.->|"animates highlighted code"| node_api
node_stream -.->|"streams highlighting"| node_api

click node_api "https://github.com/shikijs/shiki/blob/main/packages/shiki/src/core.ts"
click node_highlight "https://github.com/shikijs/shiki/blob/main/packages/core/src/highlight/code-to-hast.ts"
click node_html "https://github.com/shikijs/shiki/blob/main/packages/core/src/highlight/code-to-html.ts"
click node_tokens "https://github.com/shikijs/shiki/blob/main/packages/core/src/highlight/code-to-tokens.ts"
click node_textmate "https://github.com/shikijs/shiki/blob/main/packages/primitive/src/textmate/grammar-state.ts"
click node_primitive "https://github.com/shikijs/shiki/blob/main/packages/primitive/src/highlight/code-to-tokens-base.ts"
click node_jsengine "https://github.com/shikijs/shiki/blob/main/packages/engine-javascript/src/engine-compile.ts"
click node_scanner "https://github.com/shikijs/shiki/blob/main/packages/engine-javascript/src/scanner.ts"
click node_onig "https://github.com/shikijs/shiki/blob/main/packages/engine-oniguruma/src/oniguruma/index.ts"
click node_bundles "https://github.com/shikijs/shiki/blob/main/packages/shiki/src/langs.ts"
click node_cli "https://github.com/shikijs/shiki/blob/main/packages/cli/src/cli.ts"
click node_ansi "https://github.com/shikijs/shiki/blob/main/packages/cli/src/code-to-ansi.ts"
click node_monaco "https://github.com/shikijs/shiki/blob/main/packages/monaco/src/index.ts"
click node_rehype "https://github.com/shikijs/shiki/blob/main/packages/rehype/src/core.ts"
click node_markdownit "https://github.com/shikijs/shiki/blob/main/packages/markdown-it/src/core.ts"
click node_transformers "https://github.com/shikijs/shiki/blob/main/packages/transformers/src/shared/notation-transformer.ts"
click node_brackets "https://github.com/shikijs/shiki/blob/main/packages/colorized-brackets/src/colorizeBracketTokens.ts"
click node_twoslash "https://github.com/shikijs/shiki/blob/main/packages/twoslash/src/renderer-rich.ts"
click node_magicmove "https://github.com/shikijs/shiki/blob/main/packages/magic-move/src/renderer.ts"
click node_stream "https://github.com/shikijs/shiki/blob/main/packages/stream/src/stream.ts"
click node_packages_engine_javascript_string "https://github.com/shikijs/shiki/blob/main/packages/engine-javascript/src/string.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_highlight,node_html,node_tokens toneBlue
class node_textmate,node_primitive,node_jsengine,node_scanner,node_onig,node_bundles,node_packages_engine_javascript_string toneAmber
class node_cli,node_ansi,node_monaco,node_rehype,node_markdownit toneMint
class node_transformers,node_brackets,node_twoslash toneRose
class node_magicmove,node_stream,node_user toneIndigo
```

## Components

### Highlighting runtime

- [Shiki API](https://github.com/shikijs/shiki/blob/main/packages/shiki/src/core.ts): `packages/shiki/src/core.ts`
- [Highlight conversion](https://github.com/shikijs/shiki/blob/main/packages/core/src/highlight/code-to-hast.ts): `packages/core/src/highlight/code-to-hast.ts`
- [HTML output](https://github.com/shikijs/shiki/blob/main/packages/core/src/highlight/code-to-html.ts): `packages/core/src/highlight/code-to-html.ts`
- [Token output](https://github.com/shikijs/shiki/blob/main/packages/core/src/highlight/code-to-tokens.ts): `packages/core/src/highlight/code-to-tokens.ts`

### Grammar and engines

- [TextMate runtime](https://github.com/shikijs/shiki/blob/main/packages/primitive/src/textmate/grammar-state.ts): `packages/primitive/src/textmate/grammar-state.ts`
- [Primitive tokenizer](https://github.com/shikijs/shiki/blob/main/packages/primitive/src/highlight/code-to-tokens-base.ts): `packages/primitive/src/highlight/code-to-tokens-base.ts`
- [JavaScript regex](https://github.com/shikijs/shiki/blob/main/packages/engine-javascript/src/engine-compile.ts): `packages/engine-javascript/src/engine-compile.ts`
- [Regex scanner](https://github.com/shikijs/shiki/blob/main/packages/engine-javascript/src/scanner.ts): `packages/engine-javascript/src/scanner.ts`
- [Oniguruma engine](https://github.com/shikijs/shiki/blob/main/packages/engine-oniguruma/src/oniguruma/index.ts): `packages/engine-oniguruma/src/oniguruma/index.ts`
- [Languages and themes](https://github.com/shikijs/shiki/blob/main/packages/shiki/src/langs.ts): `packages/shiki/src/langs.ts`
- [String adapter](https://github.com/shikijs/shiki/blob/main/packages/engine-javascript/src/string.ts): `packages/engine-javascript/src/string.ts`

### Consumer integrations

- [Terminal CLI](https://github.com/shikijs/shiki/blob/main/packages/cli/src/cli.ts): `packages/cli/src/cli.ts`
- [ANSI conversion](https://github.com/shikijs/shiki/blob/main/packages/cli/src/code-to-ansi.ts): `packages/cli/src/code-to-ansi.ts`
- [Monaco adapter](https://github.com/shikijs/shiki/blob/main/packages/monaco/src/index.ts): `packages/monaco/src/index.ts`
- [Rehype adapter](https://github.com/shikijs/shiki/blob/main/packages/rehype/src/core.ts): `packages/rehype/src/core.ts`
- [Markdown-it adapter](https://github.com/shikijs/shiki/blob/main/packages/markdown-it/src/core.ts): `packages/markdown-it/src/core.ts`

### Highlighting extensions

- [Token transformers](https://github.com/shikijs/shiki/blob/main/packages/transformers/src/shared/notation-transformer.ts): `packages/transformers/src/shared/notation-transformer.ts`
- [Bracket coloring](https://github.com/shikijs/shiki/blob/main/packages/colorized-brackets/src/colorizeBracketTokens.ts): `packages/colorized-brackets/src/colorizeBracketTokens.ts`
- [Rich Twoslash renderer](https://github.com/shikijs/shiki/blob/main/packages/twoslash/src/renderer-rich.ts): `packages/twoslash/src/renderer-rich.ts`

### Framework rendering

- [Magic Move](https://github.com/shikijs/shiki/blob/main/packages/magic-move/src/renderer.ts): `packages/magic-move/src/renderer.ts`
- [Streaming highlighter](https://github.com/shikijs/shiki/blob/main/packages/stream/src/stream.ts): `packages/stream/src/stream.ts`

### Other components

- **Application**

## Connections

- Application → Shiki API: configures and highlights
- Shiki API → Highlight conversion: uses
- Highlight conversion → HTML output: renders HTML
- Highlight conversion → Token output: produces tokens
- Primitive tokenizer → TextMate runtime: uses grammar state (evidence: `packages/primitive/src/highlight/code-to-tokens-base.ts`)
- JavaScript regex → Regex scanner: constructs scanner (evidence: `packages/engine-javascript/src/engine-compile.ts`)
- Regex scanner → String adapter: uses string adapter (evidence: `packages/engine-javascript/src/scanner.ts`)
- Shiki API → JavaScript regex: re-exports engine
- Shiki API → Oniguruma engine: re-exports engine
- Shiki API → Languages and themes: uses bundled assets
- Terminal CLI → ANSI conversion: formats terminal output (evidence: `packages/cli/src/cli.ts`)
- Monaco adapter → Shiki API: integrates highlighter
- Rehype adapter → Highlight conversion: adapts code blocks
- Markdown-it adapter → Highlight conversion: adapts Markdown
- Token transformers → Highlight conversion: transforms output
- Bracket coloring → Token output: colors tokens
- Rich Twoslash renderer → Shiki API: highlights popup code
- Magic Move → Shiki API: animates highlighted code
- Streaming highlighter → Shiki API: streams highlighting
