Registry / web-framework / react-refractor

react-refractor

JSON →
library4.0.0jsnpmunverified

react-refractor is a lightweight React component for syntax highlighting code snippets, acting as a thin wrapper around the `refractor` library. `refractor` itself is a virtual DOM implementation of `Prism.js`, allowing for efficient updates and server-side rendering without direct DOM manipulation. The current stable version is v4.0.0, which dropped Node.js 18 support and upgraded to `refractor` v5. The library maintains a moderately active release cadence, with several minor and major versions released within the last year. A key differentiator is its VDOM-based approach, which makes it performant and flexible for React environments but also means it's incompatible with `Prism.js` plugins. Developers must explicitly import and register specific language syntaxes from `refractor` to keep bundle sizes small, and styling is left to the developer, often by importing `Prism.js` themes. It requires React 18+ and is ESM-only since v3.0.0.

npm install react-refractor
INSTALL
IMPORT
SIG · REACT-REFRACTOR
R
react-refractor
web-frameworkjavascriptv4.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Refractor
import { Refractor } from 'react-refractor'
import Refractor from 'react-refractor'
Since v3.0.0, react-refractor is ESM-only and uses named exports. Default imports will not work.
registerLanguage
import { registerLanguage } from 'react-refractor'
const { registerLanguage } = require('react-refractor')
Required to register specific language grammars imported from the underlying 'refractor' package.
Language modules (e.g., javascript)
import js from 'refractor/lang/javascript'
import { javascript } from 'refractor'
Language grammars are imported directly from the `refractor/lang/` path, not from `react-refractor` itself, and are typically default exports from those specific files.

This quickstart demonstrates how to install `react-refractor`, register multiple language syntaxes (JavaScript, PHP, CSS) from `refractor`, and render code snippets using the `Refractor` component. It highlights the explicit language registration process and the component's basic usage with `language` and `value` props.

import React from 'react'; import ReactDOM from 'react-dom/client'; import { Refractor, registerLanguage } from 'react-refractor'; // Import desired languages from 'refractor' and register them import js from 'refractor/lang/javascript'; import php from 'refractor/lang/php'; import css from 'refractor/lang/css'; registerLanguage(js); registerLanguage(php); registerLanguage(css); // A simple PrismJS theme can be included for basic styling // This would typically be imported from a CSS file like: import 'prismjs/themes/prism-dark.css'; // For demonstration, we'll just show the component usage. function App() { const jsCode = ` const greet = (name) => { console.log('Hello, ' + name + '!'); }; greet('World'); `; const phpCode = ` <?php $name = "PHP"; echo "Hello, " . $name . "!"; ?> `; return ( <div> <h2>JavaScript Example</h2> <Refractor language="javascript" value={jsCode} /> <h2>PHP Example</h2> <Refractor language="php" value={phpCode} /> <p>Note: Stylesheets are not automatically handled; apply your own Prism.js-compatible theme.</p> </div> ); } const root = ReactDOM.createRoot(document.getElementById('root') || document.createElement('div')); root.render(<App />);
Debug
Known issues
breakingVersion 4.0.0 drops support for Node.js versions 18 and below, requiring Node.js 20 or higher. It also upgrades the underlying `refractor` dependency to v5.0.0.
fix
Upgrade Node.js environment to version 20 or higher. Ensure `refractor` v5 is compatible with your project if you're directly interacting with it.
affects: >=4.0.0
breakingSince v3.0.0, `react-refractor` is an ESM-only module, meaning it cannot be imported using CommonJS `require()` statements. All exports are named exports, so default imports are no longer supported.
fix
Migrate your project to use ES Modules (`import ... from '...'`) or ensure your build system correctly handles ESM. Update all imports from `import Refractor from 'react-refractor'` to `import { Refractor } from 'react-refractor'`.
affects: >=3.0.0
breakingVersion 3.0.0 and above explicitly require React 18 or higher. It also dropped ES5 compatibility, requiring an ES6-compatible environment.
fix
Upgrade your React installation to version 18 or newer. Ensure your project's build targets ES6 or newer.
affects: >=3.0.0
gotchaDue to `react-refractor`'s VDOM-based approach, which differs from `Prism.js`'s direct DOM manipulation, you cannot use existing `Prism.js` plugins. This is a fundamental architectural difference.
fix
If `Prism.js` plugin functionality is crucial, `react-refractor` might not be the right choice. Consider alternative highlighting libraries that directly integrate `Prism.js`.
affects: >=1.0.0
gotchaThe library does not provide any default styling. You are responsible for importing a compatible stylesheet, typically a Prism.js theme, to make the highlighted code visible and aesthetically pleasing.
fix
Import a Prism.js-compatible CSS theme (e.g., from `prismjs/themes`) into your project. You can also customize your own CSS to target the classes generated by `refractor`.
affects: >=1.0.0
Errors
Common errors & fixes
Error: require() of ES Module node_modules/react-refractor/index.js from ... not supported.
Attempting to import `react-refractor` using CommonJS `require()` syntax in a Node.js or older environment after v3.0.0.
fix
Refactor your imports to use ES Modules syntax: `import { Refractor } from 'react-refractor';`. Ensure your project's `package.json` has `"type": "module"` or your build system handles ESM correctly.
TypeError: (0 , react_refractor__WEBPACK_IMPORTED_MODULE_2__.Refractor) is not a function
Using a default import (`import Refractor from 'react-refractor'`) when `react-refractor` has switched to named exports since v3.0.0.
fix
Change your import statement to use named exports: `import { Refractor } from 'react-refractor';`.
Error: No language registered for "javascript" (or any other language name)
The specific language grammar (e.g., 'javascript') was not imported from `refractor/lang/` and registered with `registerLanguage()` before being used by the `Refractor` component.
fix
Import the required language module (e.g., `import js from 'refractor/lang/javascript';`) and then register it: `registerLanguage(js);`.
Upgrade
Version history
4.0.0latest on npm
Audit
Dependencies
reactrequiredCore UI library for which react-refractor is a component wrapper.
refractorrequiredThe underlying syntax highlighting engine, a VDOM implementation of Prism.js.
Agent activity
4 hits · last 30 days
node
4
Resources