Preview & Workbench
Relevant source files
The following files were used as context for generating this wiki page:
The Preview & Workbench system serves as the primary integrated development environment (IDE) interface within the Bolt application. It provides a split-view workspace that allows users to alternate between a code editor and a live preview of the application being developed. The Workbench is tightly integrated with WebContainers to execute code and serve web applications directly in the browser.
This module manages the lifecycle of artifacts generated by the AI, handles file system synchronization, and provides a terminal for manual environment interaction. It is designed to be responsive, appearing only after a chat session has started and offering a seamless transition between development (Code) and verification (Preview) modes.
Sources: app/components/workbench/Workbench.client.tsx:43-149, CONTRIBUTING.md:23-28
Core Architecture
The Workbench is implemented as a client-side component that coordinates several specialized stores and sub-panels. It utilizes a state management pattern powered by nanostores to sync data between the chat interface and the development environment.
Workbench Hierarchy
The following diagram illustrates the relationship between the main Workbench component and its primary sub-modules.
The Workbench component switches views based on the currentView state, which can be either 'code' or 'preview'.
Sources: app/components/workbench/Workbench.client.tsx:43-60, app/lib/stores/workbench.ts:28-40
State Management
The WorkbenchStore acts as a central hub, orchestrating multiple underlying stores to manage different aspects of the environment.
| Store | Responsibility | Source |
|---|---|---|
PreviewsStore | Tracks active network ports and provides URLs for the iframe preview. | app/lib/stores/previews.ts |
FilesStore | Manages the virtual file system within the WebContainer. | app/lib/stores/workbench.ts:31 |
EditorStore | Handles the state of open documents, scroll positions, and selection. | app/lib/stores/editor.ts |
TerminalStore | Manages terminal instances and visibility state. | app/lib/stores/workbench.ts:33 |
Preview System
The Preview panel renders the application running inside the WebContainer using an iframe. It dynamically detects open ports and provides an address bar for navigation within the sandboxed environment.
Port Detection and Selection
The PreviewsStore listens for port events from the WebContainer API. When a port is opened (typically by a dev server), it is added to the previews atom. If multiple ports are available, the system defaults to displaying the lowest port number unless the user manually selects another via the PortDropdown.
Sources: app/lib/stores/previews.ts:25-45, app/components/workbench/Preview.tsx:49-55
URL Validation Logic
The address bar includes logic to ensure users stay within the allowed base URL of the WebContainer preview.
const validateUrl = useCallback(
(value: string) => {
if (!activePreview) return false;
const { baseUrl } = activePreview;
if (value === baseUrl) return true;
else if (value.startsWith(baseUrl)) {
return ['/', '?', '#'].includes(value.charAt(baseUrl.length));
}
return false;
},
[activePreview],
);
Sources: app/components/workbench/Preview.tsx:28-43
Editor Panel
The Editor Panel is a complex multi-pane interface managed by react-resizable-panels. It contains the file explorer, the code editor, and the integrated terminal.
Layout Components
- FileTree: Displays a hierarchical view of the project structure, allowing users to select files for editing. It supports folder collapsing and identifies unsaved changes with a visual indicator.
- CodeMirrorEditor: A highly configurable editor using CodeMirror 6. It handles syntax highlighting, line numbers, and synchronization with the
EditorStore. - Terminal: A drawer-style component at the bottom of the panel that can be toggled via the Workbench header or keyboard shortcuts.
Sources: app/components/workbench/EditorPanel.tsx:68-156, app/components/workbench/FileTree.tsx:186-214
File Synchronization Flow
When a user edits a file, the changes are propagated through the stores to ensure the WebContainer filesystem remains in sync.
Artifact Management
The Workbench is responsible for executing "Artifacts"—sets of instructions or code changes generated by the AI. Each artifact has an id, a title, and an ActionRunner that executes specific commands (e.g., shell commands or file writes).
| Feature | Description |
|---|---|
| ActionRunner | Handles the execution of individual actions within an artifact. |
| Artifact Lifecycle | Artifacts are added via addArtifact and updated as the AI streams content. |
| Streaming Support | The Workbench can receive and queue actions while the AI is still generating the message. |
| Sources: app/lib/stores/workbench.ts:12-20, app/lib/stores/workbench.ts:184-211 |
Conclusion
The Preview & Workbench system provides the essential bridge between AI-generated code and a functional development environment. By abstracting WebContainer complexities into a unified UI and state management layer, it enables a "prompt-to-app" workflow where code is not only written but immediately executed and verified within the browser.
Sources: CONTRIBUTING.md:23-28, app/components/workbench/Workbench.client.tsx:140-149