rolldown-plugin-react-forward-ref weekly downloads statistics

rolldown-plugin-react-forward-ref

Run selected React 19-style function components on React 18. The plugin adds forwardRef wrappers at module initialization and passes the received ref to the original function as a prop. It supports indirect forwarding:

The ref reaches splitProps before the function reads props. There is no extra React element around the original function, and wrappers keep their identity across renders. This package adapts ref transport only. It does not polyfill other React 19 features.

Install it as a development dependency:

API and file selection

include is required and must be a non-empty glob, regular expression, or array of those patterns. exclude accepts the same forms and takes priority. Globs use @rollup/pluginutils and resolve relative to process.cwd(). Paths use forward slashes on all platforms. There are no project-specific path defaults.

Only .js, .jsx, .ts, .tsx, .mjs, .mts, .cjs, .cts, are eligible. Declaration files, virtual modules, node_modules, and Vite ?raw/?url requests are always excluded. JSX in JavaScript files is parsed; the host must also be configured to lower JSX for the selected extension. Other query suffixes are removed before matching. Input must be an ES module; the plugin does not convert CommonJS module exports.

There is one default export for Rolldown, Vite, and Vitest. The plugin uses a transform hook, with order: "pre" and Vite's enforce: "pre". It runs before TypeScript/JSX lowering, in both development and builds. Put it before other plugins with pre-transform hooks, including @vitejs/plugin-react. Already lowered JSX cannot be detected.

Version selection belongs to the consumer configuration. The plugin does not read a React version or enable itself automatically.

Rolldown

Vite

React 18-only Vitest configuration

Read the version from the test workspace's dependency graph. An isolated React 18 workspace must install matching React and React DOM versions.

For projects that alias React, use an explicit target flag instead if the configuration's react import does not resolve to the test runtime. Disable the plugin for React 19 to retain its native behavior. The test suite also checks adapted output on React 19, with the no-ref semantics below.

Component selection

Within each selected file, the plugin selects top-level function declarations and const function initializers with an ASCII uppercase first letter and JSX in their own function body. A default-exported function can have any name or be anonymous, except names with the hook prefix use followed by an uppercase letter or digit. JSX in nested functions or classes does not count. A visible ref read is not required. Hooks and ordinary lowercase utilities stay unchanged.

This is a syntax rule, not proof that a function is a React component. Limit the file filters to component source. A PascalCase utility with JSX that otherwise meets the rule is indistinguishable from a component. Functions used as direct calls, constructors, .call/.apply/.bind targets, or arguments to opaque functions are conservatively left unchanged. This also protects render functions passed to existing forwardRef calls or custom HOCs. Local identifier aliases are followed; this conservative check can also skip a same-named binding in another scope.

| Source form | Behavior |

| function Button(props) { return } | Wrap the hoisted binding before module statements run. | | Named exports, export { Button as Input }, and export default Button | Keep the export names and shared component identity. | | export default function Button(props) { ... } | Keep its local binding and live default export. | | Anonymous default function or arrow | Wrap the expression once, with display name default. | | const Button = props => | Wrap the initializer once. | | Anonymous or named function expression | Wrap it unless its private function name is referenced in its body. | | Destructured, defaulted, optional, or generic props | Call the original function with the merged props, before parameter initialization. | | const Alias = Button | Share the wrapper. Aliases do not select lowercase or imported functions. | | memo(Button) | Keep memo outside the selected component wrapper. | | const Button = memo(props => ) | Wrap the inner function, preserving the comparator argument. | | forwardRef(...) | Leave it and its render input unchanged. | | Opaque HOCs and component factories | Leave inline/returned functions and their identifier inputs unchanged. | | Class, nested, async, generator, let/var functions | Leave unchanged. | | Functions with multiple parameters, rest parameters, or array destructuring | Leave unchanged. | | Components without JSX, including createElement-only bodies | Leave unchanged. |

memo, forwardRef, and createElement are recognized through React named, default, or namespace imports and module-level method aliases such as const cache = React.memo. Destructured aliases and namespace aliases are not resolved. Literal computed access, such as React["memo"], is supported. Dynamic API lookups, re-exports from other modules, and component registries are not resolved. Imported components must be adapted in their own source module. React.createElement references to a selected local component are supported.

Trusted element factories

Use elementFactories when a helper creates, clones, returns, or omits React elements without calling the supplied component directly. The option permits ref adaptation for that helper's component argument. It does not select files or components that would otherwise be ineligible.

Each import descriptor has these fields:

| Field | Meaning |

| source | Exact import source string in the selected file. No path or package resolution is performed. | | imported | Named export, or "default" for a default import. Local import renames are supported. | | argumentIndex | Zero-based component argument position. Defaults to 0; must be a non-negative safe integer. |…

Description from the npm listing.