WebContainer Bootstrapping
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
WebContainer bootstrapping is the critical initialization process that enables the Bolt application to run full-stack Node.js environments directly within the browser. By leveraging the @webcontainer/api, the application creates a sandboxed development environment including a virtual filesystem, a package manager, and a terminal, all running client-side without the need for remote virtual machines. Sources: CONTRIBUTING.md:12-20, app/lib/webcontainer/index.ts:21-28
This system serves as the foundation for the AI-powered development agent, allowing it to execute shell commands, manage files, and serve web applications. The bootstrapping process ensures that the environment is globally available through a shared Promise<WebContainer>, which is consumed by various application stores to synchronize the UI with the underlying container state. Sources: app/lib/webcontainer/index.ts:16-30, app/lib/stores/workbench.ts:26-30
Core Initialization Logic
The bootstrapping logic is centralized in the app/lib/webcontainer module. It utilizes a singleton-like pattern to ensure that the WebContainer is only booted once during the application lifecycle, specifically on the client-side (non-SSR). Sources: app/lib/webcontainer/index.ts:16-33
The Boot Sequence
The system checks if the environment is Server-Side Rendering (SSR). If not, it initiates WebContainer.boot() with a specific configuration. The resulting instance is stored in a exported promise.
The diagram shows the conditional logic used to prevent multiple instances and handle Hot Module Replacement (HMR) during development. Sources: app/lib/webcontainer/index.ts:21-34
Key Boot Components
| Component | Description | Source |
|---|---|---|
webcontainer | An exported Promise<WebContainer> used by stores to access the container once ready. | app/lib/webcontainer/index.ts:16-18 |
webcontainerContext | A reactive object tracking the loaded status of the container. | app/lib/webcontainer/index.ts:7-13 |
WORK_DIR_NAME | The configuration parameter defining the working directory inside the container. | app/lib/webcontainer/index.ts:25 |
Subsystem Integration
Once the WebContainer is bootstrapped, several specialized stores consume the instance to initialize their specific domains. Sources: app/lib/stores/workbench.ts:26-31
Filesystem Synchronization
The FilesStore subscribes to the container's internal path watcher. It monitors the WORK_DIR (excluding node_modules and .git) to update a local MapStore of files and folders.
- Path Watching: Uses
webcontainer.internal.watchPaths. - Decoding: Uses
TextDecoderfor text files while identifying binary files.
Sources: app/lib/stores/files.ts:60-72, app/lib/stores/files.ts:98-106
Preview and Port Management
The PreviewsStore listens for port events emitted by the WebContainer instance. This allows the application to detect when a Node.js server starts listening inside the sandbox and provides a URL for the browser iframe. Sources: app/lib/stores/previews.ts:22-48
Runtime Action Execution
The ActionRunner utilizes the bootstrapped container to spawn processes.
- Shell Actions: Uses
webcontainer.spawn('jsh', ...)to execute terminal commands. - File Actions: Uses
webcontainer.fs.writeFileandmkdirfor persistent changes.
Sources: app/lib/runtime/action-runner.ts:98-110, app/lib/runtime/action-runner.ts:133-145
State Flow Diagram
The following sequence diagram illustrates how the WorkbenchStore orchestrates the flow from bootstrapping to terminal attachment.
Summary
WebContainer Bootstrapping is the gateway to the Bolt environment. It initializes a shared container instance that powers the virtual filesystem, network previews, and the shell runner. By managing this as a shared promise, the application ensures that components like the FileTree, Terminal, and ActionRunner stay in sync with the sandboxed environment's state. Sources: app/lib/webcontainer/index.ts app/lib/stores/workbench.ts