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 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 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.
When a branch is merged, Builder Projects automatically deletes the branch, which is a typical workflow in version control. To make additional changes, create a new branch.
Each new branch is a fresh clone of the main branch and ensures the most recent codebase. For workflow tips on using branches, see the Branches section of Builder Projects: best practices.
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:
Now that your GitHub repository is connected, explore these resources to get the most out of Builder Projects:
- Builder Projects: best practices. Get tips and insights to work even smarter with connected repositories.
- The Builder Projects CLI. Learn about advanced configuration options and multi-repository workspaces.
- Convert a Figma design to code with Projects. Import your Figma designs directly into your connected repository.
- AI Credits. Understand how your AI credits work with Builder.