@octanejs/rsbuild-plugin 0.1.0 → 0.1.4

package/README.md

@@ -70,17 +70,20 @@ and browser targets cannot be mixed in the same array.
 Options are declarative and cache-stable:
 
 - `hmr` controls browser component handoff;
-- `parallelUse` controls the compiler's parallel `use()` transform;
+- `profile` enables component profiling in the browser environment;
 - `exclude` skips path fragments in the plain `.ts`/`.js` hook-slot pass; and
 - `clientEnvironment` / `serverEnvironment` rename the generated environments.
 
 App mode currently serves from the root path and uses Rsbuild's default asset
 prefix. Keep `server.base` at `/` and `output.assetPrefix` at `auto` or `/`; for
 a subpath deployment, rewrite that prefix to the app root in the hosting proxy.
-Changing routes or server-render settings in `octane.config.ts` triggers a full
-browser reload within an already enabled app. Changing `build.target`,
-`build.outDir`, `build.minify`, or adding the first route reshapes Rsbuild
-environments and requires a dev-server restart.
-
-The package follows the Rsbuild plugin model consumed by Rspeedy, but this
-release targets Octane's DOM renderer. Lynx renderer selection is future work.
+When `octane.config.ts` or one of its imported helpers changes, `rsbuild dev`
+restarts the dev server and applies the complete config atomically. This is
+required for `compiler.renderers`, because renderer selection is part of each
+Rspack compiler's cache and loader identity. Source-module edits continue to
+use the normal HMR or browser-reload path.
+
+The package forwards normalized `compiler.renderers` registry, filename-rule,
+and renderer-boundary metadata through the same Rspack compiler path used by
+Vite and direct compilation. This enables the experimental universal client
+target; a concrete Lynx runtime and cross-thread transport remain future work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/rsbuild-plugin",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -48,19 +48,20 @@
     }
   },
   "dependencies": {
-    "@octanejs/app-core": "0.0.1",
-    "@octanejs/rspack-plugin": "0.1.0"
+    "@octanejs/app-core": "0.0.5",
+    "@octanejs/rspack-plugin": "0.1.4"
   },
   "peerDependencies": {
     "@rsbuild/core": "^2.0.0",
-    "octane": "0.1.5"
+    "octane": "0.1.9"
   },
   "devDependencies": {
     "@rsbuild/core": "^2.1.5",
     "@rspack/core": "^2.1.3",
     "@types/node": "^24.3.0",
+    "playwright": "^1.61.0",
     "type-fest": "^5.6.0",
     "vitest": "^4.1.9",
-    "octane": "0.1.5"
+    "octane": "0.1.9"
   }
 }

package/src/client-assets-plugin.js

@@ -3,11 +3,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { rspack } from '@rsbuild/core';
+import { HYDRATE_QUERY_PARAM } from 'octane/compiler/bundler';
 
 import { resolveProjectModule } from './project.js';
 
 const PLUGIN_NAME = 'OctaneClientAssetsPlugin';
 
+/** @param {unknown} request */
+function isDeferredHydrationRequest(request) {
+	if (typeof request !== 'string' || request.length === 0) return false;
+	const resource = request.slice(request.lastIndexOf('!') + 1);
+	const queryStart = resource.indexOf('?');
+	if (queryStart === -1) return false;
+	const hashStart = resource.indexOf('#', queryStart);
+	const query = resource.slice(queryStart + 1, hashStart === -1 ? undefined : hashStart);
+	return new URLSearchParams(query).has(HYDRATE_QUERY_PARAM);
+}
+
 /** @param {string} file */
 function canonicalResource(file) {
 	if (!file) return '';
@@ -76,6 +88,37 @@ function collectCss(files, chunk) {
 	}
 }
 
+/**
+ * Collect CSS from compiler-generated deferred hydration groups and every
+ * async descendant below them. Their JavaScript deliberately stays out of the
+ * route asset entry so the production server does not modulepreload it.
+ *
+ * @param {Set<string>} files
+ * @param {any} group
+ * @param {boolean} [insideDeferredHydration]
+ * @param {{ eager: Set<any>, deferred: Set<any> }} [seen]
+ */
+function collectDeferredHydrationCss(
+	files,
+	group,
+	insideDeferredHydration = false,
+	seen = { eager: new Set(), deferred: new Set() },
+) {
+	if (!group) return;
+	const deferredHydration =
+		insideDeferredHydration ||
+		[...iterable(group.origins)].some((origin) => isDeferredHydrationRequest(origin?.request));
+	const visited = deferredHydration ? seen.deferred : seen.eager;
+	if (visited.has(group)) return;
+	visited.add(group);
+	if (deferredHydration) {
+		for (const chunk of iterable(group.chunks)) collectCss(files, chunk);
+	}
+	for (const child of iterable(group.childrenIterable)) {
+		collectDeferredHydrationCss(files, child, deferredHydration, seen);
+	}
+}
+
 /** @param {any} compilation @param {string} message */
 function addCompilationError(compilation, message) {
 	const error = new Error(`[octane] ${message}`);
@@ -172,6 +215,7 @@ export class OctaneClientAssetsPlugin {
 						for (const group of routeGroups.get(id) ?? []) {
 							const chunks = [...iterable(group?.chunks)];
 							for (const chunk of chunks) collectCss(css, chunk);
+							collectDeferredHydrationCss(css, group);
 							// SplitChunks inserts shared chunks before the original async chunk,
 							// so scan from the end for the route script. Do not call
 							// getEntrypointChunk(): normal Rspack async groups are not entrypoints.

package/src/index.js

@@ -150,6 +150,7 @@ function configSignature(config) {
 		preHydrate: config.router.preHydrate,
 		rootBoundary: config.rootBoundary,
 		server: config.server,
+		compiler: { renderers: config.compiler.renderers.signature },
 	});
 }
 
@@ -226,8 +227,9 @@ function assertRootPublicPaths(config, clientEnvironment) {
  *
  * @param {{
  *   hmr?: boolean,
- *   parallelUse?: boolean,
+ *   profile?: boolean,
  *   exclude?: string[],
+ *   requireDirective?: boolean,
  *   clientEnvironment?: string,
  *   serverEnvironment?: string,
  * }} [inlineOptions]
@@ -333,8 +335,23 @@ export function pluginOctane(inlineOptions = {}) {
 			}
 
 			api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
-				if (!appEnabled) return config;
-				assertRootPublicPaths(config, clientEnvironment);
+				// Renderer selection is serialized into each Rspack compiler's loader
+				// options, so a browser reload cannot apply config changes safely. Ask
+				// Rsbuild to reconstruct the dev server (and therefore every compiler)
+				// whenever the Octane config or one of its imported helpers changes.
+				// This also covers compiler-only projects without application routes.
+				const watchedConfig = initialLoaded
+					? mergeRsbuildConfig(config, {
+							dev: {
+								watchFiles: {
+									paths: [...initialLoaded.dependencies],
+									type: 'reload-server',
+								},
+							},
+						})
+					: config;
+				if (!appEnabled) return watchedConfig;
+				assertRootPublicPaths(watchedConfig, clientEnvironment);
 				const productionBuild = isProductionBuild();
 				const octaneConfig = /** @type {import('@octanejs/app-core').ResolvedOctaneConfig} */ (
 					initialConfig
@@ -353,7 +370,7 @@ export function pluginOctane(inlineOptions = {}) {
 				const targetOutput = buildTargetPlan?.browserslist
 					? { overrideBrowserslist: buildTargetPlan.browserslist }
 					: {};
-				return mergeRsbuildConfig(config, {
+				return mergeRsbuildConfig(watchedConfig, {
 					server: { htmlFallback: false, historyApiFallback: false },
 					environments: {
 						[clientEnvironment]: {
@@ -395,6 +412,23 @@ export function pluginOctane(inlineOptions = {}) {
 				});
 			});
 
+			api.modifyEnvironmentConfig((config, { mergeEnvironmentConfig }) => {
+				// Octane and several framework bindings use this conventional guard for
+				// diagnostics and production-only branches. Rsbuild does not define it
+				// when a programmatic build inherits mode "none", so scope the define to
+				// browser environments where the Node `process` global is unavailable.
+				if (config.output.target === 'node') return config;
+				return mergeEnvironmentConfig(config, {
+					source: {
+						define: {
+							'process.env.NODE_ENV': JSON.stringify(
+								isProductionBuild() ? 'production' : 'development',
+							),
+						},
+					},
+				});
+			});
+
 			if (appEnabled) {
 				api.transform(
 					{
@@ -481,10 +515,14 @@ export function pluginOctane(inlineOptions = {}) {
 						environment,
 						transpile: false,
 						...(inlineOptions.hmr === undefined ? null : { hmr: inlineOptions.hmr }),
-						...(inlineOptions.parallelUse === undefined
+						...(inlineOptions.profile === undefined
 							? null
-							: { parallelUse: inlineOptions.parallelUse }),
+							: { profile: environment === 'client' && inlineOptions.profile }),
 						...(inlineOptions.exclude === undefined ? null : { exclude: inlineOptions.exclude }),
+						...(inlineOptions.requireDirective === undefined
+							? null
+							: { requireDirective: inlineOptions.requireDirective }),
+						renderers: initialConfig?.compiler.renderers,
 					}),
 				);
 				config.resolve ??= {};

package/types/index.d.ts

@@ -11,10 +11,23 @@ export {
 export interface OctaneRsbuildPluginOptions {
 	/** Override component HMR in the browser environment. */
 	hmr?: boolean;
-	/** Disable the compiler's parallel `use()` transform. */
-	parallelUse?: boolean;
-	/** Ad-hoc path fragments skipped by the plain TypeScript/JavaScript hook-slot pass. */
+	/** Enable component profiling in the browser environment. */
+	profile?: boolean;
+	/**
+	 * Ad-hoc path fragments skipped by the plain TypeScript/JavaScript
+	 * hook-slot pass. With `requireDirective`, excluded paths are exempt from
+	 * Octane ownership entirely — including `.tsrx`/`.tsx` — for projects
+	 * routing those paths through a different tsrx compiler (e.g.
+	 * `@tsrx/react`).
+	 */
 	exclude?: string[];
+	/**
+	 * Mixed-toolchain ownership gate: compile only project modules declaring
+	 * `'use octane'`; undirected project `.tsx`/`.ts` pass through to the host
+	 * framework's own pipeline. See `@octanejs/rspack-plugin` for details.
+	 * @default false
+	 */
+	requireDirective?: boolean;
 	/** Rsbuild environment name used for the browser bundle. @default 'web' */
 	clientEnvironment?: string;
 	/** Rsbuild environment name used for the Node SSR bundle. @default 'node' */