Open Design

Class Sdk

Local Design File Usage Methods

importDesignFile
importDesignFile(filePath: string, options?: { cancelToken?: null | CancelToken }): Promise<DesignFacade>

Imports a local design file (Photoshop, Sketch, Xd, Illustrator).

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 is automatically uploaded to the API and local caching is established.

Example:

const design = await sdk.importDesignFile('data.sketch')
console.log(design.sourceFilename) // == path.join(process.cwd(), 'data.sketch')
console.log(design.id) // == server-generated UUID

// Continue working with the processed design
const artboards = design.getArtboards()

Parameters:

filePath: string

An absolute design file path or a path relative to the current working directory.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<DesignFacade>

A design object which can be used for retrieving data from the local design file using the API.

importDesignLink(url: string, options?: { cancelToken?: null | CancelToken; format?: "sketch" | "xd" | "photoshop" | "illustrator" }): Promise<DesignFacade>

Imports a design file located at the specified URL.

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 behaves exactly like a design fetched via fetchDesignById.

Example:

const design = await sdk.importDesignLink('https://example.com/designs/data.sketch')
console.log(design.id) // == server-generated UUID

// Continue working with the processed design
const artboards = design.getArtboards()

Parameters:

url: string

A design file URL.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionalformat?: "sketch" | "xd" | "photoshop" | "illustrator"

The format of the design file in case it cannot be inferred from the URL.

returns Promise<DesignFacade>

A design object which can be used for retrieving data from the local design file using the API.

Server Side Design File Usage Methods

fetchDesignById
fetchDesignById(designId: string, options?: { cancelToken?: null | CancelToken }): Promise<DesignFacade>

Fetches a previously imported 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 design = await sdk.fetchDesignById('<DESIGN_ID>')

// Continue working with the processed design
const artboards = design.getArtboards()

Parameters:

designId: string

An ID of a server-side design assigned during import (via importDesignFile(), openFigmaDesign() or convertFigmaDesign()).

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<DesignFacade>

A design object which can be used for retrieving data from the design using the API.

fetchDesignList
fetchDesignList(options?: { cancelToken?: null | CancelToken }): Promise<Array<DesignListItemFacade>>

Fetches the list of previously imported designs from the API.

Data of the designs themselves are not downloaded at this point. Each item in the design list can be expanded to a full-featured design entity.

The design list contains both processed and unprocessed designs.

The API has to be configured when using this method.

Example:

const designList = await sdk.fetchDesignList()
const designItem = designList.find((design) => design.name === 'My design')
// Expand the design list item to a full design entity
const design = await designItem.fetchDesign()
// Continue working with the processed design
const artboards = design.getArtboards()

Parameters:

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<Array<DesignListItemFacade>>

An array of design list item objects which can be used for retrieving the designs using the API.

Figma Design Usage Methods

convertFigmaDesign
convertFigmaDesign(params: { cancelToken?: null | CancelToken; designName?: null | string; exports: Array<{ format: "sketch" }>; figmaFileKey: string; figmaIds?: Array<string>; figmaToken: string }): Promise<DesignFacade>

Imports a Figma design while initiating an export to another design file format (currently only Sketch is available).

The API has to be configured when using this method. A file system has to be available for downloading the converted design file from the API but downloading the result is not a required step as it can be done later from another client.

The design is automatically imported by the API and local caching is established in case the local cache is configured.

Example:

const design = await sdk.importFigmaDesign({
  figmaToken: '<FIGMA_TOKEN>',
  figmaFileKey: 'abc',
  conversions: [
    { format: 'sketch' }
  ]
})

// Download the converted design file
await design.exportDesignFile('./design.sketch')

Parameters:

params:

Info about the Figma design

OptionalcancelToken?: null | CancelToken

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.

OptionaldesignName?: null | string

A name override for the design. The original Figma design name is used by default.

exports: Array<{ format: "sketch" }>

Design file export configurations. Only a single export to the "sketch" (Sketch) file format is available currently.

figmaFileKey: string

A Figma design "file key" from the design URL (i.e. abc from https://www.figma.com/file/abc/Sample-File).

OptionalfigmaIds?: Array<string>

A listing of Figma design frames to use.

figmaToken: string

A Figma access token generated in the "Personal access tokens" section of Figma account settings.

returns Promise<DesignFacade>

A design object which can be used for retrieving data from the Figma design or downloading the exported design file using the API.

importFigmaDesign
importFigmaDesign(params: { cancelToken?: null | CancelToken; designName?: null | string; figmaFileKey: string; figmaIds?: Array<string>; figmaToken: string }): Promise<DesignFacade>

Imports a Figma design.

The API has to be configured when using this method.

The design is automatically imported by the API and local caching is established.

Example:

const design = await sdk.importFigmaDesign({
  figmaToken: '<FIGMA_TOKEN>',
  figmaFileKey: 'abc',
})

console.log(design.id) // == server-generated UUID

// Continue working with the processed design
const artboards = design.getArtboards()

Parameters:

params:

Info about the Figma design

OptionalcancelToken?: null | CancelToken

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.

OptionaldesignName?: null | string

A name override for the design. The original Figma design name is used by default.

figmaFileKey: string

A Figma design "file key" from the design URL (i.e. abc from https://www.figma.com/file/abc/Sample-File).

OptionalfigmaIds?: Array<string>

A listing of Figma design frames to use.

figmaToken: string

A Figma access token generated in the "Personal access tokens" section of Figma account settings.

returns Promise<DesignFacade>

A design object which can be used for retrieving data from the Figma design using the API.

Utility Methods

createCancelToken
createCancelToken(): { cancel: (reason?: string | Error) => void; dispose: () => void; token: CancelToken }

This method is just an alias of createCancelToken.

Creates a cancellation token which can be used for aborting asynchronous operations of the SDK.

Most asynchronous methods accept a cancellation token (the returned token). The same cancellation token can be used for multiple sequential as well as parallel operations. Finished operations no longer react to cancellations.

This mechanism is analogous to the standard AbortSignal/AbortController API with the difference that a cancellation reason can be specified. The created tokens are also somehow compatible with the standard API by exposing the standard AbortSignal as token.signal, just as it is possible to create a CancelToken from an AbortSignal via createCancelToken.fromSignal().

Example:

const controller = sdk.createCancelToken()

sdk.fetchDesignById('<ID>', { cancelToken: controller.token })
  .then((design) => {
    doStuffWithDesign(design)
    controller.dispose()
  })
  .catch((err) => {
    if (err.code !== 'OperationCancelled') { throw err }
  })

setTimeout(() => {
  controller.cancel('Timed out.')
}, 2000)
returns { cancel: (reason?: string | Error) => void; dispose: () => void; token: CancelToken }

Configuration Methods

getWorkingDirectory
getWorkingDirectory(): null | string

Returns the current "working directory" which is used for storing the local cache and temporary files.

The SDK creates and reads from a .opendesign subdirectory within the working directory.

Note that the .opendesign subdirectory should likely not be included in version control systems.

Example:

Default directory (the process working directory)

sdk.getWorkingDirectory() // == process.cwd()

Custom directory (relative path to the process working directory)

sdk.setWorkingDirectory('data')
sdk.getWorkingDirectory() // == path.join(process.cwd(), 'data')

Custom directory (absolute path)

sdk.setWorkingDirectory('/tmp/data')
sdk.getWorkingDirectory() // == '/tmp/data'
returns null | string
setGlobalFallbackFonts
setGlobalFallbackFonts(fallbackFonts: Array<string>): void

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 can be overriden/extended for each individual design via setFallbackFonts. Fonts provided to an individual design are preferred over fonts specified here.

Example:

Set preferred fallback fonts

sdk.setFallbackFonts(['Arial', 'Courier-Bold'])

Parameters:

fallbackFonts: Array<string>

An ordered list of font postscript names or font file paths.

returns void
setGlobalFontDirectory
setGlobalFontDirectory(fontDirectoryPath: null | string): void

Sets the directory where fonts should be looked up when rendering the design.

This configuration can be overriden/extended for each individual design via setFontDirectory.

Parameters:

fontDirectoryPath: null | string

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 global configuration is cleared.

returns void
setWorkingDirectory
setWorkingDirectory(workingDirectory: null | string): void

Sets the "working directory" which is used for storing the local cache and temporary files.

The SDK creates and reads from a .opendesign subdirectory within the working directory.

Note that the .opendesign subdirectory should likely not be included in version control systems.

Example:

Custom directory (absolute path)

sdk.setWorkingDirectory('/tmp/data')
sdk.getWorkingDirectory() // == '/tmp/data'

Reset to the default directory (the process working directory)

sdk.setWorkingDirectory(null)
sdk.getWorkingDirectory() // == process.cwd()

Parameters:

workingDirectory: null | string

An absolute path to the directory or a path relative to the process working directory (process.cwd() in node.js). When null is provided, the working directory is reset to the process working directory.

returns void

Status Methods

destroy
destroy(): Promise<void>

Destroys the SDK instance.

The local rendering engine process is terminated if it has been configured.

Any design objects created by the SDK are no longer usable and the user should dispose any references to such objects to prevent memory leaks.

Example:

sdk.destroy()

sdk.importDesignFile('./design.sketch') // throws
returns Promise<void>
isDestroyed
isDestroyed(): boolean

Returns whether the SDK has been destroyed.

returns boolean