Figma's Plugin API: Read and Write to the Canvas Tree

WHY IT EXISTS: Plugins exist to automate repetitive tasks and extend Figma's core functionality. Instead of manually adjusting hundreds of layers or creating complex data visualizations by hand, developers can write code to perform these actions, creating more efficient and customized design workflows.

THE MENTAL MODEL: Think of a Figma file not as a visual canvas, but as a structured tree of data. At the very top is the DocumentNode, which contains one or more PageNodes. Each PageNode, in turn, contains a hierarchy of nodes representing every layer, shape, and text element on that page. The Plugin API is your key to programmatically read and modify this tree.

HOW IT WORKS: A plugin consists of JavaScript for logic and optional HTML for a user interface. Your script gains access to the file's contents through the global figma object. For example, figma.currentPage gives you the node for the user's currently viewed page. From there, you can traverse its children to find and manipulate nodes, changing properties like color, position, or text content.

A critical aspect is that Figma loads files dynamically to save memory. This means pages and components outside the current view are not immediately available. To access them, you must use asynchronous functions, such as figma.importComponentByKeyAsync() to pull in a library component. Similarly, fonts must be loaded with loadFontAsync() before they can be applied to text nodes.

WHEN TO USE IT: Use the Plugin API for any task that involves manipulating objects inside a Figma file. This is ideal for building tools that perform batch operations like renaming layers, applying a new color style across hundreds of components, generating complex layouts from data, or creating custom content like charts and QR codes.

WHEN NOT TO USE IT: The Plugin API is limited to the contents of a file. It cannot access broader account or file metadata. For tasks like reading a file's version history, listing comments, or checking its team location, you must use Figma's REST API, not the Plugin API. You also cannot access library styles or components unless they are already in the file or explicitly imported via an API call.

ONE CANONICAL EXAMPLE: A plugin to find and replace a specific word in every text layer on the current page. The script would call figma.currentPage.findAll(node => node.type === "TEXT"). This returns an array of all text nodes. The script would then loop through this array, check each node's characters property for the target word, and replace it if found. This demonstrates node traversal, filtering, and property modification.