Lightweight, robust, elegant virtual syntax highlighting using Prism.

• What is this?
• When should I use this?
• Playground
• Install
• Use
• API
  • refractor.highlight(value, language)
  • refractor.register(syntax)
  • refractor.alias(name[, alias])
  • refractor.registered(aliasOrlanguage)
  • refractor.listLanguages()
• Examples
  • Example: serializing hast as html
  • Example: turning hast into react nodes
• Types
• Data
• CSS
• Compatibility
• Security
• Related
• Projects
• Contribute

This package wraps Prism to output objects (ASTs) instead of a string of HTML.

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

• lib/core.js — 0 languages
• lib/common.js (default) — 36 languages
• lib/all.js — 297 languages

Bundled, minified, and gzipped, those are roughly 12.7 kB, 40 kB, and 211 kB.

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, does the same as refractor but uses highlight.js instead. If you’re looking for a really good (but rather heavy) highlighter, try starry-night.

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

This package is ESM only. In Node.js (version 14.14+, 16.0+), install with npm:

npm install refractor

In Deno with esm.sh:

import {refractor} from 'https://esm.sh/refractor@4'

In browsers with esm.sh:

<script type="module">
  import {refractor} from 'https://esm.sh/refractor@4?bundle'
</script>

import {refractor} from 'refractor'

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

console.log(tree)

Yields:

{
  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: ';'}]
    }
  ]
}

This package exports the identifier refractor. There is no default export.

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

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

Node representing highlighted code (Root).

import {refractor} from 'refractor/lib/core.js'
import css from 'refractor/lang/css.js'

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

Yields:

{
  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]}
  ]
}

Register a syntax.

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

import {refractor} from 'refractor/lib/core.js'
import markdown from 'refractor/lang/markdown.js'

refractor.register(markdown)

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

Yields:

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

Register aliases for already registered languages.

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

• language (string) — programming language name
• alias (string) — new aliases for the programming language
• list (Array<string>) — list of aliases
• aliases (Record<language, alias|list>) — map of languages to aliases or lists

import {refractor} from 'refractor/lib/core.js'
import markdown from 'refractor/lang/markdown.js'

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!

Check whether an alias or language is registered.

• aliasOrlanguage (string) — programming language name or alias

import {refractor} from 'refractor/lib/core.js'
import markdown from 'refractor/lang/markdown.js'

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

refractor.register(markdown)

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

List all registered languages (names and aliases).

Array<string>.

import {refractor} from 'refractor/lib/core.js'
import markdown from 'refractor/lang/markdown.js'

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

refractor.register(markdown)

console.log(refractor.listLanguages())

Yields:

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

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

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

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

console.log(toHtml(tree))

Yields:

<span class="token string">"use strict"</span><span class="token punctuation">;</span>

hast trees as returned by refractor can be turned into React (or Preact) with hast-to-hyperscript:

import {refractor} from 'refractor'
import {toH} from 'hast-to-hyperscript'
import React from 'react'

const tree = refractor.highlight('"use strict";', 'js')
const react = toH(React.createElement, tree)

console.log(react)

Yields:

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

This package is fully typed with TypeScript. It exports the additional types Root, Grammar, and Syntax.

If you’re using refractor/lib/core.js, no syntaxes are included. Checked syntaxes are included if you import refractor (or explicitly refractor/lib/common.js). Unchecked syntaxes are available through refractor/lib/all.js. You can import core or common 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.

• arduino — alias: ino
• bash — alias: sh, shell
• basic
• c
• clike
• cpp
• csharp — alias: cs, dotnet
• css
• diff
• go
• ini
• java
• javascript — alias: js
• json — alias: webmanifest
• kotlin — alias: kt, kts
• less
• lua
• makefile
• markdown — alias: md
• markup — alias: atom, html, mathml, rss, ssml, svg, xml
• markup-templating
• objectivec — alias: objc
• perl
• php
• python — alias: py
• r
• regex
• ruby — alias: rb
• rust
• sass
• scss
• sql
• swift
• typescript — alias: ts
• vbnet
• 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

refractor does not inject CSS for the syntax highlighted code (because well, 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 cdnjs:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.27.0/themes/prism-dark.min.css">

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

Only the custom built syntaxes in refractor/lang/*.js 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.

This package is safe.

• lowlight — the same as refractor but with highlight.js
• starry-night — similar but like GitHub and really good

• react-syntax-highlighter — React component for syntax highlighting
• @mapbox/rehype-prism — rehype plugin to highlight code blocks
• react-refractor — syntax highlighter for React

Yes please! See How to Contribute to Open Source.

MIT © Titus Wormer