Refractor is a lightweight, robust, and extensible syntax highlighter that works in both Node.js and the browser. It is built on top of the Prism syntax highlighter and provides a way to highlight code syntax in various programming languages.
Syntax Highlighting
This feature allows you to highlight code syntax for a given programming language. The example highlights a simple JavaScript code snippet.
const refractor = require('refractor');
const html = refractor.highlight('const x = 42;', 'javascript');
console.log(html);Registering Languages
You can register additional languages for syntax highlighting. This example registers the Python language and highlights a Python code snippet.
const refractor = require('refractor');
const python = require('refractor/lang/python');
refractor.register(python);
const html = refractor.highlight('print("Hello, World!")', 'python');
console.log(html);Syntax Highlighting with Plugins
Refractor supports plugins to extend its functionality. This example uses the line-numbers plugin to add line numbers to the highlighted code.
const refractor = require('refractor');
const lineNumbers = require('refractor/plugins/line-numbers');
refractor.use(lineNumbers);
const html = refractor.highlight('const x = 42;', 'javascript');
console.log(html);Highlight.js is a popular syntax highlighter written in JavaScript. It automatically detects the language of the code and applies syntax highlighting. Compared to Refractor, Highlight.js is more automatic in language detection but may not be as customizable.
Prism is a lightweight, extensible syntax highlighter, built with modern web standards in mind. Refractor is built on top of Prism, so they share many similarities. However, Refractor provides a more modular approach and additional features like plugins.
CodeMirror is a versatile text editor implemented in JavaScript for the browser. It is specialized for editing code and comes with syntax highlighting capabilities. While CodeMirror is more of a full-fledged code editor, Refractor focuses solely on syntax highlighting.
Lightweight, robust, elegant virtual syntax highlighting using Prism.
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 — 276 languagesBundled, 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.
You can play with refractor on the interactive demo (Replit).
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>
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 following identifier: refractor.
There is no default export.
refractor.highlight(value, language)Highlight value (code) as language (programming language).
value (string)
— code to highlightlanguage (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]}
]
}
refractor.register(syntax)Register a syntax.
syntax (Function)
— language function custom made for refractor, as in, the files in
refractor/lang/*.jsimport {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.
alias(name, alias|list)alias(aliases)language (string)
— programming language namealias (string)
— new aliases for the programming languagelist (Array<string>)
— list of aliasesaliases (Record<language, alias|list>)
— map of languages to aliases or listsimport {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.
aliasOrlanguage (string)
— programming language name or aliasimport {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).
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 additional Root, Grammar, and Syntax types that model their
respective interfaces.
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: inobash — alias: shellbasiccclikecppcsharp — alias: cs, dotnetcssdiffgoinijavajavascript — alias: jsjson — alias: webmanifestkotlin — alias: kt, ktslessluamakefilemarkdown — alias: mdmarkup — alias: atom, html, mathml, rss, ssml, svg, xmlmarkup-templatingobjectivec — alias: objcperlphppython — alias: pyrregexruby — alias: rbrustsassscsssqlswifttypescript — alias: tsvbnetyaml — alias: ymlabapabnfactionscriptadaagdaalantlr4 — alias: g4apacheconfapexaplapplescriptaqlarffasciidoc — alias: adocasm6502asmatmelaspnetautohotkeyautoitavisynth — alias: avsavro-idl — alias: avdlbatchbbcode — alias: shortcodebicepbirbbisonbnf — alias: rbnfbrainfuckbrightscriptbrobsl — alias: oscriptcfscript — alias: cfcchaiscriptcilclojurecmakecobolcoffeescript — alias: coffeeconcurnas — alias: conccoqcrystalcshtml — alias: razorcspcss-extrascsvcypherddartdataweavedaxdhalldjango — alias: jinja2dns-zone-file — alias: dns-zonedocker — alias: dockerfiledot — alias: gvebnfeditorconfigeiffelejs — alias: etaelixirelmerberlangetluaexcel-formula — alias: xls, xlsxfactorfalsefirestore-security-rulesflowfortranfsharpftlgapgcodegdscriptgedcomgherkingitglslgml — alias: gamemakerlanguagegn — alias: gnigo-module — alias: go-modgraphqlgroovyhamlhandlebars — alias: hbshaskell — alias: hshaxehclhlslhoonhpkphstshttpichigojamiconicu-message-formatidris — alias: idriecstignore — alias: gitignore, hgignore, npmignoreinform7iojjavadocjavadoclikejavastacktracejexljoliejqjs-extrasjs-templatesjsdocjson5jsonpjsstacktracejsxjuliakeepalivedkeymankumir — alias: kumkustolatex — alias: context, texlattelilypond — alias: lyliquidlisp — alias: elisp, emacs, emacs-lisplivescriptllvmloglolcodemagmamatlabmaxscriptmelmermaidmizarmongodbmonkeymoonscript — alias: moonn1qln4js — alias: n4jsdnand2tetris-hdlnaniscript — alias: naninasmneonnevodnginxnimnixnsisocamlopenclopenqasm — alias: qasmozparigpparserpascal — alias: objectpascalpascaligopcaxis — alias: pxpeoplecode — alias: pcodephp-extrasphpdocplsqlpowerquery — alias: mscript, pqpowershellprocessingprologpromqlpropertiesprotobufpslpugpuppetpurepurebasic — alias: pbfasmpurescript — alias: pursqqmlqoreqsharp — alias: qsracket — alias: rktreasonregorenpy — alias: rpyrestriproboconfrobotframework — alias: robotsasscalaschemeshell-session — alias: sh-session, shellsessionsmalismalltalksmartysml — alias: smlnjsolidity — alias: solsolution-file — alias: slnsoysparql — alias: rqsplunk-splsqfsquirrelstanstylussystemdt4-cs — alias: t4t4-templatingt4-vbtaptcltextiletomltremor — alias: trickle, troytsxtt2turtle — alias: trigtwigtyposcript — alias: tsconfigunrealscript — alias: uc, uscripturi — alias: urlvvalavelocityverilogvhdlvimvisual-basic — alias: vb, vbawarpscriptwasmweb-idl — alias: webidlwikiwolfram — alias: mathematica, nb, wlwrenxeora — alias: xeoracubexml-docxojoxqueryyangzigrefractor 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.25.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 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.
This package is safe.
lowlight
— the same as refractor but with highlight.jsreact-syntax-highlighter
— React component for syntax highlighting@mapbox/rehype-prism
— rehype plugin to highlight code
blocksreact-refractor
— syntax highlighter for ReactYes please! See How to Contribute to Open Source.
FAQs
Lightweight, robust, elegant virtual syntax highlighting using Prism
The npm package refractor receives a total of 2,238,014 weekly downloads. As such, refractor popularity was classified as popular.
We found that refractor demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.