@octanejs/rspack-plugin 0.1.34 → 0.1.35

package/README.md

@@ -26,7 +26,7 @@ export default {
 The plugin:
 
 - adds `.tsrx`, `.tsx`, and `.ts` resolution;
-- installs the Octane pre-loader for local and linked/raw dependency sources;
+- compiles local and linked/raw dependency sources in parallel Rspack workers;
 - selects client or server codegen from Rspack's `target` (or an explicit
   `environment` option);
 - resolves every exact bare `octane` import to one client runtime, or to
@@ -47,6 +47,14 @@ Set `transpile: false` when an existing rule already strips TypeScript. Set
 Set `profile: true` to produce a client profiling build; server compilations
 always keep profiling disabled.
 
+Octane uses up to four Rspack loader workers by default. Set `parallel: false`
+to compile on the main thread, or provide `parallel: { maxWorkers: 2 }` to
+request a different worker-pool limit. Rspack shares one loader worker pool
+per process, so the first parallel loader determines its effective size.
+Source maps, module layers, compiler metadata, and watched package manifests
+are preserved in both modes. Worker startup has a fixed cost, so very small
+builds may be faster with `parallel: false`.
+
 Set `strong: true` to reject state updates during rendering, state updates from
 effects, and ref writes during rendering in your application code:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/rspack-plugin",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -45,13 +45,13 @@
   },
   "peerDependencies": {
     "@rspack/core": "^2.0.0",
-    "octane": "0.1.39"
+    "octane": "0.1.40"
   },
   "devDependencies": {
     "@rspack/core": "^2.1.4",
     "@types/node": "^24.13.3",
     "vitest": "^4.1.10",
-    "octane": "0.1.39"
+    "octane": "0.1.40"
   },
   "scripts": {
     "test": "vitest run --config vitest.config.js"

package/src/finalize-loader.js

@@ -0,0 +1,33 @@
+/**
+ * Rspack does not copy a module's layer or buildInfo into parallel-loader
+ * workers. Pitch data is structured-cloned into the worker before compilation.
+ */
+export function pitch() {
+	this.data ??= {};
+	this.data.octaneLayer = this._module?.layer ?? null;
+	if (this._module?.buildInfo && typeof this._module.buildInfo === 'object') {
+		delete this._module.buildInfo.octane;
+	}
+}
+
+/** Restore worker-owned Octane metadata and missing-file watches on the main thread. */
+export default function finalizeOctaneLoader(source, sourceMap, metadata) {
+	const result = metadata?.__octaneParallelLoader;
+	if (result?.buildInfo) {
+		if (!this._module.buildInfo || typeof this._module.buildInfo !== 'object') {
+			this._module.buildInfo = {};
+		}
+		this._module.buildInfo.octane = result.buildInfo;
+	}
+	for (const dependency of result?.missingDependencies ?? []) {
+		this.addMissingDependency(dependency);
+	}
+	if (metadata && typeof metadata === 'object') {
+		const { __octaneParallelLoader, ...remainingMetadata } = metadata;
+		if (Object.keys(remainingMetadata).length > 0) {
+			this.callback(null, source, sourceMap, remainingMetadata);
+			return;
+		}
+	}
+	this.callback(null, source, sourceMap);
+}

package/src/parallel-loader.js

@@ -0,0 +1,34 @@
+import octaneLoader from './loader.js';
+
+/**
+ * Run the unchanged public Octane loader inside Rspack's worker pool. Rspack
+ * proxies resolution, ordinary file dependencies, warnings, and asynchronous
+ * callbacks, but omits module layer/buildInfo and addMissingDependency.
+ */
+export default function parallelOctaneLoader(source, sourceMap) {
+	const missingDependencies = [];
+	const module = this._module;
+	const finalizer = this.loaders[this.loaderIndex - 1];
+	module.layer = finalizer?.loaderItem?.data?.octaneLayer ?? undefined;
+
+	const callback = this.callback.bind(this);
+	const async = this.async.bind(this);
+	const withWorkerMetadata = (finish) => (error, output, outputMap, metadata) => {
+		if (error) {
+			finish(error);
+			return;
+		}
+		finish(null, output, outputMap, {
+			...(metadata ?? {}),
+			__octaneParallelLoader: {
+				buildInfo: module.buildInfo?.octane ?? null,
+				missingDependencies,
+			},
+		});
+	};
+
+	this.addMissingDependency = (dependency) => missingDependencies.push(dependency);
+	this.callback = withWorkerMetadata(callback);
+	this.async = () => withWorkerMetadata(async());
+	return octaneLoader.call(this, source, sourceMap);
+}

package/src/plugin.js

@@ -18,6 +18,9 @@ const PLUGIN_NAME = 'OctaneRspackPlugin';
 const PROFILE_DEFINE = '__OCTANE_PROFILE_ENABLED__';
 const PLUGIN_VERSION = createRequire(import.meta.url)('../package.json').version;
 const loaderPath = fileURLToPath(new URL('./loader.js', import.meta.url));
+const finalizeLoaderPath = fileURLToPath(new URL('./finalize-loader.js', import.meta.url));
+const parallelLoaderPath = fileURLToPath(new URL('./parallel-loader.js', import.meta.url));
+const DEFAULT_MAX_WORKERS = 4;
 const OCTANE_RULE = /\.(?:tsrx|tsx|ts|js)$/i;
 const TYPESCRIPT_RULE = /\.(?:tsrx|tsx|ts)$/i;
 
@@ -337,7 +340,22 @@ export class OctaneRspackPlugin {
 			test: OCTANE_RULE,
 			type: 'javascript/auto',
 			enforce: 'pre',
-			use: [{ loader: loaderPath, options: loaderOptions }],
+			use:
+				this.options.parallel === false
+					? [{ loader: loaderPath, options: loaderOptions }]
+					: [
+							{ loader: finalizeLoaderPath, options: loaderOptions },
+							{
+								loader: parallelLoaderPath,
+								options: loaderOptions,
+								parallel: {
+									maxWorkers:
+										typeof this.options.parallel === 'object'
+											? (this.options.parallel.maxWorkers ?? DEFAULT_MAX_WORKERS)
+											: DEFAULT_MAX_WORKERS,
+								},
+							},
+						],
 		});
 		if (this.options.transpile !== false) {
 			compiler.options.module.rules.push({

package/src/shared.js

@@ -47,7 +47,7 @@ const LOADER_OPTION_KEYS = new Set([
 	'universalRuntime',
 	'layerSpecializations',
 ]);
-const PLUGIN_OPTION_KEYS = new Set([...LOADER_OPTION_KEYS, 'runtime', 'transpile']);
+const PLUGIN_OPTION_KEYS = new Set([...LOADER_OPTION_KEYS, 'parallel', 'runtime', 'transpile']);
 const LAYER_SPECIALIZATION_KEYS = new Set(['runtime', 'renderers', 'universalRuntime']);
 
 function normalizeRuntimeRequest(value, label = 'runtime') {
@@ -153,6 +153,29 @@ function assertBooleanOption(options, key) {
 	}
 }
 
+function normalizeParallelOption(value) {
+	if (value === undefined || typeof value === 'boolean') return value;
+	if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+		throw new TypeError(
+			'@octanejs/rspack-plugin: `parallel` must be a boolean or an options object.',
+		);
+	}
+	for (const key of Object.keys(value)) {
+		if (key !== 'maxWorkers') {
+			throw new TypeError(`@octanejs/rspack-plugin: unknown \`parallel.${key}\` option.`);
+		}
+	}
+	if (
+		value.maxWorkers !== undefined &&
+		(!Number.isSafeInteger(value.maxWorkers) || value.maxWorkers < 1)
+	) {
+		throw new TypeError(
+			'@octanejs/rspack-plugin: `parallel.maxWorkers` must be a positive integer.',
+		);
+	}
+	return Object.freeze(value.maxWorkers === undefined ? {} : { maxWorkers: value.maxWorkers });
+}
+
 function normalizeOptions(value, plugin) {
 	const options = value ?? {};
 	if (typeof options !== 'object' || Array.isArray(options)) {
@@ -187,6 +210,7 @@ function normalizeOptions(value, plugin) {
 		throw new TypeError('@octanejs/rspack-plugin: `exclude` must be an array of path strings.');
 	}
 	if (plugin) assertBooleanOption(options, 'transpile');
+	const parallel = plugin ? normalizeParallelOption(options.parallel) : undefined;
 	const renderers =
 		options.renderers === undefined ? undefined : normalizeRendererConfig(options.renderers);
 	const universalRuntime = normalizeUniversalRuntime(options.universalRuntime);
@@ -206,6 +230,7 @@ function normalizeOptions(value, plugin) {
 		...(options.requireDirective === undefined
 			? null
 			: { requireDirective: options.requireDirective }),
+		...(plugin && parallel !== undefined ? { parallel } : null),
 		...(plugin && options.transpile !== undefined ? { transpile: options.transpile } : null),
 		...(plugin && options.runtime !== undefined ? { runtime: options.runtime } : null),
 	};

package/types/index.d.ts

@@ -152,6 +152,13 @@ export interface OctaneRspackLoaderOptions {
 }
 
 export interface OctaneRspackPluginOptions extends OctaneRspackLoaderOptions {
+	/**
+	 * Compile Octane modules in Rspack worker threads. Enabled by default with
+	 * at most four workers; set `false` to keep compilation on the main thread.
+	 * Provide `maxWorkers` to request a different shared worker-pool limit.
+	 * @default true
+	 */
+	parallel?: boolean | { maxWorkers?: number };
 	/**
 	 * Compiler and exact-runtime overrides selected by the current module's
 	 * Rspack layer. Unknown layers retain the top-level plugin options.

package/types/options.test-d.ts

@@ -21,6 +21,7 @@ const loaderOptions: OctaneRspackLoaderOptions = {
 
 const pluginOptions: OctaneRspackPluginOptions = {
 	strong: false,
+	parallel: { maxWorkers: 2 },
 	layerSpecializations: {
 		'native:main': {
 			runtime: '@fixture/native-main-runtime',
@@ -29,6 +30,8 @@ const pluginOptions: OctaneRspackPluginOptions = {
 	},
 };
 
+const serialPluginOptions: OctaneRspackPluginOptions = { parallel: false };
+
 const unsupportedLoaderRuntime: OctaneRspackLoaderOptions = {
 	layerSpecializations: {
 		'native:main': {
@@ -38,6 +41,13 @@ const unsupportedLoaderRuntime: OctaneRspackLoaderOptions = {
 	},
 };
 
+const unsupportedLoaderParallel: OctaneRspackLoaderOptions = {
+	// @ts-expect-error Worker-pool configuration belongs to the plugin, not the standalone loader.
+	parallel: true,
+};
+
 void loaderOptions;
 void pluginOptions;
+void serialPluginOptions;
 void unsupportedLoaderRuntime;
+void unsupportedLoaderParallel;