Registry / http-networking / figma-api

figma-api

JSON →
library2.1.2-betajsnpmunverified

The `figma-api` package provides a thin, typed JavaScript/TypeScript wrapper around the official Figma REST API. Currently in its 2.1.2-beta version, this library offers a client-side implementation designed for both browser and Node.js environments. It leverages Promises via Axios for HTTP requests and is fully typed with TypeScript, aligning its API methods directly with the official Figma REST API specifications. A significant rewrite occurred in version 2.x, standardizing endpoint method names and argument structures to precisely match Figma's documentation, ensuring future consistency. The package differentiates itself by closely mirroring the official API spec, providing a robust, type-safe interface for interacting with Figma files and resources programmatically, making it easier for developers to build integrations without constantly referring to external documentation for method signatures.

npm install figma-api
INSTALL
IMPORT
SIG · FIGMA-API
F
figma-api
http-networkingjavascriptv2.1.2-beta
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Api
import * as Figma from 'figma-api'; const api = new Figma.Api({ personalAccessToken: process.env.FIGMA_TOKEN });
import { Api } from 'figma-api'; const api = new Api({ personalAccessToken: process.env.FIGMA_TOKEN });
Since version 2.x, the `Api` class is exposed as part of a namespace import (`* as Figma`). Direct named imports like `import { Api } ...` will result in a `TypeError`.
oAuthLink
import * as Figma from 'figma-api'; const oauthUrl = Figma.oAuthLink('CLIENT_ID', 'REDIRECT_URI', 'file_read', 'STATE_STRING', 'code');
const Figma = require('figma-api'); const oauthUrl = Figma.oAuthLink(...);
Helper functions like `oAuthLink` are exposed via the `Figma` namespace. The library is primarily designed for ESM environments, and CommonJS `require` patterns may not provide the expected exports in v2.x.
oAuthToken
import * as Figma from 'figma-api'; const tokenResponse = await Figma.oAuthToken('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URI', 'CODE', 'authorization_code');
import { oAuthToken } from 'figma-api'; const tokenResponse = await oAuthToken(...);
Similar to `oAuthLink`, the `oAuthToken` function is accessed via the `Figma` namespace from a wildcard import. Named imports for these specific helper functions are incorrect and will not work.

Demonstrates how to initialize the Figma API client with a personal access token, fetch a specific Figma file by its key, and then log some basic information about the retrieved file structure, handling potential errors.

import * as Figma from 'figma-api'; const personalAccessToken = process.env.FIGMA_PERSONAL_ACCESS_TOKEN ?? ''; const fileKey = process.env.FIGMA_FILE_KEY ?? ''; if (!personalAccessToken || !fileKey) { console.error('Please set FIGMA_PERSONAL_ACCESS_TOKEN and FIGMA_FILE_KEY environment variables.'); process.exit(1); } export async function getFigmaFile() { try { console.log('Initializing Figma API client...'); const api = new Figma.Api({ personalAccessToken: personalAccessToken, }); console.log(`Fetching file with key: ${fileKey}...`); // The getFile method in v2.x expects an object with parameters const file = await api.getFile({ file_key: fileKey }); console.log('Successfully fetched Figma file structure.'); // Accessing basic file data console.log(`File Name: ${file.name}`); console.log(`Last modified: ${file.lastModified}`); console.log(`Number of top-level children: ${file.document?.children?.length ?? 0}`); return file; } catch (error) { console.error('Error fetching Figma file:', error.message); if (error.response) { console.error('Response data:', error.response.data); console.error('Response status:', error.response.status); } throw error; } } // Execute the function when the script runs getFigmaFile().catch(err => { console.error('Figma API operation failed:', err); });
Debug
Known issues
breakingVersion 2.x is a complete rewrite with significant breaking changes from 1.x. All endpoint methods have been renamed, and their arguments now consistently use objects (e.g., `pathParams`, `queryParams`, `requestBody`) instead of direct individual values.
fix
Refer to the official Figma REST API documentation for updated method names and argument structures. Update all API calls to match the new object-based parameter passing (e.g., `api.getFile({ file_key: '...' })`).
affects: >=2.0.0-beta
gotchaThe library is currently distributed as a beta version (e.g., 2.1.2-beta). While actively maintained, users should be aware of its pre-stable status and potential for further minor adjustments before a stable 2.0.0 release.
fix
Monitor the project's GitHub releases and NPM for stable version announcements. For production applications, consider locking to a specific beta version or preparing for minor updates.
affects: >=2.0.0-beta
gotchaWhen using the browser version directly via CDN links (e.g., `figma-api.min.js`), you might encounter Cross-Origin Resource Sharing (CORS) limitations if the API requests are not made from a whitelisted origin.
fix
For browser usage, it is recommended to install the library via npm (`npm i figma-api`) and bundle it with your application. Alternatively, ensure your server-side proxy handles CORS headers correctly, or configure your Figma API client with a proxy if available.
affects: >=1.0.0
gotchaAuthentication requires either a `personalAccessToken` or an `oAuthToken`. Misconfiguring or providing an invalid token will result in API errors (e.g., HTTP 403 Forbidden).
fix
Ensure you are using a valid personal access token obtained from Figma, or correctly implementing the OAuth 2.0 flow to acquire and refresh access tokens. Verify that the token has the necessary permissions (scopes) for the desired API operations.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Figma.Api is not a constructor
Attempting to import `Api` as a named import (e.g., `import { Api }`) instead of using a namespace import, or incorrectly accessing it after a CommonJS `require`.
fix
Use a namespace import: `import * as Figma from 'figma-api';` and then access the class as `new Figma.Api(...)`. If using CommonJS, which is not officially supported for modern versions, module interop might be needed or consider transpiling.
Property 'getFile' does not exist on type 'Api' or 'TypeError: api.getFile is not a function'
Attempting to call an API method with the old v1.x signature (e.g., `api.getFile('file-key')`) or on an outdated instance after upgrading to v2.x.
fix
Ensure your code uses the v2.x API method names and argument structures, which expect parameters to be passed within objects (e.g., `api.getFile({ file_key: '...' })`). Consult the official Figma REST API documentation for correct endpoint signatures.
Error: Request failed with status code 403
The provided `personalAccessToken` or `oAuthToken` is invalid, expired, or lacks the necessary permissions for the requested operation.
fix
Verify that your Figma token is correct, not expired, and has the required 'file_read' or other necessary scopes for the API call you are making. Generate a new token from Figma settings if unsure.
Error: Network Error (or) Cross-Origin Request Blocked by CORS policy
Client-side browser environment is blocking the request due to CORS policies, or there's a general network connectivity issue preventing the request from reaching Figma's API.
fix
If in a browser, ensure your application's origin is allowed by Figma (which it generally is for standard API calls) or that your browser environment isn't imposing stricter local policies. For Node.js, check network connectivity. If using a direct CDN link in the browser, consider bundling with npm to mitigate CORS, or implement a proxy.
Upgrade
Version history
2.1.2-betalatest on npm
Audit
Dependencies
axiosrequiredCore HTTP client for making API requests.
Agent activity
54 hits · last 30 days
node
48
OpenAI (training)
1
Resources