React Shiki Syntax Highlighter

Common errors

• Error: [shiki] Language 'mylang' does not exist. Did you forget to load it?

  cause The specified language was not loaded by Shiki or has an incorrect identifier.
  fix Ensure the `language` prop matches a supported Shiki language ID. If it's a custom language, load it using `loadLanguage` or provide it via the `languages` prop.

• TS2307: Cannot find module 'react-shiki/web' or its corresponding type declarations.

  cause TypeScript or your bundler cannot locate the specific bundle entry point or its type definitions.
  fix Verify the import path is correct (`react-shiki/web` or `react-shiki/core`). Ensure your `tsconfig.json` or bundler configuration is set up to resolve module paths correctly for sub-path exports. Restarting your IDE might also help.

• Code block is rendered without highlighting/styling, appears as plain text.

  cause The CSS styles provided by `react-shiki` or your custom styles are not being applied, or the component isn't receiving the code/language props correctly.
  fix Ensure you have imported the minimal default styles (if desired) and that your component props (`code`, `language`, `theme`) are correctly passed. Check browser developer tools for CSS conflicts or missing styles. Review the `warnings` section for potential CSS class name changes.

Warnings

• breaking In version 0.9.3, CSS classnames and line-number CSS variables were renamed to use an `rs-` prefix to improve CSS specificity. While legacy aliases are temporarily kept, they will be removed in a future major release, potentially breaking custom styling.
  Fix: Update your custom CSS to use the new `rs-` prefixed classnames and CSS variables (e.g., `rs-line`, `rs-line-number`, `--rs-line-number-color`). Consider utilizing CSS `@layer base` for better specificity management.
• gotcha The default `react-shiki` import uses the 'Full Bundle' which is approximately 1.2MB gzipped, including all Shiki languages and themes. This can lead to a large client-side bundle size and slower initial page loads, especially if only a few languages/themes are needed.
  Fix: For smaller bundles, import from `react-shiki/web` (~695KB gzipped) or `react-shiki/core` (minimal bundle) and explicitly load only the required languages and themes using the `loadLanguage` and `loadTheme` configuration options.
• gotcha Shiki dynamically imports languages and themes on demand. While this optimizes initial bundle size by fetching assets as needed, it requires network access to load these resources during runtime. In offline environments or strict Content Security Policy (CSP) setups, this can prevent highlighting.
  Fix: For offline use or controlled environments, preload languages and themes during application initialization using Shiki's API or configure your bundler to include them. Ensure your CSP allows network requests to the Shiki assets if not self-hosted.
• gotcha The `outputFormat` prop (introduced in v0.8.0) defaults to `jsx`, which renders React elements. While safer against XSS, rendering raw HTML strings via `outputFormat="html"` can offer significantly better performance for very large code blocks, but requires `dangerouslySetInnerHTML` internally.
  Fix: If performance is critical for large code blocks and you trust the input, set the `outputFormat` prop on `ShikiHighlighter` or the `outputFormat` option in `useShikiHighlighter` to `'html'`.

Install

• npm install react-shiki npm
• yarn add react-shiki yarn
• pnpm add react-shiki pnpm

Imports

• ShikiHighlighter
  wrong:

  const ShikiHighlighter = require('react-shiki');

  correct:

  import ShikiHighlighter from 'react-shiki';

  Primary component for direct rendering. Consider specific bundle imports like 'react-shiki/web' or 'react-shiki/core' for size optimization.
• useShikiHighlighter
  wrong:

  import useShikiHighlighter from 'react-shiki';

  correct:

  import { useShikiHighlighter } from 'react-shiki';

  A named hook for programmatic highlighting. Ensure named import syntax.
• Web Bundle Component
  wrong:

  import ShikiHighlighter from 'react-shiki';

  correct:

  import ShikiHighlighter from 'react-shiki/web';

  Use this specific import for the 'web' optimized bundle, which excludes Node.js-specific modules and reduces overall size compared to the default full bundle.
• ShikiHighlighterProps

  import type { ShikiHighlighterProps } from 'react-shiki';

  Import types for component props to leverage TypeScript's type checking capabilities.

Quickstart

This example demonstrates how to use the `ShikiHighlighter` component to display and dynamically update syntax-highlighted TypeScript code with a specified theme.

import ShikiHighlighter from "react-shiki";
import { useState } from 'react';

function CodeExample() {
  const [code, setCode] = useState(`function greet(name: string): string {
  return \`Hello, ${name}!\`;
}

const message = greet("World");
console.log(message);
`);

  return (
    <div>
      <label htmlFor="code-input">Edit code:</label>
      <textarea
        id="code-input"
        value={code}
        onChange={(e) => setCode(e.target.value)}
        rows={10}
        cols={50}
        style={{ width: '100%', minHeight: '150px' }}
      />
      <h2>Highlighted Code:</h2>
      <ShikiHighlighter
        language="typescript"
        theme="ayu-dark"
        showLanguage={true}
        wrap={true}
      >
        {code.trim()}
      </ShikiHighlighter>
    </div>
  );
}