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.
- The multi-step
publishprocess searches for and validates.mapperfiles 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.
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.
The CLI recursively searches your project for all .mapper.{tsx,jsx,ts,js,mjs} files, skipping common directories like node_modules/ and dist/.
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.
Each mapping file is checked for:
- Proper TypeScript syntax
- Correct
figmaMapping()call structure - Required properties like
componentKeyorurl - 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 '{}'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
CancelOnce 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! 🎉Integrate component mappings into your continuous integration (CI) workflow to automatically publish mappings when changes are pushed to your repository.
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
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 }}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 --yesWhen 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.
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.