Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Bolt is an open-source AI-powered software development tool that leverages the StackBlitz WebContainer API and Anthropic's Claude Sonnet 3.5 to enable users to prompt, run, edit, and deploy full-stack web applications directly in the browser. The setup process involves configuring a local Node.js environment, managing API credentials, and utilizing specific build tools like Remix and Vite to interface with Cloudflare's deployment infrastructure.
Sources: CONTRIBUTING.md:3-13, README.md:12-22
The system architecture relies on a local development environment that mimics the production environment hosted on Cloudflare Pages and Workers. Key components include the WebContainer API for browser-side sandboxing and the Remix framework for the application lifecycle.
Sources: CONTRIBUTING.md:27-35, README.md:36-44
Environment Prerequisites
The project requires specific versions of Node.js and package managers to ensure compatibility with the WebContainer and Remix environments.
| Requirement | Version | Purpose |
|---|---|---|
| Node.js | v20.15.1 (or >=18.18.0) | Core runtime for the Remix application and build scripts. |
| pnpm | v9.4.0 | Recommended package manager for dependency resolution. |
| Anthropic API Key | Required | Necessary for AI SDK integration with Claude 3.5 Sonnet. |
| Browser | Chrome Canary | Recommended for testing due to specific JS module issues in Chrome 129. |
Sources: CONTRIBUTING.md:46-50, package.json:28, vite.config.ts:34-45
Local Project Setup
Initial setup involves cloning the repository, installing dependencies, and configuring environment variables.
1. Repository Initialization
git clone https://github.com/stackblitz/bolt.new.git
cd bolt.new
pnpm install
Sources: CONTRIBUTING.md:52-62, README.md:61-71
2. Configuration of Environment Variables
Users must create a .env.local file in the root directory to store sensitive credentials and debug settings.
ANTHROPIC_API_KEY=XXX
VITE_LOG_LEVEL=debug
Sources: CONTRIBUTING.md:64-74, README.md:73-83
Initialization Logic Flow
When the application starts, it performs several checks to initialize the user's workspace, specifically regarding directory selection and existing chat persistence.
The application uses the showDirectoryPicker API to gain access to the local filesystem, which is essential for Bolt's file persistence features.
Sources: app/lib/persistence/fileSystem.ts:54-75, app/routes/_index.tsx:21-48
Available Development Scripts
The package.json defines several commands for development, building, and deployment using the Remix and Wrangler (Cloudflare) toolchains.
| Command | Action | Implementation Detail |
|---|---|---|
pnpm run dev | remix vite:dev | Starts the Remix Vite development server. |
pnpm run build | remix vite:build | Compiles the project for production. |
pnpm run start | bindings=$(./bindings.sh) && wrangler pages dev ... | Runs the app locally using Wrangler with specific bindings. |
pnpm run deploy | npm run build && wrangler pages deploy | Deploys the built application to Cloudflare Pages. |
pnpm test | vitest --run | Executes the test suite using Vitest. |
Sources: package.json:7-19, CONTRIBUTING.md:78-88
Infrastructure Configuration
Deployment is governed by wrangler.toml, which configures the Cloudflare Pages environment.
#:schema node_modules/wrangler/config-schema.json
name = "bolt"
compatibility_flags = ["nodejs_compat"]
compatibility_date = "2024-07-01"
pages_build_output_dir = "./build/client"
Sources: wrangler.toml:1-5
Build and Compilation
The Vite configuration includes polyfills for Node.js modules (like path and buffer) which are critical for the application's filesystem logic to run in the browser environment via WebContainers.
// vite.config.ts
nodePolyfills({
include: ['path', 'buffer'],
})
Sources: vite.config.ts:13-15
Verification and Testing
After installation, the setup can be verified by running the test suite to ensure the environment correctly parses AI-generated artifacts and actions.
pnpm test
The tests verify that the StreamingMessageParser correctly identifies <boltArtifact> and <boltAction> tags, which are fundamental to the "Installation & Setup" of generated code within the sandbox.
Sources: app/lib/runtime/message-parser.spec.ts:11-20, CONTRIBUTING.md:96-100
Summary
Setting up Bolt requires a Node.js v20+ environment and a valid Anthropic API key. The project leverages Remix for the frontend, Vite for the build pipeline, and Wrangler for Cloudflare integration. Key to the local experience is the browser's FileSystem API, which allows Bolt to persist code directly to the user's local directory while utilizing WebContainers for sandboxed execution.