@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.

It does not rely on Web Containers, avoiding the runtime overhead (such as startup latency and memory usage) associated with Node.js environment emulation.

Core Concepts

Real File System: The project lives in the browser’s Origin Private File System (OPFS) . Project provides a Node.js-like fs interface.
Project Main Worker: The Project instance runs in a Web Worker. The main thread object is a proxy, keeping the UI responsive.
Thread Worker: Heavy tasks (bundling, compilation) run in a dedicated Web Worker powered by a ported tokio runtime.
Loader Worker: Executes Webpack loaders in a dedicated worker with Node.js polyfills.
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.

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).
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.
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

To use @utoo/web, your server must serve the application with specific HTTP headers to create a cross-origin isolated environment.

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

webpack.config.js


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

Notes

Since the default memory allocator on Rust, dlmalloc, does not perform ideally on multi-threaded wasm, we have ported mimalloc to the wasm32-unknown-unknown platform to support running builds with threads equal to the number of CPU cores. Therefore, the difference in build performance between the browser environment and the operating system environment is very small.
In the future, we will also support the HMR feature in the browser.
Advanced features of turbopack such as persistent caching, are also in the plan and will be supported directly in the browser in the future.