Code generation CLI best practices

The 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.

What to know

• Following these best practices leads to more successful, issue-free code generation with the Code Generation CLI.
• Use code generation through either interactive or non-interactive mode.
• Use the .builderignore and .builderrules file to customize how the Code Generation CLI generates code within your project.

Key recommendations

To get the most out of the Code Generation CLI, keep the following recommendations in mind.

Commit before code generation

Before generating code, commit any existing changes to your local project. This lets you isolate the Code Generation CLI changes in separate commits or revert them if needed.

Choose the correct root directory

Always execute the command from your specific project's root directory. The Code Generation CLI analyzes project structure to determine framework, dependencies, and coding patterns.

However, do not run the 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 the Code Generation CLI.

Be specific with instructions

The Code Generation CLI is more successful when you provide specific and detailed prompts. In your prompts, describe the changes you would like in detail and what you'd like the intended effect to be.

For example, compare the following prompts:

• ❌ Don't: Add a product filter.
• ✅ Do: Add a product filter above the list of products so that users can sort by price. Make the product filter its own component.

Make small, iterative changes

The Code Generation CLI is more successful with smaller, specific changes. Verbose prompts, even if specific, may lead to unexpected outcomes.

For example, the following prompt is likely too expansive:

• ❌ Don't: 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:

• ✅ Do: Update the product card to include a carousel in place of the single existing image.
• ✅ Do: Update the product card carousel to automatically change images every five seconds.
• ✅ Do: Update the product card with a +/- button besides the quantity. Clicking '+' increases the quantity by 1 while clicking '-' decreases the quantity by 1.
• ✅ Do: Update the product card with a dropdown for the following sizes: XS, S, M, L, XL.

Smaller, specific prompts typically lead to better results with Code Generation CLI.

Interactive and non-interactive mode

Interactive mode is the recommended mode for the Code Generation CLI. To use interactive mode, follow the instructions in the Code Generation CLI or use the following command.

Mac / Linux

npx builder.io@latest code --url URL

Windows

npx "@builder.io/dev-tools@latest" code --url URL

For non-interactive mode, you can use the following command which will pass a prompt directly to the Code Generation CLI.

Mac / Linux

npx builder.io@latest code --url URL --prompt "your prompt instructions here"

Windows

npx "@builder.io/dev-tools@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

Project-level settings

There are two types of configuration files that can be used with the code command to customize code output.

1. File exclusion configuration, like .builderignore.
2. Rule files, such files within .builder/rules/ or separate .builderrules files.

Additionally, Builder CLI recognizes .cursorrules files used by the Cursor AI Code Editor.

.builderignore

The .builderignore file works similarly to .gitignore, by specifying files and directories to exclude from code generation.

# .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.ts

Use .builderignore to:

• Exclude test files. This prevents 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.

Builder rules directory

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.

To create a rules file for Builder's AI:

1. Create a .builder/ directory within the root of your project.
2. Within the .builder/ directory, create a rules/ directory.
3. Create a .mdc file within the rules/ 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.

.builderrules

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:

1. First searches for a .builderrules file within the current directory.
2. Then recursively searches up to your project's root for other .builderrules files, 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 states

Tips

If you encounter issues while working with the Code Generation CLI:

1. Confirm you are in the correct project directory when running the command.
2. Verify your Builder.io credentials. If authentication fails, try running the auth subcommand npx builder.io auth.
3. 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.

What's next

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.