Publishing is a critical step that makes your mappings available to the Figma plugin. Without publishing, your mappings exist only locally and won't be recognized when generating code from Figma designs.
When you run npx builder.io figma publish, the CLI performs several important steps.
Scanning your project
The CLI recursively searches your project for all .mapper.{tsx,jsx,ts,js,mjs} files, skipping common directories like node_modules and dist.
Analyzing Imports: During the scanning process, the CLI extracts and analyzes all ESM import statements from your mapping files:
- Import statements are captured exactly as written
- These imports will be reproduced verbatim when generating code
Validating mappings
Each mapping file is checked for:
- Proper TypeScript syntax
- Correct figmaMapping call structure
- Required properties like
componentKeyorurl - Duplicate mappings (the same Figma component being 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 '{}'Confirmation prompt
The CLI shows you the mappings that will be published and asks for confirmation:
Do you want to publish the found mappings to space "My Design System" (pk_1234)?
Existing mappings will be overwritten
❯ Publish
CancelPublishing to Builder.io
Once confirmed, your mappings are sent to the Builder.io API, making them available to the Figma plugin.
Once successful, you'll see:
Publishing Figma Mappings...
3 mappings uploaded
Done! 🎉Publishing your mappings has several important effects:
- Overwriting Existing Mappings: Any previously published mappings from your Builder.io space are be replaced with the new set you're publishing. This is an all-or-nothing operation.
- Making Mappings Available in Figma: After publishing, your mapped components appear as options when generating code in the Builder Figma plugin.
- Applying Project Settings: The CLI also ensures that your Builder.io space is configured with the correct settings for Figma integration.
When creating mappings, it's crucial to understand how import statements are handled during the publishing and code generation process:
1. Import Statements are Preserved: When your mappings are published, the ESM import statements in your mapping files are captured and will be reproduced verbatim when generating code using these mappings.
2. Location Independence: Since the generated code could be created in a different location or even a different project entirely, your import paths need to be location-independent. This means:
// ❌ 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';3. Design system considerations: This is particularly important when creating mappings for a design system:
- While your mappings may live locally within your design system project during development
- The imports should use the final package paths that end users will use to reference your components
- This ensures that generated code will work correctly when your components are consumed as a package
4. Recommended import strategies:
- Use your published package name for design system components.
- Use TypeScript path aliases (configured in
tsconfig.json) for internal project components. - Avoid relative paths that could break when code is generated in different locations.
The figma publish command supports several useful options:
- --force: Publish mappings even if TypeScript errors or other issues are detected
npx builder.io figma publish --force- --verbose: Show detailed information about the mappings being published, including the JSON payload sent to the API
npx builder.io figma publish --verbose- --dryrun: Validate mappings without actually publishing them to Builder.io
npx builder.io figma publish --dryrun- --yes: Skip confirmation prompts and automatically approve the publishing operation
npx builder.io figma publish --yesIf your mappings contain TypeScript errors but you still want to publish them, you can use the --force flag:
npx builder.io figma publish --forceThe --force flag is useful in scenarios like:
- When errors are non-critical or in parts of the code that won't affect the mapping functionality
- When you're using TypeScript features that the CLI validator doesn't fully understand
- When you're mapping to components with complex type definitions
When using --force, you'll see a warning:
Local mappings contain some errors, but --force flag was used, skipping.The CLI will then proceed with publishing despite the errors. Use this with caution, as errors in mappings may cause issues when using the Figma plugin.
You can integrate component mappings into your continuous integration (CI) workflow to automatically publish mappings when changes are pushed to your repository.
Automated CI publishing is most valuable when:
- Multiple team members are contributing to mappings
- You want to ensure mappings are always in sync with your codebase
- You have a large number of mappings that are updated frequently
- You want to enforce quality checks before mappings are published
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 keyBUILDER_PRIVATE_KEY: Your Builder.io private API keyFIGMA_PERSONAL_TOKEN: Your Figma personal access token (needed if using URL-based mappings)
Here's an example of a GitHub Actions workflow for publishing mappings:
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 }}This workflow will automatically publish your mappings whenever changes are pushed to the src/mappings directory in the main branch.
For other CI systems, you can use a simple 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.