Projects have several settings that can be modified to ensure your application works correctly as a Project.
- Access settings by hovering over a Project, clicking the three-dots button, and then selecting Project settings.
- Certain settings may not be available to you, depending on your plan.
The general Settings tab contains options that affect key setup and access values for your Project.
By clicking the Open Setup button, you are brought back to the Project setup wizard used when first setting up your Project.
The first few sections of the Settings tab includes details about the Project.
- Connected Repository: for a Project from a repository, a link to the connected repository is included here
- Project Name: an editable name for the Project
- Project ID: the Project's unique ID
The options within this section refer to required dependencies and commands needed to run your application.
Ensure your environment has the exact right tools by specifying which version of tools must be used. To add a runtime dependency:
- Click the Add Dependency button.
- Choose your tool from the available dependencies.
- Choose a version.
Include the steps Builder must take to install and setup your Project. For example, a simple Node.js Project may have the following setup script:
pnpm installThis section includes specifications for Builder so that it can run a development version of your application.
Include the command Builder must use to run your application in development mode. For example, a simple Node.js Project may have the following development server command:
pnpm run devClick the Add Environment Variables button to display two inputs representing a key-value pair. Include your environment variables here.
You can also copy and paste an entire .env file. Copy your .env file, place your cursor within the first input, and then paste.
Toggle this option if you would like this Project to only be available locally. Your Project can then be accessed by a tool like the Builder Desktop app.
After toggling Native application, add requirements for user's local machines using the Add Requirement button.
Set requirements for specific tools or operating systems, as well as a script to check for the requirement.
Defines where you'd like your Projects to run. For more details, visit execution environments.
In this tab, update settings related to working directly within the Visual Editor and the overall Builder workspace.
Add additional repositories as context in your workspace. These are cloned alongside your main project and available to the AI to reference. Useful for design systems, API documentation, etc.
To add an additional repository:
- Go to the Workspace tab.
- Click Add Repository.
- Choose your repository. For more details on how to connect your version control system to Builder, visit Projects setup overview.
- Update any necessary settings. Optionally provide specific instructions to Builder on how to reference and use this repository.
- Click Save.
The Workspace Instructions section appears after adding an additional repository
Use this text box to provide special instructions to the AI related to your workspace. For example, you might provide instructions on where API documentation can be found or where to find shared utility functions.
Within this input field, select which design systems from Builder's Design System Intelligence feature you'd like to use within this Project.
For more details on how to create a design system, visit Design system indexing.
Commands entered here are run after AI completes its task. These commands help verify that your application is still running as intended. For example, you might include the following commands to ensure correct TypeScript usage and test completion.
npm run type-check
npm run testsEnable the browser automation agent to be able to test the application in a browser to verify implementations are correct.
Browser automation runs at the end of any new prompt requests that require changes. Browser automation uses additional agent credits.
Once enabled, enter instructions on how the agent can test the application in the browser. For example, you could include instructions on how to login to the application.
Define the root directory for the project, relative to the repository root. This is particular useful for monorepos, where you want your Project to only manage part of the repository.
For example:
/apps/webIn this tab, configure version control settings related to your connected repository.
The name of your main base branch. When creating new branches or creating a pull request, this value is used.
Checking this option allows you to choose a base branch when creating a new branch on your Project.
When finalizing changes in your Project, determine how you'd like Builder to commit those changes.
- Direct Commits: commits are sent directly to the base branch.
- Draft Pull Requests: commits are added to a new branch and pull request, in draft format. For more details on draft pull requests, visit GitHub's documentation on draft pull requests.
- Pull Requests: commits are added to a new branch and pull request.
By default, Builder creates branches with randomized names and IDs to ensure uniqueness. These branch names can be manually renamed at any time.
To develop a custom naming scheme:
- Go to the Git tab.
- Find the Git Branch Naming heading.
- Choose Custom from the dropdown menu.
- Enter a format for your branch naming scheme.
Customized names can use the following variables when defining names:
| Variable | Description |
|---|---|
| The internal name of the branch defined by Builder. For example, |
| The display name of the branch, editable within Builder. For example, |
| JavaScript timestamp representing when the branch was first created. |
| The unique ID of the user who created the branch. |
Use these variables alongside text templates. For example:
feature/{friendlyName}-{createdAt}In this tab, configure who has access to this particular Project, as well as key settings about peer reviews.
Determine whether your Project is Public or Private.
- Public: all members of the current Space can access the Project.
- Private: access is restricted. For more details, visit roles and permissions.
If you choose to make your Project Private, use this section to define what exact permissions individual roles or users have.
To update permissions:
- Go to the Permissions tab within Project settings.
- Change your Project's access level to Private.
- Use the dropdown input to search for a specific role or user.
- After selecting a specific role or user, expand that section's permissions window.
- Choose that role or user's level of access for the Project. Uncheck Use default permissions to adjust specific permission actions.
- Click Save.
The options within this section define if and how peer reviews interact with the pull request process.
By default, approvals are not required before sending a pull request. Toggling this option on requires other members of your Space to interact with your Project branch before a pull request can be sent.
Once enabled, select which roles must approve the changes before the pull request can be sent. One member from each selected role must approve the changes.
In this tab, several settings can be changed to modify how Builder manages your Project. These settings also manage how other members interact with this Project.
Increase the amount of memory available for this Project at any given time. For larger and more performant machines, request an Enterprise trial.
Enter a numerical value to control how long the agent can run before asking for confirmation to continue.
The value represents the maximum number of completions the agent finishes before asking for input.
By enabling this setting, this Project can only be accessed by downloading and using the Builder Desktop app.
If your application uses hot module replacement (HMR), disable this setting as your application already refreshes when changes occur.
For other applications, enable to ensure your application refreshes when Builder implements changes.
Modify this value if you have your own docker image you'd like to use. This overrides the Node.js version Builder uses.
Add JavaScript regex patterns to ignore specific client-side errors. Errors matching these patterns won't show error popups.
To add an ignore pattern:
- Go to the Advanced tab.
- Find the Error Ignore Patterns heading.
- Click Add Pattern.
- Within the Pattern field, enter your regular expression.
Continue to click Add Pattern to add more regular expressions, or use the trash icon to remove a pattern from the list.
By default, Builder includes the entirety of your repository. For precise control over what files are included within Builder, add inclusion patterns.
To add an inclusion pattern:
- Go to the Advanced tab.
- Find the Include patterns (optional) heading.
- Enter a pattern, like
src/components/**/*. - Press the Enter key.
Continue to add patterns as needed, following the same process.
Within this field, add a CSS selector to target a specific element or iframe for design mode parsing.
If specified, the first matching element is used as the root instead of document.body. For iframes, their content is parsed. For regular elements, the element itself becomes the root.
For example:
#preview-containerWhen strict mode is toggled off and you supply design tokens for a specific CSS property, the Visual Editor only allows selecting from the predefined tokens for that property. Custom values cannot be entered for properties that have design tokens defined.
Strict mode takes this a step further. When strict mode is on, any styles that don't have corresponding design tokens are removed from the Visual Editor and users won't be able to edit those styles at all.
For more details, visit Design tokens.
By default, this value is auto-detected by Builder. To manually enter a development server URL, uncheck Auto-detect dev server URL and update the input field.
If Builder's auto-detection is not accurately accessing your development server's URL, include a regular expression here to aid Builder in detecting the URL.
Read more about Builder and Integrations, or learn about other ways to Add context to projects.