private 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 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:
For Mac or Linux:
npx builder.io@latest launchFor Windows:
npx "builder.io@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. Choose the Space where you use Projects. When you've authorized Devtools, the Builder Visual Editor opens so you can visually edit your local code. (You can still edit your code with any other IDE or tools you already use.)
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.
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 with monorepos or other advanced situations, you must adjust your configuration fields to navigate to the correct package directory.
For monorepos, your setup script may need multiple steps:
# Install any globally needed packages
npm install -g pnpm
# Change to the directory of your app
cd packages/app
# Install dependencies
pnpm installCombine directory change and start command:
cd packages/app && npm run devRemember to:
- Adjust the path (
packages/app) to match your monorepo structure. - Use the appropriate package manager commands (
npm,yarn, orpnpm) - Run any other setup steps needed for your project.
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.