refractor

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]

Lightweight,
robust,
and elegant virtual syntax highlighting using [Prism][github-prism].

Contents

* What is this?
* When should I use this?
* Playground
* Install
* Use
* API
* refractor
* Syntax
* Examples
* Example: serializing hast as html
* Example: turning hast into react nodes
* Data
* CSS
* Compatibility
* Security
* Related
* Projects
* Contribute

What is this?

This package wraps [Prism][github-prism] to output objects (ASTs) instead of a
string of HTML.

Prism,
through refractor,
supports 290+ programming languages.
Supporting all of them requires a lot of code.
That’s why there are three entry points for refractor:

* refractor/all — 297 languages
* refractor/core — 0 languages
* refractor (default) — 36 common languages

Bundled,
minified,
and gzipped,
those are roughly 12.7 kB (core),
40 kB (default),
and 211 kB (all).

When should I use this?

This package is useful when you want to perform syntax highlighting in a place
where serialized HTML wouldn’t work or wouldn’t work well.
For example,
you can use refractor when you want to show code in a CLI by rendering to ANSI
sequences,
when you’re using virtual DOM frameworks
(such as React or Preact)
so that diffing can be performant,
or when you’re working with ASTs
(rehype).

A different package,
[lowlight][github-lowlight],
does the same as refractor but uses [highlight.js][github-highlightjs]
instead.
If you’re looking for a really good but rather heavy highlighter,
try [starry-night][github-starry-night].

Playground

You can play with refractor on the
interactive demo (Replit).

Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npmjs-install]:

``sh
npm install refractor
`

In Deno with [esm.sh][esmsh]:

`js
import {refractor} from 'https://esm.sh/refractor@5'
`

In browsers with [esm.sh][esmsh]:

`html

`

Use

`js
import {refractor} from 'refractor'

const tree = refractor.highlight('"use strict";', 'js')

console.log(tree)
`

Yields:

`js
{
type: 'root',
children: [
{
type: 'element',
tagName: 'span',
properties: {className: ['token', 'string']},
children: [{type: 'text', value: '"use strict"'}]
},
{
type: 'element',
tagName: 'span',
properties: {className: ['token', 'punctuation']},
children: [{type: 'text', value: ';'}]
}
]
}
`

API

refractor has several entries in its export map:

* refractor,
which exports refractor and registers common grammars
* refractor/all,
which exports refractor and registers all grammars
* refractor/core,
which exports refractor and registers no grammars
refractor/,
where * is a language name such as markdown,
which exports a [syntax function][api-syntax] as the default export

$3

#### refractor.highlight(value, language)

Highlight value (code) as language (programming language).

###### Parameters

* value (string)
— code to highlight
* language (string or Grammar)
— programming language name,
alias,
or grammar

###### Returns

Node representing highlighted code ([Root][github-hast-root]).

###### Example

`js
import css from 'refractor/css'
import {refractor} from 'refractor/core'

refractor.register(css)
console.log(refractor.highlight('em { color: red }', 'css'))
`

Yields:

`js
{
type: 'root',
children: [
{type: 'element', tagName: 'span', properties: [Object], children: [Array]},
{type: 'text', value: ' '},
// …
{type: 'text', value: ' red '},
{type: 'element', tagName: 'span', properties: [Object], children: [Array]}
]
}
`

#### refractor.register(syntax)

Register a syntax.

###### Parameters

* syntax (Function)
— language function custom made for refractor,
as in,
the files in refractor/*

###### Example

`js
import markdown from 'refractor/markdown'
import {refractor} from 'refractor/core'

refractor.register(markdown)

console.log(refractor.highlight('Emphasis', 'markdown'))
`

Yields:

`js
{
type: 'root',
children: [
{type: 'element', tagName: 'span', properties: [Object], children: [Array]}
]
}
`

#### refractor.alias(name[, alias])

Register aliases for already registered languages.

###### Signatures

* alias(name, alias | list)
* alias(aliases)

###### Parameters

* language (string)
— programming language [name][prismjs-languages]
* alias (string)
— new aliases for the programming language
* list (Array)
— list of aliases
* aliases (Record)
— map of languages to aliases or lists

###### Example

`js
import markdown from 'refractor/markdown'
import {refractor} from 'refractor/core'

refractor.register(markdown)

// refractor.highlight('Emphasis', 'mdown')
// ^ would throw: Error: Unknown language: mdown is not registered

refractor.alias({markdown: ['mdown', 'mkdn', 'mdwn', 'ron']})
refractor.highlight('Emphasis', 'mdown')
// ^ Works!
`

#### refractor.registered(aliasOrlanguage)

Check whether an alias or language is registered.

###### Parameters

* aliasOrlanguage (string)
— programming language name or alias

###### Example

`js
import markdown from 'refractor/markdown'
import {refractor} from 'refractor/core'

console.log(refractor.registered('markdown')) //=> false

refractor.register(markdown)

console.log(refractor.registered('markdown')) //=> true
`

#### refractor.listLanguages()

List all registered languages (names and aliases).

###### Returns

Array.

###### Example

`js
import markdown from 'refractor/markdown'
import {refractor} from 'refractor/core'

console.log(refractor.listLanguages()) //=> []

refractor.register(markdown)

console.log(refractor.listLanguages())
`

Yields:

`js
[
'markup', // Note that markup (a lot of xml based languages) is a dep of markdown.
'html',
// …
'markdown',
'md'
]
`

$3

Refractor syntax function (TypeScript type).

###### Type

`ts
export type Syntax = ((prism: Refractor) => undefined | void) & {
aliases?: Array | undefined
displayName: string
}
`

Examples

$3

hast trees as returned by refractor can be serialized with
[hast-util-to-html][github-hast-util-to-html]:

`js
import {toHtml} from 'hast-util-to-html'
import {refractor} from 'refractor'

const tree = refractor.highlight('"use strict";', 'js')

console.log(toHtml(tree))
`

Yields:

`html
"use strict";
`

$3

hast trees as returned by refractor can be turned into React (or Preact) with
[hast-util-to-jsx-runtime][github-hast-util-to-jsx-runtime]:

`js
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsxs, jsx} from 'react/jsx-runtime'
import {refractor} from 'refractor'

const tree = refractor.highlight('"use strict";', 'js')
const reactNode = toJsxRuntime(tree, {Fragment, jsxs, jsx})

console.log(react)
`

Yields:

`js
{
'$$typeof': Symbol(react.element),
type: 'div',
key: 'h-1',
ref: null,
props: { children: [ [Object], [Object] ] },
_owner: null,
_store: {}
}
`

Data

If you’re using refractor/core,
no syntaxes are included.
Checked syntaxes are included if you import refractor.
Unchecked syntaxes are available through refractor/all.
You can import refractor/core or refractor and manually add more languages
as you please.

Prism operates as a singleton:
once you register a language in one place,
it’ll be available everywhere.

Only these custom built syntaxes will work with refractor because Prism’s own
syntaxes are made to work with global variables and are not importable.

* [x] arduino — alias: ino
* [x] bash — alias: sh, shell
* [x] basic
* [x] c
* [x] clike
* [x] cpp
* [x] csharp — alias: cs, dotnet
* [x] css
* [x] diff
* [x] go
* [x] ini
* [x] java
* [x] javascript — alias: js
* [x] json — alias: webmanifest
* [x] kotlin — alias: kt, kts
* [x] less
* [x] lua
* [x] makefile
* [x] markdown — alias: md
* [x] markup — alias: atom, html, mathml, rss, ssml, svg, xml
* [x] markup-templating
* [x] objectivec — alias: objc
* [x] perl
* [x] php
* [x] python — alias: py
* [x] r
* [x] regex
* [x] ruby — alias: rb
* [x] rust
* [x] sass
* [x] scss
* [x] sql
* [x] swift
* [x] typescript — alias: ts
* [x] vbnet
* [x] yaml — alias: yml
* [ ] abap
* [ ] abnf
* [ ] actionscript
* [ ] ada
* [ ] agda
* [ ] al
* [ ] antlr4 — alias: g4
* [ ] apacheconf
* [ ] apex
* [ ] apl
* [ ] applescript
* [ ] aql
* [ ] arff
* [ ] armasm — alias: arm-asm
* [ ] arturo — alias: art
* [ ] asciidoc — alias: adoc
* [ ] asm6502
* [ ] asmatmel
* [ ] aspnet
* [ ] autohotkey
* [ ] autoit
* [ ] avisynth — alias: avs
* [ ] avro-idl — alias: avdl
* [ ] awk — alias: gawk
* [ ] batch
* [ ] bbcode — alias: shortcode
* [ ] bbj
* [ ] bicep
* [ ] birb
* [ ] bison
* [ ] bnf — alias: rbnf
* [ ] bqn
* [ ] brainfuck
* [ ] brightscript
* [ ] bro
* [ ] bsl — alias: oscript
* [ ] cfscript — alias: cfc
* [ ] chaiscript
* [ ] cil
* [ ] cilkc — alias: cilk-c
* [ ] cilkcpp — alias: cilk, cilk-cpp
* [ ] clojure
* [ ] cmake
* [ ] cobol
* [ ] coffeescript — alias: coffee
* [ ] concurnas — alias: conc
* [ ] cooklang
* [ ] coq
* [ ] crystal
* [ ] cshtml — alias: razor
* [ ] csp
* [ ] css-extras
* [ ] csv
* [ ] cue
* [ ] cypher
* [ ] d
* [ ] dart
* [ ] dataweave
* [ ] dax
* [ ] dhall
* [ ] django — alias: jinja2
* [ ] dns-zone-file — alias: dns-zone
* [ ] docker — alias: dockerfile
* [ ] dot — alias: gv
* [ ] ebnf
* [ ] editorconfig
* [ ] eiffel
* [ ] ejs — alias: eta
* [ ] elixir
* [ ] elm
* [ ] erb
* [ ] erlang
* [ ] etlua
* [ ] excel-formula — alias: xls, xlsx
* [ ] factor
* [ ] false
* [ ] firestore-security-rules
* [ ] flow
* [ ] fortran
* [ ] fsharp
* [ ] ftl
* [ ] gap
* [ ] gcode
* [ ] gdscript
* [ ] gedcom
* [ ] gettext — alias: po
* [ ] gherkin
* [ ] git
* [ ] glsl
* [ ] gml — alias: gamemakerlanguage
* [ ] gn — alias: gni
* [ ] go-module — alias: go-mod
* [ ] gradle
* [ ] graphql
* [ ] groovy
* [ ] haml
* [ ] handlebars — alias: hbs, mustache
* [ ] haskell — alias: hs
* [ ] haxe
* [ ] hcl
* [ ] hlsl
* [ ] hoon
* [ ] hpkp
* [ ] hsts
* [ ] http
* [ ] ichigojam
* [ ] icon
* [ ] icu-message-format
* [ ] idris — alias: idr
* [ ] iecst
* [ ] ignore — alias: gitignore, hgignore, npmignore
* [ ] inform7
* [ ] io
* [ ] j
* [ ] javadoc
* [ ] javadoclike
* [ ] javastacktrace
* [ ] jexl
* [ ] jolie
* [ ] jq
* [ ] js-extras
* [ ] js-templates
* [ ] jsdoc
* [ ] json5
* [ ] jsonp
* [ ] jsstacktrace
* [ ] jsx
* [ ] julia
* [ ] keepalived
* [ ] keyman
* [ ] kumir — alias: kum
* [ ] kusto
* [ ] latex — alias: context, tex
* [ ] latte
* [ ] lilypond — alias: ly
* [ ] linker-script — alias: ld
* [ ] liquid
* [ ] lisp — alias: elisp, emacs, emacs-lisp
* [ ] livescript
* [ ] llvm
* [ ] log
* [ ] lolcode
* [ ] magma
* [ ] mata
* [ ] matlab
* [ ] maxscript
* [ ] mel
* [ ] mermaid
* [ ] metafont
* [ ] mizar
* [ ] mongodb
* [ ] monkey
* [ ] moonscript — alias: moon
* [ ] n1ql
* [ ] n4js — alias: n4jsd
* [ ] nand2tetris-hdl
* [ ] naniscript — alias: nani
* [ ] nasm
* [ ] neon
* [ ] nevod
* [ ] nginx
* [ ] nim
* [ ] nix
* [ ] nsis
* [ ] ocaml
* [ ] odin
* [ ] opencl
* [ ] openqasm — alias: qasm
* [ ] oz
* [ ] parigp
* [ ] parser
* [ ] pascal — alias: objectpascal
* [ ] pascaligo
* [ ] pcaxis — alias: px
* [ ] peoplecode — alias: pcode
* [ ] php-extras
* [ ] phpdoc
* [ ] plant-uml — alias: plantuml
* [ ] plsql
* [ ] powerquery — alias: mscript, pq
* [ ] powershell
* [ ] processing
* [ ] prolog
* [ ] promql
* [ ] properties
* [ ] protobuf
* [ ] psl
* [ ] pug
* [ ] puppet
* [ ] pure
* [ ] purebasic — alias: pbfasm
* [ ] purescript — alias: purs
* [ ] q
* [ ] qml
* [ ] qore
* [ ] qsharp — alias: qs
* [ ] racket — alias: rkt
* [ ] reason
* [ ] rego
* [ ] renpy — alias: rpy
* [ ] rescript — alias: res
* [ ] rest
* [ ] rip
* [ ] roboconf
* [ ] robotframework — alias: robot
* [ ] sas
* [ ] scala
* [ ] scheme
* [ ] shell-session — alias: sh-session, shellsession
* [ ] smali
* [ ] smalltalk
* [ ] smarty
* [ ] sml — alias: smlnj
* [ ] solidity — alias: sol
* [ ] solution-file — alias: sln
* [ ] soy
* [ ] sparql — alias: rq
* [ ] splunk-spl
* [ ] sqf
* [ ] squirrel
* [ ] stan
* [ ] stata
* [ ] stylus
* [ ] supercollider — alias: sclang
* [ ] systemd
* [ ] t4-cs — alias: t4
* [ ] t4-templating
* [ ] t4-vb
* [ ] tap
* [ ] tcl
* [ ] textile
* [ ] toml
* [ ] tremor — alias: trickle, troy
* [ ] tsx
* [ ] tt2
* [ ] turtle — alias: trig
* [ ] twig
* [ ] typoscript — alias: tsconfig
* [ ] unrealscript — alias: uc, uscript
* [ ] uorazor
* [ ] uri — alias: url
* [ ] v
* [ ] vala
* [ ] velocity
* [ ] verilog
* [ ] vhdl
* [ ] vim
* [ ] visual-basic — alias: vb, vba
* [ ] warpscript
* [ ] wasm
* [ ] web-idl — alias: webidl
* [ ] wgsl
* [ ] wiki
* [ ] wolfram — alias: mathematica, nb, wl
* [ ] wren
* [ ] xeora — alias: xeoracube
* [ ] xml-doc
* [ ] xojo
* [ ] xquery
* [ ] yang
* [ ] zig

CSS

refractor does not inject CSS for the syntax highlighted code.
It does not make sense: refractor doesn’t have to be turned into HTML and might
not run in a browser!
If you are in a browser,
you can use any Prism theme.
For example,
to get Prism Dark from [esm.sh][esmsh]:

`html

`

Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now,
that is Node.js 16+.
It also works in Deno and modern browsers.

Only the custom built syntaxes in refractor/* will work with
refractor as Prism’s own syntaxes are made to work with global variables and
are not importable.

refractor also does not support Prism plugins,
due to the same limitations,
and that they almost exclusively deal with the DOM.

Security

This package is safe.

Related

* [lowlight][github-lowlight]
— the same as refractor but with [highlight.js][github-highlightjs]
* [starry-night][github-starry-night]
— similar but like GitHub and really good

Projects

* react-syntax-highlighter
— [React][] component for syntax highlighting
* @mapbox/rehype-prism
— [rehype][github-rehype] plugin to highlight code
blocks
* react-refractor`
— syntax highlighter for [React][]

Contribute

Yes please!
See [How to Contribute to Open Source][opensource-guide].

License

[MIT][file-license] © [Titus Wormer][wooorm]

[api-syntax]: #syntax

[badge-build-image]: https://github.com/wooorm/refractor/workflows/main/badge.svg

[badge-build-url]: https://github.com/wooorm/refractor/actions

[badge-coverage-image]: https://img.shields.io/codecov/c/github/wooorm/refractor.svg

[badge-coverage-url]: https://codecov.io/github/wooorm/refractor

[badge-downloads-image]: https://img.shields.io/npm/dm/refractor.svg

[badge-downloads-url]: https://www.npmjs.com/package/refractor

[badge-size-image]: https://img.shields.io/bundlejs/size/refractor

[badge-size-url]: https://bundlejs.com/?q=refractor

[esmsh]: https://esm.sh

[file-license]: license

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-hast-root]: https://github.com/syntax-tree/hast#root

[github-hast-util-to-html]: https://github.com/syntax-tree/hast-util-to-html

[github-hast-util-to-jsx-runtime]: https://github.com/syntax-tree/hast-util-to-jsx-runtime

[github-highlightjs]: https://github.com/highlightjs/highlight.js

[github-lowlight]: https://github.com/wooorm/lowlight

[github-prism]: https://github.com/PrismJS/prism

[github-rehype]: https://github.com/rehypejs/rehype

[github-starry-night]: https://github.com/wooorm/starry-night

[npmjs-install]: https://docs.npmjs.com/cli/install

[opensource-guide]: https://opensource.guide/how-to-contribute/

[prismjs-languages]: https://prismjs.com/#languages-list

[react]: https://react.dev

[wooorm]: https://wooorm.com