figma-main-thread

Figma Main Thread (Plugin Sandbox) Rules

This code runs in Figma's plugin sandbox with access to the figma.* API.

Available APIs

• figma.currentPage - Current page and its children
• figma.root - Document root
• figma.createRectangle(), figma.createFrame(), etc. - Node creation
• figma.getNodeById(id) - Retrieve nodes by ID
• figma.loadFontAsync() - Required before setting text
• figma.notify() - Show toast notifications
• figma.ui.postMessage() - Send data to UI

Critical Patterns

Store IDs, Not References

Node references become stale after async operations:

// ❌ BAD - node reference may be stale after await
const node = figma.currentPage.selection[0];
await someAsyncOperation();
node.name = "New Name"; // May fail!

// ✓ GOOD - re-fetch by ID after async
const nodeId = figma.currentPage.selection[0]?.id;
await someAsyncOperation();
const node = figma.getNodeById(nodeId);
if (node) node.name = "New Name";

Font Loading

Always load fonts before setting text content:

// ✓ Required before setting characters
const textNode = figma.createText();
await figma.loadFontAsync({ family: "Inter", style: "Regular" });
textNode.characters = "Hello World";

Node Type Guards

Check node type before accessing type-specific properties:

// ✓ Use type guards
if (node.type === "FRAME") {
  console.log(node.layoutMode); // Safe - FRAME has layoutMode
}

// ✓ Or use 'in' operator
if ("fills" in node) {
  console.log(node.fills);
}

Node Traversal

Prefer built-in methods over manual recursion:

// ✓ GOOD - use findAll/findOne
const textNodes = figma.currentPage.findAll((n) => n.type === 'TEXT')
const firstFrame = figma.currentPage.findOne((n) => n.type === 'FRAME')

// ❌ AVOID - manual recursion is error-prone
function findAllText(node) { ... }

Serializing Nodes for UI

Never send raw nodes - extract only needed data:

// ✓ GOOD - serialize to plain object
function serializeNode(node: SceneNode) {
  return {
    id: node.id,
    name: node.name,
    type: node.type,
    width: "width" in node ? node.width : 0,
    height: "height" in node ? node.height : 0,
  };
}