# Install the SDK (/sdk/installation)



This page shows how to install and configure the SDK. What it covers is in the
[SDK overview](/sdk).

## Before you start [#before-you-start]

* Node.js 18.18.2 or later (`node --version`).
* A personal access token: `acc pat create --name my-app`. Copy it; it is
  shown once. See [Create and use access tokens](/guides/api-keys).
* A project id: `acc projects list`.

## 1. Install [#1-install]

<Tabs items="[&#x22;npm&#x22;,&#x22;pnpm&#x22;,&#x22;yarn&#x22;]">
  <Tab value="npm">
    ```bash
    npm install @alternatefutures/sdk
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @alternatefutures/sdk
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @alternatefutures/sdk
    ```
  </Tab>
</Tabs>

## 2. Configure [#2-configure]

Put the token and the project id in `.env`, and add `.env` to `.gitignore`:

```bash
# .env
AF_TOKEN=...          # your personal access token
AF_PROJECT_ID=...     # from acc projects list
```

No endpoint configuration is needed. The published package (0.2.4) targets
`https://api.alternatefutures.ai/graphql`, the API that runs today, for both
the token exchange and every query.

## 3. Construct the SDK [#3-construct-the-sdk]

Import from the package root, on Node as well as in the browser. The token
service takes the token and the project.

```typescript
import 'dotenv/config';
import { AlternateFuturesSdk, PersonalAccessTokenService } from '@alternatefutures/sdk';

const sdk = new AlternateFuturesSdk({
  accessTokenService: new PersonalAccessTokenService({
    personalAccessToken: process.env.AF_TOKEN!,
    projectId: process.env.AF_PROJECT_ID!,
  }),
});
```

The package also lists a `@alternatefutures/sdk/node` entry point. In 0.2.4 it
does not load under Node (see Troubleshooting), so use the root import.

To talk to another API host, for example a staging deployment, pass
`graphqlServiceApiUrl` to both constructors:

```typescript
const graphqlServiceApiUrl = 'https://api.alternatefutures.ai/graphql';

const sdk = new AlternateFuturesSdk({
  graphqlServiceApiUrl,
  accessTokenService: new PersonalAccessTokenService({
    personalAccessToken: process.env.AF_TOKEN!,
    projectId: process.env.AF_PROJECT_ID!,
    graphqlServiceApiUrl,
  }),
});
```

## 4. Verify [#4-verify]

```typescript
const projects = await sdk.projects().list();
console.log(projects.map((p) => p.name));
```

A list of your project names means the token, the project, and the endpoint
are all right.

## Troubleshooting [#troubleshooting]

* **`ERR_PACKAGE_PATH_NOT_EXPORTED` naming `files-from-path`** when importing
  `@alternatefutures/sdk/node`. That entry point's CommonJS bundle requires an
  ESM-only dependency and fails on every Node version. Import from
  `@alternatefutures/sdk` instead.
* **`UnknownError: Unexpected error. Repeat the action or contact support.`**
  The SDK reports every API error this way, including a wrong, revoked, or
  out-of-project token. Check the token with `acc pat list` and the project
  with `acc projects list`. The API's own message is not passed through;
  [Handle errors](/sdk/quickstart#handle-errors) shows how to get it with
  `curl`.
* **`SdkRequiredNodeRuntimeError`.** A legacy Node-only client was called.
  Those clients are retired; see the [overview](/sdk).

## Next steps [#next-steps]

* [SDK quick start](/sdk/quickstart)
* [SDK API reference](/sdk/api)