Version 1, Update 87

APIs for dynamic page loading

Over the past few months, Figma has been rolling out dynamic page loading, which allows documents to load pages on demand, rather than all at once. For backward compatibility, Figma loads all pages in the document before attempting to run an extension (a plugin or widget), which can sometimes result in a noticeable delay.

We're pleased to announce a new set of APIs that allow extensions to work safely with dynamic page loading, and avoid triggering the loading delay. Alongside these new APIs, we are deprecating several existing methods and properties. This will help to ensure that new extensions will be compatible with dynamic page loading by default.

To mark an extension as compatible with dynamic page loading, add "documentAccess": "dynamic-page" to manifest.json. Extensions with this manifest field will not encounter loading delays, but they'll be unable to access any of the deprecated methods and properties listed below. New extensions will include this manifest field by default.

To learn more about updating your extension, see our comprehensive migration guide. For TypeScript users, we've also provided an ESLint plugin that can help identify and automatically fix callsites that need to be updated.

Timeline

As of February 21st, dynamic page loading APIs are generally available (GA). You can update existing extensions and create new extensions using the dynamic page loading APIs and the manifest field "documentAccess": "dynamic-page".

Starting in April, the manifest field "documentAccess": "dynamic-page" will be required for all widgets, and all new plugins.

Net-new methods

• figma.loadAllPagesAsync()
• figma.variables.createVariableAliasByIdAsync()
• PageNode.loadAsync()

Deprecations and replacements

Several methods and properties have been deprecated in favor of async replacements:

• Use figma.getFileThumbnailNodeAsync() instead of figma.getFileThumbnailNode().
• Use figma.getLocalEffectStylesAsync() instead of figma.getLocalEffectStyles().
• Use figma.getLocalGridStylesAsync() instead of figma.getLocalGridStyles().
• Use figma.getLocalPaintStylesAsync() instead of figma.getLocalPaintStyles().
• Use figma.getLocalTextStylesAsync() instead of figma.getLocalTextStyles().
• Use figma.getNodeByIdAsync() instead of figma.getNodeById().
• Use figma.getStyleByIdAsync() instead of figma.getStyleById().
• Use figma.variables.getLocalVariableCollectionsAsync() instead of figma.variables.getLocalVariableCollections().
• Use figma.variables.getLocalVariablesAsync() instead of figma.variables.getLocalVariables().
• Use figma.variables.getVariableByIdAsync() instead of figma.variables.getVariableById().
• Use figma.variables.getVariableCollectionByIdAsync() instead of figma.variables.getVariableCollectionById().
• Use setRangeFillStyleIdAsync() instead of setRangeFillStyleId().
• Use setRangeTextStyleIdAsync() instead of setRangeTextStyleId().

In some specific cases, reading node properties has been deprecated in favor of an async getter:

• Use ComponentNode.getInstancesAsync() instead of ComponentNode.instances.
• Use getStyleConsumersAsync() instead of the consumers.
• Use InstanceNode.getMainComponentAsync() instead of InstanceNode.mainComponent.

In some specific cases, assigning values directly to node properties has been deprecated in favor of an async setter:

• Use figma.setCurrentPageAsync() instead of assigning to figma.currentPage.
• Use setEffectStyleIdAsync() instead of assigning to effectStyleId.
• Use setFillStyleIdAsync() instead of assigning to backgroundStyleId.
• Use setFillStyleIdAsync() instead of assigning to fillStyleId.
• Use setGridStyleIdAsync() instead of assigning to gridStyleId.
• Use setReactionsAsync() instead of assigning to reactions.
• Use setStrokeStyleIdAsync() instead of assigning to strokeStyleId.
• Use setVectorNetworkAsync() instead of assigning to vectorNetwork.
• Use TextNode.setTextStyleIdAsync() instead of assigning to TextNode.textStyleId.

If an extension's manifest contains "documentAccess": "dynamic-page", accessing any of the deprecated items listed above will throw an exception.

Method/property usage changes

If an extension's manifest contains "documentAccess": "dynamic-page", calling any of the following methods will throw an exception unless you first call figma.loadAllPagesAsync():

• DocumentNode.findAll()
• DocumentNode.findAllWithCriteria()
• DocumentNode.findOne()
• DocumentNode.findWidgetNodesByWidgetId()

For the methods listed below, passing a string ID is now deprecated in favor of passing objects that the IDs refer to. If an extension's manifest contains "documentAccess": "dynamic-page", passing an ID will throw an exception.

• figma.variables.createVariable() - Pass a VariableCollection object instead of a collection ID.
• clearExplicitVariableModeForCollection() (present on multiple node types) - Pass a VariableCollection object instead of a collection ID.
• setExplicitVariableModeForCollection() (present on multiple node types) - Pass a VariableCollection object instead of a collection ID.
• setBoundVariable() (present on multiple node types) - Pass a Variable object instead of a variable ID.

If an extension's manifest contains "documentAccess": "dynamic-page", some properties and methods of PageNode will throw an exception unless you explicitly load the page first using PageNode.loadAsync(). These include:

• PageNode.appendChild()

• PageNode.exportAsync

• PageNode.findAll()

• PageNode.findAllWithCriteria()

• PageNode.findChild()

• PageNode.findChildren()

• PageNode.findOne()

• PageNode.findWidgetNodesByWidgetId()

• PageNode.insertChild()

Changes to events

• If an extension's manifest contains "documentAccess": "dynamic-page", the documentchange event will not be available unless you first call figma.loadAllPagesAsync().
• Where possible, prefer using the nodechange and stylechange events, which do not require triggering a full-document load.