Map components with the CLI

for developers

Rather than relying on the Builder Figma Plugin’s visual interface, you can manage mappings programmatically, directly integrated into your codebase.

By using the CLI, you can can keep mappings consistent and up-to-date as designs evolve for better control and flexibility when mapping components from Figma to code.

Prerequisites

To get the most out of this article, be sure:

You have a Figma design ready with relevant components to be mapped.
You’re using the Builder Figma Plugin.
Your application is connected to Builder Devtools and running locally.
Devtools is connected to the same Builder Space as your codebase.

For setup details, visit Import from Figma.

Create a new mapping

1. In package.json, update the Builder Devtools dependency to ^1.1.25.

npm i @builder.io/dev-tools@latest --save

2. In Figma, select the component to map.

3. Open the Builder Figma Plugin and go to the Design System tab.

4. The Design tab displays unmapped components along with a CLI command that maps all components listed. Copy the command by clicking on the copy icon.

5. At the command line, run the command to start the mapping process. Notice that the command includes all the Figma IDs for the unmapped components, which the plugin uses to look up the components in the code base as well as check for duplicates.

npx builder.io@latest figma generate 9ca66...

6. When you are prompted, select the local component you want to map. If you have a lot of components, filter for a particular component by starting to type its name.6. In the prompt that opens in Figma, grant access to the Builder CLI by clicking the Allow access button.

7. Inspect the suggested mapper function and request any changes. For example, "Provide a better default value for the subtitle". Press Enter for Devtools to generate another mapper function with your recommendations.

8. When you are satisfied with the suggestion, respond to the prompt question of "How does the mapping look?" with "good".

9. At the prompt for where to save the new mappings, specify the location you'd like.

10. Open your new mapper file and edit your mapper() function if needed.

11. Repeat for all components.

The diagram below shows the before and after states of mapping components with the Builder Figma Plugin. On the left is the plugin when it finds unmapped components along with the command that is generated to map those components.

On the right is the plugin after having successfully mapped the components. For each of the components that are mapped, you can expand it to inspect or edit the mapping functions for more information, read Component Mapping Functions.

Diagram of the Builder Figma plugin in a before and after state when mapping functions. On the left is the plugin with unmapped components listed, and a note that says unmapped components are here. There is also a command for those components shown just under that with a note pointing out the command that says "use this command to map them".

The second part of the diagram has the completed state of the plug-in after having mapped the components. There is a note that points to the components that says after you successfully map components, they are listed with a green checkmark and a success message.

Publish new mappings

Publishing your Figma mappings doesn’t update your repo but pushes the updated mappings into your Builder space. This ensures that the mappings are applied the next time someone generates code in the Figma plugin.

To publish new mappings:

Run npx builder.io figma publish. Note that if you have any properties missing in a mapping function for a component, the CLI returns an error alerting you. In this case, make sure that you check that the types in the mapper file against the types in the component and provide all needed types.
When prompted to publish found mappings, choose Publish or Cancel.

To confirm that your mappings were published, run npm run dev in your project, go to the Builder Figma plugin Design System tab, and expand the component to find the new mapping. If it doesn't show up immediately, be sure to refresh by closing and re-opening the plugin.

Create a design tokens mapper in code

To create your own mapper file for mapping design tokens:

1. Name your mapper file with the naming convention of myComponent.mapper.tsx, where myComponent is the name of your component.

2. Import figmaMapping:

import { figmaMapping } from "@builder.io/dev-tools/figma";

3. Add a figmaMapping() function using designTokenMapper() to pass in your token, as in the following example that shows the designMapper() function to map blue to brand blue:

// import figmaMapping so Devtools can map components
import { figmaMapping } from "@builder.io/dev-tools/figma";

figmaMapping({
  designTokenMapper(token) {
   // if blue in Figma, return brand blue
   if (token === 'blue') {
       return 'var(--brand-blue, #18B4F4)'
   }
   // leave anything else the same
   return undefined
  }
});

4. Publish:

npx builder.io figma publish

For more advanced use cases and additional mapping functions, visit Component Mapping Functions.

Component mapping CLI command reference

The following commands are available for managing your mappings. Run these commands from the root of your project.

Starting the CLI mapping process

Start the auto-mapping command line workflow, which this document covers in detail, for the Figma component:

npx builder.io@latest figma generate 9ca66...

Publish your mappings

Pushes the updated mappings to your Builder Space so that the mappings are applied the next time a team mate generates code in the Figma plugin.

Publish your Figma mappings to Builder:

npx builder.io figma publish

Migrating your mappings

Migrate your existing Figma mappings into your local project. This command fetches Figma mappings, lists them for you, and prompts you for a location in your project to save the mappings.

This command creates any folders you specify in the path that don't exist and a new file for each mapping. For example, if you specify /src/mappings the CLI creates a mappings directory within src and a file for any existing mappings, for example, if you had a footer mapping, the CLI would create Footer.mapper.tsx:

npx builder.io figma migrate

Note that mapping files must be mapper.tsx files, but that they can be anywhere in your repo. These files contain the code responsible for translating Figma components to code components in your app. You can also have multiple mappings on a single component.

Re-authenticating Figma and Builder

Use this command for troubleshooting login issues between Figma and Builder. It should not be necessary under normal circumstances but can resolve issues where authentication has failed.

Re-authenticate with Figma and Builder:

npx builder.io figma auth

Structure of a mapper.tsx file

Each mapping file contains default mappings for the respective component. For example, a Footer.mapper.tsx file could have these features:

// import figmaMapping so Devtools can map components
import { figmaMapping } from "@builder.io/dev-tools/figma";
import Footer from "@components/Layout/Footer";

// provide figmaMapping() with the Builder component key
// in mapper(), the code is the same as in the Figma plugin
figmaMapping({
  componentKey: "d8fccf9e902602249fa68217953daab094570bba",
  mapper(figma) {
    return <Footer></Footer>;
  },
});

Migrating from the plugin mapping UI

If you've been using the Builder Figma plugin to automatically map your components, you can migrate to the improved workflow that uses the command line to map components with the instructions in this section.

If you've never used the Builder Figma plugin for mapping components in your project, skip to the next section.

To update an existing project that already uses component mapping with the Builder Figma Plugin:

1. In package.json, update the Builder Devtools dependency to ^1.1.0.

npm i @builder.io/dev-tools@1.1.0 --save

2. Start the mapping integration process.

npx builder.io figma migrate

3. Follow the command line instructions.

What's next

Certain parts of this workflow use AI, for more information, visit How Builder Uses AI.

Was this article helpful?