@octanejs/rspack-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# `@octanejs/rspack-plugin`
+
+Low-level Rspack 2.x integration for Octane. It compiles `.tsrx`, eligible
+Octane `.tsx`, and raw `.ts`/`.js` hook sources; the full routing and SSR app
+integration lives in `@octanejs/rsbuild-plugin`.
+
+## Install
+
+```sh
+pnpm add octane
+pnpm add -D @rspack/core @octanejs/rspack-plugin
+```
+
+## Rspack plugin
+
+```js
+// rspack.config.mjs
+import { OctaneRspackPlugin } from '@octanejs/rspack-plugin';
+
+export default {
+	entry: './src/main.tsrx',
+	plugins: [new OctaneRspackPlugin()],
+};
+```
+
+The plugin:
+
+- adds `.tsrx`, `.tsx`, and `.ts` resolution;
+- installs the Octane pre-loader for local and linked/raw dependency sources;
+- 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
+  `octane/server` in server compilations;
+- forwards compiler source maps and registers consulted and missing manifests
+  with Rspack's cache and watcher;
+- emits the webpack/Rspack HMR dialect when the compilation is hot; and
+- strips TypeScript with `builtin:swc-loader` after Octane by default.
+
+Use an explicit environment for targets which do not identify their consumer:
+
+```js
+new OctaneRspackPlugin({ environment: 'server' });
+```
+
+Set `transpile: false` when an existing rule already strips TypeScript. Set
+`hmr: false` to disable Octane HMR codegen even when Rspack HMR is active.
+Options contain only serializable strings, booleans, and string arrays, so the
+same configuration is safe to reuse across compiler environments and caches.
+
+Rspack's dev server enables the loader's hot context. If you run a custom dev
+server, add Rspack's `HotModuleReplacementPlugin` as usual.
+
+## Loader only
+
+The ESM loader is exported for custom rule composition:
+
+```js
+export default {
+	module: {
+		rules: [
+			{
+				test: /\.(?:tsrx|tsx|ts|js)$/,
+				enforce: 'pre',
+				type: 'javascript/auto',
+				use: {
+					loader: '@octanejs/rspack-plugin/loader',
+					options: { environment: 'client' },
+				},
+			},
+		],
+	},
+};
+```
+
+With the loader-only form, configure `.tsrx` resolution, TypeScript stripping,
+and the exact server runtime alias yourself. The class plugin is recommended
+unless another integration owns those concerns.
+
+## App-level metadata
+
+Transformed Rspack modules receive a serializable `buildInfo.octane` record
+containing `canonicalId`, `transformKind`, and `serverRpc`. App integrations can
+read the validated value with `getOctaneRspackBuildInfo(module)` without
+depending on compiler output parsing for module identity.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@octanejs/rspack-plugin",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "Rspack loader and compiler plugin for Octane TSRX source",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/rspack-plugin-octane"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "module": "src/index.js",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./loader": {
+      "types": "./types/loader.d.ts",
+      "import": "./src/loader.js",
+      "default": "./src/loader.js"
+    }
+  },
+  "dependencies": {
+    "@jridgewell/remapping": "^2.3.5"
+  },
+  "peerDependencies": {
+    "@rspack/core": "^2.0.0",
+    "octane": "0.1.5"
+  },
+  "devDependencies": {
+    "@rspack/core": "^2.1.3",
+    "@types/node": "^24.3.0",
+    "vitest": "^4.1.9",
+    "octane": "0.1.5"
+  },
+  "scripts": {
+    "test": "vitest run --config vitest.config.js"
+  }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { OctaneRspackPlugin, octaneRspack } from './plugin.js';
+export { getOctaneRspackBuildInfo, inferRspackEnvironment } from './shared.js';

package/src/loader.js

@@ -0,0 +1,95 @@
+import { isAbsolute, resolve } from 'node:path';
+import remapping from '@jridgewell/remapping';
+import { canonicalModuleId, createOctaneCompiler } from 'octane/compiler/bundler';
+import { inferRspackEnvironment, normalizeLoaderOptions } from './shared.js';
+
+function clearBuildInfo(module) {
+	if (module?.buildInfo && typeof module.buildInfo === 'object') {
+		delete module.buildInfo.octane;
+	}
+}
+
+function setBuildInfo(module, value) {
+	if (!module || typeof module !== 'object') return;
+	if (!module.buildInfo || typeof module.buildInfo !== 'object') module.buildInfo = {};
+	module.buildInfo.octane = value;
+}
+
+function registerDependencies(context, result) {
+	for (const dependency of new Set(result.dependencies ?? [])) {
+		context.addDependency?.(dependency);
+	}
+	for (const dependency of new Set(result.missingDependencies ?? [])) {
+		context.addMissingDependency?.(dependency);
+	}
+}
+
+function composeSourceMaps(outputMap, inputSourceMap) {
+	if (!outputMap || !inputSourceMap) return outputMap ?? inputSourceMap;
+	const input = typeof inputSourceMap === 'string' ? JSON.parse(inputSourceMap) : inputSourceMap;
+	const chained = remapping([outputMap, input], () => null);
+	return String(chained.mappings).length > 0 ? chained : outputMap;
+}
+
+/**
+ * Rspack's ESM loader entry. A compiler instance is intentionally scoped to
+ * one invocation: Rspack owns output caching and invalidates it from the file
+ * and missing-file dependencies registered below, while a fresh neutral
+ * compiler instance cannot retain stale manifest discovery across rebuilds.
+ */
+export default function octaneLoader(source, inputSourceMap) {
+	this.cacheable?.(true);
+	clearBuildInfo(this._module);
+
+	try {
+		const options = normalizeLoaderOptions(this.getOptions?.() ?? {});
+		const loaderRoot = this.rootContext ?? process.cwd();
+		const root = options.root
+			? isAbsolute(options.root)
+				? options.root
+				: resolve(loaderRoot, options.root)
+			: loaderRoot;
+		const environment = options.environment ?? inferRspackEnvironment(this.target);
+		const hmr =
+			environment === 'client' && this.hot === true && options.hmr !== false ? 'webpack' : false;
+		const dev =
+			environment === 'client' &&
+			(options.dev ?? (this.mode === undefined || this.mode !== 'production'));
+		const compiler = createOctaneCompiler({
+			root,
+			...(options.exclude === undefined ? null : { exclude: options.exclude }),
+			...(options.parallelUse === undefined ? null : { parallelUse: options.parallelUse }),
+		});
+		const id = this.resource ?? this.resourcePath;
+		const result = compiler.transform(String(source), id, {
+			environment,
+			hmr,
+			dev,
+			...(options.parallelUse === undefined ? null : { parallelUse: options.parallelUse }),
+		});
+
+		if (result === null) {
+			this.callback(null, source, this.sourceMap === false ? undefined : inputSourceMap);
+			return;
+		}
+
+		registerDependencies(this, result);
+		if (result.kind === 'none') {
+			this.callback(null, source, this.sourceMap === false ? undefined : inputSourceMap);
+			return;
+		}
+		setBuildInfo(this._module, {
+			canonicalId: canonicalModuleId(id, root),
+			transformKind: result.kind,
+			serverRpc:
+				result.kind === 'compile' &&
+				(result.code.includes('_$__serverRpc(') ||
+					result.code.includes('export const _$_server_$_')),
+		});
+		const sourceMap =
+			this.sourceMap === false ? undefined : composeSourceMaps(result.map, inputSourceMap);
+		this.callback(null, result.code, sourceMap);
+	} catch (error) {
+		this.callback(error instanceof Error ? error : new Error(String(error)));
+	}
+}

package/src/plugin.js

@@ -0,0 +1,124 @@
+import { createRequire } from 'node:module';
+import { isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createOctaneCompiler } from 'octane/compiler/bundler';
+import { inferRspackEnvironment, normalizePluginOptions } from './shared.js';
+
+const PLUGIN_NAME = 'OctaneRspackPlugin';
+const loaderPath = fileURLToPath(new URL('./loader.js', import.meta.url));
+const OCTANE_RULE = /\.(?:tsrx|tsx|ts|js)$/i;
+const TYPESCRIPT_RULE = /\.(?:tsrx|tsx|ts)$/i;
+
+function addUniqueExtensions(resolveOptions) {
+	const extensions = resolveOptions.extensions ?? ['.js', '.json', '.wasm'];
+	resolveOptions.extensions = [
+		...['.tsrx', '.tsx', '.ts'].filter((extension) => !extensions.includes(extension)),
+		...extensions,
+	];
+}
+
+function resolveRuntimeModule(request, root) {
+	if (isAbsolute(request)) return request;
+	try {
+		return createRequire(join(root, 'package.json')).resolve(request);
+	} catch {
+		// Let Rspack produce its normal resolution diagnostic. This fallback also
+		// keeps config inspection usable before peer dependencies are installed.
+		return request;
+	}
+}
+
+function addRuntimeAlias(resolveOptions, request, root) {
+	const aliases = resolveOptions.alias === false ? {} : (resolveOptions.alias ?? {});
+	resolveOptions.alias = {
+		...aliases,
+		octane$: resolveRuntimeModule(request, root),
+	};
+}
+
+function addDependencies(collection, values) {
+	if (!collection?.add) return;
+	for (const value of values ?? []) collection.add(value);
+}
+
+export class OctaneRspackPlugin {
+	constructor(options = {}) {
+		this.options = normalizePluginOptions(options);
+		this.sourceDependencies = [];
+	}
+
+	apply(compiler) {
+		const configuredRoot = this.options.root;
+		const compilerRoot = compiler.options.context ?? process.cwd();
+		const root = configuredRoot
+			? isAbsolute(configuredRoot)
+				? configuredRoot
+				: resolve(compilerRoot, configuredRoot)
+			: compilerRoot;
+		const environment = this.options.environment ?? inferRspackEnvironment(compiler.options.target);
+		const neutralCompiler = createOctaneCompiler({
+			root,
+			...(this.options.exclude === undefined ? null : { exclude: this.options.exclude }),
+			...(this.options.parallelUse === undefined
+				? null
+				: { parallelUse: this.options.parallelUse }),
+		});
+		const runtimeRequest = neutralCompiler.resolveRuntimeRequest('octane', environment);
+
+		compiler.options.resolve ??= {};
+		addUniqueExtensions(compiler.options.resolve);
+		addRuntimeAlias(compiler.options.resolve, runtimeRequest, root);
+
+		compiler.options.module ??= {};
+		compiler.options.module.rules ??= [];
+		const loaderOptions = {
+			root,
+			environment,
+			...(this.options.hmr === undefined ? null : { hmr: this.options.hmr }),
+			...(this.options.dev === undefined ? null : { dev: this.options.dev }),
+			...(this.options.parallelUse === undefined
+				? null
+				: { parallelUse: this.options.parallelUse }),
+			...(this.options.exclude === undefined ? null : { exclude: this.options.exclude }),
+		};
+		compiler.options.module.rules.push({
+			test: OCTANE_RULE,
+			type: 'javascript/auto',
+			enforce: 'pre',
+			use: [{ loader: loaderPath, options: loaderOptions }],
+		});
+		if (this.options.transpile !== false) {
+			compiler.options.module.rules.push({
+				test: TYPESCRIPT_RULE,
+				type: 'javascript/auto',
+				use: [{ loader: 'builtin:swc-loader', options: { detectSyntax: 'auto' } }],
+			});
+		}
+
+		let discovery;
+		const discover = () => {
+			if (discovery === undefined) {
+				discovery = neutralCompiler.discoverSourceDependencies();
+				this.sourceDependencies = Object.freeze([...(discovery.packages ?? [])]);
+			}
+			return discovery;
+		};
+		compiler.hooks.invalid?.tap(PLUGIN_NAME, (filename) => {
+			neutralCompiler.invalidate(filename);
+			discovery = undefined;
+		});
+		compiler.hooks.watchRun?.tap(PLUGIN_NAME, () => {
+			neutralCompiler.invalidate();
+			discovery = undefined;
+		});
+		compiler.hooks.thisCompilation?.tap(PLUGIN_NAME, (compilation) => {
+			const current = discover();
+			addDependencies(compilation.fileDependencies, current.dependencies);
+			addDependencies(compilation.missingDependencies, current.missingDependencies);
+		});
+	}
+}
+
+export function octaneRspack(options) {
+	return new OctaneRspackPlugin(options);
+}

package/src/shared.js

@@ -0,0 +1,110 @@
+const CLIENT_TARGETS = new Set(['web', 'webworker', 'electron-renderer', 'browserslist']);
+
+function targetValues(target) {
+	if (Array.isArray(target)) return target.flatMap(targetValues);
+	return typeof target === 'string' ? [target.toLowerCase()] : [];
+}
+
+/**
+ * Infer which Octane runtime a Rspack compilation consumes. Explicit plugin
+ * options remain authoritative; this helper covers Rspack's standard target
+ * names when the environment is omitted.
+ */
+export function inferRspackEnvironment(target) {
+	const values = targetValues(target);
+	for (const value of values) {
+		if (
+			value === 'node' ||
+			value.startsWith('node') ||
+			value === 'async-node' ||
+			value.startsWith('async-node') ||
+			value === 'electron-main' ||
+			value === 'electron-preload' ||
+			value === 'nwjs' ||
+			value.startsWith('nwjs')
+		) {
+			return 'server';
+		}
+	}
+	for (const value of values) {
+		if (CLIENT_TARGETS.has(value) || value.startsWith('web')) return 'client';
+	}
+	return 'client';
+}
+
+const LOADER_OPTION_KEYS = new Set(['root', 'environment', 'hmr', 'dev', 'parallelUse', 'exclude']);
+const PLUGIN_OPTION_KEYS = new Set([...LOADER_OPTION_KEYS, 'transpile']);
+
+function assertBooleanOption(options, key) {
+	if (options[key] !== undefined && typeof options[key] !== 'boolean') {
+		throw new TypeError(`@octanejs/rspack-plugin: \`${key}\` must be a boolean.`);
+	}
+}
+
+function normalizeOptions(value, plugin) {
+	const options = value ?? {};
+	if (typeof options !== 'object' || Array.isArray(options)) {
+		throw new TypeError('@octanejs/rspack-plugin: options must be an object.');
+	}
+	const allowed = plugin ? PLUGIN_OPTION_KEYS : LOADER_OPTION_KEYS;
+	for (const key of Object.keys(options)) {
+		if (!allowed.has(key)) {
+			throw new TypeError(`@octanejs/rspack-plugin: unknown option \`${key}\`.`);
+		}
+	}
+	if (options.root !== undefined && typeof options.root !== 'string') {
+		throw new TypeError('@octanejs/rspack-plugin: `root` must be a path string.');
+	}
+	if (
+		options.environment !== undefined &&
+		options.environment !== 'client' &&
+		options.environment !== 'server'
+	) {
+		throw new TypeError('@octanejs/rspack-plugin: `environment` must be "client" or "server".');
+	}
+	assertBooleanOption(options, 'hmr');
+	assertBooleanOption(options, 'dev');
+	assertBooleanOption(options, 'parallelUse');
+	if (
+		options.exclude !== undefined &&
+		(!Array.isArray(options.exclude) || options.exclude.some((entry) => typeof entry !== 'string'))
+	) {
+		throw new TypeError('@octanejs/rspack-plugin: `exclude` must be an array of path strings.');
+	}
+	if (plugin) assertBooleanOption(options, 'transpile');
+
+	const normalized = {
+		...(options.root === undefined ? null : { root: options.root }),
+		...(options.environment === undefined ? null : { environment: options.environment }),
+		...(options.hmr === undefined ? null : { hmr: options.hmr }),
+		...(options.dev === undefined ? null : { dev: options.dev }),
+		...(options.parallelUse === undefined ? null : { parallelUse: options.parallelUse }),
+		...(options.exclude === undefined ? null : { exclude: [...options.exclude] }),
+		...(plugin && options.transpile !== undefined ? { transpile: options.transpile } : null),
+	};
+	if (normalized.exclude) Object.freeze(normalized.exclude);
+	return Object.freeze(normalized);
+}
+
+export function normalizeLoaderOptions(value) {
+	return normalizeOptions(value, false);
+}
+
+export function normalizePluginOptions(value) {
+	return normalizeOptions(value, true);
+}
+
+/** Read the serializable metadata attached to an Octane-transformed module. */
+export function getOctaneRspackBuildInfo(module) {
+	const value = module?.buildInfo?.octane;
+	if (
+		value &&
+		typeof value === 'object' &&
+		typeof value.canonicalId === 'string' &&
+		(value.transformKind === 'compile' || value.transformKind === 'slots') &&
+		typeof value.serverRpc === 'boolean'
+	) {
+		return value;
+	}
+	return null;
+}

package/types/index.d.ts

@@ -0,0 +1,49 @@
+import type { Compiler, RspackPluginInstance } from '@rspack/core';
+
+export type OctaneRspackEnvironment = 'client' | 'server';
+
+export interface OctaneRspackLoaderOptions {
+	/** Project root used to canonicalize module IDs and discover package manifests. */
+	root?: string;
+	/** Explicit compiler target. Standard Rspack web/node targets are inferred when omitted. */
+	environment?: OctaneRspackEnvironment;
+	/** Allow webpack-dialect HMR codegen when the loader context is hot. Default `true`. */
+	hmr?: boolean;
+	/** Emit client development metadata. Defaults to Rspack's non-production mode. */
+	dev?: boolean;
+	/** Enable Octane's parallel `use()` compilation pipeline. Default `true`. */
+	parallelUse?: boolean;
+	/** Path fragments excluded from the plain `.ts`/`.js` hook-slot pass. */
+	exclude?: string[];
+}
+
+export interface OctaneRspackPluginOptions extends OctaneRspackLoaderOptions {
+	/**
+	 * Add Rspack's built-in SWC loader to strip TypeScript after Octane runs.
+	 * Disable this when another rule already owns TypeScript transpilation.
+	 * @default true
+	 */
+	transpile?: boolean;
+}
+
+export interface OctaneRspackBuildInfo {
+	canonicalId: string;
+	transformKind: 'compile' | 'slots';
+	serverRpc: boolean;
+}
+
+export declare class OctaneRspackPlugin implements RspackPluginInstance {
+	constructor(options?: OctaneRspackPluginOptions);
+	readonly options: Readonly<OctaneRspackPluginOptions>;
+	/** Raw installed packages discovered from Octane package manifests after compilation starts. */
+	sourceDependencies: readonly string[];
+	apply(compiler: Compiler): void;
+}
+
+export declare function octaneRspack(options?: OctaneRspackPluginOptions): OctaneRspackPlugin;
+
+/** Infer client/server compilation from standard Rspack target names. */
+export declare function inferRspackEnvironment(target: unknown): OctaneRspackEnvironment;
+
+/** Read the serializable metadata emitted by the loader for app-level collectors. */
+export declare function getOctaneRspackBuildInfo(module: unknown): OctaneRspackBuildInfo | null;

package/types/loader.d.ts

@@ -0,0 +1,5 @@
+import type { LoaderDefinition } from '@rspack/core';
+import type { OctaneRspackLoaderOptions } from './index.js';
+
+declare const octaneLoader: LoaderDefinition<OctaneRspackLoaderOptions>;
+export default octaneLoader;