refractor
Lightweight, robust, and elegant virtual syntax highlighting using Prism.
Contents
- What is this?
- When should I use this?
- Playground
- Install
- Use
- API
- Examples
- Data
- CSS
- Compatibility
- Security
- Related
- Projects
- Contribute
What is this?
This package wraps 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 languagesrefractor/core
— 0 languagesrefractor
(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
,
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
.
Playground
You can play with refractor on the interactive demo (Replit).
Install
This package is ESM only. In Node.js (version 16+), install with npm:
npm install refractor
In Deno with esm.sh
:
import {refractor} from 'https://esm.sh/refractor@5'
In browsers with esm.sh
:
<script type="module">
import {refractor} from 'https://esm.sh/refractor@5?bundle'
</script>
Use
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: ';'}]
}
]
}
API
refractor
has several entries in its export map:
refractor
, which exportsrefractor
and registers common grammarsrefractor/all
, which exportsrefractor
and registers all grammarsrefractor/core
, which exportsrefractor
and registers no grammarsrefractor/*
, where*
is a language name such asmarkdown
, which exports a syntax function as the default export
refractor
refractor.highlight(value, language)
Highlight value
(code) as language
(programming language).
Parameters
value
(string
) — code to highlightlanguage
(string
orGrammar
) — programming language name, alias, or grammar
Returns
Node representing highlighted code (Root
).
Example
import css from 'refractor/css'
import {refractor} from 'refractor/core'
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]}
]
}
refractor.register(syntax)
Register a syntax.
Parameters
syntax
(Function
) — language function custom made for refractor, as in, the files inrefractor/*
Example
import markdown from 'refractor/markdown'
import {refractor} from 'refractor/core'
refractor.register(markdown)
console.log(refractor.highlight('*Emphasis*', 'markdown'))
Yields:
{
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 namealias
(string
) — new aliases for the programming languagelist
(Array<string>
) — list of aliasesaliases
(Record<language, alias | list>
) — map oflanguage
s toalias
es orlist
s
Example
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
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<string>
.
Example
import markdown from 'refractor/markdown'
import {refractor} from 'refractor/core'
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'
]
Syntax
Refractor syntax function (TypeScript type).
Type
export type Syntax = ((prism: Refractor) => undefined | void) & {
aliases?: Array<string> | undefined
displayName: string
}
Examples
Example: serializing hast as html
hast trees as returned by refractor can be serialized with
hast-util-to-html
:
import {toHtml} from 'hast-util-to-html'
import {refractor} from 'refractor'
const tree = refractor.highlight('"use strict";', 'js')
console.log(toHtml(tree))
Yields:
<span class="token string">"use strict"</span><span class="token punctuation">;</span>
Example: turning hast into react nodes
hast trees as returned by refractor can be turned into React (or Preact) with
hast-util-to-jsx-runtime
:
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:
{
'$$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.
-
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
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
:
<link rel="stylesheet" href="https://esm.sh/prismjs@1.30.0/themes/prism-dark.css">
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
— the same as refractor but withhighlight.js
starry-night
— similar but like GitHub and really good
Projects
react-syntax-highlighter
— React component for syntax highlighting@mapbox/rehype-prism
— rehype plugin to highlight code blocksreact-refractor
— syntax highlighter for React
Contribute
Yes please! See How to Contribute to Open Source.