{"id":16028,"library":"figma-api","title":"Figma REST API Client","description":"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.","status":"active","version":"2.1.2-beta","language":"javascript","source_language":"en","source_url":"https://github.com/didoo/figma-api","tags":["javascript","figma","rest","api","typed","typescript"],"install":[{"cmd":"npm install figma-api","lang":"bash","label":"npm"},{"cmd":"yarn add figma-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add figma-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core HTTP client for making API requests.","package":"axios","optional":false}],"imports":[{"note":"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`.","wrong":"import { Api } from 'figma-api';\nconst api = new Api({ personalAccessToken: process.env.FIGMA_TOKEN });","symbol":"Api","correct":"import * as Figma from 'figma-api';\nconst api = new Figma.Api({ personalAccessToken: process.env.FIGMA_TOKEN });"},{"note":"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.","wrong":"const Figma = require('figma-api');\nconst oauthUrl = Figma.oAuthLink(...);","symbol":"oAuthLink","correct":"import * as Figma from 'figma-api';\nconst oauthUrl = Figma.oAuthLink('CLIENT_ID', 'REDIRECT_URI', 'file_read', 'STATE_STRING', 'code');"},{"note":"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.","wrong":"import { oAuthToken } from 'figma-api';\nconst tokenResponse = await oAuthToken(...);","symbol":"oAuthToken","correct":"import * as Figma from 'figma-api';\nconst tokenResponse = await Figma.oAuthToken('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URI', 'CODE', 'authorization_code');"}],"quickstart":{"code":"import * as Figma from 'figma-api';\n\nconst personalAccessToken = process.env.FIGMA_PERSONAL_ACCESS_TOKEN ?? '';\nconst fileKey = process.env.FIGMA_FILE_KEY ?? '';\n\nif (!personalAccessToken || !fileKey) {\n  console.error('Please set FIGMA_PERSONAL_ACCESS_TOKEN and FIGMA_FILE_KEY environment variables.');\n  process.exit(1);\n}\n\nexport async function getFigmaFile() {\n    try {\n        console.log('Initializing Figma API client...');\n        const api = new Figma.Api({\n            personalAccessToken: personalAccessToken,\n        });\n\n        console.log(`Fetching file with key: ${fileKey}...`);\n        // The getFile method in v2.x expects an object with parameters\n        const file = await api.getFile({ file_key: fileKey });\n\n        console.log('Successfully fetched Figma file structure.');\n        // Accessing basic file data\n        console.log(`File Name: ${file.name}`);\n        console.log(`Last modified: ${file.lastModified}`);\n        console.log(`Number of top-level children: ${file.document?.children?.length ?? 0}`);\n        \n        return file;\n    } catch (error) {\n        console.error('Error fetching Figma file:', error.message);\n        if (error.response) {\n          console.error('Response data:', error.response.data);\n          console.error('Response status:', error.response.status);\n        }\n        throw error;\n    }\n}\n\n// Execute the function when the script runs\ngetFigmaFile().catch(err => {\n  console.error('Figma API operation failed:', err);\n});","lang":"typescript","description":"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."},"warnings":[{"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: '...' })`).","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0-beta"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=2.0.0-beta"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Authentication requires either a `personalAccessToken` or an `oAuthToken`. Misconfiguring or providing an invalid token will result in API errors (e.g., HTTP 403 Forbidden).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"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`.","error":"TypeError: Figma.Api is not a constructor"},{"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.","cause":"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.","error":"Property 'getFile' does not exist on type 'Api' or 'TypeError: api.getFile is not a function'"},{"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.","cause":"The provided `personalAccessToken` or `oAuthToken` is invalid, expired, or lacks the necessary permissions for the requested operation.","error":"Error: Request failed with status code 403"},{"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.","cause":"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.","error":"Error: Network Error (or) Cross-Origin Request Blocked by CORS policy"}],"ecosystem":"npm"}