private beta
Builder Projects lets you create and edit applications with your real code using AI and visual tools. Follow these best practices to get the most out of Projects.
Builder Projects needs example code to work effectively.
This means that your connected repository must contain working examples of your components. Without real life code for the AI to analyze, it can't understand how your components should be used.
If you don't have these examples in the repository you are working from, you can add additional repositories to projects.
The quality and comprehensiveness of your example code directly impacts the AI's ability to generate useful results.
Builder Projects is a powerful tool that can solve several coding and design challenges you may encounter. However, Builder Projects does best with the following scenarios.
Create interfaces based on text prompts with Builder Projects. The more detailed and clear your prompts, the better output you will have.
In the video below, a text prompt asks Builder Projects to add a table to the bottom of the page using a specific Material UI component.
Quickly generate code without extensive configuration. Create an entire Project from prompts, Connect with GitHub, or Connect a local repository and let Builder Projects do the rest.
In the video below, a GitHub repository is connected to Builder Projects. The repository's application immediately begins running in Builder Projects and then is prompted to make changes.
Here's the step-by-step workflow we recommend for using Builder Projects effectively:
- Get your Developer to connect the repository you want to contribute to.
- Make a branch.
- Make your edits with the AI prompt or with the editing tools available in the Visual Editor.
- Send PRs (pull requests).
When the PR is merged, Projects automatically deletes the branch. This is a standard workflow item in version control. To make more edits after a merge, create a new branch for those edits and submit another PR.
If your company doesn't want to evaluate Projects with actual proprietary code, there are still options.
Option 1: use open source example code
- Fork an existing repository and connect it on the Projects tab. See Connecting an existing GitHub repository in the Projects document.
- Find example repositories at the bottom of the Projects tab.
Option 2: start with a low-risk internal tool code
- If you can't connect your main production app, start with a smaller or lower-value application.
- Use the code for an internal tool that your team uses for testing purposes.
Builder Projects uses standard development workflows that involve branches and pull requests. If you're new to version control like git, these concepts might be new to you. This section covers what you need to know.
A branch is like creating your own personal copy of a document to work on. Just as you might make a copy of a shared Google Doc to draft changes without affecting the original, a branch lets you make changes to the website or app without changing what's live. It's your private workspace where you can experiment and make updates safely.
Create a new branch whenever you're starting a new task or feature. It's like starting with a fresh copy each time you begin a new project. This keeps your changes organized and separated from other work happening at the same time. Examples of work warranting a branch might include:
- editing a nav
- iterating on a UI implementation
- changing colors so you can check for accessibility and cohesiveness in light and dark mode before merging
- anything that could be a discrete project
When you create a branch, it's like taking a snapshot. Your branch captures how everything looks at that exact moment and won't automatically get updates that teammates make to the main version.
- Your branch becomes outdated over time. Like working on a copy of a document while others edit the original, the longer you work on your copy, the more different it becomes from the current version.
- Busy projects change quickly. On active projects where multiple people are making updates, the main codebase can change rapidly.
- Delays make merging challenging. The longer you wait to submit your changes, the more likely your version will conflict with what others have done, making it harder to combine everything together.
- Work fast and submit promptly. Make your changes in small chunks and submit your PR quickly to avoid complications when merging.
When a branch is merged, Builder Projects automatically deletes the pull request's working branch; that is, your feature branch that you use to submit your PR.
A PR is like submitting changes for review. Think of it as sending a proposal that says "I've made these updates — can someone check them and approve them?"
- You're not changing the live site directly. Creating a PR means you're suggesting changes that developers can review first.
- Reviewers can respond in different ways. They can provide feedback, request adjustments, or approve and merge your changes into the official version.
The PR process protects the live site. It prevents mistakes from immediately affecting what users see and gives technical team members a chance to ensure your changes work well with the rest of the system.
In the video below, the Send PR button is clicked after some changes are made to a Builder Project. The user is then brought to the connected GitHub repository where they can add comments. This process does not make any updates to the code.
For best results, we recommend using Auto Layout in your Figma design.
Auto layout helps the AI understand structure, spacing, and intent — resulting in cleaner code and fewer fixes later.
Best practices:
- Apply Auto Layout to all layers.
- Explicitly define images.
- Avoid overlapping elements, oversized text boxes, and unnecessary transparency.
For more detail and tips, read Set up your design for Figma Import.
To get the most out of AI-powered editing in Builder Projects, follow these prompting guidelines.
Builder Projects better understands your prompts if provided images. Screenshots can be provided as part of a request to fix something or as design inspiration.
In the video below, both a screenshot and PDF file are used as inspiration for creating a new feature.
The more context you provide, the better the AI can help you create and iterate on your project. Provide context content by either of these options:
- pasting files into the Projects prompt
- clicking on the plus icon and selecting your files
Supported file types to upload include:
| Extension | File type name |
|---|---|
.csv | CSV (comma separate values) file |
.docx | Microsoft Word file |
.epub | EPUB file |
.html | HTML file |
.json | JSON file |
.odt | OpenDocument Text file |
PDF file under 100 pages | |
.rtf | rich text file |
.txt | text file |
.xlsx | Microsoft Excel file |
You can upload up to 20 files per chat, with a maximum size of 30 MB per file. For files other than PDFs, the AI can only use the text and cannot use the images.
Developers can also add a .builderrules or AGENTS.md file to the repo with specific instructions. For more detail, see the Add custom instructions section of Connect GitHub to Projects.
Define your preferred logic: include relevant logic or conditions the AI should follow.
State the action clearly: use explicit instructions like "add a button inside the header that links to /login" or "update the product card to show a 'New' badge if tag is new".
Prompts in need of clarity might produce unexpected or unrelated code. The AI might infer behavior that doesn’t match your intent; for example, using nonexistent data or adding unrelated elements. Here are some example prompts to get you started.
- ❌ Don't: Add logic for content length.
- ✅ Do: Add logic in the article card to display the number of words, and show it next to the publish date.
- ❌ Don't: Fix this section.
- ✅ Do: In the product grid, fix the layout issue where items overflow the container on mobile screens. Use CSS Flexbox and ensure items wrap properly.
These Do examples:
- Name the location where the work should be done.
- Identify what logic to apply.
- Define the data to use or the problem to solve.
If your app uses custom authentication, such as a CLI-based login, Projects may not be able to preview protected content within the Projects UI. To confirm that changes appear correctly, open your app in a regular browser where you’re already logged in.
Query parameters — including ones used for previewing specific content, such as ?builder.preview=internal-review or ?builder.preview=marketing-team — are not currently applied within Projects, so content behind preview tokens or environment-specific flags may not display as expected inside the Projects UI.
If the dev server goes down mid-session, Projects might crash or return a generic error. If this happens, reopen the Projects project to restart the dev server.
If your build fails, paste a list of lint errors into the prompt so Projects can fix them for you.
Treat your interaction with Builder's AI as a conversation: give feedback, point out what to change, and continue refining until you reach the desired result.
Best practices:
- Always give feedback to the AI. The first output doesn't have to be final. Be specific about what to fix or improve.
- Work iteratively. Each response from the AI is an opportunity to steer it closer to your goal. Follow up with clear instructions to clarify what you want it to do.
- Use screenshots. When describing an issue, provide screenshots of the result along with a short explanation of what should be different. This significantly improves the success rate.
- Be clear and specific. The more precise you are about what you want, the better the AI can understand your intent. Use examples, references, or detailed descriptions to guide it.
- Provide context. Explain the purpose of the task or the broader project goals. This helps the AI align its output with your goal.
Providing clear, contextual feedback — especially visual references like screenshots — helps the AI learn your intent and improves the outcome.
For more information on working with Builder Projects and Builder's AI, visit:
- Builder Figma Plugin. Learn how to use the Builder Figma plugin to get your design into Builder.
- AI Credits. Understand Builder's AI credits and how and when they apply.
- Connect GitHub to Projects. Connect your repo to Builder so you can edit your code visually and create PRs with Builder.