README
refractor
Lightweight, robust, elegant virtual syntax highlighting using Prism.
Contents
- What is this?
- When should I use this?
- Playground
- Install
- Use
- API
- Examples
- Types
- 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 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 languageslib/common.js
(default) — 36 languageslib/all.js
— 277 languages
Bundled, minified, and gzipped, those are roughly 12.7 kB, 40 kB, and 211 kB.
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.
Playground
You can play with refractor on the interactive demo (Replit).
Install
This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:
npm install refractor
In Deno with Skypack:
import {refractor} from 'https://cdn.skypack.dev/refractor@4?dts'
In browsers with Skypack:
<script type="module">
import {refractor} from 'https://cdn.skypack.dev/refractor@4?min'
</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
This package exports the following identifier: refractor
.
There is no default export.
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 {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]}
]
}
refractor.register(syntax)
Register a syntax.
Parameters
syntax
(Function
) — language function custom made for refractor, as in, the files inrefractor/lang/*.js
Example
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]}
]
}
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 {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!
refractor.registered(aliasOrlanguage)
Check whether an alias
or language
is registered.
Parameters
aliasOrlanguage
(string
) — programming language name or alias
Example
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
refractor.listLanguages()
List all registered languages (names and aliases).
Returns
Array<string>
.
Example
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'
]
Examples
Example: serializing hast as html
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>
Example: turning hast into react nodes
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: {}
}
Types
This package is fully typed with TypeScript.
It exports additional Root
, Grammar
, and Syntax
types that model their
respective interfaces.
Data
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: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
asciidoc
— alias:adoc
asm6502
asmatmel
aspnet
autohotkey
autoit
avisynth
— alias:avs
avro-idl
— alias:avdl
batch
bbcode
— alias:shortcode
bicep
birb
bison
bnf
— alias:rbnf
brainfuck
brightscript
bro
bsl
— alias:oscript
cfscript
— alias:cfc
chaiscript
cil
clojure
cmake
cobol
coffeescript
— alias:coffee
concurnas
— alias:conc
coq
crystal
cshtml
— alias:razor
csp
css-extras
csv
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
gherkin
git
glsl
gml
— alias:gamemakerlanguage
gn
— alias:gni
go-module
— alias:go-mod
graphql
groovy
haml
handlebars
— alias:hbs
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
liquid
lisp
— alias:elisp
,emacs
,emacs-lisp
livescript
llvm
log
lolcode
magma
matlab
maxscript
mel
mermaid
mizar
mongodb
monkey
moonscript
— alias:moon
n1ql
n4js
— alias:n4jsd
nand2tetris-hdl
naniscript
— alias:nani
nasm
neon
nevod
nginx
nim
nix
nsis
ocaml
opencl
openqasm
— alias:qasm
oz
parigp
parser
pascal
— alias:objectpascal
pascaligo
pcaxis
— alias:px
peoplecode
— alias:pcode
php-extras
phpdoc
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
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
stylus
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
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 (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">
Compatibility
This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 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.
Security
This package is safe.
Related
lowlight
— the same as refractor but withhighlight.js
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.