WebContainer Integration

Relevant source files

The following files were used as context for generating this wiki page:

• app/lib/webcontainer/index.ts
• app/lib/runtime/action-runner.ts
• app/lib/stores/workbench.ts
• app/lib/stores/files.ts
• app/lib/stores/terminal.ts
• app/lib/stores/previews.ts
• README.md
• CONTRIBUTING.md

WebContainer Integration is the core architectural component of the Bolt platform, enabling a full-stack development environment to run entirely within the user's browser. By leveraging StackBlitz's WebContainer API, the application provides a sandboxed Node.js environment that includes a virtual filesystem, a package manager, and a terminal, allowing AI-generated code to be executed, edited, and previewed without remote virtual machines or local installations.

Sources: README.md:16-24, CONTRIBUTING.md:16-24

Core Architecture and Bootstrapping

The integration centers around a singleton webcontainer promise that initializes the WebContainer instance. This instance is booted with a specific working directory name and managed through a context object that tracks its loading state.

The diagram shows the lifecycle of the WebContainer initialization process from application boot to store integration.
Sources: app/lib/webcontainer/index.ts:1-29

WebContainer Context and Lifecycle

The system ensures that only one instance of the WebContainer is booted during the client-side lifecycle. This is handled by checking the import.meta.env.SSR flag and caching the promise in import.meta.hot for development environments to maintain state across Hot Module Replacement (HMR).

Component	Description	Source
webcontainer	A exported Promise that resolves to the booted WebContainer instance.	index.ts:16
webcontainerContext	An object tracking whether the container has finished loading (loaded: boolean).	index.ts:7-13
WORK_DIR_NAME	The constant defining the root directory for the WebContainer environment.	index.ts:22

Action Execution and Runtime

The ActionRunner class is responsible for executing specific tasks within the WebContainer environment. It processes actions requested by the AI, such as running shell commands or writing files to the virtual filesystem.

The sequence diagram illustrates how actions are dispatched to the WebContainer's shell and filesystem interfaces.
Sources: app/lib/runtime/action-runner.ts:47-147

Action Types and Logic

The ActionRunner handles two primary types of interactions:

1. Shell Actions: Uses webcontainer.spawn to execute commands in a jsh shell. It pipes the output to the console and handles process termination via AbortSignal.
2. File Actions: Uses webcontainer.fs.writeFile to persist content. It automatically creates parent directories recursively using mkdir before writing.

Sources: app/lib/runtime/action-runner.ts:107-147

Filesystem Management

The FilesStore synchronizes the application's internal state with the WebContainer's filesystem. It utilizes a path watcher to listen for changes within the environment and update the UI in real-time.

File Event Handling

The store watches the ${WORK_DIR}/** path, excluding node_modules and .git. When events occur, it processes them into the internal files map.

Event Type	Action Taken
add_dir	Adds a folder entry to the map with a trailing slash.
remove_dir	Removes the directory and all nested children from the map.
add_file / change	Decodes the buffer and updates the file content; detects if a file is binary.
remove_file	Decrements the file count and clears the map entry.

Sources: app/lib/stores/files.ts:89-144

Terminal and Preview Services

The integration extends to interactive elements including a terminal emulator and live web previews.

Terminal Integration

The TerminalStore manages the connection between the UI terminal and the WebContainer shell. It spawns new shell processes and handles terminal resizing events to ensure the container's PTY (Pseudo-Terminal) matches the UI dimensions.
Sources: app/lib/stores/terminal.ts:11-40

Preview Monitoring

The PreviewsStore listens for 'port' events emitted by the WebContainer. When a server starts inside the container and begins listening on a port, the store captures the URL and updates the available previews.

The flow shows how network ports within the WebContainer are mapped to UI preview frames.
Sources: app/lib/stores/previews.ts:23-45

Conclusion

WebContainer Integration serves as the foundation of Bolt, enabling a seamless transition from AI generation to code execution. By centralizing the management of the WebContainer instance and distributing its capabilities through specialized stores (FilesStore, TerminalStore, PreviewsStore), the architecture ensures that the virtual environment remains the "source of truth" for the entire application.

Sources: app/lib/stores/workbench.ts:25-31, CONTRIBUTING.md:27-32