Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
This page provides the necessary technical documentation for setting up the Bolt development environment. Bolt is an AI-powered development agent that leverages the StackBlitz WebContainer API to run full-stack applications directly in the browser using Node.js, a virtual filesystem, and a dev terminal.
The local development environment is built on the Remix framework and utilizes Vite for bundling and development services. It is designed to be deployed on Cloudflare Pages using Wrangler for local emulation of production environments.
Sources: CONTRIBUTING.md:3-12, package.json:28-31
Prerequisites
Before initiating the setup, ensure the following environment specifications are met:
| Requirement | Version / Specification | Source |
|---|---|---|
| Node.js | v20.15.1 (or >=18.18.0) | CONTRIBUTING.md:58, package.json:24-26 |
| pnpm | v9.4.0 | CONTRIBUTING.md:59, package.json:7 |
| API Key | Anthropic API Key (Claude Sonnet 3.5) | CONTRIBUTING.md:71-73 |
| Browser | Chrome Canary (for local dev) | vite.config.ts:43-55 |
Initial Installation
The project uses pnpm for package management. To begin, clone the repository and install the dependencies defined in package.json.
git clone https://github.com/stackblitz/bolt.new.git
cd bolt.new
pnpm install
Sources: CONTRIBUTING.md:63-69, package.json:33-85
Environment Configuration
Users must create a .env.local file in the root directory. This file is excluded from version control via .gitignore to protect sensitive credentials.
# Required for AI interactions
ANTHROPIC_API_KEY=XXX
# Optional: Set debug level (trace, debug, info, warn, error)
VITE_LOG_LEVEL=debug
Sources: CONTRIBUTING.md:71-79
Development Workflow
The development environment consists of several scripts and tools to manage the application lifecycle.
Core Development Scripts
| Script | Command | Description |
|---|---|---|
dev | remix vite:dev | Starts the Remix Vite development server for rapid iteration. |
build | remix vite:build | Compiles the application for production, targeting esnext. |
test | vitest --run | Executes the test suite using Vitest. |
typecheck | tsc | Runs TypeScript compiler to verify type safety. |
typegen | wrangler types | Generates TypeScript types for Cloudflare environment bindings. |
Sources: package.json:10-22, CONTRIBUTING.md:83-92
Local Execution and Preview
The project provides scripts to run the application in an environment that closely mimics production.
The pnpm run start command utilizes a helper script, bindings.sh, to automatically set up Cloudflare environment bindings without duplicating variables.
Sources: package.json:17, CONTRIBUTING.md:86-88
Configuration Analysis
Vite & Browser Compatibility
The project includes a specific plugin to handle a known issue with JavaScript modules in Chrome 129 during local development. Developers are advised to use Chrome Canary for testing if they encounter this issue.
// vite.config.ts specific logic
if (version === 129) {
res.setHeader('content-type', 'text/html');
res.end('<body><h1>Please use Chrome Canary for testing.</h1>...</body>');
}
Sources: vite.config.ts:40-62
TypeScript Configuration
The project is configured with strict type checking and uses the "Bundler" module resolution strategy.
- Target: ESNext
- Module: ESNext
- Path Aliases:
~/maps to./app/for cleaner imports. - No Emit: Vite handles the build process, so
tscis only used for type checking.
Sources: tsconfig.json:3-22
Cloudflare Environment
The wrangler.toml file defines the Cloudflare Pages configuration, including compatibility flags required for Node.js features within the worker environment.
- Name: bolt
- Compatibility Flags:
nodejs_compat - Build Output:
./build/client
Sources: wrangler.toml:1-5
Summary
The local development setup for Bolt is optimized for a Cloudflare Pages deployment while providing a robust local iteration flow via Vite. By utilizing the WebContainer API and Anthropic's models, developers can contribute to a browser-based IDE experience. Proper configuration of the .env.local file and the use of compatible browsers (Chrome Canary) are critical for a functional development environment.