Language Registration

Language registration is the main bundle-size control in TanStack Highlight.

Create a selective highlighter

import { createHighlighter } from '@tanstack/highlight/core'
import { json } from '@tanstack/highlight/languages/json'
import { shell } from '@tanstack/highlight/languages/shell'
import { tsx } from '@tanstack/highlight/languages/tsx'

export const highlighter = createHighlighter({
  languages: [json, shell, tsx],
})

The resulting registry contains three definitions plus their aliases. It does not load a global grammar catalog.

highlighter.listLanguages()
// ['json', 'shell', 'tsx']

highlighter.normalizeLanguage('bash')
// 'shell'

highlighter.normalizeLanguage('python')
// 'plaintext'

Aliases belong to definitions. bash resolves only because shell was registered.

Fallback behavior

The default fallback name is plaintext:

const result = highlighter.highlight('<unsafe>', {
  lang: 'not-registered',
})

result.lang
// 'plaintext'

result.html
// The angle brackets are escaped.

You can choose another registered fallback language:

const highlighter = createHighlighter({
  fallbackLanguage: 'json',
  languages: [json],
})

Unknown inputs will then be tokenized as JSON. An unregistered fallback name still produces escaped plaintext under that name, but registering plaintext is clearer when plain output is intentional.

Root convenience entry

The package root constructs a highlighter with allLanguages and exports bound helpers:

import {
  defaultHighlighter,
  highlight,
  highlightToHtml,
  listLanguages,
  normalizeLanguage,
  renderCodeBlockData,
  tokenize,
} from '@tanstack/highlight'

This is convenient, but importing any bound helper retains the all-language registry. Use @tanstack/highlight/core when browser size matters.

Core helpers re-exported from the root, such as createHighlighter, defineLanguage, and escapeHtml, don't need that registry. Importing only those helpers lets a compatible bundler remove every built-in language.

Share one registry

Create the highlighter once at module scope:

// code-highlighter.ts
export const highlighter = createHighlighter({
  languages: [json, shell, tsx],
})

There is no benefit to creating one per block. The registry is immutable after construction and safe to reuse across server requests and client renders.

Aggregate imports

The aggregate entry exposes every shipped language module:

import { json, shell, tsx } from '@tanstack/highlight/languages'

A tree-shaking bundler can remove unused definitions because the package is side-effect free. Prefer direct subpaths when the bundle must make isolation explicit:

import { json } from '@tanstack/highlight/languages/json'

See Language Support for every name and alias.