Quickstart

This is the fastest path from an empty project to real design tokens in your codebase. In about five minutes you’ll install Figmage, connect it to Figma, and run your first sync. Each step links to a deeper page if you want the full story.

Before you start

You need:

• Node.js 22 or newer.
• A project where you can install dev dependencies.
• A published Figma library that contains at least one color, text, or effect style.
• View access to that Figma file.
• A Figma access token and the file’s file ID.

Designer handoff

If someone else owns the Figma library, ask them for the file ID, confirmation that the latest changes are published, and which token groups they expect you to sync.

1. Install Figmage

   Add Figmage and dotenv as dev dependencies. The Quickstart config below uses dotenv to load secrets from a local .env file.

   npm

   npm install --save-dev figmage dotenv

   pnpm

   pnpm add --save-dev figmage dotenv

   Yarn

   yarn add --dev figmage dotenv

   Bun

   bun add --dev figmage dotenv

   Prefer not to install? Every command also works through npx figmage ….

   See Install and Auth for global installs and other package managers.

2. Add your credentials

   Figmage reads your file through the Figma REST API, so it needs an access token and a file ID. Keep them out of source control with a .env file:

   FIGMA_ACCESS_TOKEN="figd_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
   FIGMA_FILE_ID="xxxxxxxxxxxxxxxxxxxxxx"

   Need a token or unsure where to find the file ID? Install and Auth walks through creating a read-only token and locating your file ID.

3. Create a config

   Add a figmage.config.js to your project root. This minimal config pulls three common style-based token sets — colors, typography, and shadows:

   figmage.config.js

   import "dotenv/config";
   import { defineConfig } from "figmage";
   
   export default defineConfig({
     accessToken: process.env.FIGMA_ACCESS_TOKEN,
     fileId: process.env.FIGMA_FILE_ID,
     output: {
       directory: "./tokens",
       fileType: "ts",
     },
     tokens: [
       { name: "colors", type: "color" },
       { name: "typography", type: "text" },
       { name: "shadows", type: "dropShadow" },
     ],
   });

   The defineConfig helper gives you full autocompletion and type-checking.

   Every field — global defaults, per-token overrides, output options — is covered in Configuration.

4. Run sync

   figmage sync

   Here’s what happens under the hood:

   • Figmage fetches the published styles from your Figma file.
   • It writes a token file per set under ./tokens (colors.ts, typography.ts, shadows.ts).
   • File names come from each token’s name, unless you override output.fileName.

   The sync command — plus filtering and the spritesheet command — is documented in the CLI reference.

5. Use the tokens

   A successful first sync should leave you with files like this:

   • Directorytokens

     • colors.ts
     • typography.ts
     • shadows.ts

   Import the generated files anywhere in your app:

   import { colors } from "./tokens/colors";
   
   const primary = colors.primary;

   Because the output is TypeScript, your editor autocompletes token names and flags typos at build time.

Sync only what changed

Once your config grows, you rarely need to regenerate everything. Narrow a run with --only or --skip:

# Only these token sets
figmage sync --only=colors,typography

# Everything except these
figmage sync --skip=shadows

More on selective syncing in the CLI reference.

Where to go next

You now have a working sync. From here you can go deeper:

• Measure scales and export icons — spacing, radii, and image assets come from components. See Token Types.
• Shape the output — color formats, units, casing, and file types. See Configuration.
• Automate it — wire figmage sync into CI. See CI.
• Fix a failed sync — see Troubleshooting for common errors.