@acusti/vite-plugin-react-compiler 0.0.0

package/README.md

@@ -0,0 +1,146 @@
+# @acusti/vite-plugin-react-compiler
+
+[![latest version](https://img.shields.io/npm/v/@acusti/vite-plugin-react-compiler?style=for-the-badge)](https://www.npmjs.com/package/@acusti/vite-plugin-react-compiler)
+[![maintenance status](https://img.shields.io/npms-io/maintenance-score/@acusti/vite-plugin-react-compiler?style=for-the-badge)](https://npms.io/search?q=%40acusti%2Fvite-plugin-react-compiler)
+[![downloads per month](https://img.shields.io/npm/dm/@acusti/vite-plugin-react-compiler?style=for-the-badge)](https://www.npmjs.com/package/@acusti/vite-plugin-react-compiler)
+
+A [Vite][] plugin that runs [React Compiler][] via [oxc-transform-react][],
+the native Node bindings for the oxc project’s Rust port of the compiler —
+a drop-in alternative to the Babel-based React Compiler build path.
+
+It was extracted from the build tooling of [Outlyne][], where it runs in
+production.
+
+[vite]: https://vite.dev
+[react compiler]: https://react.dev/learn/react-compiler
+[oxc-transform-react]: https://www.npmjs.com/package/oxc-transform-react
+[outlyne]: https://outlyne.io
+
+## Why this exists
+
+Vite/Rolldown decided against shipping the Rust React Compiler integration
+in Vite core over the binary size it would add, so the official React
+Compiler path for Vite remains Babel: @vitejs/plugin-react’s
+`reactCompilerPreset` running babel-plugin-react-compiler via
+[@rolldown/plugin-babel][]. That works, but it drags a full Babel
+parse/transform/print pipeline through every source file of an otherwise
+all-native oxc/rolldown build.
+
+This plugin is the published native alternative: a `transform`-hook plugin
+that calls [oxc-transform-react][], the Rust React Compiler bindings the
+oxc project publishes. The compiler pass runs with `enforce: 'pre'` (the
+same position the Babel pass occupies today) and emits JSX untouched
+(`jsx: 'preserve'`), so Vite’s own oxc transform stays in charge of
+JSX/refresh/TypeScript handling downstream — the plugin only adds the
+compiler pass. (oxc-transform-react does strip TypeScript syntax, which
+matches how the Babel path uses @babel/preset-typescript.)
+
+[@rolldown/plugin-babel]:
+    https://www.npmjs.com/package/@rolldown/plugin-babel
+
+## Usage
+
+```
+npm install --save-dev @acusti/vite-plugin-react-compiler
+# or
+yarn add --dev @acusti/vite-plugin-react-compiler
+# or
+pnpm add --save-dev @acusti/vite-plugin-react-compiler
+# or
+bun add --dev @acusti/vite-plugin-react-compiler
+```
+
+The plugin depends on an exact, tested version of [oxc-transform-react][]:
+the bindings are on a fast-moving 0.x release train tracking React Compiler
+main, and new bindings releases are close to 100% bug fixes (the Rust port
+chases parity with the existing widely-used Babel plugin), so the plugin
+pins the newest version that passes this repo’s test suite and ships it in
+regular plugin releases. If you need a different version, use your package
+manager’s `overrides` (npm, pnpm, bun) or `resolutions` (yarn) to force it.
+
+Like [@acusti/vite-plugin-svg-react][], this plugin requires Vite ≥ 8, on
+purpose: its reason for existing is completing the all-native oxc/rolldown
+pipeline that Vite 8 introduced.
+
+[@acusti/vite-plugin-svg-react]:
+    https://www.npmjs.com/package/@acusti/vite-plugin-svg-react
+
+Add the plugin to your vite config (and remove any Babel-based React
+Compiler wiring, e.g. `reactCompilerPreset` + @rolldown/plugin-babel):
+
+```ts
+// vite.config.ts
+import reactCompiler from '@acusti/vite-plugin-react-compiler';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    plugins: [react(), reactCompiler()],
+});
+```
+
+### Options
+
+The plugin takes an optional options object with four properties:
+
+- **`include`** / **`exclude`**: standard Vite
+  [`createFilter`](https://vite.dev/guide/api-plugin#filtering-include-exclude-pattern)
+  patterns selecting which modules get the compiler pass. Defaults:
+  `include: /\.[jt]sx?$/`, `exclude: /[/\\]node_modules[/\\]/`.
+- **`reactCompiler`**: options passed verbatim to React Compiler, using the
+  same names as [babel-plugin-react-compiler][compiler options]:
+  `compilationMode`, `panicThreshold` (defaults to `'none'`), `target`
+  (defaults to `'19'`), `environment` flags like
+  `enableTreatRefLikeIdentifiersAsRefs`, and so on. Callback-valued options
+  (e.g. `logger`, function-valued `sources`) don’t cross the native
+  boundary and aren’t supported; `sources` accepts an array of filename
+  substrings instead.
+- **`memoize`**: cache transform results per module id, keyed by a content
+  hash (bounded to one entry per file). Multi-environment builds (e.g.
+  React Router apps building client + SSR environments) run every transform
+  once per environment; the cache makes the repeat passes free. Defaults to
+  `true`.
+
+```ts
+reactCompiler({
+    exclude: [/node_modules/, /\.stories\./],
+    reactCompiler: {
+        environment: { enableTreatRefLikeIdentifiersAsRefs: true },
+    },
+});
+```
+
+If the compiler reports a fatal error (a parse failure or rejected
+options), the plugin fails the build via `this.error(...)`, just like a
+Babel syntax error would. Nonfatal compiler bail-outs behave as they do
+with the Babel plugin under `panicThreshold: 'none'`: the affected function
+is left uncompiled and the build continues.
+
+[compiler options]:
+    https://react.dev/reference/react-compiler/configuration
+
+## Caveats, and results from production
+
+The Rust port of React Compiler and the oxc-transform-react bindings are
+experimental and explicitly labeled as such upstream. Measure and verify
+against the Babel plugin before trusting it (the `__COMPILER_RUNTIME.c`
+memo cache calls in output are easy to diff). Alongside the plugin’s own
+tests, this repo runs an upstream-tracking suite against the pinned
+bindings version: it pins the ways the Rust port already exceeds
+babel-plugin-react-compiler@1.0.0 by tracking React Compiler main (computed
+object keys and try/catch value blocks both compile), pins Babel-parity
+fixes as they land (react-hooks lint suppressions opt functions out of
+compilation since 0.144.0), and tracks known upstream divergences as they
+arise, re-verified on every bindings bump before it ships in a plugin
+release.
+
+Verified results from the production Vite 8 + React Router app this plugin
+was extracted from, compared against babel-plugin-react-compiler@1.0.0
+across 987 source files:
+
+- **Full memoization parity with zero regressions** — every function the
+  Babel plugin compiles, the Rust port compiles. It compiles a strict
+  superset, since the Rust port tracks React Compiler main rather than the
+  latest stable release.
+- **The compiler pass is ~16x faster** than the Babel pass.
+- **The full production build is ~2.5x faster** (53s → 21s).

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { type ReactCompilerOptions } from 'oxc-transform-react';
+import { type FilterPattern, type Plugin } from 'vite';
+export type Options = {
+    /**
+     * Modules to exclude from the compiler pass (takes precedence over
+     * include).
+     * @default /[/\\]node_modules[/\\]/
+     */
+    exclude?: FilterPattern;
+    /**
+     * Modules to run the compiler pass on.
+     * @default /\.[jt]sx?$/
+     */
+    include?: FilterPattern;
+    /**
+     * Cache transform results by module id + content hash so repeated
+     * transforms of identical content (e.g. one per environment in
+     * multi-environment builds) only run the compiler once per file.
+     * @default true
+     */
+    memoize?: boolean;
+    /**
+     * Options passed verbatim to React Compiler, using the same names as
+     * babel-plugin-react-compiler (compilationMode, panicThreshold
+     * (defaults to 'none'), target (defaults to '19'), environment, etc.).
+     */
+    reactCompiler?: ReactCompilerOptions;
+};
+export default function vitePluginReactCompiler(options?: Options): Plugin;

package/dist/index.js

@@ -0,0 +1,52 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { transform } from "oxc-transform-react";
+import { createFilter } from "vite";
+//#region src/index.ts
+var defaultExclude = /[/\\]node_modules[/\\]/;
+var defaultInclude = /\.[jt]sx?$/;
+function vitePluginReactCompiler(options = {}) {
+	const filter = createFilter(options.include ?? defaultInclude, options.exclude ?? defaultExclude);
+	const isMemoizing = options.memoize !== false;
+	const cache = /* @__PURE__ */ new Map();
+	return {
+		enforce: "pre",
+		name: "vite-plugin-react-compiler",
+		transform(code, id) {
+			const [filepath] = id.split("?");
+			if (!filter(filepath)) return null;
+			const run = async () => {
+				const transformed = await transform(filepath, code, {
+					jsx: "preserve",
+					reactCompiler: options.reactCompiler ?? {},
+					sourcemap: true
+				});
+				if (transformed.fatal) {
+					const byteStart = transformed.errors[0]?.labels[0]?.start;
+					this.error(transformed.errors.map((error) => error.codeframe ? `${error.message}\n${error.codeframe}` : error.message).join("\n"), byteStart == null ? void 0 : Buffer.from(code, "utf8").subarray(0, byteStart).toString("utf8").length);
+				}
+				return {
+					code: transformed.code,
+					map: transformed.map
+				};
+			};
+			if (!isMemoizing) return run();
+			const hash = createHash("sha1").update(code).digest("hex");
+			const cached = cache.get(filepath);
+			if (cached?.hash === hash) return cached.result;
+			const result = run();
+			cache.set(filepath, {
+				hash,
+				result
+			});
+			result.catch(() => {
+				if (cache.get(filepath)?.result === result) cache.delete(filepath);
+			});
+			return result;
+		}
+	};
+}
+//#endregion
+export { vitePluginReactCompiler as default };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { Buffer } from 'node:buffer';\nimport { createHash } from 'node:crypto';\n\nimport {\n    type ReactCompilerOptions,\n    type SourceMap,\n    transform,\n} from 'oxc-transform-react';\nimport { createFilter, type FilterPattern, type Plugin } from 'vite';\n\nexport type Options = {\n    /**\n     * Modules to exclude from the compiler pass (takes precedence over\n     * include).\n     * @default /[/\\\\]node_modules[/\\\\]/\n     */\n    exclude?: FilterPattern;\n    /**\n     * Modules to run the compiler pass on.\n     * @default /\\.[jt]sx?$/\n     */\n    include?: FilterPattern;\n    /**\n     * Cache transform results by module id + content hash so repeated\n     * transforms of identical content (e.g. one per environment in\n     * multi-environment builds) only run the compiler once per file.\n     * @default true\n     */\n    memoize?: boolean;\n    /**\n     * Options passed verbatim to React Compiler, using the same names as\n     * babel-plugin-react-compiler (compilationMode, panicThreshold\n     * (defaults to 'none'), target (defaults to '19'), environment, etc.).\n     */\n    reactCompiler?: ReactCompilerOptions;\n};\n\ntype CachedTransform = {\n    hash: string;\n    result: Promise<TransformOutput>;\n};\n\ntype TransformOutput = { code: string; map?: SourceMap };\n\nconst defaultExclude = /[/\\\\]node_modules[/\\\\]/;\nconst defaultInclude = /\\.[jt]sx?$/;\n\nexport default function vitePluginReactCompiler(options: Options = {}): Plugin {\n    const filter = createFilter(\n        options.include ?? defaultInclude,\n        options.exclude ?? defaultExclude,\n    );\n    const isMemoizing = options.memoize !== false;\n    // one entry per module id, replaced whenever the content hash changes;\n    // holds the promise so overlapping transforms of identical content\n    // (e.g. concurrent client + SSR environments) share a single run\n    const cache = new Map<string, CachedTransform>();\n\n    return {\n        enforce: 'pre',\n        name: 'vite-plugin-react-compiler',\n        transform(code, id) {\n            // vite module ids can carry a query suffix (e.g. sub-request\n            // queries from other plugins); filter, cache, and compile by\n            // the underlying file path — like @vitejs/plugin-react — so\n            // the cache stays one-entry-per-file and sourcemap sources\n            // don’t include vite queries\n            const [filepath] = id.split('?');\n            if (!filter(filepath)) return null;\n\n            const run = async (): Promise<TransformOutput> => {\n                const transformed = await transform(filepath, code, {\n                    // leave JSX for vite’s own pipeline (refresh, dev runtime)\n                    jsx: 'preserve',\n                    reactCompiler: options.reactCompiler ?? {},\n                    sourcemap: true,\n                });\n\n                // fatal means a parse failure or rejected options: no code\n                // was emitted, so break the build like a Babel syntax error\n                // would, forwarding the first error’s position so vite can\n                // report the location alongside oxc’s own code frames\n                if (transformed.fatal) {\n                    // oxc label offsets are utf-8 byte offsets, but rollup’s\n                    // pos argument indexes the (utf-16) code string\n                    const byteStart = transformed.errors[0]?.labels[0]?.start;\n                    this.error(\n                        transformed.errors\n                            .map((error) =>\n                                error.codeframe\n                                    ? `${error.message}\\n${error.codeframe}`\n                                    : error.message,\n                            )\n                            .join('\\n'),\n                        byteStart == null\n                            ? undefined\n                            : Buffer.from(code, 'utf8')\n                                  .subarray(0, byteStart)\n                                  .toString('utf8').length,\n                    );\n                }\n\n                return { code: transformed.code, map: transformed.map };\n            };\n\n            if (!isMemoizing) return run();\n\n            const hash = createHash('sha1').update(code).digest('hex');\n            const cached = cache.get(filepath);\n            if (cached?.hash === hash) return cached.result;\n\n            const result = run();\n            cache.set(filepath, { hash, result });\n            // drop failed transforms so the next request retries them\n            result.catch(() => {\n                if (cache.get(filepath)?.result === result) cache.delete(filepath);\n            });\n            return result;\n        },\n    };\n}\n"],"mappings":";;;;;AA4CA,IAAM,iBAAiB;AACvB,IAAM,iBAAiB;AAEvB,SAAwB,wBAAwB,UAAmB,CAAC,GAAW;CAC3E,MAAM,SAAS,aACX,QAAQ,WAAW,gBACnB,QAAQ,WAAW,cACvB;CACA,MAAM,cAAc,QAAQ,YAAY;CAIxC,MAAM,wBAAQ,IAAI,IAA6B;CAE/C,OAAO;EACH,SAAS;EACT,MAAM;EACN,UAAU,MAAM,IAAI;GAMhB,MAAM,CAAC,YAAY,GAAG,MAAM,GAAG;GAC/B,IAAI,CAAC,OAAO,QAAQ,GAAG,OAAO;GAE9B,MAAM,MAAM,YAAsC;IAC9C,MAAM,cAAc,MAAM,UAAU,UAAU,MAAM;KAEhD,KAAK;KACL,eAAe,QAAQ,iBAAiB,CAAC;KACzC,WAAW;IACf,CAAC;IAMD,IAAI,YAAY,OAAO;KAGnB,MAAM,YAAY,YAAY,OAAO,EAAE,EAAE,OAAO,EAAE,EAAE;KACpD,KAAK,MACD,YAAY,OACP,KAAK,UACF,MAAM,YACA,GAAG,MAAM,QAAQ,IAAI,MAAM,cAC3B,MAAM,OAChB,CAAC,CACA,KAAK,IAAI,GACd,aAAa,OACP,KAAA,IACA,OAAO,KAAK,MAAM,MAAM,CAAC,CACpB,SAAS,GAAG,SAAS,CAAC,CACtB,SAAS,MAAM,CAAC,CAAC,MAChC;IACJ;IAEA,OAAO;KAAE,MAAM,YAAY;KAAM,KAAK,YAAY;IAAI;GAC1D;GAEA,IAAI,CAAC,aAAa,OAAO,IAAI;GAE7B,MAAM,OAAO,WAAW,MAAM,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK;GACzD,MAAM,SAAS,MAAM,IAAI,QAAQ;GACjC,IAAI,QAAQ,SAAS,MAAM,OAAO,OAAO;GAEzC,MAAM,SAAS,IAAI;GACnB,MAAM,IAAI,UAAU;IAAE;IAAM;GAAO,CAAC;GAEpC,OAAO,YAAY;IACf,IAAI,MAAM,IAAI,QAAQ,CAAC,EAAE,WAAW,QAAQ,MAAM,OAAO,QAAQ;GACrE,CAAC;GACD,OAAO;EACX;CACJ;AACJ"}

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@acusti/vite-plugin-react-compiler",
+    "version": "0.0.0",
+    "description": "Vite plugin that runs React Compiler via oxc-transform-react, the native Rust port’s Node bindings, instead of Babel",
+    "keywords": [
+        "memoization",
+        "oxc",
+        "react",
+        "react-compiler",
+        "rolldown",
+        "rust",
+        "ts",
+        "typescript",
+        "vite",
+        "vite-plugin"
+    ],
+    "homepage": "https://github.com/acusti/uikit/tree/main/packages/vite-plugin-react-compiler#readme",
+    "bugs": {
+        "url": "https://github.com/acusti/uikit/issues"
+    },
+    "license": "Unlicense",
+    "author": "andrew patton <andrew@acusti.ca> (https://www.acusti.ca)",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/acusti/uikit.git",
+        "directory": "packages/vite-plugin-react-compiler"
+    },
+    "files": [
+        "dist"
+    ],
+    "type": "module",
+    "sideEffects": false,
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": "./dist/index.js"
+    },
+    "scripts": {
+        "test": "vitest",
+        "build": "vite build && tsc -p tsconfig.build.json",
+        "tsc": "tsc --noEmit"
+    },
+    "dependencies": {
+        "oxc-transform-react": "0.144.0"
+    },
+    "devDependencies": {
+        "@types/node": "^26.1.0",
+        "typescript": "^7",
+        "vite": "^8",
+        "vitest": "^4"
+    },
+    "peerDependencies": {
+        "vite": ">=8.0.0"
+    }
+}