in beta
Builder Projects connects directly to your GitHub repositories, letting you visually edit code and create applications with AI assistance. This guide covers everything you need to know about setting up and managing the connection between Builder and your local codebase.
Projects supports local development via our CLI or VS Code Extension. This doc will cover the CLI flow.
Projects currently supports React, Vue, Svelte, and Angular. Other framework support is in active development.
To connect to a repository you have cloned locally, use the Builder CLI:
1. At the command line, go to the root of your project and run the command below:
npx "@builder.io/dev-tools@latest" launchThis command asks you to confirm installation. Answer y for yes.
2. The CLI opens a Builder prompt in the browser where you can select the Builder Space you want to authorize. When you've authorized Devtools, the Builder Visual Editor opens so you can visually edit your local code.
3. When the project opens in the Visual Editor, make edits using the AI prompt. Alternatively, you can also make edits manually.
The video below shows running the command at the command line followed by the repo opening in the Builder Visual Editor.
To connect to an already running dev server, you can use the --serverUrl flag to instantly launch connected to that url, e.g.
npx "builder.io@latest" launch --severUrl http://localhost:3000This is also useful if you need to connect to servers not on localhost, such as on a custom domain like https://local.mysite.com:8080
Builder Projects supports working with multiple repositories as a single virtual workspace. This feature is based on the VS Code workspace standard (but does not require using VS Code).
To set up a multi-repository workspace with the Builder CLI:
1. Create a root folder for your workspace. Inside this folder, create two files:
/workspace-root
workspace.json
AGENT.md2. In the workspace.json file, define your workspace structure:
{
"folders": [
{
"path": "./packages/ui-components",
"name": "ui"
},
{
"path": "./packages/data-services",
"name": "services"
},
{
"path": "./apps/web",
"name": "web"
}
]
}3. In the AGENT.md file, provide instructions and context for the AI agent, for example:
# Project Structure and Guidelines
This is a multi-repo workspace with the following components:
## UI Components (/packages/ui-components)
- Contains reusable React components
- Use when updating shared UI elements
## Data Services (/packages/data-services)
- Houses API and data management logic
- Update when modifying data flows or adding new services
## Web App (/apps/web)
- Main web application
- Use for page-level changes and app-specific logic
General Guidelines:
- Follow the existing code style in each repo
- Write unit tests for new components and functions
- Use TypeScript for type safety4. Run the Builder CLI command from the workspace root folder:
For Mac and Linux:
npx builder.io@latest launch --workspace ./workspace.jsonFor Windows:
npx "builder.io@latest" launch --workspace ./workspace.jsonThe workspace.json file defines the structure of your multi-repo setup, while the AGENT.md file provides context for the AI to work effectively within your project setup.
In the Visual Editor, reference files using this format:
workspaceName/path/to/file.jsFor example:
ui/src/Button.tsxrefers to./packages/ui-components/src/Button.tsxservices/index.jsrefers to./packages/data-services/index.js
This feature gives you a way to:
- Organize large projects or monorepos effectively
- Work on multiple related repositories simultaneously
- Share code and resources across different parts of your application
Builder's AI tools is aware of the workspace structure, enabling accurate suggestions and edits across your entire project. Each workspace folder can also have its own AGENT.md file for more specific instructions related to that particular part of the project.
For advanced configuration and easier setup, use a builder.config.json file in your project root. Use this file to specify various settings for your Builder workspace, including multi-repository configurations.
Create a folder for your Builder workspace and add the builder.config.json file, for example:
/builder-workspace
builder.config.jsonHere's an example of a builder.config.json file:
{
"command": "cd browser && npm run dev",
"serverUrl": "http://localhost:8070",
"commitMode": "draft-prs",
"workspace": {
"folders": [
{
"path": "./server"
},
{
"path": "browser",
"name": "browser-client"
}
]
},
"allowedCommands": [
"npm *",
"pnpm *",
"yarn *",
"git diff *",
"git log *",
"git status *",
"echo *",
"cd *",
"find *",
"ls *",
"curl *"
]
}Key features of builder.config.json:
command: Specifies the command to start your development server.serverUrl: Sets the URL where your application will be accessible.commitMode: Determines how changes are committed; for example, "draft-prs" for draft pull requests).workspace: Defines your multi-repository workspace structure.allowedCommands: Lists commands that can be executed in the Builder environment.
With this file in place, go to the /builder-workspace directory and run the command:
npx builder.io launchThis command uses the settings from your builder.config.json file, simplifying the launch process.
The builder.config.json file is versatile and can be used both when connecting from GitHub and for additional configuration in Builder Projects. It provides a convenient way to set up your workspace and customize the Builder environment to suit your project's needs.
When working frequently with Builder, it can be useful to provide a consistent set of instructions to the AI that determines how the AI should write code or organize files. These instructions can be included within a .builderrules file.
A .builderrules file is created for you when creating a new repository or connecting your repository from GitHub and making changes. You can edit this file directly within your repository to provide more context to Builder's AI. For more details on .builderrules, see Code generation best practices.
# .builderrules
# Project-wide guidelines
Follow BEM naming convention for CSS classes
Use functional components with TypeScript interfaces for props
Add JSDoc comments to all exported functions
# Component structure
All components should have prop validation
Place components in src/components/{feature}/{ComponentName}.tsx structure
Export components from an index.ts file in each directory
# Styling guidelines
Use Tailwind CSS utility classes for styling
Prefer grid layout over flexbox when appropriate
Ensure all interactive elements have proper focus statesBuilder also respects AGENTS.md files, following typical conventions for these kinds of files.
After your local repository is connected, explore these resources to enhance your development workflow:
- The Builder Projects CLI. Learn about advanced configuration, multi-repository workspaces, and monorepo support.
- Connect GitHub to Projects. Discover branch management and pull request workflows for connected repositories.
- Builder Projects: best practices. Get tips for working effectively with connected repositories.
- AI Credits. Learn about how Builder's AI credits work.