@crossbind/plugin-webpack 2.0.0-beta.50

package/AGENTS.md

@@ -0,0 +1,89 @@
+# AGENTS.md — @crossbind/plugin-webpack
+
+> Webpack **and Rspack** integration plugin. Same package serves both — Rspack reuses the Webpack plugin contract.
+
+## What lives here
+
+- `index.js` — exports `class CrossbindWebpackPlugin`. Single class, no separate kernel.
+- Sibling package `@crossbind/plugin-webpack-loader` ships the loader for `.h` files; `getRule()` references it by name.
+
+## Class API surface
+
+```
+new CrossbindWebpackPlugin()
+  ↓
+  .apply(compiler)                   ← webpack standard plugin hook
+  .getRule()                         ← module.rules entry for .h
+  .getDevServerConfig()              ← devServer block w/ COOP+COEP + middleware
+  .getLoaderOptions()                ← escape hatch: crossbind state passed to other rules
+  .setDevServerMiddleware(...)        ← internal, called by getDevServerConfig
+```
+
+User config consumes all four; see `docs/playbooks/integration/webpack-rspack.md` for the canonical wiring.
+
+## Hooks the plugin registers
+
+| webpack hook | What it does |
+|--------------|--------------|
+| `compiler.hooks.done` | After every compilation: re-run `createLib + createXCFramework + buildWasm` (mtime-aware via `isSourceNewer`) |
+| `compiler.hooks.afterCompile` | Adds `state.config.paths.native` to `compilation.contextDependencies` so webpack watch picks up `.cpp`/`.h` edits |
+
+## DevServer middleware
+
+`getDevServerConfig()` returns:
+
+```js
+{
+  watchFiles: state.config.paths.native,
+  hot: true,
+  liveReload: true,
+  headers: {
+    'Cross-Origin-Opener-Policy': 'same-origin',
+    'Cross-Origin-Embedder-Policy': 'require-corp',
+  },
+  setupMiddlewares: (middlewares, devServer) => { ... }
+}
+```
+
+The middleware adds `/crossbind.js` and `/crossbind.wasm` routes that pipe the freshly built artifacts. Both routes also re-emit COOP/COEP per-response (belt-and-suspenders for caching layers that strip top-level headers).
+
+## Rspack compatibility
+
+Rspack copies webpack's plugin / loader shape. The plugin works without modification. The Rspack-specific wrinkle: `getRule()` returns a plain object that Rspack's TypeScript-strict config types may complain about — cast to `RspackOptions['module']['rules'][number]` if needed.
+
+## Common pitfalls
+
+- **Forgetting `getRule()` while passing the plugin instance.** The `.h` loader rule and the plugin instance are independent registrations; both are required.
+- **Wrapping the plugin's `getDevServerConfig()` and dropping `headers`.** Always spread: `{ ...cppDev, ...custom, headers: { ...cppDev.headers, ...custom.headers } }`.
+- **Trying to inject `getRule()` into `plugins:` array** instead of `module.rules:`. They are distinct.
+- **Babel/SWC running on `.h` first.** Loader chain order matters; `getRule()` test is `/\.h$/` so other rules with broader tests can swallow it. Make sure no rule for `/\.[jt]sx?$/` accidentally matches `.h` (none do by default).
+- **Adding `console.log` for debugging.** Route through `crossbind` exports — `state.config` carries the logger if you need it. Plugin output should be quiet by default.
+
+## Validation
+
+Strict gate:
+
+```bash
+pnpm run ci:linux:build && pnpm run e2e:dev && pnpm run e2e:prod
+```
+
+Smoke samples:
+
+```bash
+pnpm --filter=@crossbind/example-web-react-rspack run build
+pnpm --filter=@crossbind/e2e-web-rspack run build
+```
+
+If you touch the dev-server middleware, also test:
+
+```bash
+pnpm --filter=@crossbind/example-web-react-rspack exec rspack serve
+# verify in browser: COOP/COEP headers present, /crossbind.wasm 200
+```
+
+## Reference
+
+- Loader package: `plugins/webpack-loader/`
+- Integration recipe: `docs/playbooks/integration/webpack-rspack.md`
+- Next.js variant (no devServer): `docs/playbooks/integration/nextjs.md`
+- Canonical samples: `examples/web-react-rspack`, `e2e/web-rspack`

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# @crossbind/plugin-webpack
+
+## 2.0.0-beta.50
+
+### Patch Changes
+
+- A cargo dependency no longer has to be built by hand before the app. The dependency step this
+  plugin already awaits builds one whose target is missing, and refuses to link one it could not
+  build — on wasm that case used to pass silently and leave a module that died at init.
+
+## 1.0.2
+
+### Patch Changes
+
+- Updated dependencies
+  - crossbind@1.0.4
+
+## 1.0.0
+
+### Major Changes
+
+- 🚀 first stable release
+
+### Patch Changes
+
+- Updated dependencies
+  - crossbind@1.0.0
+
+## 1.0.0-beta.10
+
+### Patch Changes
+
+- chore: add initial version of CHANGELOGS files
+- Updated dependencies
+  - crossbind@1.0.0-beta.33

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Buğra Sarı and crossbind contributors
+
+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,145 @@
+# @crossbind/plugin-webpack
+**crossbind Webpack plugin**  
+A tool for seamless C++ integration with the Webpack bundler.
+
+<a href="https://www.npmjs.com/package/@crossbind/plugin-webpack">
+    <img alt="NPM version" src="https://img.shields.io/npm/v/@crossbind/plugin-webpack?style=for-the-badge" />
+</a>
+<a href="https://github.com/crossbind/crossbind/blob/main/LICENSE">
+    <img alt="License" src="https://img.shields.io/github/license/crossbind/crossbind?style=for-the-badge" />
+</a>
+<a href="https://crossbind.js.org/docs/guide/integrate-into-existing-project/webpack">
+    <img alt="Docs - React Native" src="https://img.shields.io/badge/Docs_-_Webpack-20B2AA?style=for-the-badge" />
+</a>
+
+## Integration
+To integrate crossbind into your project using Webpack as a bundler, you can utilize the @crossbind/plugin-webpack plugin. Start by installing these package with the following command:
+
+```sh
+npm install @crossbind/plugin-webpack @crossbind/plugin-webpack-loader --save-dev
+```
+
+**Webpack**  
+To enable the plugin, modify the `webpack.config.js` file as shown below.
+
+```diff
++ const CrossbindWebpackPlugin = require('@crossbind/plugin-webpack');
++ const crossbindWebpackPlugin = new CrossbindWebpackPlugin();
++ const compiler = crossbindWebpackPlugin.getCompiler();
+
+module.exports = {
+  //...
+  plugins: [
++   crossbindWebpackPlugin,
+  ],
+  module: {
+    rules: [
++     {
++       test: /\.h$/,
++       loader: '@crossbind/plugin-webpack-loader',
++       options: { compiler },
++     }
+    ],
+  },
+};
+```
+
+**Rspack**  
+To enable the plugin, modify the `rspack.config.mjs` file as shown below.
+
+```diff
++ import CrossbindWebpackPlugin from '@crossbind/plugin-webpack';
+
++ const crossbindWebpackPlugin = new CrossbindWebpackPlugin();
++ const compiler = crossbindWebpackPlugin.getCompiler();
+
+export default defineConfig({
+	module: {
+		rules: [
++            {
++                test: /\.h$/,
++                loader: '@crossbind/plugin-webpack-loader',
++                options: { compiler },
++            }
+		]
+	},
+	plugins: [
++         crossbindWebpackPlugin,
+	].filter(Boolean),
++     devServer: {
++         watchFiles: compiler.config.paths.native,
++         setupMiddlewares: (middlewares, devServer) => {
++             if (!devServer) {
++                 throw new Error('@rspack/dev-server is not defined');
++             }
++ 
++             middlewares.unshift({
++                 name: '/crossbind.js',
++                 path: '/crossbind.js',
++                 middleware: (req, res) => {
++                     res.sendFile(`${compiler.config.paths.temp}/${compiler.config.general.name}.browser.js`);
++                 },
++             });
++             middlewares.unshift({
++                 name: '/crossbind.wasm',
++                 path: '/crossbind.wasm',
++                 middleware: (req, res) => {
++                     res.send(fs.readFileSync(`${compiler.config.paths.temp}/${compiler.config.general.name}.wasm`));
++                 },
++             });
++ 
++             return middlewares;
++         },
++     },
+});
+```
+
+**Craco**  
+To enable the plugin, create the `craco.config.js` file as shown below.
+
+```js
+const fs = require('fs');
+
+module.exports = async function () {
+    const { default: CrossbindWebpackPlugin } = await import('@crossbind/plugin-webpack');
+    const crossbindWebpackPlugin = new CrossbindWebpackPlugin();
+    const compiler = crossbindWebpackPlugin.getCompiler();
+
+    return {
+        webpack: {
+            plugins: {
+                add: [crossbindWebpackPlugin],
+            },
+            configure: (config) => {
+                config.module.rules[1].oneOf = [
+                    {
+                        test: /\.h$/,
+                        loader: '@crossbind/plugin-webpack-loader',
+                        options: { compiler },
+                    },
+                    ...config.module.rules[1].oneOf,
+                ];
+                return config;
+            },
+        },
+        devServer: (devServerConfig) => {
+            devServerConfig.watchFiles = compiler.config.paths.native;
+            devServerConfig.onBeforeSetupMiddleware = (devServer) => {
+                if (!devServer) {
+                  throw new Error('webpack-dev-server is not defined');
+                }
+
+                devServer.app.get('/crossbind.js', function (req, res) {
+                  res.sendFile(`${compiler.config.paths.temp}/${compiler.config.general.name}.browser.js`);
+                });
+
+                devServer.app.get('/crossbind.wasm', function (req, res) {
+                    res.send(fs.readFileSync(`${compiler.config.paths.temp}/${compiler.config.general.name}.wasm`));
+                });
+            };
+
+            return devServerConfig;
+        },
+    };
+};
+```

package/index.js

@@ -0,0 +1,176 @@
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+    state, createLib, buildWasm, createBridgeFile, getData, getCrossbindScript, getRustJsScript, getDependFilePath, buildDependencies, getTargetParams, getFilteredBuildTargets, isSourceNewer,
+} from 'crossbind';
+
+const targetParams = getTargetParams({ platform: ['wasm'], arch: ['wasm32'], runtime: ['st'], runtimeEnv: ['browser'] }, true);
+let buildTargetRelease = getFilteredBuildTargets(targetParams, { buildType: 'release' })?.[0];
+let buildTargetDebug = getFilteredBuildTargets(targetParams, { buildType: 'debug' })?.[0];
+
+if (!buildTargetRelease && !buildTargetDebug) {
+    throw new Error('No build targets found');
+}
+
+if (!buildTargetDebug) {
+    buildTargetDebug = buildTargetRelease;
+} else if (!buildTargetRelease) {
+    buildTargetRelease = buildTargetDebug;
+}
+
+export default class CrossbindWebpackPlugin {
+    static defaultOptions = {};
+
+    constructor(options = {}) {
+        this.options = { ...CrossbindWebpackPlugin.defaultOptions, ...options };
+        this.bridges = [];
+    }
+
+    apply(compiler) {
+        const pluginName = this.constructor.name;
+        compiler.options.resolve = compiler.options.resolve || {};
+        compiler.options.resolve.alias = compiler.options.resolve.alias || {};
+        // `cargo:` imports use the node:/npm: convention for a non-npm store; webpack's resolver
+        // has no such scheme, so the request is rewritten to the generated marker .rs (which the
+        // loader then turns into the crate-import bridge). Works on rspack via its compat layer.
+        new compiler.webpack.NormalModuleReplacementPlugin(/^cargo:/, (resource) => {
+            const marker = getDependFilePath(resource.request, buildTargetRelease);
+            if (marker) resource.request = marker;
+        }).apply(compiler);
+        // Rust packages ship no JS entry at all (their package.json is just a name), so node
+        // resolution can never find them. Each known cargo-type dependency gets an exact-match
+        // alias onto its crate root; the loader's .rs branch turns that into the proxy module.
+        for (const dep of state.config.allDependencies ?? []) {
+            if (dep.export?.type !== 'cargo' || !dep.package?.name) continue;
+            const libRs = path.resolve(dep.paths.project, dep.export.crate ?? 'crate', 'src/lib.rs');
+            if (fs.existsSync(libRs) && !(`${dep.package.name}$` in compiler.options.resolve.alias)) {
+                compiler.options.resolve.alias[`${dep.package.name}$`] = libRs;
+            }
+        }
+        // tapPromise (not tap) so webpack awaits the native C++/wasm build and a build
+        // failure surfaces as a compilation error instead of an unhandled rejection.
+        compiler.hooks.done.tapPromise(pluginName, this.onDone.bind(this));
+        compiler.hooks.afterCompile.tapAsync(pluginName, this.afterCompile.bind(this));
+    }
+
+    afterCompile(compilation, callback) {
+        state.config.paths.native.map((file) => compilation.contextDependencies.add(file));
+        callback();
+    }
+
+    async onDone({ compilation }) {
+        const isDev = compilation.options.mode === 'development';
+        const buildTarget = isDev ? buildTargetDebug : buildTargetRelease;
+        await buildDependencies({ targetParams: { ...targetParams, buildType: [buildTarget.buildType] } });
+        const force = isSourceNewer(buildTarget);
+        const sourceBuilt = createLib(buildTarget, 'Source', { force, buildSource: true });
+        // Bridge cache is keyed on the nativeGlob fingerprint: a changed bridge
+        // set rebuilds the lib even without source changes, and a rebuilt lib
+        // must force the final link too.
+        const bridgeBuilt = createLib(buildTarget, 'Bridge', { force, buildSource: false, nativeGlob: [`${state.config.paths.cli}/assets/cpp-runtime/commonBridges.cpp`, ...this.bridges] });
+        await buildWasm(buildTarget, { force: force || Boolean(sourceBuilt) || Boolean(bridgeBuilt) });
+        if (!isDev) {
+            const output = state.config.paths.output === state.config.paths.build ? compilation.options.output.path : state.config.paths.output;
+            // On a first-ever build the output dir may not exist yet when this
+            // hook runs; copyFileSync reports that as ENOENT too.
+            fs.mkdirSync(output, { recursive: true });
+            fs.copyFileSync(`${state.config.paths.build}/${buildTarget.jsName}`, `${output}/crossbind.js`);
+            fs.copyFileSync(`${state.config.paths.build}/${buildTarget.wasmName}`, `${output}/crossbind.wasm`);
+
+            const dataFilePath = `${state.config.paths.build}/${buildTarget.dataTxtName}`;
+            if (fs.existsSync(dataFilePath)) {
+                fs.copyFileSync(dataFilePath, `${output}/crossbind.data.txt`);
+            }
+            /* const workerFilePath = `${state.config.paths.build}/${state.config.general.name}.js`;
+            if (fs.existsSync(workerFilePath)) {
+                fs.copyFileSync(workerFilePath, `${output}/cpp.worker.js`);
+            } */
+        }
+    }
+
+    getLoaderOptions() {
+        return {
+            bridges: this.bridges,
+            createBridgeFile,
+            getData,
+            state,
+            getCrossbindScript,
+            getRustJsScript,
+            getTargetParams,
+            getFilteredBuildTargets
+        };
+    }
+
+    getRule() {
+        return {
+            // `rs` rides the same rule: the loader branches on the extension.
+            test: new RegExp(`\\.(${[...state.config.ext.header, 'rs'].join('|')})$`),
+            loader: '@crossbind/plugin-webpack-loader',
+            options: { ...this.getLoaderOptions() },
+        };
+    }
+
+    setDevServerMiddleware(middlewares, devServer) {
+        if (!devServer) {
+            throw new Error('devServer is not defined');
+        }
+
+        middlewares.unshift({
+            name: '/crossbind.js',
+            path: '/crossbind.js',
+            middleware: (req, res) => {
+                const filePath = `${state.config.paths.build}/${buildTargetDebug.jsName}`;
+                res.setHeader('Content-Type', 'application/javascript');
+                res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+                res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+                fs.createReadStream(filePath).pipe(res);
+            },
+        });
+
+        middlewares.unshift({
+            name: '/crossbind.wasm',
+            path: '/crossbind.wasm',
+            middleware: (req, res) => {
+                const filePath = `${state.config.paths.build}/${buildTargetDebug.wasmName}`;
+                res.setHeader('Content-Type', 'application/wasm');
+                res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+                res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+                fs.createReadStream(filePath).pipe(res);
+            },
+        });
+
+        middlewares.unshift({
+            name: '/crossbind.data.txt',
+            path: '/crossbind.data.txt',
+            middleware: (req, res) => {
+                const filePath = `${state.config.paths.build}/${buildTargetDebug.dataTxtName}`;
+                res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+                res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+                if (!fs.existsSync(filePath)) {
+                    res.statusCode = 404;
+                    res.end();
+                    return;
+                }
+                fs.createReadStream(filePath).pipe(res);
+            },
+        });
+
+        return middlewares;
+    }
+
+    getDevServerConfig() {
+        return {
+            watchFiles: state.config.paths.native,
+            hot: true,
+            liveReload: true,
+            headers: {
+                'Cross-Origin-Opener-Policy': 'same-origin',
+                'Cross-Origin-Embedder-Policy': 'require-corp',
+            },
+            setupMiddlewares: (middlewares, devServer) => {
+                return this.setDevServerMiddleware(middlewares, devServer);
+            },
+        };
+    }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@crossbind/plugin-webpack",
+  "version": "2.0.0-beta.50",
+  "description": "crossbind Webpack plugin: A tool for seamless C++ integration with the Webpack bundler.",
+  "homepage": "https://github.com/crossbind/crossbind/tree/main/plugins/webpack#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "dependencies": {
+    "crossbind": "^2.0.0-beta.50",
+    "@crossbind/core-embind-rust": "^2.0.0-beta.50"
+  },
+  "peerDependencies": {
+    "webpack": ">=5.109.2"
+  },
+  "keywords": [
+    "crossbind-plugin",
+    "webpack",
+    "bind",
+    "c++"
+  ]
+}