@tailmark/shiki

Lazy Shiki highlighting for @tailmark/react, with dual-theme CSS variables and an instance-local MRU cache.

bun add @tailmark/shiki @tailmark/react shiki

Setup

Create the highlighter at module scope so its engine and cache survive component remounts:

import { createShikiHighlighter } from "@tailmark/shiki";
import { StreamingMarkdown } from "@tailmark/react";

const highlighter = createShikiHighlighter({
  langs: [
    () => import("shiki/langs/typescript.mjs"),
    () => import("shiki/langs/json.mjs"),
  ],
  themes: {
    light: () => import("shiki/themes/github-light.mjs"),
    dark: () => import("shiki/themes/github-dark.mjs"),
  },
  maxHighlightChars: 100_000,
  cacheBudgetChars: 20_000_000,
});

export function Message({ text, pending }: { text: string; pending: boolean }) {
  return (
    <StreamingMarkdown isStreaming={pending} highlighter={highlighter}>
      {text}
    </StreamingMarkdown>
  );
}

langs accepts explicit Shiki language importers. themes.light and themes.dark are both required. maxHighlightChars defaults to 100,000 and cacheBudgetChars defaults to 20,000,000 weighted characters.

Preset and bundle discipline

commonLangs is a curated array of 30 lazy importers:

import { commonLangs, createShikiHighlighter } from "@tailmark/shiki";

const highlighter = createShikiHighlighter({
  langs: commonLangs,
  themes: {
    light: () => import("shiki/themes/github-light.mjs"),
    dark: () => import("shiki/themes/github-dark.mjs"),
  },
});

The JavaScript regex engine, themes, and requested grammars load only after the first highlight demand. Each importer remains a separate chunk, so using a short explicit list gives the strictest bundle control. Unsupported languages and oversized snippets stay as plain code.

Cache behavior

The cache key is language plus source. Reads refresh MRU order, writes happen only through the React package's settled or settle-gated policy, and oldest entries are evicted until the configured weighted budget is met. A single entry larger than the budget is not cached.

Both themes must load before highlighting becomes available. If either theme fails, the instance fails closed and keeps rendering plain code rather than producing one-theme output with incorrect switching behavior.