Map components with the CLI

in beta

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 Importing Figma Designs.

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.

Creating a new mapping

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

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

2. In Figma, select the component you want to map.

3. Press Cmd + L, which is available in the Figma context menu under Copy/Paste as > Copy link to selection.

4. At the command line, run the command to start the mapping process. Replace the placeholder <URL> with the link you copied in Figma within quotes.

npx builder.io figma add "https://figma.com..."

6. In the prompt that opens in Figma, grant access to the Builder CLI by clicking the Allow access button.

7. Back at the command line, when you are prompted, select the local component you want to map. Type the name to filter, if you have a lot of components.

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

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

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

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

Publishing a new mapping

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 a new mapping:

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.

Creating 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 figma add <URL>

Publising 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>;
  },
});

What's next

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

Was this article helpful?