Virtual File System
Relevant source files
The following files were used as context for generating this wiki page:
The Virtual File System (VFS) in Bolt is a browser-based abstraction layer that interfaces with the StackBlitz WebContainer API to provide a full-stack Node.js environment directly in the user's browser. It enables AI agents and users to perform standard filesystem operations—such as creating, reading, updating, and deleting files—without the need for remote servers or local installations. Sources: CONTRIBUTING.md:1-20
The VFS architecture is primarily managed through the FilesStore, which synchronizes the in-memory state of the application with the WebContainer's actual filesystem. This system allows the AI to have complete control over the environment, including installing packages via npm and running Node.js servers. Sources: CONTRIBUTING.md:43-50, app/lib/stores/files.ts:25-45
Core Architecture and Data Storage
The VFS is structured around a centralized store that tracks the state of all files and folders within the project directory. The primary data structure is a FileMap, which maps file paths to Dirent objects (either a File or a Folder).
Data Structures
| Structure | Type | Description |
|---|---|---|
File | interface | Represents a file with its content (string) and a isBinary flag. |
Folder | interface | Represents a directory entry. |
FileMap | Record<string, Dirent> | A map where keys are file paths and values are file or folder objects. |
EditorDocument | interface | State for a file specifically when opened in the editor, including scroll position. |
Sources: app/lib/stores/files.ts:16-29, app/lib/stores/editor.ts:4-5
File Synchronization Flow
The following diagram illustrates how the FilesStore maintains synchronization between the WebContainer filesystem and the UI state.
The system uses a path watcher to observe changes within the working directory (WORK_DIR), excluding node_modules and .git to maintain performance. Sources: app/lib/stores/files.ts:88-100
FilesStore Logic
The FilesStore class is the central coordinator for filesystem operations. It initializes by mounting a watcher on the WebContainer's internal filesystem.
Event Processing
When changes occur in the filesystem (e.g., from a shell command or AI action), the FilesStore processes them through a buffered event handler:
- add_dir / remove_dir: Updates the
FileMapto reflect directory changes. Folders are distinguished in the tree by a trailing slash. - add_file / change: Decodes the file content using
TextDecoder(UTF-8). If a file is detected as binary, content decoding is skipped to prevent editor issues. - remove_file: Decrements the internal file count and removes the entry from the store.
Sources: app/lib/stores/files.ts:102-155
Binary Detection
The VFS uses a "best guess" approach to identify binary files by checking a chunk of the file buffer (typically the first 100 bytes). This prevents the editor from attempting to render non-textual data. Sources: app/lib/stores/files.ts:168-175
Modification Tracking and Diffs
To communicate changes back to the AI model efficiently, the VFS tracks modifications made by the user.
Diff Generation
When a file is saved, the VFS stores the original content in a #modifiedFiles map. Before sending data back to the LLM, it computes a unified diff between the original and current state. If a diff is larger than the file content itself, the system defaults to sending the full file content to optimize token usage. Sources: app/utils/diff.ts:24-45, app/lib/stores/files.ts:39-44
The final modifications are wrapped in a custom <bolt_file_modifications> HTML tag for the AI to parse. Sources: app/utils/diff.ts:88-105
UI Integration: File Tree and Navigation
The VFS state is visualized through the FileTree and FileBreadcrumb components.
File Tree Organization
The FileTree component builds a hierarchical view from the flat FileMap. It implements:
- Sorting: Folders are displayed before files, and items are sorted alphabetically.
- Filtering: Standard directories like
node_modules,.next, and.astroare hidden by default. - Collapsing: Users can toggle folder visibility, which is tracked via a
Setof collapsed paths.
Sources: app/components/workbench/FileTree.tsx:11-30, app/components/workbench/FileTree.tsx:162-210
Breadcrumb Navigation
The FileBreadcrumb allows users to navigate the directory structure via a segmented path display. Each segment (excluding the root and current file) can be clicked to open a dropdown containing a sub-tree of that specific directory. Sources: app/components/workbench/FileBreadcrumb.tsx:64-105
Workbench and Editor Interaction
The WorkbenchStore acts as a high-level orchestrator that connects the FilesStore with the EditorStore.
- Document Management: When files are loaded, the
EditorStorecreatesEditorDocumentobjects which track the text value and scroll positions. Sources: app/lib/stores/editor.ts:31-50 - Unsaved States: The system maintains a
SetofunsavedFiles. A file is considered unsaved if its current content in the editor differs from the content stored in theFilesStore. Sources: app/lib/stores/workbench.ts:100-115 - Auto-Selection: Upon loading a project, the Workbench automatically selects the first available file in the project to display in the editor. Sources: app/lib/stores/workbench.ts:85-93
Summary
The Virtual File System is a robust synchronization engine that bridges the gap between a sandboxed browser environment (WebContainer) and a reactive UI. By utilizing atomic stores and efficient diffing algorithms, it provides a seamless development experience where AI-generated changes and user edits are tracked, visualized, and persisted in real-time. Sources: app/lib/stores/workbench.ts:14-30, CONTRIBUTING.md:25-35