Repository files navigation

Lightweight,robust,and elegant virtual syntax highlighting usingPrism.

• 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

This package wrapsPrism to output objects (ASTs) instead of astring 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).

This package is useful when you want to perform syntax highlighting in a placewhere 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 ANSIsequences,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 useshighlight.jsinstead.If you’re looking for areally good but rather heavy highlighter,trystarry-night.

You can play with refractor on theinteractive demo (Replit).

This package isESM only.In Node.js (version 16+),install withnpm:

npm install refractor

In Deno withesm.sh:

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

In browsers withesm.sh:

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

import{refractor}from'refractor'consttree=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:';'}]}]}

refractor has several entries in its export map:

• refractor,which exportsrefractor and registers common grammars
• refractor/all,which exportsrefractor and registers all grammars
• refractor/core,which exportsrefractor and registers no grammars
• refractor/*,where* is a language name such asmarkdown,which exports asyntax function as the default export

Highlightvalue (code) aslanguage (programming language).

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

Node representing highlighted code (Root).

importcssfrom'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]}]}

Register a syntax.

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

importmarkdownfrom'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]}]}

Register aliases for already registered languages.

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

• language (string)— programming languagename
• alias (string)— new aliases for the programming language
• list (Array<string>)— list of aliases
• aliases (Record<language, alias | list>)— map oflanguages toaliases orlists

importmarkdownfrom'refractor/markdown'import{refractor}from'refractor/core'refractor.register(markdown)// refractor.highlight('*Emphasis*', 'mdown')// ^ would throw: Error: Unknown language: `mdown` is not registeredrefractor.alias({markdown:['mdown','mkdn','mdwn','ron']})refractor.highlight('*Emphasis*','mdown')// ^ Works!

Check whether analias orlanguage is registered.

• aliasOrlanguage (string)— programming language name or alias

importmarkdownfrom'refractor/markdown'import{refractor}from'refractor/core'console.log(refractor.registered('markdown'))//=> falserefractor.register(markdown)console.log(refractor.registered('markdown'))//=> true

List all registered languages (names and aliases).

Array<string>.

importmarkdownfrom'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']

Refractor syntax function (TypeScript type).

exporttypeSyntax=((prism:Refractor)=>undefined|void)&{aliases?:Array<string>|undefineddisplayName:string}

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

import{toHtml}from'hast-util-to-html'import{refractor}from'refractor'consttree=refractor.highlight('"use strict";','js')console.log(toHtml(tree))

Yields:

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

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

import{toJsxRuntime}from'hast-util-to-jsx-runtime'import{Fragment,jsxs,jsx}from'react/jsx-runtime'import{refractor}from'refractor'consttree=refractor.highlight('"use strict";','js')constreactNode=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:{}}

If you’re usingrefractor/core,no syntaxes are included.Checked syntaxes are included if you importrefractor.Unchecked syntaxes are available throughrefractor/all.You can importrefractor/core orrefractor and manually add more languagesas 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 withrefractor because Prism’s ownsyntaxes 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.It does not make sense: refractor doesn’t have to be turned into HTML and mightnot run in a browser!If you are in a browser,you can use any Prism theme.For example,to get Prism Dark fromesm.sh:

<linkrel="stylesheet"href="https://esm.sh/prismjs@1.30.0/themes/prism-dark.css">

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 inrefractor/* will work withrefractor as Prism’s own syntaxes are made to work with global variables andare 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 withhighlight.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 codeblocks
• react-refractor— syntax highlighter forReact

Yes please!SeeHow to Contribute to Open Source.

MIT ©Titus Wormer