React Refractor - Syntax Highlighter

Common errors

• Error: require() of ES Module node_modules/react-refractor/index.js from ... not supported.

  cause 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

  cause 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)

  cause 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);`.

Warnings

• breaking Version 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.
• breaking Since 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'`.
• breaking Version 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.
• gotcha Due 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`.
• gotcha The 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`.

Install

• npm install react-refractor npm
• yarn add react-refractor yarn
• pnpm add react-refractor pnpm

Imports

• Refractor
  wrong:

  import Refractor from 'react-refractor'

  correct:

  import { Refractor } from 'react-refractor'

  Since v3.0.0, react-refractor is ESM-only and uses named exports. Default imports will not work.
• registerLanguage
  wrong:

  const { registerLanguage } = require('react-refractor')

  correct:

  import { registerLanguage } from 'react-refractor'

  Required to register specific language grammars imported from the underlying 'refractor' package.
• Language modules (e.g., javascript)
  wrong:

  import { javascript } from 'refractor'

  correct:

  import js from 'refractor/lang/javascript'

  Language grammars are imported directly from the `refractor/lang/` path, not from `react-refractor` itself, and are typically default exports from those specific files.

Quickstart

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 />);