in beta
for developers
With the Builder Figma plugin, you can map your Figma designs to your code components.
As an example, suppose you have a design system in Figma and a set of components in code that correspond to the designs in Figma. With the Builder Figma Plugin, you can map these components to each other and generate quality code.
The image below shows a design and its corresponding code, which component mapping can help you achieve.
To get the most out of this document, you should:
- Have a Next.js, Remix, React with Vite, or Angular app ready with React or Angular components.
- Have a Builder Space.
- Have design components in Figma.
To map your Figma components using the Builder Figma plugin:
- In Figma, open the Builder Figma plugin.
- Click the Login button that displays on the bottom left of the plugin or the Connect with Builder button.
- When prompted in the browser, choose the Space you want to authorize access to and click the Authorize button.
- Go back to Figma. When the authorization is successful, the plugin shows the Space you're connected to.
- Select the design.
- On the plugin, click Map.
- On the Design System tab, copy the generated command.
- Paste the command at the command line. This command contains Figma IDs for mapping the components.
- When prompted, authorize the Builder CLI by clicking on the Allow access button.
- Confirm you have the right Space selected and Authorize Devtools by clicking on the Authorize button.
- Back at the command line, the CLI authenticates and detects components.
- Select the components you want to map.
For details on the plugin, read Importing from Figma. The video below shows using the plugin and CLI to authenticate, authorize the CLI and Devtools, and map components from an example Figma design.
For details on the plugin, read Importing from Figma.
To map components in your codebase, they need to be discoverable by Builder's Devtools. That means you must export your components from any JavaScript or TypeScript file in your code, and (ideally) define their prop types in TypeScript or JSDoc types.
Additionally, you must make sure the plugin has the correct Public API Key and that the model names match.
Provided components are properly exported, the plugin can detect components in the following types of files:
.js.jsx.ts.tsx
In order for the plugin to detect library components, always make sure to export the components you want to map from one of the file types listed earlier in this section.
As a best practice, export the component and use types for props:
// ✅
export function MyComponent(props: { title: string }) {
return ...
}
// ✅
export const MyOtherComponent = () => ...It's also acceptable to export the component later in your file:
type MyProps = { title: string }
const MyComponent = (props: MyProps) => ...
// ✅
export default MyComponent;You must always export the components you want to map. If you do not export them, they do not show up in the plugin. As an example, notice that this component is never exported, so it will not work:
// 🚩 doesn't work, needs to be exported!
function MyComponent() { ... }The plugin operates optimally with TypeScript, enhancing its ability to map your Figma designs to the respective code components efficiently. Because of this, we recommend that you always define types for your component props.
// ✅
export function MyComponent(props: { title: string }) {
return ...
}
// ✅
type MyProps = { title: string }
export function MyComponent(props: MyProps) {
return ...
}While JavaScript without TypeScript is compatible, adding types to your props is ideal for the Builder's automapper to function most effectively:
/**
* @param {Object} props
* @param {string} props.title
* @param {number} props.enabled
* @param {number} props.count
*/
export function MyComponent(props) {
return ...
}When integrating code into your project from libraries like shadcn, the Builder Figma plugin works out of the box because it recognizes components that are defined and exported directly from the code. However, if you're using components from a package that aren't explicitly present in your codebase, you can still map them by re-exporting as below:
// src/components.tsx
export { Button, Card, TextField } from '@mui/material'
export { DatePicker } from 'antd';The example shows a file called components.tsx — though the actual file name doesn't matter — and exports components from libraries. By being exported in this way, these components are discoverable by Builder's Devtools.
Be sure to export each component you want to map. In the above example, only Button, Card, TextField, and DatePicker will be mappable. Export globs; for example, export * from 'package', are not currently supported.
When using Builder Devtools with component mapping, a new route called figma imports is generated in your project so you can access imported Figma components.
This workflow assumes you are developing on localhost. To enable access for users who are not running Devtools locally, you must update the Preview URL in Builder for the Figma Imports model.
- Using the techniques outlined in this document, map at least one Figma design to a code component in your project. After you've successfully mapped at least one component, a model named Figma Imports model displays in Builder and a route is added to your project.
- Deploy the project to a production environment.
- Go to Models in Builder and update the Preview URL for the Figma Imports model in Builder to match the production URL format; for example,
yoursite.com/figma-imports. This makes sure that users accessing the Figma components without running Devtools locally can use the imported components.
The video below shows going to the Models section of Builder and selecting the Figma Imports model. Note that you won't find that model listed if you haven't completed at least one Figma import using component mapping.
When you open the model, edit the Preview URL field so that others can use the newly mapped component.
This section covered Preview URLs specifically for Figma Imports. For more information on Preview URLs in other use cases, visit Editing and Previewing Your Site.
Certain parts of the this workflow use AI, for more information, visit How Builder Uses AI.
