react-shiki 0.6.0 → 0.7.1

package/README.md

@@ -14,33 +14,38 @@ A performant client-side syntax highlighting component and hook for React, built
   - [Features](#features)
   - [Installation](#installation)
   - [Usage](#usage)
+  - [Bundle Options](#bundle-options)
+  - [Configuration](#configuration)
     - [Common Configuration Options](#common-configuration-options)
     - [Component-specific Props](#component-specific-props)
-    - [Integration with react-markdown](#integration-with-react-markdown)
-    - [Handling Inline Code](#handling-inline-code)
     - [Multi-theme Support](#multi-theme-support)
     - [Custom Themes](#custom-themes)
     - [Custom Languages](#custom-languages)
       - [Preloading Custom Languages](#preloading-custom-languages)
     - [Custom Transformers](#custom-transformers)
-  - [Performance](#performance) 
-  - [Throttling Real-time Highlighting](#throttling-real-time-highlighting)
-  - [Streaming and LLM Chat UI](#streaming-and-llm-chat-ui)
+    - [Line Numbers](#line-numbers)
+  - [Integration](#integration)
+    - [Integration with react-markdown](#integration-with-react-markdown)
+    - [Handling Inline Code](#handling-inline-code)
+  - [Performance](#performance)
+    - [Throttling Real-time Highlighting](#throttling-real-time-highlighting)
+    - [Streaming and LLM Chat UI](#streaming-and-llm-chat-ui)
   <!--toc:end-->
 
 ## Features
 
 - 🖼️ Provides both a `ShikiHighlighter` component and a `useShikiHighlighter` hook for more flexibility
-- 🔐 No `dangerouslySetInnerHTML` - output from Shiki is parsed using `html-react-parser`
-- 📦 Supports all built-in Shiki languages and themes
+- 🔐 Shiki output is processed from HAST directly into React elements, no `dangerouslySetInnerHTML` required
+- 📦 Multiple bundle options: Full bundle (~1.2MB gz), web bundle (~695KB gz), or minimal core bundle for fine-grained bundle control
 - 🖌️ Full support for custom TextMate themes and languages
-- 🔧 Supports passing custom Shiki transformers to the highlighter
+- 🔧 Supports passing custom Shiki transformers to the highlighter, in addition to all other options supported by `codeToHast`
 - 🚰 Performant highlighting of streamed code, with optional throttling
 - 📚 Includes minimal default styles for code blocks
 - 🚀 Shiki dynamically imports only the languages and themes used on a page for optimal performance
 - 🖥️ `ShikiHighlighter` component displays a language label for each code block
   when `showLanguage` is set to `true` (default)
 - 🎨 Customizable styling of generated code blocks and language labels
+- 📏 Optional line numbers with customizable starting number and styling
 
 ## Installation
 
@@ -55,7 +60,7 @@ You can use either the `ShikiHighlighter` component or the `useShikiHighlighter`
 **Using the Component:**
 
 ```tsx
-import { ShikiHighlighter } from "react-shiki";
+import ShikiHighlighter from "react-shiki";
 
 function CodeBlock() {
   return (
@@ -78,18 +83,89 @@ function CodeBlock({ code, language }) {
 }
 ```
 
+## Bundle Options
+`react-shiki`, like `shiki`, offers three entry points to balance convenience and bundle optimization:
+
+### `react-shiki` (Full Bundle)
+```tsx
+import ShikiHighlighter from 'react-shiki';
+```
+- **Size**: ~6.4MB minified, 1.2MB gzipped
+- **Languages**: All Shiki languages and themes
+- **Use case**: Unknown language requirements, maximum language support
+- **Setup**: Zero configuration required
+
+### `react-shiki/web` (Web Bundle)  
+```tsx
+import ShikiHighlighter from 'react-shiki/web';
+```
+- **Size**: ~3.8MB minified, 695KB gzipped
+- **Languages**: Web-focused languages (HTML, CSS, JS, TS, JSON, Markdown, Vue, JSX, Svelte)
+- **Use case**: Web applications with balanced size/functionality
+- **Setup**: Drop-in replacement for main entry point
+
+### `react-shiki/core` (Minimal Bundle)
+```tsx
+import ShikiHighlighter, { 
+  createHighlighterCore,        // re-exported from shiki/core
+  createOnigurumaEngine,        // re-exported from shiki/engine/oniguruma
+  createJavaScriptRegexEngine,  // re-exported from shiki/engine/javascript
+} from 'react-shiki/core';
+
+// Create custom highlighter with dynamic imports to optimize client-side bundle size
+const highlighter = await createHighlighterCore({
+  themes: [import('@shikijs/themes/nord')],
+  langs: [import('@shikijs/langs/typescript')],
+  engine: createOnigurumaEngine(import('shiki/wasm')) 
+    // or createJavaScriptRegexEngine()
+});
+
+<ShikiHighlighter highlighter={highlighter} language="typescript" theme="nord">
+  {code}
+</ShikiHighlighter>
+```
+- **Size**: Minimal (only what you import)
+- **Languages**: User-defined via custom highlighter  
+- **Use case**: Production apps requiring maximum bundle control
+- **Setup**: Requires custom highlighter configuration
+- **Engine options**: Choose JavaScript engine (smaller bundle, faster startup) or Oniguruma (WASM, maximum language support)
+
+### RegExp Engines
+
+Shiki offers two built-in engines:
+- **Oniguruma** - default, uses the compiled Oniguruma WebAssembly, and offer maximum language support
+- **JavaScript** - smaller bundle, faster startup, recommended when running highlighting on the client
+
+Unlike the Oniguruma engine, the JavaScript engine is [strict by default](https://shiki.style/guide/regex-engines#use-with-unsupported-languages). It will throw an error if it encounters an invalid Oniguruma pattern or a pattern that it cannot convert. If you want best-effort results for unsupported grammars, you can enable the forgiving option to suppress any conversion errors:
+
+```tsx
+createJavaScriptRegexEngine({ forgiving: true });
+```
+
+See [Shiki - RegExp Engines](https://shiki.style/guide/regex-engines) for more info.
+
+
+## Configuration
+
 ### Common Configuration Options
 
-| Option              | Type               | Default         | Description                                                               |
-| ------------------- | ------------------ | --------------- | ------------------------------------------------------------------------- |
-| `code`            | `string`           | -               | Code to highlight                                                          |
-| `language`          | `string \| object` | -               | Language to highlight, built-in or custom textmate grammer object                                                         |
+
+| Option              | Type               | Default         | Description                                                                   |
+| ------------------- | ------------------ | --------------- | ----------------------------------------------------------------------------- |
+| `code`            | `string`           | -               | Code to highlight                                                               |
+| `language`          | `string \| object` | -               | Language to highlight, built-in or custom textmate grammer object             |
 | `theme`             | `string \| object` | `'github-dark'` | Single or multi-theme configuration, built-in or custom textmate theme object |
 | `delay`             | `number`           | `0`             | Delay between highlights (in milliseconds)                                    |
-| `transformers`      | `array`            | `[]`            | Custom Shiki transformers for modifying the highlighting output               |
 | `customLanguages`   | `array`            | `[]`            | Array of custom languages to preload                                          |
+| `showLineNumbers`   | `boolean`          | `false`         | Display line numbers alongside code                                           |
+| `startingLineNumber` | `number`           | `1`             | Starting line number when line numbers are enabled                           |
+| `transformers`      | `array`            | `[]`            | Custom Shiki transformers for modifying the highlighting output               |
 | `cssVariablePrefix` | `string`           | `'--shiki'`     | Prefix for CSS variables storing theme colors                                 |
 | `defaultColor`      | `string \| false`  | `'light'`       | Default theme mode when using multiple themes, can also disable default theme |
+| `tabindex`          | `number`           | `0`             | Tab index for the code block                                                  |
+| `decorations`       | `array`            | `[]`            | Custom decorations to wrap the highlighted tokens with                        |
+| `structure`        | `string`           | `classic`  | The structure of the generated HAST and HTML - `classic` or `inline`               |
+| [`codeToHastOptions`](https://github.com/shikijs/shiki/blob/main/packages/types/src/options.ts#L121) | -             | -              | All other options supported by Shiki's `codeToHast`      |
 
 ### Component-specific Props
 
@@ -105,13 +181,188 @@ The `ShikiHighlighter` component offers minimal built-in styling and customizati
 | `style`            | `object`  | -       | Inline style object for the code block                     |
 | `langStyle`        | `object`  | -       | Inline style object for the language label                 |
 
+### Multi-theme Support
+
+To use multiple theme modes, pass an object with your multi-theme configuration to the `theme` prop in the `ShikiHighlighter` component:
+
+```tsx
+<ShikiHighlighter
+  language="tsx"
+  theme={{
+    light: "github-light",
+    dark: "github-dark",
+    dim: "github-dark-dimmed",
+  }}
+  defaultColor="dark"
+>
+  {code.trim()}
+</ShikiHighlighter>
+```
+
+Or, when using the hook, pass it to the `theme` parameter:
+
+```tsx
+const highlightedCode = useShikiHighlighter(
+  code,
+  "tsx",
+  {
+    light: "github-light",
+    dark: "github-dark",
+    dim: "github-dark-dimmed",
+  },
+  {
+    defaultColor: "dark",
+  }
+);
+```
+
+See [shiki's documentation](https://shiki.matsu.io/docs/themes) for more information on dual and multi theme support, and for the CSS needed to make the themes reactive to your site's theme.
+
+### Custom Themes
+
+Custom themes can be passed as a TextMate theme in JavaScript object. For example, [it should look like this](https://github.com/antfu/textmate-grammars-themes/blob/main/packages/tm-themes/themes/dark-plus.json).
+
+```tsx
+import tokyoNight from "../styles/tokyo-night.json";
+
+// Component
+<ShikiHighlighter language="tsx" theme={tokyoNight}>
+  {code.trim()}
+</ShikiHighlighter>
+
+// Hook
+const highlightedCode = useShikiHighlighter(code, "tsx", tokyoNight);
+```
+
+### Custom Languages
+
+Custom languages should be passed as a TextMate grammar in JavaScript object. For example, [it should look like this](https://github.com/shikijs/textmate-grammars-themes/blob/main/packages/tm-grammars/grammars/typescript.json)
+
+```tsx
+import mcfunction from "../langs/mcfunction.tmLanguage.json";
+
+// Component
+<ShikiHighlighter language={mcfunction} theme="github-dark">
+  {code.trim()}
+</ShikiHighlighter>
+
+// Hook
+const highlightedCode = useShikiHighlighter(code, mcfunction, "github-dark");
+```
+
+#### Preloading Custom Languages
+
+For dynamic highlighting scenarios where language selection happens at runtime:
+
+```tsx
+import mcfunction from "../langs/mcfunction.tmLanguage.json";
+import bosque from "../langs/bosque.tmLanguage.json";
+
+// Component
+<ShikiHighlighter
+  language="typescript"
+  theme="github-dark"
+  customLanguages={[mcfunction, bosque]}
+>
+  {code.trim()}
+</ShikiHighlighter>
+
+// Hook
+const highlightedCode = useShikiHighlighter(code, "typescript", "github-dark", {
+  customLanguages: [mcfunction, bosque],
+});
+```
+
+### Custom Transformers
+
+```tsx
+import { customTransformer } from "../utils/shikiTransformers";
+
+// Component
+<ShikiHighlighter language="tsx" transformers={[customTransformer]}>
+  {code.trim()}
+</ShikiHighlighter>
+
+// Hook
+const highlightedCode = useShikiHighlighter(code, "tsx", "github-dark", {
+  transformers: [customTransformer],
+});
+```
+
+### Line Numbers
+
+Display line numbers alongside your code, these are CSS-based
+and can be customized with CSS variables:
+
+```tsx
+// Component
+<ShikiHighlighter 
+  language="javascript"
+  theme="github-dark"
+  showLineNumbers,
+  startingLineNumber={0} // default is 1
+>
+  {code}
+</ShikiHighlighter>
+
+<ShikiHighlighter 
+  language="python" 
+  theme="github-dark" 
+  showLineNumbers 
+  startingLineNumber={0}
+>
+  {code}
+</ShikiHighlighter>
+
+// Hook (import 'react-shiki/css' for line numbers to work)
+const highlightedCode = useShikiHighlighter(code, "javascript", "github-dark", {
+  showLineNumbers: true,
+  startingLineNumber: 0, 
+});
+```
+
+> [!NOTE]
+> When using the hook with line numbers, import the CSS file for the line numbers to work:
+> ```tsx
+> import 'react-shiki/css';
+> ```
+> Or provide your own CSS counter implementation and styles for `.line-numbers` (line `span`) and `.has-line-numbers` (container `code` element)
+
+Available CSS variables for customization:
+```css
+--line-numbers-foreground: rgba(107, 114, 128, 0.5);
+--line-numbers-width: 2ch;
+--line-numbers-padding-left: 0ch;
+--line-numbers-padding-right: 2ch;
+--line-numbers-font-size: inherit;
+--line-numbers-font-weight: inherit;
+--line-numbers-opacity: 1;
+```
+
+You can customize them in your own CSS or by using the style prop on the component:
+```tsx
+<ShikiHighlighter 
+  language="javascript"
+  theme="github-dark"
+  showLineNumbers
+  style={{
+    '--line-numbers-foreground': '#60a5fa',
+    '--line-numbers-width': '3ch'
+  }}
+>
+  {code}
+</ShikiHighlighter>
+```
+
+## Integration
+
 ### Integration with react-markdown
 
 Create a component to handle syntax highlighting:
 
 ```tsx
 import ReactMarkdown from "react-markdown";
-import { ShikiHighlighter, isInlineCode } from "react-shiki";
+import ShikiHighlighter, { isInlineCode } from "react-shiki";
 
 const CodeHighlight = ({ className, children, node, ...props }) => {
   const code = String(children).trim();
@@ -155,7 +406,7 @@ ways to replicate this functionality and API.
 `react-shiki` exports `isInlineCode` which parses the `node` prop from `react-markdown` and identifies inline code by checking for the absence of newline characters:
 
 ```tsx
-import { isInlineCode, ShikiHighlighter } from "react-shiki";
+import ShikiHighlighter, { isInlineCode } from "react-shiki";
 
 const CodeHighlight = ({ className, children, node, ...props }) => {
   const match = className?.match(/language-(\w+)/);
@@ -224,114 +475,6 @@ const CodeHighlight = ({
 };
 ```
 
-### Multi-theme Support
-
-To use multiple theme modes, pass an object with your multi-theme configuration to the `theme` prop in the `ShikiHighlighter` component:
-
-```tsx
-<ShikiHighlighter
-  language="tsx"
-  theme={{
-    light: "github-light",
-    dark: "github-dark",
-    dim: "github-dark-dimmed",
-  }}
-  defaultColor="dark"
->
-  {code.trim()}
-</ShikiHighlighter>
-```
-
-Or, when using the hook, pass it to the `theme` parameter:
-
-```tsx
-const highlightedCode = useShikiHighlighter(
-  code,
-  "tsx",
-  {
-    light: "github-light",
-    dark: "github-dark",
-    dim: "github-dark-dimmed",
-  },
-  {
-    defaultColor: "dark",
-  }
-);
-```
-
-See [shiki's documentation](https://shiki.matsu.io/docs/themes) for more information on dual and multi theme support, and for the CSS needed to make the themes reactive to your site's theme.
-
-### Custom Themes
-
-Custom themes can be passed as a TextMate theme in JavaScript object. For example, [it should look like this](https://github.com/antfu/textmate-grammars-themes/blob/main/packages/tm-themes/themes/dark-plus.json).
-
-```tsx
-import tokyoNight from "../styles/tokyo-night.json";
-
-// Using the component
-<ShikiHighlighter language="tsx" theme={tokyoNight}>
-  {code.trim()}
-</ShikiHighlighter>
-
-// Using the hook
-const highlightedCode = useShikiHighlighter(code, "tsx", tokyoNight);
-```
-
-### Custom Languages
-
-Custom languages should be passed as a TextMate grammar in JavaScript object. For example, [it should look like this](https://github.com/shikijs/textmate-grammars-themes/blob/main/packages/tm-grammars/grammars/typescript.json)
-
-```tsx
-import mcfunction from "../langs/mcfunction.tmLanguage.json";
-
-// Using the component
-<ShikiHighlighter language={mcfunction} theme="github-dark">
-  {code.trim()}
-</ShikiHighlighter>
-
-// Using the hook
-const highlightedCode = useShikiHighlighter(code, mcfunction, "github-dark");
-```
-
-#### Preloading Custom Languages
-
-For dynamic highlighting scenarios where language selection happens at runtime:
-
-```tsx
-import mcfunction from "../langs/mcfunction.tmLanguage.json";
-import bosque from "../langs/bosque.tmLanguage.json";
-
-// With the component
-<ShikiHighlighter
-  language="typescript"
-  theme="github-dark"
-  customLanguages={[mcfunction, bosque]}
->
-  {code.trim()}
-</ShikiHighlighter>
-
-// With the hook
-const highlightedCode = useShikiHighlighter(code, "typescript", "github-dark", {
-  customLanguages: [mcfunction, bosque],
-});
-```
-
-### Custom Transformers
-
-```tsx
-import { customTransformer } from "../utils/shikiTransformers";
-
-// Using the component
-<ShikiHighlighter language="tsx" transformers={[customTransformer]}>
-  {code.trim()}
-</ShikiHighlighter>
-
-// Using the hook
-const highlightedCode = useShikiHighlighter(code, "tsx", "github-dark", {
-  transformers: [customTransformer],
-});
-```
-
 ## Performance
 
 ### Throttling Real-time Highlighting
@@ -447,7 +590,7 @@ export const CodeHighlight = ({
 };
 ```
 
-Passed to `react-markdown` as a `code` component in memo-ized chat messages:
+Passed to `react-markdown` as a `code` component in memoized chat messages:
 
 ```tsx
 const RenderedMessage = React.memo(({ message }: { message: Message }) => (