rollup-plugin-react-compat

0.1.1 verified Mon Apr 27 auth: no javascript

Rollup plugin to alias 'react', 'react-dom', and related modules to Preact ('preact/compat' or 'preact-compat') with configurable options like React-like compatibility flags (usePreactX, noPropTypes, etc.). Version 0.1.1 (first stable release), low release cadence. Key differentiator: provides a one-stop Rollup integration for swapping React with Preact's compat layer, supporting aliasModules for custom mappings. Alternatives like @rollup/plugin-alias require manual configuration.

Common errors

error Error: Cannot find module 'preact-compat' while using rollup-plugin-react-compat ↓

cause The plugin expects 'preact-compat' to be installed as a dependency in your project.

fix

Run 'npm install preact-compat' and ensure it's listed in your package.json.

error TypeError: reactCompat is not a function ↓

cause You imported the plugin incorrectly (e.g., using named import instead of default).

fix

Use 'import reactCompat from 'rollup-plugin-react-compat'' (default import).

error (!) Plugin rollup-plugin-react-compat: options.usePreactCompat is deprecated. Use useReactCompat instead. ↓

cause The option 'usePreactCompat' is deprecated.

fix

Change 'usePreactCompat: true' to 'useReactCompat: true' in the plugin options.

Warnings

gotcha The plugin does not install preact or preact-compat for you; you must add them as dependencies. ↓

fix npm install preact preact-compat

gotcha If you enable both usePreactX and resolvePreactCompat, the plugin may double-alias, causing unexpected behavior. ↓

fix Set only one of them to true, or ensure your configuration is mutually exclusive.

breaking When 'useReactCompat: true', the plugin aliases 'react' to 'preact/compat' and 'react-dom' to 'preact/compat'. This changes the module resolution and may break code that expects React internals. ↓

fix Ensure your codebase is compatible with Preact's compat layer.

deprecated The option 'usePreactCompat' (boolean) is deprecated in favor of 'useReactCompat' and may be removed in future versions. ↓

fix Replace 'usePreactCompat: true' with 'useReactCompat: true'.

Install

npm install rollup-plugin-react-compat

yarn add rollup-plugin-react-compat

pnpm add rollup-plugin-react-compat

Imports

default

wrong

const reactCompat = require('rollup-plugin-react-compat').default

correct

import reactCompat from 'rollup-plugin-react-compat'

CommonJS require works but no .default needed; ESM import is default.

Quickstart

Configures Rollup to alias React modules to Preact's compat layer with custom aliases.

// rollup.config.js
import reactCompat from 'rollup-plugin-react-compat';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [
    reactCompat({
      useReactCompat: true,
      usePreactX: false,
      noPropTypes: true,
      resolvePreactCompat: true,
      aliasModules: {
        'react-css-styled': 'preact-css-styled'
      }
    })
  ]
};