Getting started

Getting started with the Specify SDK.

Prerequisites

• NodeJS >= 18.x

• [Optional] Typescript >= 4.9

TypeScript vs JavaScript

We recommend using TypeScript for a better developer experience. TypeScript's autocompletion in your editor can save you numerous trips to the documentation by suggesting methods and options from the Specify APIs.

Installation

Let's pretend you have a front-end application structured as follows:

my-app/
    src/
        components/
            ...
        index.ts
    public/
    package.json
    ...

Create a specify directory

You'll start by creating a specify directory at the application level.

my-app/
    specify/
        ...
    src/
        components/
            ...
        index.ts
    public/
    package.json
    ...

Initialize a JavaScript module

Using your terminal, navigate to the directory.

cd ./specify

Within this directory, you initialize a JavaScript module by using the package manager of your choice - preferably the one you use to manage your application.

npm

npm init
npm install -D @specifyapp/sdk dotenv typescript

Yarn

pnpm

If you use vanilla JavaScript, you can skip the installation of the typescript package.

The init command creates a minimal package.json file where the dev dependencies will be added too. Then, you complete/override the content to match the following:

with TypeScript

specify/package.json

{
  "name": "specify-design-tokens-extractor",
  "private": true,
  "version": "1.0.0",
  "description": "Extract design tokens from Specify repositories",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "extract": "tsc && node ./extract.js"
  }
}

with JavaScript

Note that "type": "module" is mandatory for the SDK to properly work.

Setup TypeScript

If you use vanilla JavaScript, you can skip this step.

Within the specify directory, you create a tsconfig.json file which matches the following configuration:

{
  "compilerOptions": {
    "strict": true,
    "target": "es2022",
    "lib": ["es2022"],
    "moduleDetection": "force",
    "module": "NodeNext",
    "sourceMap": true,
    "skipLibCheck": true,
    "outDir": ".",
    "rootDir": "./"
  },
  "include": ["./extract.ts"],
  "exclude": ["node_modules"]
}

Prepare the environment secrets

To interact with your Specify repositories you'll need to provide a Personal Access Token that you prefer to keep secret. For that reason, we recommend the use of the dotenv package.

Thus, create a .env file within the specify directory:

specify/.env

SPECIFY_PERSONAL_ACCESS_TOKEN=YOUR-PERSONAL-ACCESS-TOKEN

If you use a version control utility like git, you most likely want to add the specify/.env file to your ignore configuration.

Get a Personal Access Token from your user settings ↗︎

Create a Specify Client

Within the specify directory, you create an extract.ts file. This TypeScript script will handle the extraction process by utilizing the personal access token specified in your .env file.

specify/extract.ts

import { config } from "dotenv";
import { createSpecifyClient, updaters, parsers } from "@specifyapp/sdk";

// Load Personal Access Token from .env file
const { parsed } = config({ path: ".env" });

If you use vanilla JavaScript, you can name this file extract.js.

Authenticate

In order to consume the private data from a Specify repository, you must authenticate using your personal access token stored in .env.

specify/extract.ts

// Initialize Specify Client
const specifyClient = createSpecifyClient();
await specifyClient.authenticate(parsed?.SPECIFY_PERSONAL_ACCESS_TOKEN || "");

console.log(`User authenticated: ${specifyClient.whoAmI()?.email}`);

Test your script

From your terminal, launch the script.

npm

npm run extract

Yarn

pnpm

You should get a log such as:

User authenticated: [email protected]

Your configuration does not run? Get in touch with us on Discord.

List your organization repositories

Get a list of repositories belonging to your organization.

const repositories = await specifyClient.getRepositories();

console.log(repositories); // [{ id: '...', name: '...' }, ...]