Specify CLI VS Specify SDK

TL;DR - The CLI is faster to get started, but the SDK is more flexible and can match exactly what you need

Historically, if you wanted to convert your tokens to various outputs: CSS, Swift, Typescript... you could only distribute your tokens thanks to a configuration file. With the introduction of the SDK, you might want to know which option suits your needs, so let's compare them!

This page will be an overview of both options, so if you need more details, you can have look to the Specify CLI page, and the Specify SDK page.

Overview

	Specify CLI	Specify SDK
Running parsers remotely	✅	✅
Running parsers locally	❌	✅
Update the tokens	✅	✅
Filter the tokens	✅	✅
Converting a token to a specific format	❌	✅
Create a custom output	❌	✅

Setup

CLI

In the case of the CLI, you'll first need to install the CLI:

NPM

npm install @specifyapp/cli 

Yarn

yarn global add @specifyapp/cli

And then create a .specifyrc.json :

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": []
}

SDK

For the SDK, you'll first want to install the dependencies of the SDK, and the SDTF:

NPM

npm install -D @specifyapp/sdk1.0.0-beta.5 @specifyapp/specify-design-token-format

YARN

yarn install -D @specifyapp/sdk @specifyapp/sdtf

Then you, you have to create a file where we'll import all the installed dependencies:

specify.ts

import { createSpecifyClient } from '@specifyapp/sdk';

async function run() {
  const specifyClient = createSpecifyClient();

  await specifyClient.authenticate('<your-personal-access-token>');
  
  const sdtfClient = specifyClient.getSDTFClientByName('<repository-name>');
}

run()

Running a parser

CLI

We first need to fill up a bit the configuration file with the parser we want to run:

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Tokens as CSS Variables",
      "parsers": [
        {
          "name": "to-css-custom-properties",
          "output": {
            "type":"file",
            "filePath": "tokens.css"
          }
        }
      ]
    }
  ]
}

Then we can run everything through the CLI:

specify pull

SDK

On the SDK side, there's two way of doing it.

Running parsers locally

The main interest of the SDK is to be able to run everything locally. To do so, you can do the following:

import { createSpecifyClient, createSpecifyFileSystemHelper } from '@specifyapp/sdk';
import { toCssCustomProperties } from '@specifyapp/sdk/next';

async function run() {
  const specifyClient = createSpecifyClient();

  await specifyClient.authenticate('<your-personal-access-token>');
  
  const sdtfClient = specifyClient.getSDTFClientByName('<repository-name>');
  
  const generatorPipelineOutput = await sdtfClient.createParserPipeline(
    toCssCustomProperties({ filePath: 'myFile.css' }),
  );
  
  const fileSystemHelper = createSpecifyFileSystemHelper({ generatorPipelineOutput });
  
  await fileSystemHelper.writeToDisk('./rootFolder');
}

run()

There's actually a way to choose which parser runs locally, and which one runs remotely, you can learn more about it here.

Running parsers remotely

Running parsers remotely is basically wrapping the configuration into the SDK:

import { createSpecifyClient, createSpecifyFileSystemHelper } from '@specifyapp/sdk';

async function run() {
  const specifyClient = createSpecifyClient();

  await specifyClient.authenticate('<your-personal-access-token>');
  
  const sdtfClient = specifyClient.getSDTFClientByName('<repository-name>');
  
  const pipeEngineRuleResponseBody = await sdtfClient.transformWithRemoteParsers([
    {
      name: 'to-css-custom-properties',
      output: {type: 'file', filePath: 'tokens.css'},
    },
  ]);
  
  const fileSystemHelper = createSpecifyFileSystemHelper({
    pipeEngineRuleResponseBody
  });
  
  const writtenFiles = await fileSystemHelper.writeToDisk('./public');
}

run()

Filtering the tokens

CLI

To do so, we'll need to introduce a new parser in the configuration file:

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Tokens as CSS Variables",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "where": {
              "collection": "colors",
              "select": {
                "collection": true,
                "children": {
                  "tokens": true
                }
              }
            }
          }
        },
        {
          "name": "to-css-custom-properties",
          "output": {
            "type":"file",
            "filePath": "tokens.css"
          }
        }
      ]
    }
  ]
}

SDK

Because the SDK is loading the SDTF, we can work directly with it. No need to run a parser, we can just execute filtering methods, and then generate our tokens:

import { createSpecifyClient, createSpecifyFileSystemHelper } from '@specifyapp/sdk';
import { toCssCustomProperties } from '@specifyapp/sdk/next';

async function run() {
  const specifyClient = createSpecifyClient();

  await specifyClient.authenticate('<your-personal-access-token>');
  
  const sdtfClient = specifyClient.getSDTFClientByName('<repository-name>');
  
  const filteredGraph = sdtfClient.query({
    where: {
      collection: "colors",
      select: {
        collection: true,
        children: {
          tokens: true
        }
      }
    }
  });
  
  const generatorPipelineOutput = await filteredGraph
    .createParserPipeline(
      toCssCustomProperties({ filePath: 'myFile.css' }),
    )
    .execute();
  
  const fileSystemHelper = createSpecifyFileSystemHelper({ generatorPipelineOutput });
  
  await fileSystemHelper.writeToDisk('./rootFolder');
}

run()

Updating tokens

CLI

Just like before, it can be done through a parser:

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Tokens as CSS Variables",
      "parsers": [
        {
          "name": "convert-color",
          "options": {
            "toFormat": "hex"
          }
        },
        {
          "name": "to-css-custom-properties",
          "output": {
            "type":"file",
            "filePath": "tokens.css"
          }
        }
      ]
    }
  ]
}

SDK

Again, as the SDK is loading the SDTF, we can work directly with it through the update method and an updater:

import { createSpecifyClient, createSpecifyFileSystemHelper } from '@specifyapp/sdk';
import { toCssCustomProperties, updaters } from '@specifyapp/sdk/next';

async function run() {
  const specifyClient = createSpecifyClient();

  await specifyClient.authenticate('<your-personal-access-token>');
  
  const sdtfClient = specifyClient.getSDTFClientByName('<repository-name>');
  
  sdtfClient.update(
    updaters.color({ toFormat: 'hex' }, { where: { token: '^theme', select: true }})
  );
  
  const generatorPipelineOutput = await filteredGraph
    .createParserPipeline(
      toCssCustomProperties({ filePath: 'myFile.css' }),
    )
    .execute();
  
  const fileSystemHelper = createSpecifyFileSystemHelper({ generatorPipelineOutput });
  
  await fileSystemHelper.writeToDisk('./rootFolder');
}

run()

Converting a token to a specific format

CLI

This cannot be done with the CLI.

SDK

Here is an example of converting a token to CSS, more detals on the conversion can be found here.

import { createSpecifyClient } from '@specifyapp/sdk';
import {
  dimensionToCss,
  breakpointToCss,
  colorToCss,
  createResolveAliasStrategy 
} from '@specify/sdk/css'

async function run() {
  const specifyClient = createSpecifyClient();

  await specifyClient.authenticate('<your-personal-access-token>');
  
  const sdtfClient = specifyClient.getSDTFClientByName('<repository-name>');
  
  const strategy = createResolveAliasStrategy()

  const outputs = sdtfClient.mapTokenStates(tokenState => 
    tokenState.matchByType(
      {
        dimension: dimensionToCss(strategy) // Output example: '12px'
        breakpoint: breakpointToCss(strategy) // Output example: '12px'
        color: colorToCss(strategy) // Output example: '#ff00ff'
      }, 
      _ => undefined
    )
  )
}

run()