in beta
for developers
CLI Code Generation is a powerful tool for translating Figma designs to functional code. This document highlights best practices for developers when using CLI Code Generation.
- Following these best practices will lead to more successful and issue-free code generations with Code Generation CLI.
- Code generation can be completed through either interactive or non-interactive mode.
- The
.builderignoreand.builderrulesfile can be used to customize how Code Generation CLI generates code within your project.
To get the most out Code Generation CLI, keep the following recommendations in mind.
Before generating code with Code Generation CLI, make sure to commit any existing changes to your local project. This will make it easy for you to encapsulate all Code Generation CLI changes within separate commits, or undo unwanted changes.
Always execute the command from your specific project's root directory. Code Generation CLI analyzes project structure to determine framework, dependencies, and coding patterns.
However, do not run Code Generation CLI at the root of a monorepo or in folders containing multiple projects, as this will confuse the analysis and lead to poor results. Instead, first cd into the specific package/app directory before running Code Generation CLI.
Code Generation CLI will be more successful when provided specific and detailed prompts. In your prompts, describe in detail the changes you would like to see and what the intended effect will be of those changes.
For example, compare the following prompts:
- ❌ Add a product filter.
- ✅ Add a product filter above the list of products so that users to sort by price. Make the product filter its own component.
Code Generation CLI will be more successful when provided smaller, specific changes. Verbose prompts, even if specific, may lead to unexpected outcomes.
For example, the following prompt is likely too expansive:
- ❌ Update the product card to include a carousel for images (each image should pause for 5 seconds before rotating to the next image automatically), a +/- button besides the quantity, and a dropdown for the following sizes: XS, S, M, L, XL.
Instead, consider the following set of smaller prompts that could be provided one after another:
- ✅ Update the product card to include a carousel in place of the single existing image.
- ✅ Update the product card carousel to automatically change images every five seconds.
- ✅ Update the product card with a +/- button besides the quantity. Clicking '+' increases the quantity by 1 while clicking '-' decreases the quantity by 1.
- ✅ Update the product card with a dropdown for the following sizes: XS, S, M, L, XL.
Smaller, specific prompts will typically lead to better results with Code Generation CLI.
Interactive mode is the recommended mode for Code Generation CLI. To use interactive mode, follow the instructions in Code Generation CLI or use the following command.
npx builder.io@latest code --url URLFor non-interactive mode, you can use the following command which will pass a prompt directly to Code Generation CLI.
npx builder.io@latest code --url URL --prompt "your prompt instructions here"The code command will accept the following flags:
- --url: The design URL to generate code from
- --spaceId: Your Builder.io space ID
- --prompt: Instructions for non-interactive mode
- --cwd: The working directory for the command
- --help: View usage instructions and additional flags
There are two types of configuration files that can be used with the code command to customize code output.
- File exclusion configuration, like
.builderignore. - Rule files, such files within
.builder/rules/or separate.builderrulesfiles.
Additionally, Builder CLI recognizes .cursorrules files used by the Cursor AI Code Editor.
The .builderignore file works similarly to .gitignore, allowing you to specify files and directories that should be excluded from code generation consideration.
# .builderignore example file
# Exclude test files
**/*.test.tsx
**/*.spec.ts
# Exclude specific directories
node_modules/
.next/
dist/
# Exclude specific files
src/legacy-components/
src/utils/deprecated-helpers.tsThe .builderignore file can be used to:
- Exclude test files. This prevent test files from being modified during code generation.
- Protect critical files. Keep sensitive or complex code from being altered.
- Focus code generation. Direct the CLI to work only on relevant parts of your codebase.
- Exclude third-party code. Prevent modification of vendored or library code.
A .builder/rules/ directory provides custom instructions that guide how code is generated for your project. These files are used whenever the code generation tool is given a new prompt.
These files can scope rules to specific files and allow for more granular instructional precision.
To create a rules file for Builder's AI:
- Create a
.builder/directory within the root of your project. - Within the
.builder/directory, create arules/directory. - Create a
.mdcfile within therules/directory. Provide a sensible name for your file and provide the metadata as shown below.
# .builder/rules/component-structure.mdc
---
description: Component structure
globs:
alwaysApply: true
---
All components should have prop validation.
Organize new components in the following way:
- src/components/{feature}/{ComponentName}.tsx
Export components from an index.ts file in each directory.In the rules file above, specific instructions are provided to the AI about the component structure.
The following options are available as keys within the metadata header:
- description: a brief description of the file's rules
- globs: specific file paths where these rules should apply
- alwaysApply: if set to
true, the AI always applies these rules; otherwise, the AI contextually decides when to apply the rules
An alternative to the .builder/rules/ directory is to create individual .builderrules files. The .builderrules file provides custom instructions that guide how code is generated for your project. This file is used whenever the code generation tool is given a new prompt.
Builder's AI:
- First searches for a
.builderrulesfile within the current directory. - Then recursively searches up to your project's root for other
.builderrulesfiles, joining all instructions together.
Rule files in the current directory take precedence over rule files in parent directories. This allows you to have project-wide rules in the root directory and more specific rules in subdirectories.
# .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 statesIf you encounter issues while working with Code Generation CLI:
- Confirm you are in the correct project directory when running the command.
- Verify your Builder.io credentials. If authentication fails, try running the auth subcommand
npx builder.io auth. - Ensure you're signed into the same space in the Figma plugin, the Code Generation CLI, and the Builder.io dashboard.
You may also use the --help flag with the code command or reach out for help on the Builder Community Forum.
Learn more about the Builder Figma plugin or see Figma export modes for more details on how to export your design from Figma. After that, learn to Map components with the CLI.