File System State

Relevant source files

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

• app/lib/stores/files.ts
• app/lib/persistence/fileSystem.ts
• app/components/workbench/FileTree.tsx
• app/lib/stores/workbench.ts
• app/lib/stores/editor.ts

The File System State in Bolt.new-Builder is a multi-layered synchronization system designed to manage code across three primary environments: the browser-based WebContainer, the local user's file system (via the File System Access API), and the application's internal reactive state (Nano Stores). It ensures that changes generated by the AI, edits made by the user in the CodeMirror editor, and external updates on the disk are kept in a consistent state.

At its core, the system utilizes a centralized FilesStore to track the state of the WebContainer's virtual file system and a WorkbenchStore to orchestrate higher-level synchronization logic. This architecture allows the application to support full-stack web development entirely within the browser while maintaining a persistent link to the user's local workspace.

Core Architecture and Data Flow

The architecture follows a unidirectional and reactive pattern powered by nanostores. The FilesStore acts as the primary source of truth for the files currently active in the WebContainer environment.

Synchronization Flow

The following diagram illustrates how file changes propagate through the system when a user saves a file:

The WorkbenchStore coordinates saving by updating both the virtual WebContainer and the physical local file system simultaneously.
Sources: app/lib/stores/workbench.ts:168-190, app/lib/stores/files.ts:80-111

Key Components and Stores

FilesStore

The FilesStore manages the FileMap, a reactive mapping of file paths to their contents and metadata. It monitors the WebContainer for changes using a path watcher and updates the internal state accordingly.

Feature	Description
files	A MapStore containing the current state of all files and folders.
modifiedFiles	Tracks original content of files since the last AI interaction to compute diffs.
watchPaths	Initializes a watcher on the WebContainer to sync external process changes.

Sources: app/lib/stores/files.ts:31-64, app/lib/stores/files.ts:114-121

persistence/fileSystem.ts

This module interacts with the browser's File System Access API. It handles directory selection, persistent handles in localStorage, and recursive directory traversal for change detection.

Function	Purpose
selectDirectory	Opens a directory picker and stores the handle for persistence.
writeFile	Recursively creates directories and writes file content to the local disk.
checkForFileChanges	Scans the local directory to identify updates made outside the browser.

Sources: app/lib/persistence/fileSystem.ts:54-82, app/lib/persistence/fileSystem.ts:110-142, app/lib/persistence/fileSystem.ts:175-207

State Structures

The system represents the file system using specific TypeScript interfaces to distinguish between files, folders, and editor-specific states.

Data Models

// From FilesStore
export type FileMap = Record<string, Dirent | undefined>;

type Dirent = File | Folder;

export interface File {
  type: 'file';
  content: string;
  isBinary: boolean;
}

// From EditorStore
export interface EditorDocument {
  value: string;
  isBinary: boolean;
  filePath: string;
  scroll?: ScrollPosition;
}

Sources: app/lib/stores/files.ts:24-30, app/components/editor/codemirror/CodeMirrorEditor.tsx:47-52

File Change Detection and Conflict Resolution

The system implements a periodic check (defaulting to every 30 seconds) to detect if files on the local disk have changed independently of the application.

When changes are detected, the WorkbenchStore compares the disk content with the current EditorStore documents. If they differ, the editor and the internal file store are updated to match the disk.
Sources: app/lib/stores/workbench.ts:149-166, app/lib/persistence/fileSystem.ts:175-207

File Tree Representation

The FileTree component transforms the flat FileMap into a hierarchical visual structure. It uses a depth-first traversal to sort and display nodes while managing UI states like folder collapse and file selection.

Tree Building Logic

1. Filtering: Excludes hidden files defined in DEFAULT_HIDDEN_FILES (e.g., node_modules).
2. Path Segmentation: Splits file paths to identify parent folders.
3. Sorting: Folders are prioritized over files, followed by alphabetical sorting.
4. Flattening: The tree is maintained as a flat list for efficient rendering, with depth properties managing indentation.

Sources: app/components/workbench/FileTree.tsx:188-246, app/components/workbench/FileTree.tsx:273-314

Summary

The File System State is a robust implementation of a virtualized workspace. By bridging the gap between the ephemeral WebContainer memory and the user's persistent local storage, it provides a seamless development experience. The use of Nano Stores allows for fine-grained reactivity, ensuring that components like the FileTree and CodeMirrorEditor update instantly as the file system evolves through AI actions or manual edits.