Token Studio SDK

This is the official SDK for Tokens Studio.

View technical diagram which we created to showcase how the SDK & CLI work, how to create an API key, and how you can use the GraphQL Apollo Sandbox environment to play around with our API and run regular HTTP requests against it to query or mutate data.

Quickstart

Installation

npm install @tokens-studio/sdk

CLI

See help menu for usage of the CLI.

npx tokensstudio --help
npx tokensstudio setup --help
npx tokensstudio pull --help

Example pulling tokens into local filesystem, after having created and filled a .tokensstudio.json file in the current working directory through the setup command:

TOKENS_STUDIO_API_KEY=your_api_key npx tokensstudio setup
TOKENS_STUDIO_API_KEY=your_api_key npx tokensstudio pull

Note: if you don't pass an environment variable for the API key, the CLI will prompt you for it instead.

Which will pull the tokens from your configured org, project and branch, assuming the API key has read permissions to the tokensets in that project.

.tokensstudio.json Example

{
	"version": "2",
	"org": "1f15691a-1d96-4049-bd53-943c869ce827",
	"project": "bd5e89d5-96f3-441a-bf9c-6041d5eccebc",
	"branch": "main",
	"release": "",
	"output": "studio-export"
}

Host Configuration

You can configure the GraphQL host URL in your .tokensstudio.json config file to avoid specifying --host on every command. This is useful for local development or custom Studio instances.

{
	"version": "2",
	"org": "1f15691a-1d96-4049-bd53-943c869ce827",
	"project": "bd5e89d5-96f3-441a-bf9c-6041d5eccebc",
	"branch": "main",
	"release": "",
	"output": "studio-export",
	"host": "graphql.app.prod.tokens.studio"
}

Precedence order: The --host command-line flag takes precedence over the config file host, which takes precedence over the default host (graphql.prod.tokens.studio).

Examples:

# Uses host from config file
npx tokensstudio pull

# Overrides config file host with command-line flag
npx tokensstudio pull --host graphql.app.prod.tokens.studio

Releases

When you have created a release for your project, you can specify the release property to pull tokens and executable Style Dictionary JavaScript file from that specific release. Running this with NodeJS will build the platform outputs for you.

{
	"version": "2",
	"org": "1f15691a-1d96-4049-bd53-943c869ce827",
	"project": "bd5e89d5-96f3-441a-bf9c-6041d5eccebc",
	"branch": "main",
	"release": "^1.0.0",
	"output": "studio-export"
}

You have a couple of options here:

• A SemVer version, which will pull from that specific version -> e.g. "1.0.0"
• A SemVer version range (using NPM SemVer implementation), which will pull the release with the version that is the highest satisfyable version in the specified range. -> e.g. "^1.0.0"
• "latest", which will pull from the latest release. It does a SemVer sort

See NPM SemVer for more information. We use this module internally for resolving a range or "latest" to a version.

Local backend

For Studio devs that run the Studio App backend locally:

npx tokensstudio pull --host localhost:4200 --insecure

If your API key was created through seeding rather than in the frontend app itself, ensure you associate the key with the correct user in the database (e.g through Prisma Studio).

Contributing

When running tests, ensure that you run the build step first because the tests run the compiled CLI directly as a way to test end to end.

Underlying GraphQL documentation

See the documentation for the GraphQL API here.

Documentation

You can generate the GraphQL documentation locally with the following command (from the sdk directory). We're using SpectaQL to generate the docs.

npm run docs:graphql

You can then view them by running open docs/graphql/index.html

We'll publish those docs once we figure out how to host them nicely.

The old documentation is available on this documentation site.

ESM

This library is ESM by default. We do not compile to CommonJS.

Type secure

The entire library is built with TypeScript and provides multiple utilities to ensure type safety.

License

This repository is published under the MIT license.