Learn how to improve your code output with the creation of custom configuration files. These files instruct the AI on how to generate code.
- Add rule files with an
.mdcextension to a.builder/rules/directory. These files should provide explicit instructions to the AI. - Create and update a single
.builderrulesfile to the root of your project using the Settings and instructions button at the bottom of the prompt window.
AI doesn't retain memory between sessions. Rules provide persistent and reusable context.
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
Builder's AI will not make any changes to your rule files.
Builder currently supports .builderrules files as well.
All instructions can be placed in a .builderrules file and will be read by Builder's AI. Consider adding structured headings to improve the readability of this file.
These files can be placed in any directory, and Builder will recursively search through your project to join each file. Files closer to the current working directory take precedence over files in parent directories.
This allows you to have project-wide rules in the root directory and more specific rules in subdirectories.
For more details, visit Project-level settings.
Create or update the root .builderrules file within Builder's Visual Editor by doing the following:
- Click on the cog icon at the bottom of the prompt field.
- Enter rules you want the AI to follow when generating code.
- Click the Save button.
This button provides easy access to the root .builderrules file. Keep in mind that changing the contents within this panel will change the file!
Rules should be actionable, focused, precise, and scoped.
- Keep rules under 500 lines.
- Split large rules into multiple, composable rules.
- Provide concrete examples or referenced files.
- Avoid vague guidance. Write rules like clear internal docs.
- Ensure rules in one file do not conflict with rules in another file.
Full .builderrules examples are included below.
A file like this should be placed in the root directory of your application.
# .builderrules (root)
## Operating principles
- Prefer small, composable changes over large rewrites.
- Match existing project patterns (folder structure, naming, exports, conventions) before introducing new ones.
- If requirements are unclear, implement the smallest reasonable interpretation and leave TODO comments only when necessary.
## UI component decision checklist (do this in order)
1) Reuse an existing component in the codebase if it fits (or extend it).
2) Use the project's design system / UI library components before custom UI.
3) Prefer utility classes / tokens (spacing, colors, typography) over one-off CSS.
4) Only write custom CSS when tokens/utilities can't achieve the design.
## Styling rules
- Avoid inline styles except for truly dynamic values (e.g., computed widths).
- Do not use `!important`.
- Use design tokens / CSS variables when available; include safe fallbacks where appropriate.
- Ensure hover/focus/active/disabled states exist for interactive elements.
## Accessibility baseline (must-haves)
- Every interactive element must be keyboard-accessible.
- Provide visible focus styles (don't remove outlines without replacing them).
- Use semantic HTML first (button for actions, a for navigation).
- All form inputs must have labels (explicit or aria-label).
- Images require alt text (empty alt only for decorative images).
- Respect reduced motion preferences for animations when relevant.
## TypeScript / safety rules
- No `any` unless there is a documented reason and a tight scope.
- Validate external data at boundaries (API responses, localStorage, query params).
- Handle loading + error + empty states for async UI.
## Testing and reliability (lightweight)
- Add or update tests when behavior changes (unit/component preferred).
- Avoid brittle tests tied to layout; test behavior and critical rendering.
## Output expectations
- Provide complete, copy/pasteable code changes.
- Include brief notes for any assumptions or tradeoffs.A file like this should be in your components/ directory.
# src/components/.builderrules
## Component API design
- Components should be single-responsibility and reusable.
- Props:
- Prefer a small, stable prop surface.
- Use explicit types and sensible defaults.
- Avoid "god props" that mix many concerns.
- Events:
- Use clear callback names: onSelect, onChange, onSubmit, onOpenChange, etc.
- Keep callbacks stable and avoid unnecessary re-renders.
## File conventions (adapt to existing repo)
- One component per folder when components have styles/tests:
- Component.tsx
- Component.test.tsx (or .spec.tsx)
- Component.module.css (if using CSS modules)
- index.ts (re-export)
- Otherwise, co-locate small leaf components near their usage.
## Documentation
- Exported/shared components must include:
- A short doc comment describing purpose and key props
- Any constraints (controlled vs uncontrolled, accessibility notes)
## Error boundaries (when appropriate)
- For complex UI (charts, editors, large forms), include a safe fallback UI on failure.Place a file like this within a directory where you manage your routes or pages.
# src/pages/.builderrules
## Page responsibilities
- Pages compose existing components; avoid placing complex UI logic directly in pages.
- Keep page files focused on:
- Data fetching / route params
- High-level layout composition
- Passing data down to components
## Async UI state requirements
For any async data on a page, always include:
- Loading state (skeleton or placeholder)
- Error state (user-friendly message + retry when possible)
- Empty state (when data is valid but absent)
## Data fetching guidance
- Prefer the project's established data layer (existing hooks/services/query library).
- Do not introduce a new fetching library unless explicitly requested.
- Validate and narrow types at the boundary; don't trust unknown JSON blindly.
## Performance basics
- Avoid fetching the same data multiple times in the same render path.
- Defer non-critical work until after the first meaningful paint when possible.Place a file like this where you store the styles for your application.
# styles/.builderrules
## Theming and tokens
- Prefer tokens (CSS variables) for:
- color, spacing, typography, radius, shadow, z-index
- If a token is missing, add it rather than hard-coding repeated values.
## CSS hygiene
- Keep selectors shallow (avoid deeply nested selectors).
- Avoid styling by tag name globally unless it's a deliberate reset.
- Don't couple styles to DOM structure that may change.
## Responsive design rules
- Use the project's breakpoints consistently.
- Prefer fluid layouts (flex/grid) over fixed widths.
- Ensure touch targets are comfortably sized on mobile.Learn more about Configuration files in Builder, or read up on AI instruction best practices.