figma-export-assets

Install

npm install figma-export-assets

Description

A highly customizable package for exporting assets from the Figma API in any supported format.

🙏🏻 Based on concepts by https://github.com/tsimenis/figma-export-icons and https://github.com/nate-summercook/figma-assets-exporter but with focus on customizability. Thanks to both of them for their work!

Features

• 📄 Multiple Figma Pages/Frames: Configure to process assets from various Figma pages or specific frames.
• 🔄 Batch Exporting: Supports batch exporting out of the box to handle Figma API export limits.
• 📁 Customizable Asset Paths/Names: Set unique saving paths or names for each asset.
• 🌈 Customizable Asset Format: Choose any Figma export format for each asset.
• 🚫 Asset Exclusion: Easily exclude specific assets from export based on their names.
• 🌟 Variant Exporting: Overridable option to export components with variants as separate assets.

Examples

Basic Usage

import { FigmaExporter } from "figma-export-assets";
import dotenv from "dotenv";
dotenv.config();

const exporter = new FigmaExporter({
	figmaPersonalToken: process.env.FIGMA_PERSONAL_TOKEN,
	fileId: process.env.FILE_ID,
	page: process.env.PAGE,
	assetsPath: "src/assets",
	format: "svg",
});

await exporter.setAssets();
await exporter.createAssets();

Export variants with custom names

import { FigmaExporter } from "figma-export-assets";
import dotenv from "dotenv";
dotenv.config();

const exporter = new FigmaExporter({
	figmaPersonalToken: process.env.FIGMA_PERSONAL_TOKEN,
	fileId: process.env.FILE_ID,
	page: process.env.PAGE,
	frame: "component",
	exportVariants: true,
	assetsPath: "src/assets",
	format: "svg",
});

await exporter.setAssets();

await exporter.createAssets((assets) =>
	assets.map((a) => ({
		...a,
		name: a.name.replace("component/", ""),
	}))
);

Chaining exports to multiple formats/paths

import { FigmaExporter } from "figma-export-assets";
import dotenv from "dotenv";
dotenv.config();

const baseConfig = {
	figmaPersonalToken: process.env.FIGMA_PERSONAL_TOKEN,
	fileId: process.env.FILE_ID,
	page: process.env.PAGE,
	exportVariants: true,
};

const exporter = new FigmaExporter(baseConfig);

await exporter.setAssets();

await exporter.createAssets(
	(assets) =>
		assets
			.filter((a) => !a.name.includes("images"))
			.map((a) => ({
				...a,
				name: a.name.replace("icons/", ""),
			})),
	{ assetsPath: "src/svg", format: "svg" }
);

await exporter.createAssets(
	(assets) =>
		assets
			.filter((a) => a.name.includes("images"))
			.map((a) => ({
				...a,
				name: a.name.replace("images/", ""),
			})),
	{ assetsPath: "src/jpg", format: "jpg" }
);

Methods

constructor(config: Config)

• Description: Initializes the FigmaExporter instance with the provided configuration.
• Parameters: config - The configuration object containing the Figma API token, file ID, page name, and other settings.

setAssets()

• Description: Sets the assets by fetching them from the Figma API.
• Parameters: None
• Returns: Promise<FigmaExporter> - The instance of the exporter with the assets set.

createAssets(assetTransformFn, config)

• Description: Creates assets by asking the Figma API for the assets and saving them to the specified path.
• Parameters:
  • assetTransformFn: Callback function to transform the assets before saving them. It receives the assets as an argument and should return an array of assets.
    • Parameters: assets: Asset[] - The array of assets to transform.
    • Returns: Asset[] - The transformed array of assets.
    • Example: (assets) => assets.map((a) => ({ ...a, name: a.name.replace("component/", "") }))
  • config: Optional configuration object to override the default settings for this export.
• Returns: Promise<FigmaExporter> - The instance of the exporter with the assets set.

Parameters

Config

This can be overriden in every createAssets call.

{
    /**
     * - Personal access token for the Figma API.
     */
    figmaPersonalToken: string;
    /**
     * - The ID of the Figma file to export assets from.
     */
    fileId: string;
    /**
     * - The name of the page to export assets from.
     */
    page: string;
    /**
     * - The path to save the exported assets.
     */
    assetsPath: string;
    /**
     * - The format of the exported assets.
     */
    format?: string;
    /**
     * - The scale at which to export assets.
     */
    scale?: number;
    /**
     * - Whether to export variants of the assets.
     */
    exportVariants?: boolean;
    /**
     * - The name of the frame to export assets from.
     */
    frame?: string;
    /**
     * - The number of assets to export in each batch.
     */
    batchSize?: number;
    /**
     * - The maximum number of concurrent requests.
     */
    concurrencyLimit?: number;
    /**
     * - Whether to skip existing files.
     */
    skipExistingFiles?: boolean;
};

Asset

This can be overriden in every createAssets call to optimize paths or names.

{
    /**
     * - The ID of the asset.
     */
    id: string;
    /**
     * - The name of the asset.
     */
    name: string;
    /**
     * - The URL of the asset image.
     */
    url?: string;
    /**
     * - The path to save the asset.
     */
    assetsPath?: string;
}

Contributing

Versioning

Create a changeset via pnpm changeset that describes the changes you made to the codebase. This will be used to generate a changelog entry and version bump. It will be picked up by the release workflow.

Testing

The tests are based on the following file: https://www.figma.com/design/fgP5dbJzh1bnZqMgnDXoyd/test?node-id=0-1&p=f&t=5uSDKcMwgBqsYBg0-11

To test yourself, duplicate the file to your drafts and add the needed data to the .env file (see .env.example).