Connect a local repo to Projects

Builder Projects connects directly to your local 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 through Builder's CLI or VS Code Extension. This doc covers the CLI flow.

Projects currently supports React, Vue, Svelte, and Angular. Other framework support is in active development.

Connect a local repository

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" launch

This 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.

Adjustments to your repository, such as changing the name or deleting branches, can affect Builder's connection to your repository.

Potential breaking changes include:

Changing your repository name
Changing the name of one of your repository's branches
Changing the name of the base branch, or changing which branch serves as the base branch
Deleting a branch
Deleting the repository

If you make any of these changes, you may need to reconnect your repository. Follow your platform-specific instructions, or review the Project setup Overview.

Using --serverUrl

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/dev-tools@latest" launch --serverUrl http://localhost:3000

This 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

Launch in the desktop app

To launch your local repository within the Builder desktop app, include the --app flag within the launch command.

npx "@builder.io/dev-tools@latest" launch --app --serverUrl http://localhost:3000

Launch in chat mode

To enable an AI only chat mode, use the --chat flag. This opens Builder's prompt window for your project without the Visual Editor.

Use chat mode for any kind of general development work.

npx "@builder.io/dev-tools@latest" launch --chat

In the video below, the user runs the above command within a local repository, which opens chat mode in their browser.

Update your allowlist

All Builder Projects access the following list of URLs. Ensure these are included within your application or organization's allowlist.

firestore.googleapis.com firebasestorage.googleapis.com identitytoolkit.googleapis.com *.builder.io *.builder.codes *.builder.my *.builderio.dev *.builderio.xyz *.fly.dev

Each of these URLs serves the following purpose:

Domain	Description
`firestore.googleapis.com`	Base URL for the Cloud Firestore API.
`firebasestorage.googleapis.com`	Base URL for the Firebase Cloud Storage, which serves content such as photos or videos.
`identitytoolkit.googleapis.com`	Base URL for Google's Identity Toolkit API.
`*.builder.io`	Several Builder operations routed through this URL.
`*.builder.codes`	Sandbox Builder operations are routed through this URL. User-generated applications run on this URL.
`*.builder.my`	Preview URLs utilize this domain.
`*.builderio.dev`	Sandbox Builder operations are routed through this URL. User-generated applications run on this URL.
`*.builderio.xyz`	Legacy operations use this URL. Prefer `builderio.dev` for new configurations. If your existing config uses the `builderio.xyz` URL, you don't need to make any changes.
`*.fly.dev`	Legacy operations used this URL. Currently in the process of being deprecated.

Multi-repository workspaces

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.md

2. 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 safety

4. Run the Builder CLI command from the workspace root folder:

For Mac and Linux:

npx "@builder.io/dev-tools@latest" launch --workspace ./workspace.json

For Windows:

npx "@builder.io/dev-tools@latest" launch --workspace ./workspace.json

The 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.

Reference files in the Visual Editor

In the Visual Editor, reference files using this format:

workspaceName/path/to/file.js

For example:

ui/src/Button.tsx refers to ./packages/ui-components/src/Button.tsx
services/index.js refers 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.

Configure builder.config.json

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.json

Here'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 *" ], "repoIndexingConfig": { "designSystems": [ "my-org-react-design-system" ] } }

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.
repoIndexingConfig: Defines design systems indexed as part of Component Indexing to be used during code generation.

With this file in place, go to the /builder-workspace directory and run the command:

npx builder.io launch

This 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 your remote repository 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.

Add custom instructions

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 your remote repository 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 states

Refine code output with AGENTS.md

Builder also respects AGENTS.md files, following typical conventions. Use your AGENTS.md file to tell the AI what kinds of code conventions you want, where API docs are, and any other settings you'd like the AI to use when generating code.

The video below features Builder's CEO, Steve Sewell, editing the AGENTS.md to refine code output:

For more information, see the blog post Improve your AI code output with AGENTS.md.

What's next

Was this article helpful?