> For the complete documentation index, see [llms.txt](https://docs.specifyapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.specifyapp.com/guides/specify-sdk-usage-101/getting-started.md).

# Getting started

### 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.

<pre><code>my-app/
<strong>    specify/
</strong><strong>        ...
</strong>    src/
        components/
            ...
        index.ts
    public/
    package.json
    ...
</code></pre>

### 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.

{% tabs %}
{% tab title="npm" %}

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

{% endtab %}

{% tab title="Yarn" %}

```bash
yarn init
npm add -D @specifyapp/sdk dotenv typescript
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm init
pnpm add -D @specifyapp/sdk dotenv typescript
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
If you use vanilla JavaScript, you can skip the installation of the `typescript` package.
{% endhint %}

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:

{% tabs %}
{% tab title="with TypeScript" %}

<pre class="language-json" data-title="specify/package.json"><code class="lang-json">{
  "name": "specify-design-tokens-extractor",
<strong>  "private": true,
</strong>  "version": "1.0.0",
  "description": "Extract design tokens from Specify repositories",
<strong>  "type": "module",
</strong><strong>  "scripts": {
</strong><strong>    "build": "tsc",
</strong><strong>    "extract": "tsc &#x26;&#x26; node ./extract.js"
</strong><strong>  }
</strong>}
</code></pre>

{% endtab %}

{% tab title="with JavaScript" %}

<pre class="language-json" data-title="specify/package.json"><code class="lang-json">{
  "name": "specify-design-tokens-extractor",
<strong>  "private": true,
</strong>  "version": "1.0.0",
  "description": "Extract design tokens from Specify repositories",
<strong>  "type": "module",
</strong><strong>  "scripts": {
</strong><strong>    "extract": "node ./extract.js"
</strong><strong>  }
</strong>}
</code></pre>

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Note that `"type": "module"` is mandatory for the SDK to properly work.
{% endhint %}

### Setup TypeScript

{% hint style="info" %}
If you use vanilla JavaScript, you can skip this step.
{% endhint %}

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

```json5
{
  "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](https://github.com/motdotla/dotenv) package.

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

{% code title="specify/.env" %}

```
SPECIFY_PERSONAL_ACCESS_TOKEN=YOUR-PERSONAL-ACCESS-TOKEN
```

{% endcode %}

{% hint style="warning" %}
If you use a version control utility like git, you most likely want to add the `specify/.env` file to your ignore configuration.
{% endhint %}

{% hint style="info" %}
Get a Personal Access Token from [your user settings ↗︎](https://specifyapp.com/user/personal-access-tokens)
{% endhint %}

### 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.&#x20;

{% code title="specify/extract.ts" %}

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

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

{% endcode %}

{% hint style="info" %}
If you use vanilla JavaScript, you can name this file `extract.js`.
{% endhint %}

### Authenticate

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

{% code title="specify/extract.ts" %}

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

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

{% endcode %}

### Test your script

From your terminal, launch the script.

{% tabs %}
{% tab title="npm" %}

```bash
npm run extract
```

{% endtab %}

{% tab title="Yarn" %}

```bash
yarn extract
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm run extract
```

{% endtab %}
{% endtabs %}

You should get a log such as:

```
User authenticated: your-user@your-company.com
```

{% hint style="info" %}
Your configuration does not run? Get in touch with us on [Discord](https://discord.gg/yRgTDgUp).
{% endhint %}

## List your organization repositories

Get a list of repositories belonging to your organization.

```typescript
const repositories = await specifyClient.getRepositories();

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