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.
During the code generation process, you will be asked to select a context file. This identifies the most relevant file to your request.
For many requests the context file is not necessary. However, if your prompts lead to changes in more files than you'd expect, or are misunderstood, choose a context file.
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
Two files can be used with Code Generation CLI to customize code output.
.builderignore # Exclude specific files from code generation
.builderrules # Add custom instructions for code generationAdditionally, if your project contains a .cursorrules file for the Cursor AI Code Editor, Code Generation CLI will utilize that as well.
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.tsUse .builderignore to:
- Exclude test files from being modified
- Protect critical or sensitive files from changes
- Focus code generation on specific parts of your codebase
- Exclude third-party code
The .builderrules file provides custom instructions that guide how code is generated for your project.
# .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 statesUse .builderrules to:
- Ensure generated code follows your team's coding standards and conventions
- Guide code generation for specific frameworks like Next.js or React
- Maintain consistent file structure and organization for your project's architecture
- Specify a11y standards that must be followed for your project
- Include instructions about code splitting or optimization
- Guide integration with specific libraries your project uses
If 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.