File System & Sync

Relevant source files

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

• app/lib/persistence/fileSystem.ts
• app/lib/stores/files.ts
• app/lib/stores/workbench.ts
• app/lib/stores/editor.ts
• app/components/editor/codemirror/CodeMirrorEditor.tsx
• app/utils/diff.ts

The File System & Sync system provides a robust architecture for managing project files within a browser-based environment. It leverages the WebContainer API to maintain an in-memory virtual file system while simultaneously providing synchronization with the user's local physical file system via the File System Access API. This ensures that changes made by the AI, the user in the editor, or external tools on the local machine are consistently reflected across the application state.

The system is primarily composed of persistence utilities for local disk access, centralized stores for state management (nanostores), and background processes that monitor for external changes to maintain data integrity between the virtual and physical environments.

System Architecture & Data Flow

The architecture follows a multi-layered approach where file state exists in three primary locations: the local file system (physical), the WebContainer (virtual runtime), and the Application Stores (reactive state).

Data Flow Overview

The following diagram illustrates how file content moves between the different layers of the system during a save operation or an external sync.

Persistence Layer (Local File System)

The persistence layer interacts directly with the browser's File System Access API to bridge the gap between the web application and the local machine.

Key Components

Function / Variable	Description
selectedDirectoryHandle	A nanostore atom holding the FileSystemDirectoryHandle for the currently opened project.
writeFile(path, content)	Navigates the local directory structure and writes content to the physical disk, creating directories as needed.
checkForFileChanges()	Recursively traverses the local directory to detect changes made outside the browser.
selectDirectory()	Triggers the native directory picker and persists the handle reference in localStorage.

Sources: app/lib/persistence/fileSystem.ts:7-14, app/lib/persistence/fileSystem.ts:107-138, app/lib/persistence/fileSystem.ts:182-214

Directory Synchronization Logic

When a user selects a directory, the system looks for a .boltnew file to identify existing chat sessions. The checkForFileChanges function runs on an interval to ensure the virtual environment stays in sync with external edits.

Virtual File System (WebContainer)

The FilesStore manages the state of the WebContainer's virtual file system. It listens to internal file events and maintains a FileMap that the rest of the application uses as a source of truth for the project structure.

Event Processing

The system handles several types of file system events from the WebContainer:

• add_dir / remove_dir: Updates the directory structure in the store.
• add_file / change: Reads file buffers, checks for binary content, and updates the reactive file map.
• remove_file: Decrements the file count and removes the entry from the map.

// app/lib/stores/files.ts:114-142
switch (type) {
  case 'add_dir': {
    this.files.setKey(sanitizedPath, { type: 'folder' });
    break;
  }
  case 'add_file':
  case 'change': {
    if (type === 'add_file') { this.#size++; }
    const isBinary = isBinaryFile(buffer);
    let content = isBinary ? '' : this.#decodeFileContent(buffer);
    this.files.setKey(sanitizedPath, { type: 'file', content, isBinary });
    break;
  }
}

Sources: app/lib/stores/files.ts:108-154

Change Tracking & Diffs

To facilitate efficient communication with AI models, the system tracks modifications made since the last interaction.

Modification Logic

The FilesStore maintains a #modifiedFiles map which stores the original content of files before user edits. When requested, the system computes unified diffs using the diff library. If a diff is larger than the actual file content, the system sends the full file instead.

Component	Description
computeFileModifications	Compares current file state with original content to determine what changed.
diffFiles	Generates a unified diff format while omitting specific headers to save token space.
fileModificationsToHTML	Encapsulates diffs or file updates in custom <bolt_file_modifications> tags.

Sources: app/utils/diff.ts:19-54, app/lib/stores/files.ts:41-43

Editor Integration

The EditorStore and CodeMirrorEditor component consume the file system state to provide an interactive interface.

State Synchronization

1. Selection: When a file is selected in the FileTree, setSelectedFile updates the EditorStore.
2. Content Loading: The editor retrieves the file content from the EditorStore, which is derived from the FilesStore.
3. Unsaved Changes: The WorkbenchStore tracks a Set<string> of paths that have content in the editor differing from the virtual file system.

Summary

The File System & Sync module ensures a seamless developer experience by unifying local file access with a virtualized browser runtime. Through the use of nanostores for reactive state and the WebContainer API for execution, it provides a performant way to edit, track, and synchronize code changes across the physical and virtual project boundaries.

Sources: app/lib/persistence/fileSystem.ts, app/lib/stores/files.ts, app/lib/stores/workbench.ts