Class DesignFacade
Identification Properties
The absolute path of the original design file. This is not available for designs loaded from the API.
Identification Accessors
The key which can be used to name files in the file system.
This is the ID of the referenced server-side design or (if the API is not configured) the basename of the local file.
It can theoretically be null when the design is created only virtually in memory but such feature is yet to be implemented thus the value can safely be assumed as always available and for that reason, it is annotated as non-nullable.
Example:
design.renderArtboardToFile(`./artboards/${design.fileKey}/${artboard.fileKey}.png`)The ID of the referenced server-side design. This is not available when the API is not configured for the SDK.
The ID of the referenced server-side design version. This is not available when the API is not configured for the SDK.
Data Accessors
The name of the design. This is the basename of the file by default or a custom name provided during design import.
Data Methods
Returns the bounds of the specified artboard.
The API has to be configured when using this method to get bounds of an uncached artboard.
Example:
const artboardBounds = await design.getArtboardBounds('<ARTBOARD_ID>')Parameters:
The ID of the artboard to inspect.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The artboard bounds.
Returns the attributes of the spececified layer.
Example:
const attrs = await design.getArtboardLayerAttributes('<ARTBOARD_ID>', '<LAYER_ID>')
const { blendingMode, opacity, visible } = attrsParameters:
The ID of the artboard from which to inspect the layer.
The ID of the layer to inspect.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
Layer attributes.
Returns various bounds of the specified layer.
The rendering engine and the local cache have to be configured when using this method.
Example:
const layerBounds = await design.getArtboardLayerBounds('<ARTBOARD_ID>', '<LAYER_ID>')
const boundsWithEffects = layerBounds.fullBoundsParameters:
The ID of the artboard from which to inspect the layer.
The ID of the layer to inspect.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
Various layer bounds.
Figma Design Usage Methods
Imports a Figma design as a version of the design.
All versions of a design must originate from the same design file format which makes this method usable only for designs originally also imported from Figma.
The API has to be configured when using this method.
The design is automatically imported by the API and local caching is established.
Example:
Explicitly provided Figma token
const version = await design.importVersionFigmaDesign({
figmaToken: '<FIGMA_TOKEN>',
figmaFileKey: 'abc',
})
console.log(version.id) // == server-generated UUID
// Continue working with the processed design version
const artboards = version.getArtboards()Figma token not provided, using Figma OAuth connection
const version = await design.importVersionFigmaDesign({
figmaFileKey: 'abc',
})
console.log(version.id) // == server-generated UUID
// Continue working with the processed design version
const artboards = version.getArtboards()Parameters:
Info about the Figma design
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the design is not deleted from the server when the token is cancelled during processing; the server still finishes the processing but the SDK stops watching its progress and does not download the result). A cancellation token can be created via createCancelToken.
A name override for the design version. The original Figma design name is used by default.
A Figma design "file key" from the design URL (i.e. abc from https://www.figma.com/file/abc/Sample-File).
A listing of Figma design frames to use.
A Figma access token generated in the "Personal access tokens" section of Figma account settings. This is only required when the user does not have a Figma account connected.
A design object which can be used for retrieving data from the design version using the API.
Layer Lookup Methods
Returns the first layer object from any page or artboard (optionally down to a specific nesting level) matching the specified criteria.
This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
Layer by name from any artboard
const layer = await design.findLayer({ name: 'Share icon' })Layer by function selector from any artboard
const shareIconLayer = await design.findLayer((layer) => {
return layer.name === 'Share icon'
})Layer by name from a certain artboard subset
const layer = await design.findLayer({
name: 'Share icon',
artboardId: [ '<ID1>', '<ID2>' ],
})With timeout
const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layer = await design.findLayer(
{ name: 'Share icon' },
{ cancelToken: token }
)Parameters:
A design-wide layer selector. All specified fields must be matched by the result.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level within page and artboard layers to search. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in artboards should be searched.
A matched layer object.
Returns the first layer object which has the specified ID.
Layer IDs are unique within individual artboards but different artboards can potentially have layer ID clashes. This is the reason the method is not prefixed with "get".
This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
const layer = await design.findLayerById('<ID>')With timeout
const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layer = await design.findLayerById('<ID>', { cancelToken: token })Parameters:
A layer ID.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
A layer object.
Returns a collection of all layer objects from all pages and artboards (optionally down to a specific nesting level) matching the specified criteria.
This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
Layers by name from all artboards
const layers = await design.findLayers({ name: 'Share icon' })Layers by function selector from all artboards
const shareIconLayers = await design.findLayers((layer) => {
return layer.name === 'Share icon'
})Invisible layers from all a certain artboard subset
const layers = await design.findLayers({
visible: false,
artboardId: [ '<ID1>', '<ID2>' ],
})With timeout
const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layer = await design.findLayers(
{ type: 'shapeLayer' },
{ cancelToken: token }
)Parameters:
A design-wide layer selector. All specified fields must be matched by the result.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level within page and artboard layers to search. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in artboards should be searched.
A layer collection with layer matches.
Returns a collection of all layer objects which have the specified ID.
Layer IDs are unique within individual artboards but different artboards can potentially have layer ID clashes.
This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
const layers = await design.findLayersById('<ID>')With timeout
const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layers = await design.findLayersById('<ID>', { cancelToken: token })Parameters:
A layer ID.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
A layer collection with layer matches.
Returns the top-most layer located at the specified coordinates within the specified artboard.
The rendering engine and the local cache have to be configured when using this method.
Example:
const layerId = await design.getArtboardLayerAtPosition('<ARTBOARD_ID>', 100, 200)Parameters:
The ID of the artboard from which to render the layer.
The X coordinate in the coordinate system of the artboard where to look for a layer.
The Y coordinate in the coordinate system of the artboard where to look for a layer.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
A layer object.
Returns all layers located within the specified area of the the specified artboard.
The rendering engine and the local cache have to be configured when using this method.
Example:
Layers fully contained in the area
const layerIds = await design.getArtboardLayersInArea(
'<ARTBOARD_ID>',
{ left: 80, top: 150, width: 40, height: 30 }
)Layers fully or partially contained in the area
const layerIds = await design.getArtboardLayersInArea(
'<ARTBOARD_ID>',
{ left: 80, top: 150, width: 40, height: 30 },
{ partialOverlap: true }
)Parameters:
The ID of the artboard from which to render the layer.
The area in the corrdinate system of the artboard where to look for layers.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
Whether to also return layers which are only partially contained within the specified area.
A layer list.
Returns a collection of all layers from all pages and artboards (optionally down to a specific nesting level).
The produced collection can be queried further for narrowing down the search.
This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
All layers from all artboards
const layers = await design.getFlattenedLayers()Root layers from all artboards
const rootLayers = await design.getFlattenedLayers({ depth: 1 })With timeout
const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layers = await design.getFlattenedLayers({ cancelToken: token })Parameters:
Object
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level of layers within pages and artboards to include in the collection. By default, all levels are included. 0 also means "no limit"; 1 means only root layers in artboards should be included.
A layer collection with the flattened layers.
Asset Methods
Downloads the specified bitmap asset to the local cache.
The API and the local cache have to be configured when using this method.
Example:
const bitmapAssetDescs = await design.getBitmapAssets({ depth: 1 })
await Promise.all(bitmapAssetDescs.map(async (bitmapAssetDesc) => {
return design.downloadBitmapAsset(bitmapAssetDesc)
}))Parameters:
The bitmap asset to download.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. assets are not deleted from the disk). A cancellation token can be created via createCancelToken.
The location of the bitmap asset within the file system.
Downloads the specified bitmap assets to the local cache.
Assets which have already been downloaded are skipped.
The API and the local cache have to be configured when using this method.
Example:
Download all assets
const bitmapAssetFilenames = await design.downloadBitmapAssets()Download specific assets
const bitmapAssetDescs = await design.getBitmapAssets({ depth: 1 })
const bitmapAssetFilenames = await design.downloadBitmapAssets(bitmapAssetDescs)Parameters:
A list of bitmap assets to download. When not provided, all bitmap assets of the design are downloaded.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the asset is not deleted from the disk). A cancellation token can be created via createCancelToken.
The locations of the bitmap assets within the file system. Keys of the produced object are the name values from the provided bitmap asset descriptors (or all bitmap asset names by default).
Returns the file system location of the specified bitmap asset if it is downloaded.
The local cache has to be configured when using this method.
Example:
const bitmapAssetDescs = await design.getBitmapAssets({ depth: 1 })
const downlodedBitmapAssetFilenames = []
await Promise.all(bitmapAssetDescs.map(async (bitmapAssetDesc) => {
const filename = design.getBitmapAssetFilename(bitmapAssetDesc)
if (filename) {
downlodedBitmapAssetFilenames.push(filename)
}
}))Parameters:
A list of bitmap assets to download.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected. A cancellation token can be created via createCancelToken.
The location of the bitmap asset. null is returned when the asset is not downloaded.
Returns a list of bitmap assets used by layers in all pages and artboards (optionally down to a specific nesting level).
This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
All bitmap assets from all artboards
const bitmapAssetDescs = await design.getBitmapAssets()Bitmap assets excluding pre-rendered bitmaps from all artboards
const bitmapAssetDescs = await design.getBitmapAssets({
includePrerendered: false,
})Parameters:
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level within page and artboard layers to search for bitmap asset usage. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in artboards should be searched.
Whether to also include "pre-rendered" bitmap assets. These assets can be produced by the rendering engine (if configured; future functionality) but are available as assets for either performance reasons or due to the some required data (such as font files) potentially not being available. By default, pre-rendered assets are included.
A list of bitmap assets.
Returns a list of fonts used by layers in all pages and artboards (optionally down to a specific nesting level).
This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
All fonts from all artboards
const fontDescs = await design.getFonts()Parameters:
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level within page and artboard layers to search for font usage. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in artboards should be searched.
A list of fonts.
Rendering Methods
Renders the specified layer from the specified artboard as an PNG image file.
In case of group layers, all visible nested layers are also included.
Uncached items (artboard content and bitmap assets of rendered layers) are downloaded and cached.
The rendering engine and the local cache have to be configured when using this method.
Example:
await design.renderArtboardLayerToFile(
'<ARTBOARD_ID>',
'<LAYER_ID>',
'./rendered/layer.png'
)With custom scale and crop and using the component background color
await design.renderArtboardLayerToFile(
'<ARTBOARD_ID>',
'<LAYER_ID>',
'./rendered/layer.png',
{
scale: 2,
// The result is going to have the dimensions of 400x200 due to the 2x scale.
bounds: { left: 100, top: 0, width: 100, height: 50 },
includeComponentBackground: true,
}
)Parameters:
The ID of the artboard from which to render the layer.
The ID of the artboard layer to render.
The target location of the produced PNG image file.
Render options
The blending mode to use for rendering the layer instead of its default blending mode.
The area (in the coordinate system of the artboard) to include. This can be used to either crop or expand (add empty space to) the default layer area.
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
Whether to apply clipping by a mask layer if any such mask is set for the layer (see isMasked). Clipping is disabled by default. Setting this flag for layers which do not have a mask layer set has no effect on the results.
Whether to render the component background from the main/master component. By default, the configuration from the main/master component is used. Note that this configuration has no effect when the artboard background is not included via explicit includeComponentBackground=true nor the main/master component configuration as there is nothing with which to blend the layer.
Whether to apply layer effects of the layer. Rendering of effects of nested layers is not affected. By defaults, effects of the layer are applied.
The opacity to use for the layer instead of its default opacity.
The scale (zoom) factor to use for rendering instead of the default 1x factor.
Renders the specified layers from the specified artboard as a single composed PNG image file.
In case of group layers, all visible nested layers are also included.
Uncached items (artboard content and bitmap assets of rendered layers) are downloaded and cached.
The rendering engine and the local cache have to be configured when using this method.
Example:
With default options (1x, whole combined layer area)
await design.renderArtboardLayersToFile(
'<ARTBOARD_ID>',
['<LAYER1>', '<LAYER2>'],
'./rendered/layers.png'
)With custom scale and crop and using the custom layer configuration
await design.renderArtboardLayersToFile(
'<ARTBOARD_ID>',
['<LAYER1>', '<LAYER2>'],
'./rendered/layers.png',
{
scale: 2,
// The result is going to have the dimensions of 400x200 due to the 2x scale.
bounds: { left: 100, top: 0, width: 100, height: 50 },
layerAttributes: {
'<LAYER1>': { blendingMode: 'SOFT_LIGHT', includeComponentBackground: true },
'<LAYER2>': { opacity: 0.6 },
}
}
)Parameters:
The ID of the artboard from which to render the layers.
The IDs of the artboard layers to render.
The target location of the produced PNG image file.
Render options
The area (in the coordinate system of the artboard) to include. This can be used to either crop or expand (add empty space to) the default layer area.
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
Layer-specific options to use for the rendering instead of the default values.
The scale (zoom) factor to use for rendering instead of the default 1x factor.
Renders the specified artboard as an PNG image file.
All visible layers from the artboard are included.
Uncached items (artboard content and bitmap assets of rendered layers) are downloaded and cached.
The rendering engine and the local cache have to be configured when using this method.
Example:
With default options (1x, whole artboard area)
await design.renderArtboardToFile('<ARTBOARD_ID>', './rendered/artboard.png')With custom scale and crop
await design.renderArtboardToFile('<ARTBOARD_ID>', './rendered/artboard.png', {
scale: 4,
// The result is going to have the dimensions of 400x200 due to the 4x scale.
bounds: { left: 100, top: 0, width: 100, height: 50 },
})Parameters:
The ID of the artboard to render.
The target location of the produced PNG image file.
Render options
The area (in the coordinate system of the artboard) to include. This can be used to either crop or expand (add empty space to) the default artboard area.
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The scale (zoom) factor to use for rendering instead of the default 1x factor.
Renders all artboards from the specified page as a single PNG image file.
All visible layers from the artboards are included.
Uncached items (artboard contents and bitmap assets of rendered layers) are downloaded and cached.
The rendering engine and the local cache have to be configured when using this method.
Example:
With default options (1x, whole page area)
await design.renderPageToFile('<PAGE_ID>', './rendered/page.png')With custom scale and crop
await design.renderPageToFile('<PAGE_ID>', './rendered/page.png', {
scale: 2,
// The result is going to have the dimensions of 400x200 due to the 2x scale.
bounds: { left: 100, top: 0, width: 100, height: 50 },
})Parameters:
The ID of the page to render.
The target location of the produced PNG image file.
Render options
The area (in the coordinate system of the page) to include. This can be used to either crop or expand (add empty space to) the default page area.
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The scale (zoom) factor to use for rendering instead of the default 1x factor.
SVG Export Methods
Returns an SVG document string of the specified layer from the specified artboard.
In case of group layers, all visible nested layers are also included.
Bitmap assets are serialized as base64 data URIs.
Uncached items (artboard content and bitmap assets of exported layers) are downloaded and cached.
The SVG exporter has to be configured when using this methods. The local cache has to also be configured when working with layers with bitmap assets.
Example:
With default options (1x)
const svg = await design.exportArtboardLayerToSvgCode(
'<ARTBOARD_ID>',
'<LAYER_ID>'
)With custom scale and opacity
const svg = await design.exportArtboardLayerToSvgCode(
'<ARTBOARD_ID>',
'<LAYER_ID>',
{
opacity: 0.6,
scale: 2,
}
)Parameters:
The ID of the artboard from which to export the layer.
The IDs of the artboard layer to export.
Export options
The blending mode to use for the layer instead of its default blending mode.
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
Whether to apply clipping by a mask layer if any such mask is set for the layer (see isMasked). Clipping is disabled by default. Setting this flag for layers which do not have a mask layer set has no effect on the results.
Whether to apply layer effects of the layer. Effects of nested layers are not affected. By defaults, effects of the layer are applied.
The opacity to use for the layer instead of its default opacity.
The scale (zoom) factor to use instead of the default 1x factor.
An SVG document string.
Exports the specified layer from the specified artboard as an SVG file.
In case of group layers, all visible nested layers are also included.
Bitmap assets are serialized as base64 data URIs.
Uncached items (artboard content and bitmap assets of exported layers) are downloaded and cached.
The SVG exporter has to be configured when using this methods. The local cache has to also be configured when working with layers with bitmap assets.
Example:
With default options (1x)
await design.exportArtboardLayerToSvgFile(
'<ARTBOARD_ID>',
'<LAYER_ID>',
'./layer.svg'
)With custom scale and opacity
await design.exportArtboardLayerToSvgFile(
'<ARTBOARD_ID>',
'<LAYER_ID>',
'./layer.svg',
{
opacity: 0.6,
scale: 2,
}
)Parameters:
The ID of the artboard from which to export the export.
The IDs of the artboard layer to export.
The target location of the produced SVG file.
Export options.
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The scale (zoom) factor to use instead of the default 1x factor.
Returns an SVG document string of the specified layers from the specified artboard.
In case of group layers, all visible nested layers are also included.
Bitmap assets are serialized as base64 data URIs.
Uncached items (artboard content and bitmap assets of exported layers) are downloaded and cached.
The SVG exporter has to be configured when using this methods. The local cache has to also be configured when working with layers with bitmap assets.
Example:
With default options (1x)
const svg = await design.exportArtboardLayersToSvgCode(
'<ARTBOARD_ID>',
['<LAYER1>', '<LAYER2>']
)With custom scale
const svg = await design.exportArtboardLayersToSvgCode(
'<ARTBOARD_ID>',
['<LAYER1>', '<LAYER2>'],
{
scale: 2,
layerAttributes: {
'<LAYER1>': { blendingMode: 'SOFT_LIGHT' },
'<LAYER2>': { opacity: 0.6 },
}
}
)Parameters:
The ID of the artboard from which to export the layers.
The IDs of the artboard layers to export.
Export options.
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
Layer-specific options to use for instead of the default values.
The scale (zoom) factor to use instead of the default 1x factor.
An SVG document string.
Export the specified layers from the specified artboard as an SVG file.
In case of group layers, all visible nested layers are also included.
Bitmap assets are serialized as base64 data URIs.
Uncached items (artboard content and bitmap assets of exported layers) are downloaded and cached.
The SVG exporter has to be configured when using this methods. The local cache has to also be configured when working with layers with bitmap assets.
Example:
With default options (1x)
await design.exportArtboardLayersToSvgFile(
'<ARTBOARD_ID>',
['<LAYER1>', '<LAYER2>'],
'./layers.svg'
)With custom scale
await design.exportArtboardLayersToSvgFile(
'<ARTBOARD_ID>',
['<LAYER1>', '<LAYER2>'],
'./layers.svg',
{
scale: 2,
layerAttributes: {
'<LAYER1>': { blendingMode: 'SOFT_LIGHT' },
'<LAYER2>': { opacity: 0.6 },
}
}
)Parameters:
The ID of the artboard from which to export the layers.
The IDs of the artboard layers to export.
The target location of the produced SVG file.
Export options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The scale (zoom) factor to use instead of the default 1x factor.
Artboard Lookup Methods
Looks up the first artboard object matching the provided criteria.
Example:
const productArtboard = design.findArtboard({ name: /Product/i })
const productArtboard = design.findArtboard((artboard) => /Product/i.test(artboard.name))
const oneOfArtboards123 = design.findArtboard({ id: ['<ID1>', '<ID2>', '<ID3>'] })Parameters:
An artboard selector. All specified fields must be matched by the result.
An artboard object.
Looks up all artboard objects matching the provided criteria.
Example:
const productArtboards = design.findArtboards({ name: /Product/i })
const productArtboards = design.findArtboards((artboard) => /Product/i.test(artboard.name))
const artboards123 = design.findArtboards({ id: ['<ID1>', '<ID2>', '<ID3>'] })Parameters:
An artboard selector. All specified fields must be matched by the results.
An artboard list.
Returns an artboard object of a specific (main/master) component. These can be used to work with the artboard contents.
Example:
const artboard = design.getArtboardByComponentId('<COMPONENT_ID>')Returns a single artboard object. These can be used to work with the artboard contents.
Example:
const artboard = design.getArtboardById('<ARTBOARD_ID>')Returns a complete list of artboard object in the design. These can be used to work with artboard contents.
Example:
const artboards = design.getArtboards()Returns (main/master) component artboard objects. These can be used to work with artboard contents.
Example:
const componentArtboards = design.getComponentArtboards()Returns artboard objects for a specific page (in case the design is paged). These can be used to work with artboard contents.
Example:
const pageArtboards = design.getPageArtboards('<PAGE_ID>')Configuration Methods
Sets the fonts which should be used as a fallback in case the actual fonts needed for rendering text layers are not available.
The first font from this list which is available in the system is used for all text layers with missing actual fonts. If none of the fonts are available, the text layers are not rendered.
This configuration overrides/extends the global configuration set via setGlobalFallbackFonts. Fonts specified here are preferred over the global config.
This configuration is copied to any other versions of the design later obtained through this design object as the default font configuration.
Example:
design.setFallbackFonts([ 'Calibri', './custom-fonts/Carolina.otf', 'Arial' ])Parameters:
An ordered list of font postscript names or font file paths.
Sets the directory where fonts should be looked up when rendering the design.
Fonts are matched based on their postscript names, not the file basenames.
This configuration overrides the global font directory configuration (set up via setGlobalFontDirectory) – i.e. fonts from the globally configured directory are not used for the design.
This configuration is copied to any other versions of the design later obtained through this design object as the default font configuration.
Example:
design.setFontDirectory('./custom-fonts')
design.setFontDirectory('/var/custom-fonts')Parameters:
An absolute path to a directory or a path relative to the process working directory (process.cwd() in node.js). When null is provided, the configuration is cleared for the design.
Design Versions Methods
Fetches a previously imported version of the design newer than the current version of the DesignFacade entity from the API.
The API has to be configured when using this method. Local caching is established in case the local cache is configured.
Example:
const nextVersion = await design.getNextVersion()
// Continue working with the processed design version
const versionArtboards = nextVersion.getArtboards()Parameters:
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the local cache is not cleared once created). A cancellation token can be created via createCancelToken.
A design object which can be used for retrieving data from the design version using the API.
Fetches a previously imported version of the design older than the current version of the DesignFacade entity from the API.
The API has to be configured when using this method. Local caching is established in case the local cache is configured.
Example:
const prevVersion = await design.getPrevVersion()
// Continue working with the processed design version
const versionArtboards = prevVersion.getArtboards()Parameters:
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the local cache is not cleared once created). A cancellation token can be created via createCancelToken.
A design object which can be used for retrieving data from the design version using the API.
Fetches a previously imported version of the design from the API.
The API has to be configured when using this method. Local caching is established in case the local cache is configured.
Example:
const version = await design.getVersionById('<VERSION_ID>')
// Continue working with the processed design version
const versionArtboards = version.getArtboards()Parameters:
An ID of a server-side design version assigned during import (via importVersionDesignFile()).
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the local cache is not cleared once created). A cancellation token can be created via createCancelToken.
A design object which can be used for retrieving data from the design version using the API.
Returns a complete list of versions of the design.
Data of the design versions themselves are not downloaded at this point. Each item in the design version list can be expanded to a full-featured design entity.
The design version list contains both processed and unprocessed design versions.
The API has to be configured when using this method.
Example:
const versionList = await design.getVersions()
const versionItem = versionList.find((version) => version.status === 'done')
// Expand the design version list item to a full design entity
const version = await versionItem.fetchDesign()
// Continue working with the processed design version
const versionArtboards = version.getArtboards()Parameters:
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected. A cancellation token can be created via createCancelToken.
An array of design list item objects which can be used for retrieving the design versions using the API.
Imports a local design file (Photoshop, Sketch, Xd, Illustrator) as a version of the design.
All versions of a design must originate from the same design file format.
The API has to be configured when using this method. This is also requires a file system (i.e. it is not available in the browser).
The design file is automatically uploaded to the API and local caching is established.
Example:
const version = await design.importVersionDesignFile('data.sketch')
console.log(version.sourceFilename) // == path.join(process.cwd(), 'data.sketch')
console.log(version.id) // == server-generated UUID
// Continue working with the processed design version
const versionArtboards = version.getArtboards()Parameters:
An absolute design file path or a path relative to the current working directory.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the design is not deleted from the server when the token is cancelled during processing; the server still finishes the processing but the SDK stops watching its progress and does not download the result). A cancellation token can be created via createCancelToken.
A design object which can be used for retrieving data from the design version using the API.
Imports a design file located at the specified URL as a version of the design.
All versions of a design must originate from the same design file format.
The API has to be configured when using this method.
The design file is not downloaded to the local environment but rather imported via the API directly. Once imported via the API, the design version behaves exactly like a design version fetched via getVersionById.
Example:
const version = await sdk.importVersionDesignLink('https://example.com/designs/data.sketch')
console.log(version.id) // == server-generated UUID
// Continue working with the processed design version
const versionArtboards = version.getArtboards()Parameters:
A design file URL.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the design is not deleted from the server when the token is cancelled during processing; the server still finishes the processing but the SDK stops watching its progress and does not download the result). A cancellation token can be created via createCancelToken.
A design object which can be used for retrieving data from the design version using the API.
Page Lookup Methods
Looks up the first artboard object matching the provided criteria.
Example:
const mobilePage = design.findPage({ name: /mobile/i })
const mobilePage = design.findPage((page) => /mobile/i.test(page.name))
const oneOfPages123 = design.findPage({ id: ['<ID1>', '<ID2>', '<ID3>'] })Parameters:
A page selector. All specified fields must be matched by the result.
A page object.
Looks up all artboard objects matching the provided criteria.
Example:
const mobilePages = design.findPages({ name: /mobile/i })
const mobilePages = design.findPages((page) => /mobile/i.test(page.name))
const pages123 = design.findPages({ id: ['<ID1>', '<ID2>', '<ID3>'] })Parameters:
A page selector. All specified fields must be matched by the results.
A page list.
Returns a single page object. These can be used to work with the page contents and contents of artboards inside the page.
Example:
const page = design.getPageById('<PAGE_ID>')Returns a complete list of page object in the design. These can be used to work with artboard contents.
An empty list is returned for unpaged designs.
Example:
const pages = design.getPages()Returns info about whether the design is paged (i.e. has artboards organized on different pages).
Example:
const shouldRenderPageList = design.isPaged()Serialization Methods
Downloads the design file of the specified format produced by a server-side design file export.
In case no such export has been done for the design yet, a new export is initiated and the resulting design file is downloaded.
Example:
Export a Figma design as a Sketch design file (the only supported conversion)
await design.exportDesignFile('./exports/design.sketch')Parameters:
An absolute path to which to save the design file or a path relative to the current working directory.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. a partially downloaded file is not deleted). A cancellation token can be created via createCancelToken.
Returns info about a design file of the specified format produced by a server-side design file format export.
In case no such export has been done for the design yet, a new export is initiated and the resulting design file info is then returned.
Example:
// Initiate/fetch an export of a Figma design to the Sketch format (the only supported conversion)
const export = await design.getExportToFormat('sketch')
// Optional step to get lower-level info
const url = await export.getResultUrl()
console.log('Downloading export:', url)
// Download the exported Sketch design file
await export.exportDesignFile('./exports/design.sketch')Parameters:
The format to which the design should be exported.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected. A cancellation token can be created via createCancelToken.
A design export object.
Status Methods
Releases all loaded data of the design from memory. The design object is no longer usable after this.
If it is only desired to clean loaded data from memory while keeping the object usable, call unload instead.
Releases all loaded data of the design from memory. The design object can be used for loading the data again later.
Releases data related to the specified artboard from memory.
Parameters:
The ID of the artboard to unload.
Was this article helpful?