Migrating from v1

Figmage v2 is a substantial rewrite of how you configure and run the tool. The core idea is unchanged — read your published Figma library and generate design tokens as code — but the config format, the commands, and the token type names are all different. This guide maps every v1 concept to its v2 equivalent so you can upgrade in one sitting.

What changed at a glance

Area	v1	v2
Config file	.figmage.json / .figmagerc / package.json (JSON)	figmage.config.js (JS with defineConfig)
Credentials	Read from env via --env	Passed explicitly as accessToken / fileId in the config
Commands	figmage tokenize then figmage codegen	A single figmage sync
Intermediate spec	A token JSON written by tokenize, consumed by codegen	None — sync goes straight from Figma to code
Config shape	outDir, tokenize, codegen	tokens, output, transform
Token source	nodeId / nodeName on the token	A source object (componentSet / frame / frameId)
Filtering values	include / exclude regex rules	A filter predicate function

Step-by-step migration guide

1. Move to figmage.config.js

   v1 read configuration from a JSON file (.figmage.json, .figmagerc, or a "figmage" key in package.json). v2 uses a JavaScript file, figmage.config.js, that default-exports your config. Wrap it in the defineConfig helper for full autocompletion and type-checking.

   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,
     tokens: [{ name: "colors", type: "color" }],
   });

   Delete your old .figmage.json / .figmagerc once you’ve ported the settings, and remove the "figmage" key from package.json if you used that. See Configuration for the full reference.

2. Pass credentials in the config

   In v1 the access token and file ID were read implicitly from the environment, and you pointed at a custom env file with --env. In v2 you load the environment yourself (e.g. with dotenv) and pass the values explicitly to defineConfig:

   import "dotenv/config";
   import { defineConfig } from "figmage";
   
   export default defineConfig({
     accessToken: process.env.FIGMA_ACCESS_TOKEN,
     fileId: process.env.FIGMA_FILE_ID,
     // ...
   });

   The env variable names are unchanged (FIGMA_ACCESS_TOKEN, FIGMA_FILE_ID), so your existing .env file keeps working. See Install and Auth for details.

3. Replace tokenize + codegen with sync

   v1 was a two-step pipeline:

   # v1
   figmage tokenize   # fetch from Figma, write an intermediate token JSON spec
   figmage codegen    # turn that spec into code

   v2 collapses this into a single command — there is no intermediate spec to generate or commit:

   # v2
   figmage sync

   If your CI or scripts called tokenize and codegen separately, replace both with figmage sync. You can now narrow a run with --only and --skip:

   figmage sync --only=colors,typography
   figmage sync --skip=icons

   The full command reference, including the global --verbose flag, lives in the CLI reference.

4. Restructure the config

   The top-level shape changed. v1 nested everything under tokenize and codegen and used outDir; v2 has a flat tokens array plus output and transform for defaults.

   v1

   {
     "outDir": "tokens",
     "tokenize": {
       "tokens": [
         { "name": "colors", "type": "color" },
         { "name": "typography", "type": "text" }
       ]
     },
     "codegen": {
       "defaults": { "filetype": "ts", "tokenCase": "camel" },
       "typography": { "filetype": "json", "tokenCase": "kebab" }
     }
   }

   v2

   export default defineConfig({
     accessToken: process.env.FIGMA_ACCESS_TOKEN,
     fileId: process.env.FIGMA_FILE_ID,
     output: { directory: "./tokens", fileType: "ts" },
     transform: { defaultCasing: "camel" },
     tokens: [
       { name: "colors", type: "color" },
       {
         name: "typography",
         type: "text",
         output: { fileType: "json" },
         transform: { casing: "kebab" },
       },
     ],
   });

   Key mappings:

   v1	v2
   outDir	output.directory
   codegen.defaults.filetype	output.fileType
   codegen.defaults.tokenCase	transform.defaultCasing
   codegen.[token].filename	per-token output.fileName
   codegen.[token].filetype	per-token output.fileType
   codegen.[token].tokenCase	per-token transform.casing

5. Update token types and sources

   Several token type names were renamed, and component-based tokens now use a source object instead of nodeId / nodeName.

   v1 type	v2 type	Notes
   color	color	Unchanged
   text	text	Unchanged
   drop-shadow	dropShadow	Renamed (camelCase)
   width	property + source.property: "absoluteBoundingBox.width"	Now a measured property
   height	property + source.property: "absoluteBoundingBox.height"	Now a measured property
   dimensions	property (measure each dimension separately)	Use one property token per dimension
   radius	property + source.property: "cornerRadius"	Now a measured property
   svg	imageVector or imageSprite	imageVector for files; imageSprite for a sprite sheet
   png	imageRaster	Renamed; format can be png or jpg

   Sources: nodeId / nodeName → source

   v1 pointed at the frame containing your components with nodeId or nodeName directly on the token. v2 moves this to a source object and adds componentSet as an option:

   // v1
   { "name": "icons", "nodeId": "123:456", "type": "svg" }
   { "name": "spacing", "nodeName": "My Spacing", "type": "height" }
   
   // v2
   { name: "icons", type: "imageVector", source: { frameId: "123:456" } }
   {
     name: "spacing",
     type: "property",
     source: { frame: "My Spacing", property: "absoluteBoundingBox.height" },
   }

   source accepts componentSet, frame (by name), or frameId (the node-id from the Figma URL). See Token Types for the complete catalog.

   SVG color conversion moved

   v1 disabled currentColor conversion with options.convertColors. v2 expresses SVG processing as SVGO overrides under transform.optimize:

   // v1
   { "name": "icons-multicolor", "nodeId": "y:y", "type": "svg", "options": { "convertColors": false } }
   
   // v2
   {
     name: "icons-multicolor",
     type: "imageVector",
     source: { frame: "Icons Multicolor" },
     transform: { optimize: [["convertColors", false]] },
   }

6. Replace include/exclude rules with filter

   v1 filtered individual tokens with include / exclude objects of regex or exact-match strings on group and token. v2 replaces these with a single filter predicate function — plain JavaScript, no escaped regex strings required.

   // v1
   {
     "codegen": {
       "colors": {
         "exclude": { "token": "^\\bFigma\\b.*" }
       }
     }
   }
   
   // v2
   {
     name: "colors",
     type: "color",
     filter: ({ name }) => !name.startsWith("Figma"),
   }

   The predicate receives { name, value, group }, so you can filter on a token’s name, value, or group. To select whole token sets at runtime, use --only / --skip instead.

7. Update the spritesheet command flags

   The standalone figmage spritesheet command still bundles local SVG files, but several flags were renamed and the IDs output is now configured with dedicated flags.

   v1 flag	v2 flag
   --sprite-input	--sprite-input
   --sprite-out-dir	--sprite-output
   (implicit filename)	--sprite-filename (required)
   --sprite-ids-out-dir	--sprite-ids-output (with --sprite-ids-enabled)
   --sprite-case	--sprite-case
   --sprite-convert-colors	--sprite-convert-colors

   # v1
   figmage spritesheet \
     --sprite-input ./icons \
     --sprite-out-dir ./public \
     --sprite-ids-out-dir ./app/components
   
   # v2
   figmage spritesheet \
     --sprite-input ./icons \
     --sprite-output ./public \
     --sprite-filename icon-sprite \
     --sprite-ids-enabled \
     --sprite-ids-output ./src/tokens \
     --sprite-ids-filename icon-sprite-ids

   See the full flag list in the CLI reference.

Migration checklist

1. Upgrade the package: npm install --save-dev figmage@latest.
2. Create figmage.config.js and port your settings, deleting the old JSON config.
3. Pass accessToken and fileId explicitly (load your .env with dotenv).
4. Move outDir → output.directory and codegen.defaults → output / transform.
5. Rename token types and convert nodeId / nodeName to source.
6. Replace include / exclude rules with filter predicates.
7. Swap tokenize + codegen for figmage sync in all scripts and CI.
8. Update any figmage spritesheet invocations to the new flags.

Where to go next

• Quickstart — a fresh five-minute setup with the v2 flow.
• Configuration — every field in figmage.config.js.
• Token Types — the full v2 token catalog.
• Spritesheets — generate SVG sprite sheets for your icons.
• CLI — the sync and spritesheet commands.