openfig-core

openfig-core

Isomorphic .fig file parser — reads Figma binary format in Node.js and browsers.

Parses .fig (Figma Design), .deck (Figma Slides), and .jam (FigJam) files into a traversable node tree. Zero Node.js dependencies — works in browsers via bundlers.

Install

npm install openfig-core

Quick start

import { parseFig, nodeId } from 'openfig-core';
import { readFileSync } from 'fs';

const data = new Uint8Array(readFileSync('design.fig'));
const doc = parseFig(data);

console.log(doc.header);          // { prelude: 'fig-kiwi', version: 52 }
console.log(doc.nodes.length);    // number of nodes in the file

// Traverse the node tree
for (const node of doc.nodes) {
  const id = nodeId(node);
  const children = doc.childrenMap.get(id) ?? [];
  console.log(`${id} ${node.type} "${node.name}" (${children.length} children)`);
}

Browser

const resp = await fetch('/design.fig');
const data = new Uint8Array(await resp.arrayBuffer());
const doc = parseFig(data);

API

parseFig(data: Uint8Array): FigDocument

Parse a complete .fig ZIP archive. Extracts canvas.fig, meta.json, thumbnail.png, and images/*.

parseFigBinary(data: Uint8Array): FigDocument

Parse raw canvas.fig binary data (the blob inside the ZIP). Use this if you extract the ZIP yourself.

nodeId(node: FigNode): string | null

Format a node's GUID as "sessionID:localID" (e.g. "1:127"). Returns null if the node has no GUID.

FigDocument

interface FigDocument {
  header: { prelude: string; version: number };
  nodes: FigNode[];                      // all nodes (flat array)
  nodeMap: Map<string, FigNode>;         // id → node
  childrenMap: Map<string, FigNode[]>;   // parent id → children
  schema: any;                           // decoded kiwi binary schema
  compiledSchema: any;                   // compiled schema (encodeMessage/decodeMessage)
  rawChunks: Uint8Array[];               // raw length-prefixed binary chunks
  message: any;                          // full decoded kiwi message
  meta?: Record<string, any>;            // meta.json contents
  thumbnail?: Uint8Array;                // thumbnail.png bytes
  images: Map<string, Uint8Array>;       // filename → image bytes
}

FigNode

interface FigNode {
  guid: FigGuid;
  type: string;                          // FRAME, TEXT, ELLIPSE, SYMBOL, INSTANCE, ...
  name: string;
  phase?: string;                        // CREATED, REMOVED, etc.
  parentIndex?: { guid: FigGuid; position: string };
  size?: { x: number; y: number };
  transform?: { m00, m01, m02, m10, m11, m12: number };
  fillPaints?: FigPaint[];
  textData?: { characters: string };
  [key: string]: any;                    // open for all kiwi-decoded fields
}

Encoding (write .fig files)

Round-trip: open, edit, save

import { parseFig, encodeFigParts, assembleCanvasFig, createFigZip } from 'openfig-core';

const doc = parseFig(data);

// Edit nodes...
doc.message.nodeChanges[2].name = "Renamed";

const parts = encodeFigParts(doc);

// Caller must zstd-compress the message (openfig-core stays isomorphic)
const messageCompressed = yourZstdCompress(parts.messageRaw, 3);

const canvasFig = assembleCanvasFig({
  prelude: parts.prelude,
  version: parts.version,
  schemaCompressed: parts.schemaCompressed,
  messageCompressed,
  passThrough: parts.passThrough,
});

const figZip = createFigZip({
  canvasFig,
  meta: doc.meta,
  thumbnail: doc.thumbnail,
  images: doc.images,
});
// figZip is a Uint8Array — write to disk or trigger download

From scratch: create a new .fig file

import { createEmptyFigDoc, encodeFigParts, assembleCanvasFig, createFigZip } from 'openfig-core';

const doc = createEmptyFigDoc();

// Add nodes to doc.message.nodeChanges...

const parts = encodeFigParts(doc);
const messageCompressed = yourZstdCompress(parts.messageRaw, 3);
const canvasFig = assembleCanvasFig({ ...parts, messageCompressed });
const figZip = createFigZip({ canvasFig, meta: doc.meta, thumbnail: doc.thumbnail });

encodeFigParts(doc: FigDocument): EncodedFigParts

Encodes a FigDocument into kiwi binary parts. Returns the raw message (caller must zstd-compress for chunk 1) and the deflate-compressed schema (chunk 0).

assembleCanvasFig(input: AssembleCanvasFigInput): Uint8Array

Assembles the canvas.fig binary from pre-compressed chunks. Format: [prelude 8B][version uint32 LE][len+chunk0][len+chunk1][len+chunk2+]...

createFigZip(input: CreateFigZipInput): Uint8Array

Packages canvas.fig + optional meta.json, thumbnail.png, and images/* into a .fig ZIP archive (store mode).

createEmptyFigDoc(): FigDocument

Creates an empty FigDocument with a bundled kiwi schema, a Document node, and a Page node. Ready for adding content and encoding.

File format documentation

Detailed documentation of the Figma binary format is in docs/:

Doc	Covers
Archive structure	ZIP layout, canvas.fig binary, kiwi schema, encoding pipeline
Nodes	Node types, GUIDs, parentIndex, hierarchy
Shapes	ROUNDED_RECTANGLE, FRAME, transforms, geometry
Vector	VECTOR nodes, commandsBlob format, blob resolution, helper API
Text	TEXT nodes, styles, fonts
Images	Image storage, SHA-1 hashing, thumbnails
Colors	Color variables, palette
Overrides	Symbol overrides (text, image, nested)
Slides	Slide dimensions, cloning, ordering
Modes	Slides mode vs Design mode
Invariants	Hard rules and sentinel values
Research	Binary format analysis and references

Dependencies

• fflate — ZIP extraction + deflate decompression
• kiwi-schema — Kiwi binary format decoding
• fzstd — Zstandard decompression

License

MIT

Disclaimer

Figma is a trademark of Figma, Inc. This project is not affiliated with, endorsed by, or sponsored by Figma, Inc.