# 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.
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.
{% 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" %}
{
"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"
}
}
{% endtab %}
{% tab title="with JavaScript" %}
{
"name": "specify-design-tokens-extractor",
"private": true,
"version": "1.0.0",
"description": "Extract design tokens from Specify repositories",
"type": "module",
"scripts": {
"extract": "node ./extract.js"
}
}
{% 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.
{% 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: '...' }, ...]
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.specifyapp.com/guides/specify-sdk-usage-101/getting-started.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.