rehype-react

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/rehype-react/index.js from ... not supported.

  cause Attempting to import rehype-react using `require()` in a CommonJS module, but rehype-react is an ESM-only package.
  fix Change `const rehypeReact = require('rehype-react')` to `import rehypeReact from 'rehype-react'` and ensure your project is configured for ESM (e.g., by adding `"type": "module"` to `package.json`).

• TypeError: Cannot read properties of undefined (reading 'Fragment')

  cause This error typically occurs in v8.0.0 when passing individual `Fragment` and `createElement` imports to `rehypeReact` options, which is no longer supported.
  fix Instead of `{Fragment, createElement}`, pass an object containing the JSX runtime functions, usually imported as `import * as production from 'react/jsx-runtime'` and then `.use(rehypeReact, production)`.

• TypeError: `fixTableCellAlign` is not a valid option

  cause Using the deprecated option name `fixTableCellAlign` with rehype-react v8.0.0 or later.
  fix Rename the option `fixTableCellAlign` to `tableCellAlignToStyle` in your plugin configuration.

• ReferenceError: process is not defined

  cause Attempting to run a Node.js specific global (`process`) in a browser environment without proper polyfills or environment setup (e.g., Vite/Webpack configurations for browser).
  fix Ensure your build tools correctly polyfill Node.js globals for browser contexts, or conditionally access `process.version` only in Node.js environments. For example, use `typeof process !== 'undefined' ? process.version : 'browser'`.

Warnings

• breaking rehype-react v8.0.0 and later requires Node.js version 16 or higher. Older Node.js versions are not supported.
  Fix: Upgrade your Node.js environment to version 16 or newer. Use `nvm install 16` or `nvm use 16` if you use nvm.
• breaking rehype-react v7.0.0 and later is an ESM-only package. Attempting to `require()` it in a CommonJS module will result in a runtime error.
  Fix: Migrate your project to use ESM (`import` statements) or ensure that your build system correctly transpiles ESM for CommonJS consumption. For Node.js, add `"type": "module"` to your `package.json`.
• breaking The `rehypeReact` plugin options for specifying `Fragment` and `createElement` have changed in v8.0.0. Instead of passing individual components, you must now pass an object containing the JSX runtime functions (e.g., `Fragment`, `jsx`, `jsxs`) from `react/jsx-runtime`.
  Fix: Change your `rehypeReact` usage from `.use(rehypeReact, {Fragment, createElement})` to `.use(rehypeReact, {Fragment: prod.Fragment, jsx: prod.jsx, jsxs: prod.jsxs})` after importing `import * as prod from 'react/jsx-runtime'`.
• breaking The option `fixTableCellAlign` was renamed to `tableCellAlignToStyle` in v8.0.0.
  Fix: Update your plugin options from `fixTableCellAlign: true` to `tableCellAlignToStyle: true`.
• breaking The types for rehype-react were significantly improved in v7.0.0. While this is generally beneficial, it could introduce breaking changes if your TypeScript code was relying on previously looser typings or internal structures.
  Fix: Review your TypeScript code for type errors after upgrading and adjust types or cast as necessary, especially around the `file.result` type or custom component props.

Install

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

Imports

• rehypeReact
  wrong:

  const rehypeReact = require('rehype-react')

  correct:

  import rehypeReact from 'rehype-react'

  rehype-react is an ESM-only package since v7.0.0. CommonJS `require` statements will fail.
• production (JSX runtime object)
  wrong:

  import {Fragment, createElement} from 'react'

  correct:

  import * as production from 'react/jsx-runtime'

  Since v8.0.0, rehype-react expects a JSX runtime object (e.g., from `react/jsx-runtime` or equivalent) as its second argument, replacing the explicit `Fragment` and `createElement` imports used in previous versions.
• unified
  wrong:

  import unified from 'unified'

  correct:

  import { unified } from 'unified'

  The `unified` function is a named export from the `unified` package, not a default export.

Quickstart

This quickstart demonstrates how to use `rehype-react` within a React component to transform an HTML string into a React element tree, supporting multiple JSX runtimes since v8.0.0.

import { Fragment, createElement, useEffect, useState } from 'react';
import * as prod from 'react/jsx-runtime';
import rehypeParse from 'rehype-parse';
import rehypeReact from 'rehype-react';
import { unified } from 'unified';

// To run this example:
// npm install react react-dom rehype-parse rehype-react unified

// @ts-expect-error: The react types might be missing for `prod` object
const production = { Fragment: prod.Fragment, jsx: prod.jsx, jsxs: prod.jsxs };

const htmlContent = `<h2>Hello, world from rehype-react!</h2>\n<p>This paragraph contains <em>emphasized</em> text and a <a href="#">link</a>.</p>\n<p>Current Node.js version is ${process.version}.</p>`;

/**
 * A React hook to process HTML content using rehype-react.
 * @param {string} text The HTML string to process.
 * @returns {JSX.Element} A React component tree.
 */
function useHtmlProcessor(text) {
  const [Content, setContent] = useState(createElement(Fragment));

  useEffect(
    function () {
      (async function () {
        const file = await unified()
          .use(rehypeParse, { fragment: true })
          .use(rehypeReact, production)
          .process(text);

        setContent(file.result);
      })();
    },
    [text]
  );

  return Content;
}

export default function App() {
  return useHtmlProcessor(htmlContent);
}

// In a typical React app, you would render <App /> using ReactDOM.createRoot:
// import ReactDOM from 'react-dom/client';
// const root = ReactDOM.createRoot(document.getElementById('root'));
// root.render(<App />);