API docs - @fuzdev/fuz

fuz_code

syntax styler for TypeScript, Svelte, Markdown, and more 🎨

code.fuz.dev

npm i -D @fuzdev/fuz_code

usage #

fuz_code tokenizes code with one lexer per language, without regular expressions, and generates HTML with .token_* classes for a theme to style. The Code Svelte component is the typical entry point.

To use it, import the default theme or your own:

// +layout.svelte
import '@fuzdev/fuz_code/theme.css'; // add this

then use Code:

<script>
	// Something.svelte
	import Code from '@fuzdev/fuz_code/Code.svelte';
</script>

<Code content="<header>hello world</header>" />

outputs:

<header>hello world</header>

Dependencies
#

The default theme reads color-scheme-aware color variables from fuz_css; see its usage docs for setup. Without fuz_css, import theme_variables.css or define the variables yourself:

// +layout.svelte
import '@fuzdev/fuz_code/theme.css';
// if not using fuz_css, add this too:
import '@fuzdev/fuz_code/theme_variables.css';

Preprocessor
#

The svelte_preprocess_fuz_code preprocessor styles static Code content at build time:

// vite.config.ts
import {defineConfig} from 'vite';
import {sveltekit} from '@sveltejs/kit/vite';
import {vitePreprocess} from '@sveltejs/vite-plugin-svelte';
import {svelte_preprocess_fuz_code} from '@fuzdev/fuz_code/svelte_preprocess_fuz_code.ts';

export default defineConfig({
  plugins: [
    sveltekit({
      preprocess: [
        svelte_preprocess_fuz_code(),
        vitePreprocess(),
      ],
    }),
  ],
});

A content that is statically known (a string, a module-level constant, or a ternary of those) is replaced with pre-rendered HTML. Anything else is left for runtime styling.

Svelte support
#

The Svelte lexer was originally based on prism-svelte by @pngwn (pngwn.at). Code styles Svelte by default:

<Code content="<scr..." />

styled:

<script lang="ts">
	import Card from '@fuzdev/fuz_ui/Card.svelte';
	console.log('hello Card', Card);
</script>

<Card>
	<div class="greeting">hi {friend}</div>
</Card>

TypeScript support
#

Code supports TypeScript with lang="ts":

<Code lang="ts" content="export type A<T> = ('b' | 3) & T;" />

export type A<T> = ('b' | 3) & T;

Markdown support
#

Code supports Markdown with lang="md", and fenced blocks for all languages:

# hello `world`

```ts
	const a = 1;
```

Disabling styling
#

Passing lang={null} disables syntax styling:

<Code lang={null} content="<aside>all is gray</aside>" /> <aside>all is gray</aside>

The plaintext language does the same by name. Every SyntaxStyler registers it, so it also works with stylize:

<Code lang="plaintext" content="<aside>all is gray</aside>" /> <aside>all is gray</aside>

A lang that isn't registered also renders as plain text in Code, and logs an error in development. Called directly, stylize and lex throw on an unregistered language, so check with has_lang first or fall back to plaintext:

const html = syntax_styler_global.stylize(
	text,
	syntax_styler_global.has_lang(lang) ? lang : 'plaintext'
);

Layout
#

Code is a block by default:

abc

<div>ab<Code content="c" /></div>

It can be inlined with <Code inline content="..." />

Programmatic usage
#

fuz_code can be used directly from TypeScript without Svelte. Import syntax_styler_global for a pre-configured instance with all built-in languages:

import {syntax_styler_global} from '@fuzdev/fuz_code/syntax_styler_global.ts';

const html = syntax_styler_global.stylize('const x: number = 42;', 'ts');

returns an HTML string:

<span class="token_keyword">const</span> x<span class="token_type_annotation"><span class="token_:">:</span> <span class="token_type"><span class="token_builtin">number</span></span></span> <span class="token_operator">=</span> <span class="token_number">42</span><span class="token_punctuation">;</span>

then rendered with:

<code data-lang="ts">{@html programmatic_result}</code>

renders:

const x: number = 42;

For a custom configuration, create your own SyntaxStyler and register only the languages you need:

import {SyntaxStyler} from '@fuzdev/fuz_code/syntax_styler.ts';
import {lexer_markup} from '@fuzdev/fuz_code/lexer_markup.ts';
import {lexer_css} from '@fuzdev/fuz_code/lexer_css.ts';

const styler = new SyntaxStyler();
styler.add_lang(lexer_markup);
styler.add_lang(lexer_css);

const html = styler.stylize('<div class="example">hello</div>', 'html');

Experimental highlighting API
#

fuz_code also has experimental support for the CSS Custom Highlight API with CodeHighlight — see the samples and textarea.

samples #

Syntax-styled samples in every supported language, rendered with Code and the experimental CodeHighlight.

textarea #

CodeTextarea highlights an editable <textarea> live using the CSS Custom Highlight API. Type below to see it re-highlight. Requires theme_highlight.css.

⚠️ This browser does not support the CSS Custom Highlight API — the textarea still works, but text is shown without highlighting.

const a = 1;

const b: string = 'b';

const c = true;

export type SomeType = 1 | 'b' | true;

declare const some_decorator: any;

abstract class Base {
	abstract abstract_method(): void;
}

/* eslint-disable no-console */

@some_decorator
class D extends Base {
	readonly d1: string = 'd';
	d2: number;
	d3 = $state(null);

	@some_decorator
	decorated = true;

	constructor(d2: number) {
		super();
		this.d2 = d2;
	}

	abstract_method(): void {
		// implementation
	}

	@some_decorator('example', {option: true})
	class_method(): string {
		return `Hello, ${this.d1}`;
	}

	instance_method = (): void => {
		/* ... */
		let i = 0;
		do {
			i++;
		} while (i < 3);

		for (const c2 of this.d1) {
			if (c2 === 'd') continue;
			if (!c2) break;
			this.#private_method(a, c2);
		}

		switch (this.d1) {
			case 'a':
				console.log('case a');
				break;
			case 'b':
			case 'c':
				console.log('case b or c');
				break;
			default:
				console.log('default');
		}

		const obj: {has_d1?: boolean; is_d: boolean} = {
			has_d1: 'd1' in this,
			is_d: this instanceof D,
		};
		delete obj.has_d1;
		// foo
	};

	#private_method(a2: number, c2: any): void {
		throw new Error(`${this.d1}
			multiline
			etc ${a2 + c2}
		`);
	}

	*generator(): Generator<number | Array<number>> {
		yield 1;
		yield* [2, 3];
	}

	async *async_generator(): AsyncGenerator<number> {
		yield await Promise.resolve(4);
	}

	protected async protected_method(): Promise<void> {
		try {
			await new Promise((resolve) => setTimeout(resolve, 100));
			if (Math.random() > 0.5) {
				console.log(new Date());
			} else if (Math.random() > 0.2) {
				console.log('else if branch');
			} else {
				console.log('else branch');
			}
		} catch (error: unknown) {
			console.error(error);
		} finally {
			console.log('finally block');
		}
	}
}

// comment

/*
other comment

const comment = false;
*/

/**
 * JSDoc comment
 */

import {sample_langs, type SampleLang} from '#lib/code_sample.ts';
import * as A from '#lib/code_sample.ts';

export {a, A, b, c, D};

sample_langs as unknown as SampleLang satisfies SampleLang;

export interface SomeE<T = null> {
	name: string;
	age: number;
	t?: T;
}

const e: {name: string; age: number} = {name: 'A. H.', age: 100};
const v = [['', e]] as const;
export const some_e: Map<string, SomeE> = new Map(v);

export function add(x: number, y: number): number {
	return x + y;
}

export const plus = (a: any, b: any): any => a + b;

// boundary test cases
export const str_with_keywords = 'const class function string';
export const str_with_comment = '// this is not a comment';
export const template_with_expr = `Value: ${1 + 2}`;

// regex that looks like comment
export const regex = /\/\/.*/g;
export const complex_regex = /^(?:\/\*.*?\*\/|\/\/.*|[^/])+$/;

// string in comment should not be highlighted as string
// const commented = "this string is in a comment";

const a = 1;

const b: string = 'b';

const c = true;

export type SomeType = 1 | 'b' | true;

declare const some_decorator: any;

abstract class Base {
	abstract abstract_method(): void;
}

/* eslint-disable no-console */

@some_decorator
class D extends Base {
	readonly d1: string = 'd';
	d2: number;
	d3 = $state(null);

@some_decorator
	decorated = true;

constructor(d2: number) {
		super();
		this.d2 = d2;
	}

abstract_method(): void {
		// implementation
	}

@some_decorator('example', {option: true})
	class_method(): string {
		return `Hello, ${this.d1}`;
	}

instance_method = (): void => {
		/* ... */
		let i = 0;
		do {
			i++;
		} while (i < 3);

for (const c2 of this.d1) {
			if (c2 === 'd') continue;
			if (!c2) break;
			this.#private_method(a, c2);
		}

switch (this.d1) {
			case 'a':
				console.log('case a');
				break;
			case 'b':
			case 'c':
				console.log('case b or c');
				break;
			default:
				console.log('default');
		}

const obj: {has_d1?: boolean; is_d: boolean} = {
			has_d1: 'd1' in this,
			is_d: this instanceof D,
		};
		delete obj.has_d1;
		// foo
	};

#private_method(a2: number, c2: any): void {
		throw new Error(`${this.d1}
			multiline
			etc ${a2 + c2}
		`);
	}

*generator(): Generator<number | Array<number>> {
		yield 1;
		yield* [2, 3];
	}

async *async_generator(): AsyncGenerator<number> {
		yield await Promise.resolve(4);
	}

protected async protected_method(): Promise<void> {
		try {
			await new Promise((resolve) => setTimeout(resolve, 100));
			if (Math.random() > 0.5) {
				console.log(new Date());
			} else if (Math.random() > 0.2) {
				console.log('else if branch');
			} else {
				console.log('else branch');
			}
		} catch (error: unknown) {
			console.error(error);
		} finally {
			console.log('finally block');
		}
	}
}

// comment

/*
other comment

const comment = false;
*/

/**
 * JSDoc comment
 */

import {sample_langs, type SampleLang} from '#lib/code_sample.ts';
import * as A from '#lib/code_sample.ts';

export {a, A, b, c, D};

sample_langs as unknown as SampleLang satisfies SampleLang;

export interface SomeE<T = null> {
	name: string;
	age: number;
	t?: T;
}

const e: {name: string; age: number} = {name: 'A. H.', age: 100};
const v = [['', e]] as const;
export const some_e: Map<string, SomeE> = new Map(v);

export function add(x: number, y: number): number {
	return x + y;
}

export const plus = (a: any, b: any): any => a + b;

// boundary test cases
export const str_with_keywords = 'const class function string';
export const str_with_comment = '// this is not a comment';
export const template_with_expr = `Value: ${1 + 2}`;

// regex that looks like comment
export const regex = /\/\/.*/g;
export const complex_regex = /^(?:\/\*.*?\*\/|\/\/.*|[^/])+$/;

// string in comment should not be highlighted as string
// const commented = "this string is in a comment";

benchmark #

fuz_code is optimized for runtime syntax styling. This page compares it with Prism and Shiki, measures its two renderers in the browser, and lists the benchmarks that run from a checkout.

Shiki targets build-time use and runs the Oniguruma regexp engine that TextMate grammars require, trading runtime speed for grammar and theme coverage. fuz_code trades that coverage for a small, fast runtime path. For static content, the svelte_preprocess_fuz_code preprocessor renders at build time. Languages it lacks can be added by writing a lexer.

Compared to Shiki and Prism
#

The cross-implementation benchmark measures fuz_code against Prism and Shiki (both the JavaScript and Oniguruma engines). For end-to-end stylize (lexing plus HTML generation), fuz_code runs roughly an order of magnitude faster than Prism and about two orders of magnitude faster than Shiki:

language	fuz_code vs Prism	fuz_code vs Shiki
`ts`	~18×	~140×
`css`	~8×	~90×
`html`	~11×	~80×
`json`	~17×	~95×
`svelte`	~14×	~165×

Representative stylize results on larger inputs from one machine; absolute numbers vary by hardware. See the committed comparison results for the full matrix across engines and sizes, plus tokenize-only rows that compare the raw lexers without HTML generation.

In the browser
#

The in-browser benchmark measures real DOM rendering rather than pure compute. It times fuz_code's two renderers — the standard HTML path (Code) and the experimental CSS Custom Highlight API path (CodeHighlight, ranges) — across the sample languages, reporting mean, median, percentiles, coefficient of variation, and throughput, with system-stability gating between samples.

Set the iteration count, warmup runs, cooldown, and content multiplier, then run it on your own hardware. For the steadiest numbers, launch Chromium with garbage collection exposed (chromium --js-flags="--expose-gc") so the harness can settle the heap between samples.

A sample run of work time — stylize plus DOM commit — per language for each renderer. The default Code path builds a .token_* span per token; the experimental CodeHighlight path skips that DOM, so it commits less:

Code (html) CodeHighlight (ranges)

ts

91 ms 1.00x

12 ms 7.58x

css

11 ms 1.00x

3 ms 3.67x

html

28 ms 1.00x

4 ms 7.00x

json

11 ms 1.00x

2 ms 5.50x

svelte

91 ms 1.00x

13 ms 7.00x

md

69 ms 1.00x

10 ms 6.90x

sh

49 ms 1.00x

8 ms 6.13x

Lower is better. Each language's ratios are relative to its highlighted row, and a negative ratio means that many times slower; hover the other row to compare against it. Ratios come from the rounded times shown, and this run does not include Rust. The benchmark uses complex samples at the tool's default size, so this is illustrative, not representative of most inputs. The live tool also reports paint-settle time, percentiles, and throughput.

On your machine
#

The command-line benchmarks run from a checkout of the repo:

npm run benchmark — the internal suite, timing every sample at normal and 100× sizes against a local baseline for regression detection.
npm run benchmark:vs — compares against Prism and Shiki and produces the results above.

The internal suite includes a pathological group of adversarial inputs (deeply nested and degenerate source) that tracks the lexer's worst-case cost; the same generators back the linearity tests.

Design
#

No regular expressions — char-code scanning, native indexOf, keyword maps.
One single-pass lexer per language emitting a flat Int32Array event stream, rendered to HTML in a single forward pass.
No grammar interpreter and no regex backtracking; delimiter scans are amortized linear. A test suite checks that lexing time stays near-linear on adversarial inputs.
No dependencies in the lexers or styler — they import nothing outside the package.

The engine keeps no resumable state, so it re-lexes the whole document on every change rather than tokenizing incrementally. In the committed results the largest inputs, up to a few hundred kilobytes of source, take under about ten milliseconds.

See usage for the API and samples for output in every language.

api #

Browse the full api docs.