Basics of using the SDK

Dive into hands-on examples that demonstrate the SDK's capabilies.

Let's illustrate how fast it is to start building experiences with Supernova SDK. You can do all data manipulation in and out of Supernova, and through the main Supernova SDK object.

Obtain an SDK instance

To obtain an SDK instance, simply create a new Supernova instance:

                                                            import { Supernova } from "@supernovaio/sdk"
                                                        const sdk = new Supernova(apiKey)

Both OAuth Bearer token or personal access token are allowed. With this SDK object, you can now start reading and writing data at will.

Read workspace structure

Most data requests require a design system or version to fetch from to be specified. Supernova allows you access the workspaces, design systems, versions and brands. You will need to fetch this data to allow users to select which design system they want to work with.


Here is how you can obtain each level of the access using the SDK:

                                                            // Fetch current user
                                                        const me = await
                                                        // Fetch all available workspaces
                                                        const workspaces = await sdk.workspaces.workspaces(
                                                        const firstWorkspace = workspaces[0]
                                                        // Fetch all available design systems from the first design system
                                                        const designSystems = await sdk.designSystems.designSystems(
                                                        const firstDesignSystem = designSystems[0]
                                                        // Fetch draft version of the first design system. Draft version is the only write-enabled version.
                                                        const draftVersion = await sdk.versions.getActiveVersion(
                                                        // Fetch all brands in the version
                                                        const brands = await sdk.brands.getBrands({

This code allows you to very quickly get to the default workspace/design system users visit when logging into Supernova Cloud.

Read design system data

Once you've selected the design system, version, and potentially the brand, you can start fetching the data from your design system. Here are some examples to help you get started.

To retrieve all tokens:

                                                            const tokens = await sdk.tokens.getTokens({
                                                          designSystemId: designSystemId,
                                                          versionId: versionId,
                                                          type: TokenType.color, // Optionally filter by specific token type
                                                          brandId: brandId, // Optionally filter by specific brand

To retrieve all token themes:

                                                            const themes = await sdk.tokens.getTokenThemes({
                                                          designSystemId: designSystemId,
                                                          versionId: versionId,

To retrieve all token groups:

                                                            const groups = await sdk.tokens.getTokenGroups({
                                                          designSystemId: designSystemId,
                                                          versionId: versionId,

To retrieve all components:

                                                            const components = await sdk.components.getComponents({
                                                          designSystemId: designSystemId,
                                                          versionId: versionId,

To retrieve all assets:

                                                            const assets = await sdk.assets.getAssets({
                                                          designSystemId: designSystemId,
                                                          versionId: versionId,

And so on! SDK is structured into logical sections, so just type what you feel would be appropriate — you'll likely get it right on the first try :)

Modify design system data

Modifying the data is straightforward as well — it just requires a little bit more setup in terms of creating the data, as our system will prioritize data integrity above all else and reject anything that doesn't fit the required input.

Fortunately, we have created tons of helpers so you don't have to write too much code yourself, for example, to write new tokens into the system:

                                                            // Fetch all the groups from tokens
                                                        const allGroups = await sdk.tokens.getTokenGroups({
                                                          designSystemId: designSystemId,
                                                          versionId: versionId,
                                                        // Find the root color group - we'll put the new token there. It always exists, for all token types
                                                        const rootColorGroup = allGroups.find((group) => group.isRoot === true && group.tokenType === TokenType.color)!
                                                        // Create new color token locally
                                                        let newColorToken = await sdk.tokens.createLocalToken(TokenType.color, versionId, brandId, [])
                                                        // Update token directly
                                               = "white"
                                                        // Or use dozens of helpers from TokenUtils to update the token
                                                        newColorToken = TokenUtils.colorTokenByUpdatingColor(newColorToken, {
                                                          r: 255,
                                                          g: 255,
                                                          b: 255,
                                                        // Write the token to server
                                                        await sdk.tokens.createToken({
                                                          designSystemId: designSystemId,
                                                          versionId: versionId,
                                                        }, newColorToken,

Explore all options

This introduction page serves as high-level overview how you work with the SDK — but barely scratches the surface of its true capabilities. Consult our SDK Reference guide to learn all there is!