figma-node-query

Fetch and inspect nodes within Figma files via URL and PAT, with results serialized as JSON objects/arrays.

---

Usage

1. Install the package as dependency or devDependency, based on your usage:

npm install @ontech7/figma-node-query dotenv
# or
npm install -D @ontech7/figma-node-query dotenv

2. Retrieve/generate your Figma personal Access Token from:

figma.com > Login > [Your Name] > Settings > Security > Personal access tokens > Generate new token

And add it in your .env file as FIGMA_TOKEN or export it in your terminal export FIGMA_TOKEN=<your-token>

3. Retrieve your file-key from Figma project URL:

URL-like: https://www.figma.com/design/[file-key]/[file-name]

eg.: https://www.figma.com/design/qWrhGNCtP9avcXdYiaBVxE/%F0%9F%94%AE-Buttons-Library--Community-

[file-key] => qWrhGNCtP9avcXdYiaBVxE
[file-name] => Buttons Library (Community)

4. Copy the interested node-id from the Figma project:

Page-name > Node-name -> Copy as -> Copy link to selection

URL-like: https://www.figma.com/design/[file-key]/[file-name]?node-id=[node-id]

eg.: https://www.figma.com/design/qWrhGNCtP9avcXdYiaBVxE/%F0%9F%94%AE-Buttons-Library--Community-?node-id=1-5

[node-id] => 1-5

5. Import FigmaNodeClient to your project:

// index.ts
import { FigmaNodeClient } from "@ontech7/figma-node-query";

type FigmaRGBA = { r: number; g: number; b: number; a: number };

const client = new FigmaNodeClient("qWrhGNCtP9avcXdYiaBVxE"); // initialize client with [file-name]

const node = await client.node("1-5"); // call Figma API with [node-id] to generate a FigmaNodeCollection instance

const secondaryButton = node
  .getAll("@COMPONENT") // search for all nodes with type = "COMPONENT"
  .get("~State=") // search for first node with name that starts with "State="
  .toJSON<{ backgroundColor: FigmaRGBA }>(); // transforms FigmaNodeCollection to serializable JSON object

console.log(secondaryButton.backgroundColor);

// { r: 0.12083333730697632, g: 0.5074999332427979, b: 0.7250000238418579, a: 1 }

Disclaimer: if the response from client.node(NODE_ID) is too big, an exception will be thrown. The best practice should be calling smaller and more client.node(NODE_ID) instead.

---

Methods

Name	Description
new FigmaNodeClient(fileKey, ttl?)	Instance of a Figma client
fileName	Title of the Figma file
lastModified	Date of the last update done by an author of the Figma file
node(nodeId)	Calls Figma API to retrieve the node by [node-id]
get(selector)	Retrieve the first node with specified selector. Throws error if no match.
getAll(selector)	Retrieve all nodes with specified selector. Returns empty array if no match.
toJSON<T>()	Result as JSONObject (or JSONObject if getAll method)
FigmaNodeClient.clearCache()	Clear any current cache

---

Special Lookup Tokens

Name	Description
#	Look up for id
@	Look up for type
~	Look up for name if alike (a.k.a. s1.includes(s2))
^	Look up for name if starts-with (a.k.a. s1.startsWith(s2))
$	Look up for name if ends-with (a.k.a. s1.endsWith(s2))

---

Example

Here are simple examples:

• Check example folder

---

Credits

Written by Andrea Losavio.