feat: Add support for custom regex engines with engine param (#100)

This PR adds support for custom regex engines in the highlighter factory functions. It:

- Adds an optional `engine` parameter to `createFullHighlighter` and `createWebHighlighter` functions
- Defaults to using the Oniguruma engine when no custom engine is provided
- Re-exports JavaScript regex engines from Shiki in the main bundles for convenience
- Adds the `engine` option to the `HighlighterOptions` type

These changes allow users to customize the regex engine used for syntax highlighting, providing more flexibility in different environments.

Author: AVGVSTVS96

.changeset/breezy-jeans-type.md

@@ -0,0 +1,5 @@
+---
+"react-shiki": minor
+---
+
+feat: support custom regex engine selection for full (main) and web bundles

package/README.md

@@ -97,15 +97,17 @@ import ShikiHighlighter from 'react-shiki';
 ```
 - **Size**: ~6.4MB minified, ~1.2MB gzipped (includes ~12KB react-shiki)
 - **Languages**: All Shiki languages and themes
+- **Exported engines**: `createJavaScriptRegexEngine`, `createJavaScriptRawEngine`
 - **Use case**: Unknown language requirements, maximum language support
 - **Setup**: Zero configuration required
 
-### `react-shiki/web` (Web Bundle)  
+### `react-shiki/web` (Web Bundle)
 ```tsx
 import ShikiHighlighter from 'react-shiki/web';
 ```
 - **Size**: ~3.8MB minified, ~707KB gzipped (includes ~12KB react-shiki)
 - **Languages**: Web-focused languages (HTML, CSS, JS, TS, JSON, Markdown, Vue, JSX, Svelte)
+- **Exported engines**: `createJavaScriptRegexEngine`, `createJavaScriptRawEngine`
 - **Use case**: Web applications with balanced size/functionality
 - **Setup**: Drop-in replacement for main entry point
 
@@ -137,11 +139,59 @@ const highlighter = await createHighlighterCore({
 
 ### 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
+Shiki offers three built-in engines for syntax highlighting:
+- **Oniguruma** - Default engine using compiled WebAssembly, offers maximum language support
+- **JavaScript RegExp** - Smaller bundle, faster startup, compiles patterns on-the-fly, recommended for client-side highlighting
+- **JavaScript Raw** - For [pre-compiled languages](https://shiki.style/guide/regex-engines#pre-compiled-languages), skips transpilation step for best performance
 
-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:
+#### Using Engines with Full and Web Bundles
+
+The full and web bundles use Oniguruma by default, but you can override this with the `engine` option:
+
+```tsx
+import {
+  useShikiHighlighter,
+  createJavaScriptRegexEngine,
+  createJavaScriptRawEngine
+} from 'react-shiki';
+
+// Hook with JavaScript RegExp engine
+const highlightedCode = useShikiHighlighter(code, 'typescript', 'github-dark', {
+  engine: createJavaScriptRegexEngine()
+});
+
+// Component with JavaScript Raw engine (for pre-compiled languages)
+// See https://shiki.style/guide/regex-engines#pre-compiled-languages
+<ShikiHighlighter
+  language="typescript"
+  theme="github-dark"
+  engine={createJavaScriptRawEngine()}
+>
+  {code}
+</ShikiHighlighter>
+```
+
+#### Using Engines with Core Bundle
+
+When using the core bundle, you must specify an engine:
+
+```tsx
+import {
+  createHighlighterCore,
+  createOnigurumaEngine,
+  createJavaScriptRegexEngine
+} from 'react-shiki/core';
+
+const highlighter = await createHighlighterCore({
+  themes: [import('@shikijs/themes/nord')],
+  langs: [import('@shikijs/langs/typescript')],
+  engine: createJavaScriptRegexEngine() // or createOnigurumaEngine(import('shiki/wasm'))
+});
+```
+
+#### Engine Options
+
+The JavaScript RegExp engine is [strict by default](https://shiki.style/guide/regex-engines#use-with-unsupported-languages). For best-effort results with unsupported grammars, enable the `forgiving` option:
 
 ```tsx
 createJavaScriptRegexEngine({ forgiving: true });
@@ -163,6 +213,7 @@ See [Shiki - RegExp Engines](https://shiki.style/guide/regex-engines) for more i
 | `delay`             | `number`           | `0`             | Delay between highlights (in milliseconds)                                    |
 | `customLanguages`   | `array`            | `[]`            | Array of custom languages to preload                                          |
 | `langAlias`         | `object`           | `{}`            | Map of language aliases                                                       |
+| `engine`            | `RegexEngine`      | Oniguruma       | RegExp engine for syntax highlighting (Oniguruma, JavaScript RegExp, or JavaScript Raw) |
 | `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               |

package/package.json

@@ -26,13 +26,8 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "src/lib/styles.css"
-  ],
-  "sideEffects": [
-    "src/lib/styles.css"
-  ],
+  "files": ["dist", "src/lib/styles.css"],
+  "sideEffects": ["src/lib/styles.css"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",

package/src/bundles/full.ts

@@ -1,4 +1,10 @@
-import { getSingletonHighlighter, type Highlighter } from 'shiki';
+import {
+  getSingletonHighlighter,
+  type Highlighter,
+  type Awaitable,
+  type RegexEngine,
+} from 'shiki';
+import { createOnigurumaEngine } from 'shiki/engine/oniguruma';
 import type { ShikiLanguageRegistration } from '../lib/extended-types';
 import type { Theme } from '../lib/types';
 
@@ -8,18 +14,21 @@ import type { Theme } from '../lib/types';
  */
 export async function createFullHighlighter(
   langsToLoad: ShikiLanguageRegistration,
-  themesToLoad: Theme[]
+  themesToLoad: Theme[],
+  engine?: Awaitable<RegexEngine>
 ): Promise<Highlighter> {
   try {
     return await getSingletonHighlighter({
       langs: [langsToLoad],
       themes: themesToLoad,
+      engine: engine ?? createOnigurumaEngine(import('shiki/wasm')),
     });
   } catch (error) {
     if (error instanceof Error && error.message.includes('Language')) {
       return await getSingletonHighlighter({
         langs: ['plaintext'],
         themes: themesToLoad,
+        engine: engine ?? createOnigurumaEngine(import('shiki/wasm')),
       });
     }
     throw error;

package/src/bundles/web.ts

@@ -1,7 +1,10 @@
 import {
   getSingletonHighlighter,
   type Highlighter,
+  type Awaitable,
+  type RegexEngine,
 } from 'shiki/bundle/web';
+import { createOnigurumaEngine } from 'shiki/engine/oniguruma';
 import type { ShikiLanguageRegistration } from '../lib/extended-types';
 import type { Theme } from '../lib/types';
 
@@ -12,18 +15,21 @@ import type { Theme } from '../lib/types';
  */
 export async function createWebHighlighter(
   langsToLoad: ShikiLanguageRegistration,
-  themesToLoad: Theme[]
+  themesToLoad: Theme[],
+  engine?: Awaitable<RegexEngine>
 ): Promise<Highlighter> {
   try {
     return await getSingletonHighlighter({
       langs: [langsToLoad],
       themes: themesToLoad,
+      engine: engine ?? createOnigurumaEngine(import('shiki/wasm')),
     });
   } catch (error) {
     if (error instanceof Error && error.message.includes('Language')) {
       return await getSingletonHighlighter({
         langs: ['plaintext'],
         themes: themesToLoad,
+        engine: engine ?? createOnigurumaEngine(import('shiki/wasm')),
       });
     }
     throw error;

package/src/core.ts

@@ -22,28 +22,43 @@ export type {
 
 export { createHighlighterCore } from 'shiki/core';
 export { createOnigurumaEngine } from 'shiki/engine/oniguruma';
-export { createJavaScriptRegexEngine } from 'shiki/engine/javascript';
+export {
+  createJavaScriptRegexEngine,
+  createJavaScriptRawEngine,
+} from 'shiki/engine/javascript';
 
 /**
- * A React hook that provides syntax highlighting using Shiki with a custom highlighter.
- * Requires a highlighter to be provided in options for minimal bundle size.
+ * Highlight code with shiki (core bundle)
+ *
+ * @param code - Code to highlight
+ * @param lang - Language (bundled or custom)
+ * @param theme - Theme (bundled, multi-theme, or custom)
+ * @param options - react-shiki options + shiki options
+ * @returns Highlighted code as React elements or HTML string
  *
  * @example
- * ```ts
+ * ```tsx
  * import { createHighlighterCore, createOnigurumaEngine } from 'react-shiki/core';
  *
+ *
  * const highlighter = await createHighlighterCore({
- *   themes: [import('@shikijs/themes/nord')],
+ *   themes: [import('@shikijs/themes/github-light'), import('@shikijs/themes/github-dark')],
  *   langs: [import('@shikijs/langs/typescript')],
  *   engine: createOnigurumaEngine(import('shiki/wasm'))
  * });
  *
- * const code = useShikiHighlighter(code, 'typescript', 'nord', { highlighter });
+ * const highlighted = useShikiHighlighter(
+ *   'const x = 1;',
+ *   'typescript',
+ *   {
+ *     light: 'github-light',
+ *     dark: 'github-dark'
+ *   },
+ *   { highlighter }
+ * );
  * ```
  *
- * For plug-and-play usage, consider:
- * - `react-shiki` for full shiki bundle (~6.4MB minified, 1.2MB gzipped)
- * - `react-shiki/web` for smaller shiki web bundle (~3.8MB minified, 695KB gzipped)
+ * Core bundle (minimal). For plug-and-play: `react-shiki` or `react-shiki/web`
  */
 export const useShikiHighlighter: UseShikiHighlighter = (
   code,

package/src/index.ts

@@ -20,15 +20,33 @@ export type {
   HighlighterOptions,
 } from './lib/types';
 
+export {
+  createJavaScriptRegexEngine,
+  createJavaScriptRawEngine,
+} from 'shiki/engine/javascript';
+
 /**
- * A React hook that provides syntax highlighting using Shiki with the full bundle.
- * Includes all languages and themes for maximum compatibility.
+ * Highlight code with shiki (full bundle)
+ *
+ * @param code - Code to highlight
+ * @param lang - Language (bundled or custom)
+ * @param theme - Theme (bundled, multi-theme, or custom)
+ * @param options - react-shiki options + shiki options
+ * @returns Highlighted code as React elements or HTML string
  *
- * Bundle size: ~6.4MB minified (1.2MB gzipped)
+ * @example
+ * ```tsx
+ * const highlighted = useShikiHighlighter(
+ *   'const x = 1;',
+ *   'typescript',
+ *   {
+ *     light: 'github-light',
+ *     dark: 'github-dark'
+ *   }
+ * );
+ * ```
  *
- * For smaller bundles, consider:
- * - `react-shiki/web` for smaller shiki web bundle (~3.8MB minified, 695KB gzipped)
- * - `react-shiki/core` for custom fine-grained bundle
+ * Full bundle (~6.4MB minified, 1.2MB gzipped). For smaller bundles: `react-shiki/web` or `react-shiki/core`
  */
 export const useShikiHighlighter: UseShikiHighlighter = (
   code,

package/src/lib/hook.ts

@@ -15,6 +15,9 @@ import type {
   CodeOptionsMultipleThemes,
   Highlighter,
   HighlighterCore,
+  Awaitable,
+  RegexEngine,
+  BundledTheme,
 } from 'shiki';
 
 import type { ShikiLanguageRegistration } from './extended-types';
@@ -53,7 +56,8 @@ export const useShikiHighlighter = (
   options: HighlighterOptions = {},
   highlighterFactory: (
     langsToLoad: ShikiLanguageRegistration,
-    themesToLoad: Theme[]
+    themesToLoad: Theme[],
+    engine?: Awaitable<RegexEngine>
   ) => Promise<Highlighter | HighlighterCore>
 ) => {
   const [highlightedCode, setHighlightedCode] = useState<
@@ -99,10 +103,10 @@ export const useShikiHighlighter = (
           themes: multiTheme || DEFAULT_THEMES,
           defaultColor,
           cssVariablePrefix,
-        } as CodeOptionsMultipleThemes)
+        } as CodeOptionsMultipleThemes<BundledTheme>)
       : ({
           theme: singleTheme || DEFAULT_THEMES.dark,
-        } as CodeOptionsSingleTheme);
+        } as CodeOptionsSingleTheme<BundledTheme>);
 
     const transformers = restOptions.transformers || [];
     if (showLineNumbers) {
@@ -127,7 +131,8 @@ export const useShikiHighlighter = (
         ? stableOpts.highlighter
         : await highlighterFactory(
             langsToLoad as ShikiLanguageRegistration,
-            themesToLoad
+            themesToLoad,
+            stableOpts.engine
           );
 
       const loadedLanguages = highlighter.getLoadedLanguages();

package/src/lib/types.ts

@@ -9,6 +9,8 @@ import type {
   Highlighter,
   HighlighterCore,
   BundledHighlighterOptions,
+  Awaitable,
+  RegexEngine,
 } from 'shiki';
 
 import type { ReactNode } from 'react';
@@ -133,7 +135,10 @@ interface HighlighterOptions
       'defaultColor' | 'cssVariablePrefix'
     >,
     Omit<CodeToHastOptions, 'lang' | 'theme' | 'themes'>,
-    Pick<BundledHighlighterOptions<string, string>, 'langAlias'> {}
+    Pick<
+      BundledHighlighterOptions<string, string>,
+      'langAlias' | 'engine'
+    > {}
 
 /**
  * State for the throttling logic
@@ -151,7 +156,6 @@ interface TimeoutState {
 
 /**
  * Public API signature for the useShikiHighlighter hook.
- * This ensures all entry points have consistent signatures.
  */
 export type UseShikiHighlighter = (
   code: string,

package/src/web.ts

@@ -20,15 +20,33 @@ export type {
   HighlighterOptions,
 } from './lib/types';
 
+export {
+  createJavaScriptRegexEngine,
+  createJavaScriptRawEngine,
+} from 'shiki/engine/javascript';
+
 /**
- * A React hook that provides syntax highlighting using Shiki with the web bundle.
- * Includes web-focused languages (HTML, CSS, JS, TS, JSON, Markdown, Astro, JSX, Svelte, Vue etc.)
+ * Highlight code with shiki (web bundle)
+ *
+ * @param code - Code to highlight
+ * @param lang - Language (bundled or custom)
+ * @param theme - Theme (bundled, multi-theme, or custom)
+ * @param options - react-shiki options + shiki options
+ * @returns Highlighted code as React elements or HTML string
  *
- * Bundle size: ~3.8MB minified (695KB gzipped)
+ * @example
+ * ```tsx
+ * const highlighted = useShikiHighlighter(
+ *   'const x = 1;',
+ *   'typescript',
+ *   {
+ *     light: 'github-light',
+ *     dark: 'github-dark'
+ *   }
+ * );
+ * ```
  *
- * For other options, consider:
- * - `react-shiki` for full shiki bundle (~6.4MB minified, 1.2MB gzipped)
- * - `react-shiki/core` for custom fine-grained bundle
+ * Web bundle (~3.8MB minified, 695KB gzipped). For other bundles: `react-shiki` or `react-shiki/core`
  */
 export const useShikiHighlighter: UseShikiHighlighter = (
   code,