figma-api
v2.0.1-beta
Published
Thin typed wrapper around the Figma REST API
Downloads
48,955
Readme
[!IMPORTANT] Version 2.0 Beta - This version is a complete rewrite of the library, based on the Figma REST API specifications. Many endpoint methods have been renamed from version 1.x, and all the endpoint methods' arguments now match the Figma REST API documentation. If you were using the previous version, and intend to use the new one, you will have to update your code accordingly. The good news is that from now on they should always remain in sync, so no major disruptions in the future, with the benefit of a full alignment with the official Figma REST API documentation and specifications.
figma-api
JavaScript client-side implementation of the Figma REST API.
Thin layer on top of the official Figma REST API specifications, fully typed with TypeScript, uses Promises (via Axios) & ES6.
Supports both browser & Node.js implementations.
Install
npm i figma-api
or browser version:
https://raw.githubusercontent.com/didoo/figma-api/master/lib/figma-api.js
https://raw.githubusercontent.com/didoo/figma-api/master/lib/figma-api.min.js
If you have CORS limitation, import the figma-api[.min].js
file in your codebase via the npm package.
Usage
In a Node.js script:
import * as Figma from 'figma-api';
export async function main() {
const api = new Figma.Api({
personalAccessToken: 'my-token',
});
const file = await api.getFile('my-file-key');
// ... access file data ...
}
or in a browser script:
const api = new Figma.Api({ personalAccessToken: 'my-personal-access-token' });
api.getFile({ file_key: 'my-file-key'}).then((file) => {
// access file data
});
In this case, the Figma
object is gloabl and all the API methods are associated with it.
Api
We have followed the same organisation as the official Figma API documentation to describe our API methods, so it's easier to find the exact endpoint call you are looking for.
Authentication
new Api ({ personalAccessToken, oAuthToken })
Creates new Api object with specified personalAccessToken
or oAuthToken
. For details about how to get these tokens, see the documentation
function oAuthLink(
client_id: string,
redirect_uri: string,
scope: 'file_read',
state: string,
response_type: 'code',
): string;
Returns link for OAuth auth flow. Users should open this link, allow access and they will be redirected to redirect_uri?code=<code>
. Then they should use oAuthToken
method to get an access token.
function oAuthToken(
client_id: string,
client_secret: string,
redirect_uri: string,
code: string,
grant_type: 'authorization_code',
): Promise<{
access_token: string,
refresh_token: string,
expires_in: number,
}>
Returns the access token from oauth code (see oAuthLink
method).
Other helpers:
Api.appendHeaders(headers)
- Populate headers with auth.Api.request(url, opts)
- Make request with auth headers.
Endpoints
All these endpoints methods receive objects like pathParams
, queryParams
, requestBody
, as arguments, and return a Promise. For details about the shape of these objects refer to the official Figma REST API documentation (see links below).
Files
See: https://www.figma.com/developers/api#files-endpoints
Api.getFile(pathParams,queryParams)
Api.getFileNodes(pathParams,queryParams)
Api.getImages(pathParams,queryParams)
Api.getImageFills(pathParams)
Comments
See: https://www.figma.com/developers/api#comments-endpoints
Api.getComments(pathParams)
Api.postComment(pathParams,requestBody)
Api.deleteComment(pathParams)
Api.getCommentReactions(pathParams,queryParams)
Api.postCommentReaction(pathParams,requestBody)
Api.deleteCommentReactions(pathParams)
Users
See: https://www.figma.com/developers/api#users-endpoints
Api.getUserMe()
Version History (File Versions)
See: https://www.figma.com/developers/api#version-history-endpoints
Api.getFileVersions(pathParams)
Projects
See: https://www.figma.com/developers/api#projects-endpoints
Api.getTeamProjects(pathParams)
Api.getProjectFiles(pathParams,queryParams)
Components and Styles (Library Items)
See: https://www.figma.com/developers/api#library-items-endpoints
Api.getTeamComponents(pathParams,queryParams)
Api.getFileComponents(pathParams)
Api.getComponent(pathParams)
Api.getTeamComponentSets(pathParams,queryParams)
Api.getFileComponentSets(pathParams)
Api.getComponentSet(pathParams)
Api.getTeamStyles(pathParams,queryParams)
Api.getFileStyles(pathParams)
Api.getStyle(pathParams)
Webhooks
See: https://www.figma.com/developers/api#webhooks_v2
Api.getWebhook(pathParams)
Api.postWebhook(requestBody)
Api.putWebhook(pathParams,requestBody)
Api.deleteWebhook(pathParams)
Api.getTeamWebhooks(pathParams)
Api.getWebhookRequests(pathParams)
Activity Logs
See: https://www.figma.com/developers/api#activity-logs-endpoints
[!TIP] [TODO] Open to contributions if someone is needs to use these endpoints
Payments
See: https://www.figma.com/developers/api#payments-endpoints
[!TIP] [TODO] Open to contributions if someone is needs to use these endpoints
Variables
[!NOTE] These APIs are available only to full members of Enterprise orgs.
See: https://www.figma.com/developers/api#variables-endpoints
Api.getLocalVariables(pathParams)
Api.getPublishedVariables(pathParams)
Api.postVariables(pathParams,requestBody)
Dev Resources
See: https://www.figma.com/developers/api#dev-resources-endpoints
Api.getDevResources(pathParams,queryParams)
Api.postDevResources(requestBody)
Api.putDevResources(requestBody)
Api.deleteDevResources(pathParams)
Analytics
See: https://www.figma.com/developers/api#library-analytics-endpoints
Api.getLibraryAnalyticsComponentActions(pathParams,queryParams)
Api.getLibraryAnalyticsComponentUsages(pathParams,queryParams)
Api.getLibraryAnalyticsStyleActions(pathParams,queryParams)
Api.getLibraryAnalyticsStyleUsages(pathParams,queryParams)
Api.getLibraryAnalyticsVariableActions(pathParams,queryParams)
Api.getLibraryAnalyticsVariableUsages(pathParams,queryParams)
Types
The library is fully typed using the official Figma REST API specifications. You can see those types in the generated file here: https://github.com/figma/rest-api-spec/blob/main/dist/api_types.ts.
Alternatively, you can refer to the official Figma REST API documentation (see links above).
Development
git clone https://github.com/didoo/figma-api.git
cd figma-api
git checkout main
npm i
npm run build
Release
npm version [<newversion> | major | minor | patch]
#if not yet logged in
npm login
npm publish
(notice: tags are created automatically after a few minutes from the publishing)