Component mapping in-depth

For developers

Enterprise plans

Deprecated

Builder.io is transitioning from manual component mapping to Component indexing, which automatically discovers and maps your design system components.

To migrate away from component mapping, visit the Component mapping migration guide.

The instructions in Map components demonstrates the most straightforward way to use your own code components during code generation. In this document, learn more details about the mapping process and how to leverage it to your benefit.

What to know

The multi-step publish process searches for and validates .mapper files before sharing the file contents with Builder.io's API.
CI automation is useful if multiple team members are contributing to mappings or you have a large number of mappings that are frequently updated.

Understand the publish process

To let Builder know about your component mappings, you must publish mapped components. Multiple steps occur when you run the publish command through the Builder CLI.

1. Scan project

The CLI recursively searches your project for all .mapper.{tsx,jsx,ts,js,mjs} files, skipping common directories like node_modules/ and dist/.

2. Analyze imports

Next, the CLI extracts and analyzes all ESM import statements from your mapping files. Import statements are captured exactly as written, therefore it is critical to use package imports or TypeScript path aliases.

// ❌ Don't use relative imports import { Button } from '../components/button'; import { Input } from '../../forms/input'; // ✅ Use package imports or TypeScript path aliases import { Button } from '@your-org/components'; import { Input } from '@/components/forms';

While your mappings may live locally within your design system project during development, the imports should use the final package paths that end users use to reference your components. This ensures that generated code works correctly when your components are consumed as a package.

3. Validate mappings

Each mapping file is checked for:

Proper TypeScript syntax
Correct figmaMapping() call structure
Required properties like componentKey or url
Duplicated mappings where the same Figma component is mapped multiple times

If validation issues are found, you’ll see detailed error messages:

TypeScript errors in src/mappings/Button.mapper.tsx: • Cannot find name 'ButtonProps' • Property 'variant' does not exist on type '{}'

4. Request confirmation

Once all previous steps have been completed, the CLI displays a confirmation prompt, alerting you of any mappings that will be overwritten.

Do you want to publish the found mappings to space "My Design System" (pk_1234)? Existing mappings will be overwritten ❯ Publish Cancel

5. Publish

Once confirmed, your mappings are sent to the Builder.io API, making them available to the Builder Figma plugin when it is connected to the same Space.

Publishing Figma Mappings... 3 mappings uploaded Done! 🎉

Continuous integration automation

Integrate component mappings into your continuous integration (CI) workflow to automatically publish mappings when changes are pushed to your repository.

Environment variables for CI

The CLI supports several environment variables that make it possible to run non-interactively in CI environments:

BUILDER_PUBLIC_KEY: your Builder.io public API key
BUILDER_PRIVATE_KEY: your Builder.io private API key
FIGMA_PERSONAL_TOKEN: your Figma personal access token; required if using URL-based mappings

Sample CI workflow for GitHub Actions

The following .yaml file can be used with GitHub's GitHub Actions feature.

This file runs a publish job when a new push is made on the main branch. When this happens, the script runs Builder CLI's figma publish command to publish all mappings within the specified path.

name: Publish Figma Mappings on: push: branches: [main] paths: - "src/mappings/**" jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: "18" - name: Install dependencies run: npm ci - name: Publish Figma mappings run: npx builder.io figma publish --ci --yes env: BUILDER_PUBLIC_KEY: ${{ secrets.BUILDER_PUBLIC_KEY }} BUILDER_PRIVATE_KEY: ${{ secrets.BUILDER_PRIVATE_KEY }} FIGMA_PERSONAL_TOKEN: ${{ secrets.FIGMA_PERSONAL_TOKEN }}

Sample CI script for other systems

For other CI systems, use the following script.

#!/bin/bash # Set environment variables export BUILDER_PUBLIC_KEY="your-public-key" export BUILDER_PRIVATE_KEY="your-private-key" export FIGMA_PERSONAL_TOKEN="your-figma-token" # Install dependencies if needed npm ci # Publish mappings npx builder.io figma publish --ci --yes

Security considerations

When setting up CI for Figma mappings, follow these security best practices:

Use secrets management: never hardcode API keys in your scripts or CI configuration. Use your CI provider's secrets management feature.
Use scoped access tokens: Create dedicated access tokens for CI usage with minimal permissions.
Consider branch protection: For production environments, consider requiring approval before mappings can be published from certain branches.

What's next

See Builder CLI API for more details on the figma commands that may be useful to you. For more advanced tooling around mapping components, see how to manually Create a mapping function or how to customize the mapping process with Map design tokens.

Was this article helpful?