Project settings
Projects have several settings that can be modified to ensure your application works correctly as a Project.
What to know
- 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.
General
The General tab contains basic details about your Project.
Project name
Your Project's name. This is the name that is displayed on your dashboard.
Require Desktop app
By enabling this setting, this Project can only be accessed by downloading and using the Builder Desktop app.
Project access
Determine whether your Project should be visible to your Team or Private.
- Team: all members of the current Space can access the Project.
- Private: access is restricted. For more details, visit roles and permissions.
Project 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.
Delete Project
Click this button and enter your Project's name to permanently delete your Project. Keep in mind that this change is permanent.
Setup
The Setup tab contains settings necessary for establishing your Project. Look here for configuration options that enable your Project to correctly launch within the Visual Editor and support the AI in developing consistent content.
Project setup
By clicking the Open Setup button, you are brought back to the Project setup wizard used when first setting up your Project.
Design systems
Within this input field, select which design systems from Builder's Design System Intelligence feature you'd like to use within this Project. You can also click the Index New Design System button to create a new design system.
For more details on how to create a design system, visit Design System Intelligence with Builder UI.
Environment variables
Click the Add Variable 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.
Runtime dependencies
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.
Dependency install script
Include the steps Builder must take to install and set up your Project. For example, a basic Node.js Project might have the following setup script:
Dev command
Include the command Builder must use to run your application in development mode. For example, a basic Node.js Project might have the following development server command:
Dev server URL
The command or script developers use to start the development server. Check the Auto-Detect box to have Builder automatically detect the running server.
Dev server patterns
Builder tries to detect the URL using built-in patterns. You can add custom patterns to improve detection.
Validation command
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.
Advanced setup
The following settings are likely only relevant in specific scenarios.
.npmrc contents
The .npmrc file is an instruction file that contains authentication and location information for private npm packages. If needed, enter the contents of this file here.
Other file overrides
Drag and drop files here that you wish to be included in your Project setup. These files are likely configuration files that require edits to work with Builder.
Fusion execution environment
Defines where you'd like your Projects to run. For more details, visit execution environments.
Docker image path
Modify this value if you have your own docker image you'd like to use. This overrides the Node.js version Builder uses.
Workspace
The Workspace tab provides settings that modify and improve the experience of working on your Project with AI.
Additional repositories
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.
Workspace instructions
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.
App subpath
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:
Automatic refresh preview
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.
Error ignore patterns
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.
Design mode selector
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:
Git
The Git tab provides a way to manage and customize the connection your repository, as well as how you would like Builder to interact with your Project's version control.
Test connection
Click the Test Connection button to test Builder's connection to your repository. This tests Builder's connection from several subdomains.
Preferred Project for repository
Toggle this option on to set this Project as the preferred Project for its connected repository. When an agent is asked to do something with this repository, it will use this Project by default.
This is particularly useful if you use Builder's agent outside of a Project, such as when you Integrate Slack.
Commit mode
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.
Default branch visibility
When creating a new branch, determine whether your Project is visible only to you or if it's visible to other members on your team.
- Private: your branches are, by default, only visible to you. You can still manually share your Project with others. For more details, visit Collaboration in Projects.
- Shared: your branches are visible to other members of your team.
Main branch name
The name of your main base branch. When creating new branches or creating a pull request, this value is used.
Choose base branch when creating new branches
Checking this option allows you to choose a base branch when creating a new branch on your Project.
Enable merging PRs
If toggled on, allow merging pull requests directly from Builder as opposed to needing to go to your version control provider.
Git branch naming
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:
File include patterns
Specify which parts of your repository to include when cloning. Press the Enter key or leave the field to add a pattern.
Follow typical path conventions. For example, the following pattern would include everything within the packages/app/ directory:
Review
The Review tab provides customizations for Builder's Peer reviews, as well as its AI-powered quality reviews.
Peer review
By default, approvals are not required before sending a pull request. Toggling this option on requires at least one other member of your Space to approve your Project branch before a pull request can be sent.
Required role approvals
Enterprise plans
Enterprise plans may select which roles must approve the changes before the pull request can be sent. One member from each selected role must approve the changes.
Quality review
Team plans
Enterprise plans
Whenever a Builder user submits a pull request, Builder can provide feedback directly on the request. To enable this feature, toggle the Code Review option on.
After enabling, optionally choose a model to use for code reviews or add instructions on how the agent should review the proposed code.
For more details, visit Enable review agent.
Agent
The Agent tab displays options for providing additional context to Builder's agent.
Workspace instructions
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.
Agent run duration
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.
Enforce default command restrictions
By default, this option is toggled on. When toggled on, the AI agent is restricted from running certain shell commands, such as curl and npx.
Agent mode
When toggled on, show the Agent tab and keep users in agent chat instead of auto-switching to preview mode.
Hosting
The Hosting tab displays options for hosting Projects with Builder. Here you can manage the published site and details about it.
Hosting details
There are several details at the top of the Hosting tab section:
- Status: this displays whether or not your site is currently live.
- Web address: your deployed website's live URL.
- Custom domain: your custom domain address, if configured. Click the Connect Domain button to provide a custom domain.
AI usage
Select your application's agent connection:
- Use Builder Agent: Builder provides your AI agent. Purchase additional credits directly within Builder.
- Use your own Anthropic or OpenAI key: provide a key from one of these service providers to use them as your AI agent.
- Users bring their own key: prompt users to provide their own key when using AI capabilities within this Project.
Site AI token
When you choose to pay for AI credits for your users, a token is created by Builder. If you need to revoke your token for any reason, click the Revoke Token button.
Advanced settings
Additional settings related to your deployment can be found here. These settings can override builder.config.json when publishing.
Build command
Enter the command required to build your application. Typically something like the following:
Output directory
The destination directory for the results of your build command.
Node version
Determines which version of node is used for your published application.
Build environment variables
Provide environment variables necessary for your build step.
Production environment variables
Provide environment variables specifically for the production build of your application.
Unpublish
Click the Unpublish button take your site offline. Your code is not affected by this change, and your URL stays reserved.
Installation commands
The options within this section refer to required dependencies and commands needed to run your application.
Dev server commands
This section includes specifications for Builder so that it can run a development version of your application.
Native application
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.
Host requirements
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.
Agent
In this tab, update settings related to working directly within the Visual Editor and the overall Builder workspace.
Browser automation
Enable 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.
Git
In this tab, configure version control settings related to your connected repository.
Permissions
In this tab, configure who has access to this particular Project, as well as key settings about peer reviews.
Advanced
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.
Memory
Increase the amount of memory available for this Project at any given time. For larger and more performant machines, request an Enterprise trial.
Include patterns
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.
Strict mode
When 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.
Development server URL
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.
Advanced auto-detection settings
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.