Contributing Guidelines
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 to run full-stack web applications directly in the browser. It combines AI models like Claude Sonnet 3.5 with a sandboxed Node.js environment, allowing developers to prompt, run, edit, and deploy code without local installations.
The purpose of these guidelines is to provide developers with the necessary information to set up their local environment, understand the project structure, and follow the established workflows for development, testing, and deployment. Contributors can utilize the core components of this repository to build their own AI development tools.
Sources: README.md:1-25, CONTRIBUTING.md:1-30
Development Environment Setup
To contribute to the project, developers must ensure their local environment meets specific version requirements for Node.js and package management.
Prerequisites
The project relies on specific versions of the following tools:
- Node.js: v20.15.1
- pnpm: v9.4.0
Sources: README.md:65-69, CONTRIBUTING.md:70-74
Initial Setup
- Clone the Repository: Obtain the source code using Git.
- Install Dependencies: Use
pnpm installto set up the workspace. - Environment Variables: Create a
.env.localfile in the root directory. This file is excluded from version control via.gitignore.ANTHROPIC_API_KEY: Required for Claude AI integration.VITE_LOG_LEVEL: Optional (e.g.,debug).
Sources: README.md:73-88, CONTRIBUTING.md:78-93
Available Development Scripts
The project uses pnpm to manage lifecycle scripts for development, building, and validation.
| Script | Description |
|---|---|
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 and bindings.sh. |
pnpm test | Executes the test suite using Vitest. |
pnpm run typecheck | Runs TypeScript type checking across the codebase. |
pnpm run lint | Runs ESLint to ensure code quality and style consistency. |
pnpm run deploy | Builds and deploys the application to Cloudflare Pages. |
Sources: README.md:92-102, CONTRIBUTING.md:97-107, package.json:1-25
Development Workflow
The development process follows a standard flow from local changes to automated CI/CD pipelines.
Feature Lifecycle
The following diagram illustrates the path from a local code change to a production release:
This flow ensures that all code merged into the main branch is functionally sound and passes all quality gates.
Sources: README.md:210-220
Local Iteration
Developers primarily use pnpm run dev to start the Remix Vite development server. This environment includes specific safeguards, such as the chrome129IssuePlugin, which warns users about JavaScript module issues in specific browser versions during local development.
Sources: vite.config.ts:37-60
Testing and Quality Assurance
Quality is enforced through a combination of automated testing and static analysis.
- Vitest: Used for unit and integration testing. All tests must pass before a PR is allowed to merge.
- TypeScript: While some pre-existing type errors may exist in modules like
fileSystem.ts, contributors are encouraged to resolve them to improve maintainability. - ESLint: Enforces coding standards and prevents common patterns that lead to bugs.
Sources: README.md:107-109, VERCEL_DEPLOYMENT.md:25-30, package.json:15-20
Deployment Configurations
The project is optimized for two primary deployment targets: Cloudflare Pages and Vercel.
Cloudflare Pages (Default)
The production environment is hosted on Cloudflare Pages, utilizing Cloudflare Workers for server-side logic. Deployment requires CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID environment variables.
Vercel Support
Specific configuration files are provided for Vercel deployment:
vercel.json: Defines the build command (pnpm run build) and output directory (build/client).remix.config.js: Configures Remix for server-side rendering on Vercel's infrastructure.
Sources: README.md:113-117, VERCEL_DEPLOYMENT.md:1-15
Summary
Contributing to Bolt requires adherence to specific Node.js and pnpm versions to ensure environment parity. The workflow centers on a robust CI/CD pipeline where automated tests, type checking, and linting must pass before merging into the production branch. By following these guidelines, contributors help maintain the stability of the browser-based development environment and the AI integration core.