Many complex applications use multiple repositories, each interconnected with the others. However, Builder Projects require you to choose a single repository as the Project's entry point.
By connecting multiple repositories to a single Project, Builder's AI can update features across them.
Multi-repo support provides you with the ability to make coordinated changes across repositories. Create multiple PRs, commit to different repos, and run apps independently in separate terminals.
Pair these benefits with custom workspace instructions to make setup even more powerful. Teach our AI how the repos relate to each other, what each one is responsible for, and any relevant workflow context.
This leads to smarter, more accurate changes within your codebase.
To add additional repositories to a Builder Project:
- Go to your Builder Projects page.
- Click the three-dot menu on your selected Project.
- Navigate to the Agents tab.
- Under the Additional Repositories heading, click the Add Repository button.
- Choose a repository to add from the dropdown list.
- Toggle on the Allow Write Access toggle.
- Click Save.
When working on your Project, Builder can now edit the repositories associated with this Project.
Now, whenever you Create a pull request, you have the option to create pull requests to multiple attached repositories.
To run multiple repositories at once, create two commands within your main repository:
- A command to install dependencies for all dependent repositories.
- A command to run all repository servers concurrently.
For example, imagine an application with the following three services:
- main: a service that runs other services and manages requests.
- frontend: a service that displays a front-end client to the user.
- backend: a service that runs a backend server with a database connection.
Within your main directory, you might use the following script to install all dependencies for all three services:
npm install && \
cd ../frontend && npm install && \
cd ../backend && npm installThis assumes all three repositories are within a single directory, all at the same level of depth.
To run all three services concurrently, you may wish to use the concurrently package, using a script like the following:
npx concurrently \
--names "main,frontend,backend" --prefix name --kill-others \
"npm start" \
"cd ../frontend && npm start" \
"cd ../backend && npm start"You could also codify these scripts into files or a configuration file, so that they are easier to share. For example, you could add the following to a package.json file within your main service:
{
"scripts": {
"install-all": "npm install && cd ../frontend && npm install && cd ../backend && npm install",
"run-all": "npx concurrently --names \"main,frontend,backend\" --prefix name --kill-others \"npm start\" \"cd ../frontend && npm start\" \"cd ../backend && npm start\""
}
}By default, Builder only visually previews the main repository used to create the Project initially. This works well for many applications, where additional repositories may be focused on data delivery or particular services.
However, if your application has multiple repositories that deliver visual interfaces, you must take additional steps.
- First, download the Builder.io Desktop App. Multiple repository preview only works when run by the Desktop App.
- Next, update your Dependency Install Script. Your install script should assume your main Project repository as the root directory, and run installation commands for all other repositories. For example:
npm install && cd ../additional-repo && npm install- Finally, update your Dev Command. Use a tool to run all your repositories simultaneously, such as the concurrently package.
npx concurrently \
--names "main,additional" --prefix name --kill-others \
"npm start" \
"cd ../additional-repo && npm start"Builder can now preview each repository individually. Use the location bar within the Visual Editor to adjust the URL and visit other parts of your application.
Environment variables can be added to Projects within the Project settings menu. However, if your additional repositories require separate environment variables, update your Dev Command script to expose and use them.
npx concurrently \
--names "main,additional" --prefix name --kill-others \
"npm start" \
"cd ../additional-repo && MY_ENV=$MY_ENV && npm start"