@octanejs/rsbuild-plugin 0.1.49 → 0.1.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/rsbuild-plugin",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -48,12 +48,12 @@
     }
   },
   "dependencies": {
-    "@octanejs/app-core": "0.0.50",
-    "@octanejs/rspack-plugin": "0.1.49"
+    "@octanejs/app-core": "0.0.52",
+    "@octanejs/rspack-plugin": "0.1.51"
   },
   "peerDependencies": {
     "@rsbuild/core": "^2.0.0",
-    "octane": "^0.1.51 || ^0.2.0"
+    "octane": "^0.3.0"
   },
   "devDependencies": {
     "@rsbuild/core": "^2.1.6",
@@ -62,6 +62,6 @@
     "@types/node": "^24.13.3",
     "playwright": "^1.61.1",
     "vitest": "^4.1.10",
-    "octane": "0.2.7"
+    "octane": "0.3.0"
   }
 }

package/src/build.js

@@ -10,6 +10,8 @@ import path from 'node:path';
  *   root: string,
  *   config: import('@octanejs/app-core').ResolvedOctaneConfig,
  *   assetMapFilename?: string,
+ *   clientBuildFilename?: string,
+ *   independentHydrationManifestFilename?: string,
  *   log?: (message: string) => void,
  * }} options
  */
@@ -19,11 +21,18 @@ export async function finalizeOctaneRsbuildOutput(options) {
 	const clientDir = path.resolve(root, outDir, 'client');
 	const serverDir = path.resolve(root, outDir, 'server');
 	const assetMapFilename = options.assetMapFilename ?? 'octane-client-assets.json';
+	const clientBuildFilename = options.clientBuildFilename ?? 'octane-client-build.json';
+	const independentHydrationManifestFilename =
+		options.independentHydrationManifestFilename ?? 'octane-independent-hydration.json';
 	const log = options.log ?? (() => {});
 	const clientHtml = path.join(clientDir, 'index.html');
 	const serverHtml = path.join(serverDir, 'index.html');
 	const clientAssetMap = path.join(clientDir, assetMapFilename);
 	const serverAssetMap = path.join(serverDir, assetMapFilename);
+	const clientBuildPath = path.join(clientDir, clientBuildFilename);
+	const serverBuildPath = path.join(serverDir, clientBuildFilename);
+	const clientIndependentHydration = path.join(clientDir, independentHydrationManifestFilename);
+	const serverIndependentHydration = path.join(serverDir, independentHydrationManifestFilename);
 	const serverEntry = path.join(serverDir, 'entry.js');
 
 	if (!fs.existsSync(clientHtml)) {
@@ -37,12 +46,45 @@ export async function finalizeOctaneRsbuildOutput(options) {
 	if (!fs.existsSync(serverEntry)) {
 		throw new Error(`[@octanejs/rsbuild-plugin] Server entry was not emitted at ${serverEntry}.`);
 	}
+	if (!fs.existsSync(clientBuildPath)) {
+		throw new Error(
+			`[@octanejs/rsbuild-plugin] Client build metadata was not emitted at ${clientBuildPath}.`,
+		);
+	}
+	const clientBuild = JSON.parse(fs.readFileSync(clientBuildPath, 'utf8'));
+	if (
+		clientBuild?.version !== 1 ||
+		typeof clientBuild.buildId !== 'string' ||
+		!clientBuild.buildId ||
+		clientBuild.mode !== 'production' ||
+		typeof clientBuild.capabilities?.independentHydration !== 'boolean'
+	) {
+		throw new Error('[@octanejs/rsbuild-plugin] Invalid production client build metadata.');
+	}
+	if (fs.existsSync(clientIndependentHydration)) {
+		const widgets = JSON.parse(fs.readFileSync(clientIndependentHydration, 'utf8'));
+		if (widgets.buildId !== clientBuild.buildId) {
+			throw new Error(
+				'[@octanejs/rsbuild-plugin] Independent hydration and client build metadata disagree.',
+			);
+		}
+	} else if (clientBuild.capabilities.independentHydration) {
+		throw new Error(
+			'[@octanejs/rsbuild-plugin] Client build is missing independent hydration metadata.',
+		);
+	}
 
 	fs.mkdirSync(serverDir, { recursive: true });
 	fs.rmSync(serverHtml, { force: true });
 	fs.rmSync(serverAssetMap, { force: true });
+	fs.rmSync(serverBuildPath, { force: true });
 	fs.renameSync(clientHtml, serverHtml);
 	fs.renameSync(clientAssetMap, serverAssetMap);
+	fs.renameSync(clientBuildPath, serverBuildPath);
+	fs.rmSync(serverIndependentHydration, { force: true });
+	if (fs.existsSync(clientIndependentHydration)) {
+		fs.renameSync(clientIndependentHydration, serverIndependentHydration);
+	}
 
 	log(`Server build complete: ${path.relative(root, serverEntry)}`);
 	if (options.config.adapter?.serverTarget !== 'webworker') {

package/src/dev-server.js

@@ -5,6 +5,8 @@ import { nodeRequestToWebRequest, sendWebResponse } from '@octanejs/app-core/nod
 
 import { isRsbuildOwnedUrl } from './html.js';
 
+const INDEPENDENT_HYDRATION_MANIFEST_FILENAME = 'octane-independent-hydration.json';
+
 /**
  * @typedef {{
  *   manifest: import('@octanejs/app-core/production').ServerManifest,
@@ -27,6 +29,35 @@ function collectAssetPaths(stats) {
 	return paths;
 }
 
+/** @param {import('@rspack/core').Stats} stats */
+function readIndependentHydrationManifest(stats) {
+	const asset = stats.compilation.getAsset?.(INDEPENDENT_HYDRATION_MANIFEST_FILENAME);
+	if (!asset) return null;
+	const source = asset.source.source();
+	return JSON.parse(typeof source === 'string' ? source : Buffer.from(source).toString('utf8'));
+}
+
+/** @param {import('@rspack/core').Stats} stats */
+function readClientBuild(stats) {
+	const asset = stats.compilation.getAsset?.('octane-client-build.json');
+	if (!asset) throw new Error('The Octane client build metadata is missing.');
+	const source = asset.source.source();
+	const metadata = JSON.parse(
+		typeof source === 'string' ? source : Buffer.from(source).toString('utf8'),
+	);
+	if (
+		metadata?.version !== 1 ||
+		metadata.buildId !== stats.hash ||
+		metadata.mode !== 'development' ||
+		typeof metadata.capabilities?.independentHydration !== 'boolean'
+	) {
+		throw new Error(
+			'The Octane client build metadata is incompatible with this development compilation.',
+		);
+	}
+	return metadata;
+}
+
 /**
  * Create the early Connect middleware used by the Rsbuild Environment API.
  * Asset/internal requests fall through to Rsbuild; matched app/RPC requests
@@ -54,7 +85,7 @@ export function createOctaneDevMiddleware(options) {
 
 	let assetHash = '';
 	let assetPaths = new Set();
-	/** @type {WeakMap<object, { html: string, handler: (request: Request) => Promise<Response> }>} */
+	/** @type {WeakMap<object, { html: string, assetHash: string, handler: (request: Request) => Promise<Response> }>} */
 	const handlerCache = new WeakMap();
 
 	return async function octaneDevMiddleware(request, response, next) {
@@ -69,6 +100,7 @@ export function createOctaneDevMiddleware(options) {
 				return;
 			}
 			const clientStats = await clientApi.getStats();
+			if (clientStats.hasErrors()) throw new Error('The Octane client compilation failed.');
 			if (clientStats.hash !== assetHash) {
 				assetHash = clientStats.hash ?? '';
 				assetPaths = collectAssetPaths(clientStats);
@@ -92,13 +124,24 @@ export function createOctaneDevMiddleware(options) {
 
 			const html = await clientApi.getTransformedHtml(options.clientEntry);
 			let cached = handlerCache.get(typedBundle.manifest);
-			if (!cached || cached.html !== html) {
+			if (!cached || cached.html !== html || cached.assetHash !== assetHash) {
+				const independentHydration = readIndependentHydrationManifest(clientStats);
+				const clientBuild = readClientBuild(clientStats);
+				if (independentHydration !== null && independentHydration.buildId !== clientBuild.buildId) {
+					throw new Error(
+						'The Octane independent widget metadata belongs to another client build.',
+					);
+				}
 				cached = {
 					html,
-					handler: createHandler(typedBundle.manifest, {
-						...typedBundle.rendererDeps,
-						htmlTemplate: html,
-					}),
+					assetHash,
+					handler: createHandler(
+						{ ...typedBundle.manifest, independentHydration, clientBuild },
+						{
+							...typedBundle.rendererDeps,
+							htmlTemplate: html,
+						},
+					),
 				};
 				handlerCache.set(typedBundle.manifest, cached);
 			}

package/src/html.js

@@ -9,6 +9,42 @@ function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/**
+ * A classic bootstrap can run after the streamed shell only if its native
+ * entrypoint needs no deferred prerequisite and starts no other entry module.
+ * Keep the bundler's runtime/chunk ownership intact; reject unsafe overrides.
+ *
+ * @param {import('@rspack/core').Compilation} compilation
+ * @param {string} name
+ * @param {string} clientEntry
+ */
+export function assertEarlyHydrationEntry(compilation, name, clientEntry) {
+	const entrypoint = compilation.entrypoints.get(name);
+	const chunk = entrypoint?.getEntrypointChunk();
+	const files = entrypoint?.getFiles().filter((file) => /\.m?js(?:\?.*)?$/.test(file)) ?? [];
+	if (!chunk || files.length !== 1 || !chunk.files.has(files[0])) {
+		throw new Error(
+			'Octane early hydration requires one self-contained entry script. ' +
+				'Do not extract its runtime or initial JavaScript dependencies into deferred chunks.',
+		);
+	}
+	const entries = [...compilation.chunkGraph.getChunkEntryModulesIterable(chunk)];
+	const entry = entries[0];
+	const root = entry && 'rootModule' in entry ? (entry.rootModule ?? entry) : entry;
+	const resource =
+		root && typeof root === 'object' && 'resource' in root ? root.resource : undefined;
+	if (
+		entries.length !== 1 ||
+		typeof resource !== 'string' ||
+		fs.realpathSync(resource.split('?', 1)[0]) !== fs.realpathSync(clientEntry)
+	) {
+		throw new Error(
+			'Octane early hydration must own its entry module exclusively. ' +
+				'Keep user entries and pre-entry scripts separate from the generated hydration entry.',
+		);
+	}
+}
+
 /**
  * Rsbuild has already injected the web entry by the time `modifyHTML` runs.
  * Mark the concrete generated tag so the shared production runtime can add a

package/src/index.js

@@ -25,12 +25,15 @@ import {
 	write_project_generated_file,
 } from '@octanejs/app-core/codegen';
 import { OctaneRspackPlugin } from '@octanejs/rspack-plugin';
-import { createOctaneCompiler } from 'octane/compiler/bundler';
+import {
+	INDEPENDENT_HYDRATION_MANIFEST_FILENAME,
+	createOctaneCompiler,
+} from 'octane/compiler/bundler';
 
 import { finalizeOctaneRsbuildOutput } from './build.js';
 import { OctaneClientAssetsPlugin } from './client-assets-plugin.js';
 import { createOctaneDevMiddleware } from './dev-server.js';
-import { markHydrationEntry } from './html.js';
+import { assertEarlyHydrationEntry, markHydrationEntry } from './html.js';
 import {
 	collectClientEntries,
 	discoverServerModules,
@@ -397,6 +400,18 @@ export function pluginOctane(inlineOptions = {}) {
 					server: { htmlFallback: false, historyApiFallback: false },
 					environments: {
 						[clientEnvironment]: {
+							// Keep the generated bootstrap self-contained by default, including
+							// downlevel helpers. Explicit splitting remains subject to the
+							// emitted-entry ownership check instead of being silently replaced.
+							...(watchedConfig.splitChunks !== false &&
+							Object.keys(watchedConfig.splitChunks ?? {}).length === 0 &&
+							watchedConfig.environments?.[clientEnvironment]?.splitChunks !== false &&
+							Object.keys(watchedConfig.environments?.[clientEnvironment]?.splitChunks ?? {})
+								.length === 0 &&
+							watchedConfig.performance?.chunkSplit === undefined &&
+							watchedConfig.environments?.[clientEnvironment]?.performance?.chunkSplit === undefined
+								? { splitChunks: { chunks: 'async' } }
+								: {}),
 							...targetConfig,
 							source: { entry: { [CLIENT_ENTRY_NAME]: clientEntryFile } },
 							html: { template },
@@ -480,6 +495,7 @@ export function pluginOctane(inlineOptions = {}) {
 						}));
 						return create_client_entry_source({
 							staticEntries: entries,
+							clientBuildIdExpression: '__webpack_hash__',
 							generatedBy: PLUGIN_NAME,
 						});
 					},
@@ -520,7 +536,11 @@ export function pluginOctane(inlineOptions = {}) {
 							rpcModulePaths: serverModules.ids,
 							...(webWorkerServer ? { mode: 'webworker' } : null),
 							...(production && !webWorkerServer
-								? { clientAssetMapFile: CLIENT_ASSET_MAP }
+								? {
+										clientAssetMapFile: CLIENT_ASSET_MAP,
+										clientBuildFile: 'octane-client-build.json',
+										independentHydrationManifestFile: INDEPENDENT_HYDRATION_MANIFEST_FILENAME,
+									}
 								: { clientAssetMap: {} }),
 							resolveImport: (id) => resolveProjectModule(id, root),
 							configModuleId: localRequire.resolve('@octanejs/app-core/config'),
@@ -551,6 +571,7 @@ export function pluginOctane(inlineOptions = {}) {
 					new OctaneRspackPlugin({
 						root,
 						environment,
+						clientBuildMode: productionBuild ? 'production' : 'development',
 						transpile: false,
 						...(inlineOptions.parallel === undefined ? null : { parallel: inlineOptions.parallel }),
 						...(inlineOptions.cssModuleConstants === undefined
@@ -645,6 +666,9 @@ export function pluginOctane(inlineOptions = {}) {
 
 			api.modifyHTML((html, context) => {
 				if (context.environment.name !== clientEnvironment) return html;
+				if (isProductionBuild()) {
+					assertEarlyHydrationEntry(context.compilation, CLIENT_ENTRY_NAME, clientEntryFile);
+				}
 				const entrypoint = context.compilation.entrypoints.get(CLIENT_ENTRY_NAME);
 				const entryFiles = entrypoint?.getEntrypointChunk().files ?? [];
 				return markHydrationEntry(html, entryFiles);
@@ -685,6 +709,7 @@ export function pluginOctane(inlineOptions = {}) {
 					root,
 					config: loaded.config,
 					assetMapFilename: CLIENT_ASSET_MAP,
+					independentHydrationManifestFilename: INDEPENDENT_HYDRATION_MANIFEST_FILENAME,
 					log: createLog(api.logger),
 				});
 			});