Registry / web-framework / esbuild-plugin-react18

esbuild-plugin-react18

library0.2.6jsnpmunverified

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.

web-framework ai-ml

npm install esbuild-plugin-react18

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-REA

esbuild-plugin-react18

web-frameworkjavascriptv0.2.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

default

✓ import esbuildPluginReact18 from 'esbuild-plugin-react18'

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

Default export; named import will give undefined.

plugin

✓ import plugin from 'esbuild-plugin-react18'

✗ const { plugin } = require('esbuild-plugin-react18')

Default export is the plugin function. CommonJS: const plugin = require('esbuild-plugin-react18').default

PluginOptions

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

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

TypeScript type export for configuration options.

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' } ] }) ] });

Debug

Known issues

gotchaWhen 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()] })

affects: >=0.0.0

breakingBefore 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'`.

affects: >=0.2.0

gotchaThe 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.

affects: >=0.0.0

gotchaThe '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.

affects: >=0.0.0

Errors

Common errors & fixes

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

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.

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

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'`.

Upgrade

Version history

0.2.6latest on npm

Audit

Dependencies

reactoptionalPeer dependency for React 18/19; required for JSX runtime and server component directives

@types/reactoptionalPeer dependency for TypeScript type definitions

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/react18-tools/esbuild-plugin-react18 ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-react18 ↗