swipl-wasm 5.2.9 → 7.0.0

package/README.md

@@ -155,6 +155,43 @@ npm run server
 Then visit <http://127.0.0.1:8080>. You should see the message "Hello world from
 Prolog".
 
+### Webpack Configuration for Browser Builds
+
+When bundling `swipl-wasm` with Webpack for the browser, the underlying
+Emscripten-generated code may import Node.js built-in modules using the `node:`
+scheme (e.g. `node:fs`, `node:crypto`). Webpack does not handle the `node:`
+scheme by default and will produce errors like:
+
+```
+Module build failed: UnhandledSchemeError: Reading from "node:fs" is not handled by plugins (Unhandled scheme).
+```
+
+To fix this, add the following to your `webpack.config.js`:
+
+```js
+const { NormalModuleReplacementPlugin } = require('webpack');
+
+module.exports = {
+  // ...your existing config
+  resolve: {
+    fallback: {
+      path: false,
+      fs: false,
+      crypto: false,
+      perf_hooks: false,
+    },
+  },
+  plugins: [
+    new NormalModuleReplacementPlugin(/^node:/, (resource) => {
+      resource.request = resource.request.replace(/^node:/, '');
+    }),
+  ],
+};
+```
+
+The `NormalModuleReplacementPlugin` strips the `node:` prefix so that the
+imports are resolved by the `resolve.fallback` entries, which map them to
+`false` (i.e. empty modules) since they are not needed in the browser.
 
 ## Browser Builds
 
@@ -211,6 +248,20 @@ The package can be built using npm. Please use npm to add new dependencies
 and update the package-lock.json file. The SWI-Prolog WebAssembly version is
 currently built inside Docker with Emscripten.
 
+### Serving Files
+
+When self-hosting the bundled files, ensure your server includes `charset=utf-8` in the `Content-Type` header for JavaScript files:
+
+```
+Content-Type: text/javascript; charset=utf-8
+```
+
+Without the charset, WASM streaming instantiation may fail in headless browsers with errors like:
+- Firefox: `CompileError: wasm validation error: at offset 642: byte size mismatch in type section`
+- Chromium: `CompileError: WebAssembly.instantiate(): section was shorter than expected size`
+
+Most static file servers (e.g., `express.static()`) set this automatically, but custom streaming handlers using `createReadStream().pipe(res)` may not.
+
 ### Development
 
 To develop with this package, clone the repository and run: