Figma Plugin Data Storage: clientStorage vs Plugin Data, and When to Use Each

A team building an internal plugin stored each user’s preferred export settings using clientStorage, expecting that once one team member configured the plugin, everyone else opening the same file would see those same settings already applied. Instead, every team member saw the plugin’s default settings every time, regardless of what a colleague had configured earlier, because clientStorage does not persist data the way they had assumed it did.

This is a genuinely common point of confusion, since Figma’s plugin API offers several storage options that sound similar on the surface but persist data in distinctly different places, with different scope and different visibility to other users and other plugins entirely.

The Core Distinction: Where Each Storage Type Actually Lives

This is the fundamental thing to understand before choosing between them. clientStorage persists data locally on the specific user’s machine, tied to their specific Figma account on that device, and is never automatically shared with anyone else, regardless of what file they open. setPluginData and getPluginData, by contrast, persist data directly within the document file itself, attached to a specific node, meaning this data travels with the file and is visible to anyone who opens it, provided they are using the same plugin.

This single distinction directly explains the team’s confusion — clientStorage was never going to synchronize a setting across team members, since it was never designed to be shared in the first place; it is explicitly local-only storage by design.

clientStorage: Local to the User, Not the Document

clientStorage is the right tool specifically for storing data that should genuinely persist per-user, across any file they open, on that specific device — preferences like a default export format, a remembered UI panel size, or an API key the user has entered once and does not want to re-enter every time they open the plugin.

// Saving a user preference
await figma.clientStorage.setAsync('exportFormat', 'PNG');

// Retrieving it later
const format = await figma.clientStorage.getAsync('exportFormat');

Worth using when: The data is genuinely about this specific user’s personal preferences or settings, and you want it to persist across different files they open, but you have no expectation or need for anyone else to see this same data.

setPluginData and getPluginData: Tied to the Document and a Specific Node

These methods attach data directly to a specific node (or the document itself) within the file, meaning the data is saved as part of the file’s actual content. Anyone who opens that same file, using the same plugin, can read this data, since it travels with the document rather than staying local to whoever originally set it.

// Attaching data to a specific selected node
figma.currentPage.selection[0].setPluginData('status', 'reviewed');

// Reading it back, including by a different user who opens the same file
const status = figma.currentPage.selection[0].getPluginData('status');

Worth using when: The data is genuinely about the document or a specific element within it — a review status on a frame, configuration that should travel with the file, or any state that should be the same for everyone who opens this particular file, not specific to whichever individual happens to be viewing it.

The team’s actual fix: Switching their export settings from clientStorage to setPluginData attached to the document node immediately solved their synchronization problem, since the setting now lived within the file itself rather than being scoped to whichever individual had originally configured it.

setSharedPluginData and getSharedPluginData: Visible Across Different Plugins

A related but distinct method, setSharedPluginData, also attaches data to the document or a node, but under a namespace that other plugins (not just your own) can read, provided they know the specific namespace and key you used. Regular setPluginData, by contrast, is only readable by the same plugin that originally wrote it.

Worth using when: You specifically want a different plugin (perhaps a companion tool, or another team’s plugin) to be able to read data your plugin has written, rather than keeping this data exclusively accessible to your own plugin’s later invocations.

This is a less commonly needed option than standard setPluginData, since most plugins do not need to expose their internal data to unrelated plugins, but it exists specifically for the cases where genuine cross-plugin data sharing within the same file is the actual intended design.

A Practical Way to Decide

Ask directly: should this data follow the specific user wherever they go, or should it follow the specific file regardless of who opens it. If the answer is the user, clientStorage is correct. If the answer is the file, setPluginData (or setSharedPluginData, if another plugin specifically needs read access) is correct.

A secondary question, only relevant if you chose file-level storage: does this data belong to the document broadly, or to one specific node within it. Settings or status that conceptually apply to the whole file are often better attached to the document object itself rather than an arbitrary specific node that might later be deleted, taking your stored data down with it.

A Quick Reference Comparison

What Resolved the Team’s Confusion

Once we walked through this distinction directly — clientStorage follows the person, setPluginData follows the file — the team’s actual intended behavior (settings shared across whoever opens a given file) clearly pointed to setPluginData rather than the clientStorage they had defaulted to without specifically considering this distinction, and the fix took only a few minutes once the correct mental model was in place.

Are you trying to persist something specific to one user across files, or something specific to one file regardless of who opens it? Describe what you’re storing and I can help you determine which storage method genuinely fits your case.