> ## Documentation Index
> Fetch the complete documentation index at: https://docs.billingos.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the BillingOS SDK in your project.

## Install the packages

<CodeGroup>
  ```bash npm theme={null}
  npm install @billingos/sdk @tanstack/react-query
  ```

  ```bash pnpm theme={null}
  pnpm add @billingos/sdk @tanstack/react-query
  ```

  ```bash yarn theme={null}
  yarn add @billingos/sdk @tanstack/react-query
  ```
</CodeGroup>

| Package                 | Where it runs   | Purpose                                     |
| ----------------------- | --------------- | ------------------------------------------- |
| `@billingos/sdk`        | Browser (React) | UI components, hooks, client                |
| `@tanstack/react-query` | Browser (React) | Data fetching and caching (peer dependency) |

For server-side operations (session tokens, entitlements), install the Node SDK separately:

<CodeGroup>
  ```bash npm theme={null}
  npm install @billingos/node
  ```

  ```bash pnpm theme={null}
  pnpm add @billingos/node
  ```

  ```bash yarn theme={null}
  yarn add @billingos/node
  ```
</CodeGroup>

## Peer dependencies

The React SDK requires these peer dependencies:

```json theme={null}
{
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0",
  "@tanstack/react-query": "^5.0.0"
}
```

Most React projects already have `react` and `react-dom`. You just need to add `@tanstack/react-query` if you don't have it already.

## Requirements

* **React** 18.0 or later (React 19 supported)
* **Node.js** 18.0 or later (for the server SDK)

## Environment variables

Add your BillingOS secret key to your server environment:

```bash .env.local theme={null}
BILLINGOS_SECRET_KEY=sk_test_your_secret_key_here
```

<Warning>
  Your secret key starts with `sk_test_` (sandbox) or `sk_live_` (production). Never expose it in client-side code.
</Warning>

You can find your API keys in the [BillingOS Dashboard](https://app.billingos.com).

## Next step

Set up the [BillingOSProvider](/sdk/provider) to connect the SDK to your app.