File Explorer Component

The File Explorer Component is a core UI system within the Bolt workbench that provides users with a hierarchical view of the project's filesystem. It enables users to navigate directories, select files for editing, and visualize the status of files (such as unsaved changes). It integrates deeply with the WebContainer API to reflect real-time changes in the browser-based development environment.

The component consists of two primary sub-components: the FileTree, which provides the sidebar navigation, and the FileBreadcrumb, which offers path-based navigation and quick-access dropdowns for directory contents.

Component Architecture

The File Explorer is built on a reactive architecture using nanostores to sync state between the UI and the underlying WebContainer filesystem.

Data Flow and State Management

The file explorer relies on the FilesStore to track the state of the WebContainer filesystem. The FilesStore uses a path watcher to listen for events like add_file, change, or remove_dir, updating a flat FileMap object.

The diagram shows how filesystem events propagate from the WebContainer to the UI components via centralized stores.
Sources: app/lib/stores/files.ts:60-100, app/lib/stores/workbench.ts:28-45

Core Components

Sources: app/components/workbench/FileTree.tsx:18-35, app/components/workbench/FileBreadcrumb.tsx:15-20

File Tree Logic

The FileTree component transforms a flat FileMap into a sorted, hierarchical list suitable for rendering.

Tree Construction and Sorting

The logic uses a buildFileList function to process the FileMap. It splits paths into segments, determines nesting depth, and filters out hidden files (e.g., node_modules).

1. Flattening: It iterates through the FileMap and creates Node objects for every segment in a path.
2. Sorting: The sortFileList function organizes nodes so that folders appear before files, with both sorted alphabetically.
3. Filtering: Collapsed folders prevent their children from being included in the filteredFileList during render.

Folder Interaction

Folders maintain an internal state of collapsedFolders. When a folder is toggled, it updates this set, triggering a re-calculation of the visible nodes.
Sources: app/components/workbench/FileTree.tsx:55-104

File Breadcrumb System

The FileBreadcrumb provides context-aware navigation. Each segment of the path is interactive; clicking a segment opens a dropdown containing a FileTree scoped to that specific directory.

Breadcrumb Logic

• Path Parsing: The EditorPanel splits the currentDocument.filePath into segments to pass to the breadcrumb.
• Root Context: It uses a WORK_DIR_REGEX to ensure only paths within the project's working directory are displayed.
• Recursive UI: It re-uses the FileTree component inside the Radix UI Dropdown Menu to show directory contents when a segment is clicked.

Key Data Structures

Node Interface

The FileTree uses a Node union type to manage the internal flat list representation.

type Node = FileNode | FolderNode;

interface BaseNode {
  id: number;
  depth: number;
  name: string;
  fullPath: string;
}

interface FileNode extends BaseNode {
  kind: 'file';
}

interface FolderNode extends BaseNode {
  kind: 'folder';
}

Sources: app/components/workbench/FileTree.tsx:162-179

Configuration Constants

The File Explorer uses specific constants for UI layout and default behavior.

• NODE_PADDING_LEFT = 8: The horizontal indentation (in pixels) for each nesting level.
• DEFAULT_HIDDEN_FILES: RegEx patterns for items like node_modules, .next, and .astro.
• WORK_DIR: The root directory used to filter path segments in breadcrumbs and tree views.

Sources: app/components/workbench/FileTree.tsx:8-9, app/components/workbench/FileBreadcrumb.tsx:11

Conclusion

The File Explorer Component acts as the primary interface for project navigation in Bolt. By combining the FileTree and FileBreadcrumb, it provides a flexible system that handles large filesystems efficiently through reactive stores and depth-first traversal sorting, while remaining synced with the browser-based WebContainer environment.