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:
Workspace / Design System / Version and Brand (Default) selection experience
Here is how you can obtain each level of the access using the SDK:
// Fetch current user
const me = await sdk.me.me()
// Fetch all available workspaces
const workspaces = await sdk.workspaces.workspaces(me.id)
const firstWorkspace = workspaces[0]
// Fetch all available design systems from the first design system
const designSystems = await sdk.designSystems.designSystems(firstWorkspace.id)
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(firstDesignSystem.id)
// Fetch all brands in the version
const brands = await sdk.brands.getBrands({
designSystemId: firstDesignSystem.id,
versionId: draftVersion.id,
})
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
newColorToken.name = "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, rootColorGroup.id)
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!