{"id":25396,"library":"esbuild-plugin-react18","title":"esbuild-plugin-react18","description":"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.","status":"active","version":"0.2.6","language":"javascript","source_language":"en","source_url":"https://github.com/react18-tools/esbuild-plugin-react18","tags":["javascript","React Server Components","ESBuild","Plugin","Libraries","React18","React19","Server-side rendering","Frontend development","typescript"],"install":[{"cmd":"npm install esbuild-plugin-react18","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-react18","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-react18","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React 18/19; required for JSX runtime and server component directives","package":"react","optional":true},{"reason":"Peer dependency for TypeScript type definitions","package":"@types/react","optional":true}],"imports":[{"note":"Default export; named import will give undefined.","wrong":"import { esbuildPluginReact18 } from 'esbuild-plugin-react18'","symbol":"default","correct":"import esbuildPluginReact18 from 'esbuild-plugin-react18'"},{"note":"Default export is the plugin function. CommonJS: const plugin = require('esbuild-plugin-react18').default","wrong":"const { plugin } = require('esbuild-plugin-react18')","symbol":"plugin","correct":"import plugin from 'esbuild-plugin-react18'"},{"note":"TypeScript type export for configuration options.","wrong":"import { PluginOptions } from 'esbuild-plugin-react18' (not a value)","symbol":"PluginOptions","correct":"import type { PluginOptions } from 'esbuild-plugin-react18'"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport plugin from 'esbuild-plugin-react18';\n\nawait esbuild.build({\n  entryPoints: ['src/index.tsx'],\n  bundle: true,\n  outdir: 'dist',\n  plugins: [\n    plugin({\n      // automatically add 'use client' directive to files with client components\n      useClient: true,\n      // remove data-testid attributes from production builds\n      removeDataTestId: true,\n      // ignore test files (e.g., *.test.tsx, *.spec.tsx)\n      ignoreTestFiles: true,\n      // custom patterns to replace in the output\n      replacePatterns: [\n        { from: /__VERSION__/g, to: '1.0.0' }\n      ]\n    })\n  ]\n});","lang":"typescript","description":"Shows basic configuration of the plugin with esbuild, including 'use client' directive injection, test file exclusion, and custom text replacement patterns."},"warnings":[{"fix":"tsup({ esbuildPlugins: [plugin()] })","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Change `import { plugin } from 'esbuild-plugin-react18'` to `import plugin from 'esbuild-plugin-react18'`.","message":"Before v0.2.0, the plugin exported a 'plugin' named export. In v0.2.0, it switched to default export only. Named import breaks.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Ensure your source code uses standard JSX; for advanced JSX transforms, consider using Babel outside esbuild.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Add 'use client' manually in barrel files or use the 'replacePatterns' option to inject it.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install react as a peer dependency and add `external: ['react', 'react-dom']` to esbuild build options.","cause":"React is not installed or not marked as external in esbuild config when bundling a library.","error":"Error: [esbuild] Transform failed with 1 error:\nerror: Could not resolve \"react\""},{"fix":"Change to default import: `import plugin from 'esbuild-plugin-react18'`.","cause":"Using the plugin as a named import instead of default import after v0.2.0.","error":"TS2345: Argument of type 'typeof import(\"...\")' is not assignable to parameter of type 'Plugin'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}