Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
These guidelines provide developers with the necessary technical framework to contribute to the Bolt open-source codebase. Bolt is an AI-powered software development tool that leverages StackBlitz’s WebContainer API to run full-stack Node.js environments directly in the browser.
The project is built using the Remix framework and deployed on Cloudflare Pages, integrating the Vercel AI SDK to communicate with LLM models like Claude 3.5 Sonnet. Understanding the interaction between the local file system, the browser-based WebContainer, and the deployment environment is critical for effective contributions.
Sources: CONTRIBUTING.md:3-30, README.md:3-30
Development Environment Setup
To contribute to Bolt, you must configure a local development environment that mirrors the production runtime. The project requires specific versions of Node.js and pnpm to ensure dependency consistency.
Prerequisites and Installation
Developers must have the following installed:
- Node.js: v20.15.1 (or at least 18.18.0 as per engine requirements)
- pnpm: v9.4.0
The following sequence diagram illustrates the initial setup flow:
The application relies on an Anthropic API key for AI functionality. This should be placed in a .env.local file in the root directory.
Sources: CONTRIBUTING.md:46-65, package.json:23-25, README.md:46-65
Core Scripts and Workflow
The project utilizes a set of standardized scripts for development, testing, and deployment. These are managed via pnpm.
| Script | Command | Description |
|---|---|---|
| Development | pnpm run dev | Starts the Remix Vite development server. |
| Build | pnpm run build | Compiles the project using remix vite:build. |
| Local Start | pnpm run start | Runs the build locally using Wrangler Pages and bindings.sh. |
| Testing | pnpm test | Executes the test suite using Vitest. |
| Type Check | pnpm run typecheck | Runs TypeScript compiler checks. |
| Deployment | pnpm run deploy | Builds and deploys to Cloudflare Pages. |
Sources: package.json:9-21, CONTRIBUTING.md:67-79, README.md:67-79
Project Architecture and Technologies
Contributors should be familiar with the following core technology stack used in the project:
Frontend and Framework
- Remix: Used as the primary web framework for both UI and server components.
- Vite: Acts as the build tool and development server.
- UnoCSS: Utilized for atomic CSS styling.
- NanoStores: Used for lightweight state management.
AI and Runtime
- WebContainer API: Provides the browser-based Node.js sandbox.
- AI SDK: Facilitates communication with Anthropic's Claude 3.5 Sonnet.
Infrastructure
- Cloudflare Pages/Workers: The deployment target.
- Wrangler: Used for local simulation of Cloudflare environments and deployment.
Sources: CONTRIBUTING.md:32-44, vite.config.ts:9-30, wrangler.toml:1-5
Persistence and File Management
A unique aspect of Bolt is its ability to interact with the user's local file system through the FileSystem module. This allows the AI-generated code to be saved directly to the user's machine.
File System Interaction
The application uses the window.showDirectoryPicker() API to gain access to local folders. It maintains a selectedDirectoryHandle in a NanoStore to track the active project directory.
Key functions in app/lib/persistence/fileSystem.ts include:
createProjectFiles: Extracts file content from assistant messages and writes them to disk.writeFile: Navigates subdirectories and writes content usingFileSystemDirectoryHandle.checkForFileChanges: Periodically polls the local directory for external modifications.
Sources: app/lib/persistence/fileSystem.ts:16-100
Testing Standards
All contributions should include relevant tests. The project uses Vitest for unit and integration testing.
- Execution: Run
pnpm testfor a single run orpnpm test:watchduring development. - Location: Tests are typically located alongside the source code with a
.spec.tssuffix (e.g.,app/lib/runtime/message-parser.spec.ts).
Sources: package.json:13-14, CONTRIBUTING.md:86-88, README.md:86-88
Deployment Process
The deployment is automated through Cloudflare Wrangler. The wrangler.toml file defines the project configuration for the Cloudflare 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"
To deploy, ensure you have the necessary Cloudflare permissions and run:
pnpm run deploy
Sources: wrangler.toml:1-5, package.json:9
Technical Summary
The Bolt project represents a complex integration of browser-native sandboxing (WebContainers) and AI orchestration. Contributors are expected to maintain the decoupled nature of the UI and the runtime, ensuring that file system operations are handled safely through the provided persistence abstractions and that all new features are verified against the Remix-based production build.