esbuild-plugin-react18

0.2.6 verified Fri May 01 auth: no javascript

An esbuild plugin (v0.2.6) that enables library authors to build React components compatible with React 18 Server Components (RSC), including automatic 'use client' directive injection, test file exclusion, data-testid removal, and custom ignore/replace patterns. Supports both ESM and CJS output, full TypeScript types, and works with tsup or esbuild. Actively maintained with frequent releases. Differentiators: specifically targets RSC library development, not just client-side builds; handles JSX runtime deduplication and CSS variable renaming; provides a GitHub template for quick setup.

Common errors

error Error: [esbuild] Transform failed with 1 error: error: Could not resolve "react" ↓

cause React is not installed or not marked as external in esbuild config when bundling a library.

fix

Install react as a peer dependency and add external: ['react', 'react-dom'] to esbuild build options.

error TS2345: Argument of type 'typeof import("...")' is not assignable to parameter of type 'Plugin'. ↓

cause Using the plugin as a named import instead of default import after v0.2.0.

fix

Change to default import: import plugin from 'esbuild-plugin-react18'.

Warnings

gotcha When using with tsup, the plugin must be passed as part of the esbuildPlugins array, not directly. tsup internally calls esbuild and passes the plugin. ↓

fix tsup({ esbuildPlugins: [plugin()] })

breaking Before v0.2.0, the plugin exported a 'plugin' named export. In v0.2.0, it switched to default export only. Named import breaks. ↓

fix Change `import { plugin } from 'esbuild-plugin-react18'` to `import plugin from 'esbuild-plugin-react18'`.

gotcha The plugin does not handle Babel transforms; it only processes JavaScript/TypeScript with esbuild's built-in JSX transform. If you need custom Babel plugins, use a different build pipeline. ↓

fix Ensure your source code uses standard JSX; for advanced JSX transforms, consider using Babel outside esbuild.

gotcha The 'useClient' option only adds the 'use client' directive to files that contain React client components. Files without client components are left untouched. This may cause missing directives if your client component is re-exported through a barrel file. ↓

fix Add 'use client' manually in barrel files or use the 'replacePatterns' option to inject it.

Install

npm install esbuild-plugin-react18

yarn add esbuild-plugin-react18

pnpm add esbuild-plugin-react18

Imports

default

wrong

import { esbuildPluginReact18 } from 'esbuild-plugin-react18'

correct

import esbuildPluginReact18 from 'esbuild-plugin-react18'

Default export; named import will give undefined.

plugin
wrong
```
const { plugin } = require('esbuild-plugin-react18')
```
correct
```
import plugin from 'esbuild-plugin-react18'
```
Default export is the plugin function. CommonJS: const plugin = require('esbuild-plugin-react18').default

PluginOptions

wrong

import { PluginOptions } from 'esbuild-plugin-react18' (not a value)

correct

import type { PluginOptions } from 'esbuild-plugin-react18'

TypeScript type export for configuration options.

Quickstart

Shows basic configuration of the plugin with esbuild, including 'use client' directive injection, test file exclusion, and custom text replacement patterns.

import esbuild from 'esbuild';
import plugin from 'esbuild-plugin-react18';

await esbuild.build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    plugin({
      // automatically add 'use client' directive to files with client components
      useClient: true,
      // remove data-testid attributes from production builds
      removeDataTestId: true,
      // ignore test files (e.g., *.test.tsx, *.spec.tsx)
      ignoreTestFiles: true,
      // custom patterns to replace in the output
      replacePatterns: [
        { from: /__VERSION__/g, to: '1.0.0' }
      ]
    })
  ]
});