@utoo/web

@utoo/web enables a complete web development environment in the browser, including a file system, dependency management, and build process. It integrates @utoo/pack (Rust + Turbopack), targeting wasm32-unknown-unknown.

Core Concepts

1. Real File System: The project lives in the browser’s Origin Private File System (OPFS) . Project provides a Node.js-like fs interface.
2. Project Main Worker: The Project instance runs in a Web Worker. The main thread object is a proxy, keeping the UI responsive.
3. Thread Worker: Heavy tasks (bundling, compilation) run in a dedicated Web Worker powered by a ported tokio runtime.
4. Loader Worker: Executes Webpack loaders in a dedicated worker with Node.js polyfills.
5. Service Worker: Acts as a local server to intercept requests and serve built files for preview.

File Watching & Incremental Builds

@utoo/web leverages the modern FileSystemObserver API  to implement efficient file system watching directly in the browser. This is crucial for supporting Turbopack’s incremental build capabilities.

1. FileSystemObserver Integration: The tokio-fs-ext crate (used by utoo-wasm) provides a watch module that wraps the FileSystemObserver API. This allows the Rust code to receive notifications about file changes in the Origin Private File System (OPFS).

2. OpfsOffload Layer: The implementation of OpfsOffload  not only solves the thread safety issue of JS objects in Rust (allowing multiple Rust threads to call OPFS concurrently) but also extends the turbo-tasks-fs file system with minimal intrusiveness. When a file change is detected, the event is also propagated through this layer to the Turbopack engine running in the WASM environment.

3. Incremental Compilation: Turbopack’s architecture is built on a reactive graph. When it receives a file change event, it invalidates only the affected parts of the dependency graph. This triggers a re-computation (rebuild) of only the changed modules and their dependents, resulting in extremely fast updates.

This architecture ensures that @utoo/web delivers a responsive development experience even for large projects running entirely within the browser.

Server Requirements

You must configure your server to send the following two headers:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

This is a security requirement browsers enforce to enable powerful features like SharedArrayBuffer, which are essential for the multi-threaded performance of the underlying WebAssembly components.

Example: webpack-dev-server

module.exports = {
  devServer: {
    headers: {
      "Cross-Origin-Opener-Policy": "same-origin",
      "Cross-Origin-Embedder-Policy": "require-corp",
    },
  },
};