Introduction to Bolt.new
Relevant source files
The following files were used as context for generating this wiki page:
Bolt.new is a sophisticated AI-powered software development agent and full-stack development environment that operates entirely within the web browser. It leverages the StackBlitz WebContainer API to provide a sandboxed Node.js environment, allowing users to prompt, run, edit, and deploy full-stack web applications without any local installation or remote virtual machines.
The system serves as a bridge between high-level AI reasoning—provided by models like Claude 3.5 Sonnet—and a functional development environment. By integrating the AI SDK integration with browser-based containers, Bolt.new grants AI models direct control over a filesystem, package manager, and terminal.
Sources: CONTRIBUTING.md:5-15, README.md:10-18
System Architecture
The architecture of Bolt.new is built on a modern full-stack web foundation, utilizing Remix for the application framework and Vite as the build tool. The core of its execution capability lies in the WebContainer API, which enables a local-like development experience in the browser.
Core Technologies
| Technology | Purpose |
|---|---|
| WebContainer API | Provides the in-browser Node.js runtime, filesystem, and terminal. |
| Claude 3.5 Sonnet | The primary AI model used for code generation and architectural reasoning. |
| Remix | The full-stack web framework used to build the application and server components. |
| Vercel AI SDK | Facilitates the integration and streaming of AI model responses. |
| Cloudflare Pages/Workers | The deployment platform for the Bolt application itself. |
Sources: CONTRIBUTING.md:20-35, package.json:44-70
Operational Flow
The following diagram illustrates how a user request is transformed into a running application.
The flow begins with a user prompt, which is processed by the AI to generate a stream of text containing specialized tags. These tags are parsed in real-time to execute actions within the WebContainer.
Sources: CONTRIBUTING.md:12-25, app/lib/runtime/message-parser.ts:7-15
Message Processing and Execution
Bolt.new uses a custom protocol to allow the AI model to communicate structured development actions within a standard text stream. This is handled by the StreamingMessageParser.
Artifacts and Actions
The system identifies structured blocks within the LLM's response using XML-like tags:
<boltArtifact>: Represents a logical grouping of work (e.g., "Project Scaffold").<boltAction>: Represents a specific task to perform, such as writing a file or running a shell command.
Sources: app/lib/runtime/message-parser.ts:7-10
Action Types
The parser recognizes two primary types of actions defined in the ActionType schema:
- Shell Actions: Commands executed directly in the WebContainer terminal (e.g.,
npm install). - File Actions: Operations involving the creation or modification of files at a specific
filePath.
Sources: app/lib/runtime/message-parser.ts:213-225, app/lib/runtime/message-parser.ts:25-30
This sequence shows the lifecycle of a message as it is parsed and converted into executable steps.
Sources: app/lib/runtime/message-parser.ts:70-130, app/lib/stores/workbench.ts:260-285
State Management and Workbench
The WorkbenchStore is the central authority for managing the state of the development environment. It coordinates the filesystem, terminal instances, and the active code editor.
Key Store Responsibilities
- Filesystem Management: Tracks all files within the
projectdirectory and manages unsaved changes. - Artifact Tracking: Maintains a list of all artifacts generated during a session via
artifactIdList. - View Coordination: Toggles between "code" and "preview" views.
Sources: app/lib/stores/workbench.ts:35-65
File Modification Logic
To efficiently communicate changes back to the AI or save them, Bolt uses a diffing utility. If changes are extensive, the system sends the full file content; otherwise, it computes a unified diff to minimize token usage.
// Example of computing modifications for LLM feedback
export function computeFileModifications(files: FileMap, modifiedFiles: Map<string, string>) {
// ... logic to choose between full file content or diff ...
if (unifiedDiff.length > file.content.length) {
modifications[filePath] = { type: 'file', content: file.content };
} else {
modifications[filePath] = { type: 'diff', content: unifiedDiff };
}
}
Sources: app/utils/diff.ts:20-45
User Interface and Interaction
The UI is divided between the Chat interface and the Workbench.
Chat Interface (BaseChat)
The chat component provides the entry point for user interaction. It includes:
- Prompt Input: A textarea supporting multi-line input and "Shift + Enter" for new lines.
- Enhancement Tool: An "Enhance Prompt" feature that uses AI to refine the user's initial instructions before submission.
- Example Prompts: Quick-start templates for common tasks like building a Todo app or a blog.
Sources: app/components/chat/BaseChat.tsx:85-150
The Workbench
The Workbench contains the technical tools:
- File Tree: A hierarchical view of the project structure, excluding sensitive directories like
node_modules. - Code Editor: A CodeMirror-based editor for manual adjustments.
- Terminal: Real-time output of shell commands.
- Preview: An integrated browser window showing the running application.
Sources: app/components/workbench/FileTree.tsx:15-40, app/lib/stores/workbench.ts:38-50
Configuration and Setup
The project relies on specific scripts for both local development and deployment.
Development Commands
| Command | Description |
|---|---|
pnpm run dev | Starts the Remix Vite development server. |
pnpm run build | Builds the project for production. |
pnpm run start | Runs the built application locally using Wrangler Pages. |
pnpm run deploy | Deploys the application to Cloudflare Pages. |
Sources: CONTRIBUTING.md:65-80, package.json:8-20
Environment Requirements
- Node.js: Version 20.15.1 or higher.
- pnpm: Version 9.4.0.
- API Keys: Requires an
ANTHROPIC_API_KEYfor AI functionalities.
Sources: CONTRIBUTING.md:40-60
Conclusion
Bolt.new represents a shift in development tools by unifying the AI chat experience with a fully functional, browser-based runtime. By utilizing the WebContainer API and structured message parsing, it allows for a collaborative development process where the AI can act as a primary developer, executing complex full-stack tasks directly in the user's browser environment.