experimental
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 codebase.
Projects currently supports React, Vue, Svelte, and Angular. Other framework support is in active development.
To connect an existing GitHub repository:
- On the Projects page, click Connect Repo.
- Connect a GitHub account and grant access to all or selected repositories.
- Select a GitHub repository to use within Projects.
- In the Project Settings dialogue, update the configuration fields.
- Click Save.
The following are the configuration fields:
- Project Name: a unique name to identify the project.
- Development Server Port: the local port the app uses such as
3000or5173. - Setup Script: the command to setup and install dependencies, such as
npm install,yarn.Can be multiple lines and steps. - Development Server Command: the command to start the development server, not a production build.
- Primary Branch Name: the branch to clone, such as
mainordev. - Environment Variables: include key–value pairs that support installation and development.
Builder clones your repository, installs dependencies, runs the development server, and opens the Visual Editor, giving full access to the connected project for real-time content editing and previewing.
The video below demonstrates how to connect an existing GitHub repository:
When working with monorepos or other advanced situations, you must adjust your configuration fields to navigate to the correct package directory.
Your setup script might need multiple lines to navigate to the correct directory and install dependencies:
# Install any globally needed packages
npm install -g pnpm
# Change to the directory of your app
cd packages/app
# Install dependendies
pnpm installThis ensures the development server starts in the correct package directory. Remember to:
- Adjust the path (
packages/app) to match your monorepo structure. - Run any other setup steps you need for your project.
For monorepos, combine the directory change, cd, and start command in one line:
cd packages/app && npm run devThis ensures the development server starts in the correct package directory. Remember to:
- Adjust the path (
packages/app) to match your monorepo structure. - Use the appropriate package manager commands (
npm,yarn, orpnpm).
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/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, or manually if you prefer.
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:
- Create a root folder for your workspace. Inside this folder, create two files:
/workspace-root
workspace.json
AGENT.md- In the
workspace.jsonfile, define your workspace structure:
{
"folders": [
{
"path": "./packages/ui-components",
"name": "ui"
},
{
"path": "./packages/data-services",
"name": "services"
},
{
"path": "./apps/web",
"name": "web"
}
]
}- In the
AGENT.mdfile, 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 safety- Run the Builder CLI command from the workspace root folder:
For macOS/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 allows you 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 will be 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 more advanced configuration and easier setup, you can use a fusion.config.json file in your project root. This file allows you to specify various settings for your Builder workspace, including multi-repository configurations.
Create a folder for your Builder workspace and add the fusion.config.json file, e.g.:
/builder-workspace
fusion.config.jsonHere's an example of a fusion.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 fusion.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 (e.g., "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, you can navigate to the /builder-workspace folder and simply run:
npx builder.io launchThis command will use the settings from your fusion.config.json file, simplifying the launch process.
The fusion.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 on a Project, create a branch to feature your updates. Typically, pull requests are submitted from a feature branch to the main codebase.
To manage branches in connected repos:
- Go to Projects.
- To create a branch, click + New Branch. Builder starts the project and creates a new branch. The new branch is displayed on the tile for that project when you return to the Projects page.
- To rename, delete, or share a branch, go to the tile for the repo and click the settings wheel by Branches. Select the appropriate option.
Note that to have a + New Branch button available for a connected repo, the Commit Mode for that repo's settings must be set to Pull Requests or Draft Pull Requests. To edit this setting:
- Go to the repo's settings by clicking the Settings wheel on the upper right of the repo's tile.
- In the dialogue that opens, go to Advanced Settings and for Commit Mode, select Pull Requests or Draft Pull Requests.
The video below shows creating, renaming, sharing, and deleting a branch.
To submit changes and create a pull request (PR) to the connected repository:
- In the Visual Editor, make the required updates.
- Click Send PR from the toolbar.
- In the Pull requests tab, review the proposed changes.
- To request additional edits, comment in the pull request and tag @builderio-bot with specific instructions. The bot applies the changes to the same PR.
The following video demonstrates sending a PR and using the Builder agent to apply changes:
For more information on getting your Figma designs into Builder, visit: