Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the procedures and technical requirements for contributing to the Bolt open-source project. Bolt is an AI-powered software development tool built with Remix and the StackBlitz WebContainer API, designed to allow users to prompt, run, and deploy full-stack applications directly in the browser.
Contributions focus on maintaining the UI components, server logic, and integration with the WebContainer API and Anthropic's AI SDK.
Sources: CONTRIBUTING.md:1-25, README.md:1-15
Development Environment Setup
To contribute to the codebase, developers must adhere to specific versioning and environmental requirements. The project relies on Node.js and the pnpm package manager for dependency resolution and script execution.
Prerequisites and Installation
| Requirement | Version | Description |
|---|---|---|
| Node.js | v20.15.1 | Minimum version required for runtime compatibility. |
| pnpm | v9.4.0 | Required package manager. |
| Anthropic API Key | Required | Needed for AI model interactions via Claude Sonnet 3.5. |
Sources: CONTRIBUTING.md:46-64, package.json:34
The initialization process involves cloning the repository and installing dependencies:
git clone https://github.com/stackblitz/bolt.new.git
pnpm install
Sources: CONTRIBUTING.md:54-61
Technical Architecture & Workflow
The Bolt architecture integrates a Remix-based frontend with a specialized runtime that interfaces with WebContainers. Understanding this flow is critical for contributing to the core logic.
Environment Lifecycle
The following diagram illustrates the lifecycle of a development session, from starting the server to deploying changes.
The system uses WebContainer API to provide a full-stack sandbox including a Node.js server, filesystem, and terminal inside the browser tab.
Sources: CONTRIBUTING.md:12-25, README.md:18-28
Key Development Scripts
Developers should utilize the following pnpm scripts during the contribution cycle:
| Script | Purpose |
|---|---|
dev | Starts the Remix Vite development server. |
build | Compiles the project using remix vite:build. |
test | Runs the test suite using Vitest. |
typecheck | Executes TypeScript type checking across the project. |
lint | Runs ESLint to ensure code style consistency. |
deploy | Builds and deploys the application to Cloudflare Pages. |
Sources: package.json:10-21, CONTRIBUTING.md:83-93
Code Standards and State Management
Contributions must follow the established state management patterns using nanostores and adhere to the project's reactive architecture.
Workbench and Store Logic
The WorkbenchStore manages the global state of the editor, terminal, and file system. It coordinates between the UI and the WebContainer instance.
Key methods like saveAllFiles() are automatically invoked before sending new prompts to the AI to ensure the model receives the most recent file state via diffing.
Sources: app/lib/stores/workbench.ts:32-80, app/components/chat/Chat.client.tsx:165-175
Configuration
The project uses Vite for bundling. Contributors should be aware of the vite.config.ts which includes polyfills for Node.js modules like path and buffer to ensure they run in the browser environment.
Sources: vite.config.ts:12-20
Testing and Quality Assurance
Before submitting a pull request, contributors must ensure that all tests pass and types are valid.
- Unit Testing: Bolt uses Vitest for unit and integration testing. Run
pnpm testto verify logic in components likemessage-parser. - Linting: ESLint is used with a specific
@blitz/eslint-plugin. - Type Safety:
tscis used for type checking.
Sources: package.json:13-20, CONTRIBUTING.md:104-108
Conclusion
Contributing to Bolt requires an understanding of browser-based full-stack execution environments. By following these guidelines—ensuring correct environment setup, utilizing the standard pnpm scripts, and adhering to the nanostores state management pattern—developers can help expand the capabilities of AI-powered development tools.