Introduction to Bolt.new-Builder
Relevant source files
The following files were used as context for generating this wiki page:
Bolt.new-Builder is an open-source AI-powered software development tool that enables developers to prompt, run, edit, and deploy full-stack web applications entirely within the browser. By leveraging the StackBlitz WebContainer API, the system provides a sandboxed Node.js environment, allowing AI direct access to a filesystem, package manager, and development terminal without requiring local installations or remote virtual machines.
Sources: README.md:1-15, CONTRIBUTING.md:1-15
The project is built using the Remix framework and integrates with the Vercel AI SDK to facilitate collaborative development between the user and an AI assistant (specifically Claude 3.5 Sonnet). It emphasizes a seamless flow where the AI can generate code, execute shell commands, and respond to user edits in real-time within a secure, browser-based sandbox.
Sources: README.md:19-25, CONTRIBUTING.md:19-25
System Architecture
The architecture of Bolt.new-Builder revolves around the interaction between the Remix-based UI, the local browser filesystem (via the File System Access API), and the WebContainer runtime. The state is managed through nanostores, which synchronize code changes between the editor, the AI's suggestions, and the persistent storage.
Sources: app/lib/stores/workbench.ts:1-30, app/lib/persistence/fileSystem.ts:1-10
High-Level Component Interaction
The following diagram illustrates how user prompts are processed and how the resulting code is executed within the sandboxed environment.
This flow ensures that AI-generated code is immediately actionable within the browser's terminal and editor.
Sources: app/lib/runtime/message-parser.ts:50-100, app/lib/stores/workbench.ts:200-230
Core Modules and Components
1. Persistence and File System
The system uses the fileSystem.ts module to interface with the browser's local directory handles. This allows the application to "persist" projects by writing AI-generated content directly to a user-selected folder.
Sources: app/lib/persistence/fileSystem.ts:60-100
- Key Functions:
selectDirectory(): Prompts user for folder access and checks for existing.boltnewproject markers.writeFile(filePath, content): Recursively creates directories and writes file content.createProjectFiles(chatItem): Parses a chat history to extract and recreate the project structure.
Sources: app/lib/persistence/fileSystem.ts:15-130
2. Message Parsing and Artifacts
The StreamingMessageParser identifies special XML-like tags within the AI's streaming output. These tags, known as boltArtifact and boltAction, define tasks such as creating files or running terminal commands.
Sources: app/lib/runtime/message-parser.ts:5-45
| Element | Description |
|---|---|
<boltArtifact> | A container for a set of related development actions (e.g., "Install dependencies"). |
<boltAction type="file"> | Instructs the system to create or update a specific file. |
<boltAction type="shell"> | Instructs the system to execute a command in the WebContainer terminal. |
| Sources: app/lib/runtime/message-parser.ts:10-15, app/types/actions.ts (referenced) |
3. Workbench and State Management
The WorkbenchStore acts as the central hub for managing the application's state, including the file tree, editor documents, and running processes. It coordinates the synchronization between the WebContainer's virtual filesystem and the UI.
Sources: app/lib/stores/workbench.ts:35-80
Sources: app/lib/stores/workbench.ts:250-310
Technical Specifications
The project leverages a modern web stack designed for high performance and low latency in a browser environment.
| Category | Technology |
|---|---|
| Framework | Remix Run with Vite |
| Runtime | StackBlitz WebContainer API |
| AI Integration | Vercel AI SDK (Anthropic Claude 3.5 Sonnet) |
| Styling | UnoCSS & SCSS Modules |
| State Management | Nanostores |
| Code Editor | CodeMirror 6 |
| Sources: package.json:20-80, CONTRIBUTING.md:40-60 |
Deployment and Environment
Bolt.new-Builder is designed to be deployed on Cloudflare Pages using Cloudflare Workers for server-side logic.
Sources: wrangler.toml:1-5, package.json:10-15
- Prerequisites: Node.js v20.15.1 and pnpm v9.4.0.
- Environment Variables: Requires
ANTHROPIC_API_KEYfor AI functionality. - Scripts:
pnpm run dev: Starts the Remix Vite development server.pnpm run build: Compiles the project for production.pnpm run deploy: Deploys to Cloudflare Pages via Wrangler.
Sources: CONTRIBUTING.md:70-110
Conclusion
Bolt.new-Builder bridges the gap between AI code generation and local development by providing a fully integrated, sandboxed environment. By utilizing the WebContainer API and a robust streaming parser, it transforms AI suggestions into immediate, executable project structures, enabling a "prompt-to-app" workflow that operates entirely within the user's browser.
Sources: README.md:5-15, CONTRIBUTING.md:5-15