Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides comprehensive instructions for setting up the Bolt development environment. Bolt is a full-stack AI development tool built with Remix that leverages the WebContainer API to run Node.js environments directly in the browser.
The setup process involves configuring a local environment that mimics the production stack, which is primarily designed for Cloudflare Pages and Cloudflare Workers, or optionally Vercel.
Sources: README.md:23-45, CONTRIBUTING.md:23-45
Prerequisites
Before initiating the installation, the following software versions are strictly required to ensure compatibility with the WebContainer runtime and the Remix build pipeline:
| Requirement | Version | Description |
|---|---|---|
| Node.js | v20.15.1 | Recommended version for stability with WebContainers. |
| pnpm | v9.4.0 | Required package manager for dependency resolution. |
Sources: README.md:49-52, CONTRIBUTING.md:49-52
Initial Local Setup
The local installation follows a standard Node.js project initialization workflow. The project uses pnpm for managing workspace dependencies and vite as the primary build tool.
Steps to Initialize
- Clone the Repository: Retrieve the source code from the official repository.
- Install Dependencies: Use
pnpm installto populate thenode_modulesdirectory. - Configure Environment: Create a
.env.localfile in the root directory.
git clone https://github.com/stackblitz/bolt.new.git
pnpm install
Sources: README.md:56-65, CONTRIBUTING.md:56-65
Environment Configuration
The application requires specific API keys to function, primarily for the AI SDK integration. These must be defined in a .env.local file (or set as environment variables in production).
| Variable | Required | Description |
|---|---|---|
ANTHROPIC_API_KEY | Yes | API key for Claude Sonnet 3.5 integration. |
VITE_LOG_LEVEL | No | Sets the debug level (e.g., debug) for Vite. |
GROQ_API_KEY | No | API key for Groq integration (optional). |
CLOUDFLARE_API_TOKEN | No | Required for the MVP publish feature. |
CLOUDFLARE_ACCOUNT_ID | No | Required for the MVP publish feature. |
Sources: README.md:67-75, VERCEL_DEPLOYMENT.md:38-40, README.md:144-147
Development Workflow
Once the environment is configured, the development server can be launched. The project uses remix-cloudflare-dev-proxy to simulate the Cloudflare environment during local development.
This diagram illustrates the flow from the initial development command to the execution of the application within the browser's WebContainer environment.
Sources: vite.config.ts:16-24, README.md:83-84
Chrome 129 Compatibility Note
There is a known issue with Chrome 129 regarding JavaScript modules and Vite local development. Developers using this specific browser version are advised to use Chrome Canary for local testing. This issue does not affect the production build.
Sources: vite.config.ts:40-60
Build and Deployment Options
Bolt supports multiple deployment targets, with Cloudflare Pages being the primary production environment.
Cloudflare Pages (Standard)
The project is configured via wrangler.toml for Cloudflare. The pnpm run start command uses a bindings.sh script to set up necessary environment variables without duplication.
#: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, README.md:94-102
Vercel Configuration
For Vercel deployments, a specific configuration is provided via vercel.json and remix.config.js.
| Configuration | Setting |
|---|---|
| Build Command | pnpm run build |
| Output Directory | build/client |
| Node.js Version | 20.x |
| Framework | Remix |
Sources: VERCEL_DEPLOYMENT.md:5-12
Deployment Lifecycle
The automated deployment process ensures that all code passing through CI/CD is automatically pushed to the production environment on Cloudflare.
Sources: README.md:126-135, README.md:167-183
Available Scripts Reference
The following scripts are defined in the project configuration for lifecycle management:
pnpm run dev: Starts the Remix Vite development server.pnpm run build: Compiles the project for production.pnpm run start: Runs the built application locally using Wrangler Pages.pnpm test: Executes the test suite using Vitest.pnpm run typecheck: Performs TypeScript static analysis.pnpm run deploy: Deploys the built assets to Cloudflare Pages.
Sources: README.md:92-102, CONTRIBUTING.md:92-102, package.json:1-25
Conclusion
The installation and setup of Bolt require strict adherence to Node.js v20 and pnpm v9. By configuring the Anthropic API keys and leveraging either Cloudflare Wrangler or Vercel, developers can create a high-performance sandbox for AI-driven web development. The use of WebContainers ensures that once the setup is complete, the entire development environment operates securely within the user's browser.