# Getting Started

> Get started with the Context7 TypeScript SDK

<Warning>
  **Work in Progress**: This SDK is currently under active development. The API is subject to change and may introduce breaking changes in future releases.
</Warning>

# Getting Started

`@upstash/context7-sdk` is a TypeScript SDK for Context7, enabling easier access to library documentation with full type coverage.

Using `@upstash/context7-sdk` you can:

- Search across available libraries
- Get documentation context for any library
- Access library metadata including trust scores and versions

You can find the Github Repository [here](https://github.com/upstash/context7/tree/master/packages/sdk).

## Install

<CodeGroup>
  ```shell npm
  npm install @upstash/context7-sdk
  ```

```shell pnpm
pnpm add @upstash/context7-sdk
```

```shell yarn
yarn add @upstash/context7-sdk
```

```shell bun
bun add @upstash/context7-sdk
```

</CodeGroup>

## Usage

### Initializing the Client

To use the Context7 SDK, you need an API key. You can get your API key from the [Context7 Dashboard](https://context7.com/dashboard).

#### Using environment variables

The SDK automatically reads from environment variables if no API key is provided in the config:

```bash
CONTEXT7_API_KEY="your_api_key_here"
```

When an environment variable is set, you can initialize the client without any parameters:

```typescript
import { Context7 } from "@upstash/context7-sdk";

const client = new Context7();
```

#### Using a configuration object

If you prefer to pass configuration in code, the constructor accepts a config object containing the apiKey value. This could be useful if your application needs to interact with multiple projects, each with a different configuration.

```typescript
import { Context7 } from "@upstash/context7-sdk";

const client = new Context7({
  apiKey: "YOUR_API_KEY",
});
```

<Note>
  The SDK checks for API keys in this order: 1. `config.apiKey` (if provided) 2.
  `process.env.CONTEXT7_API_KEY`
</Note>

#### Production HTTP configuration

The SDK applies a 30-second request timeout and retries transient network failures, `408`, `425`,
`429`, and `5xx` responses. Only `GET` requests are retried; mutating requests remain
single-attempt.

```typescript
const client = new Context7({
  apiKey: "YOUR_API_KEY",
  timeout: 10_000,
  retry: {
    retries: 3,
    backoff: (attempt) => 100 * 2 ** attempt,
  },
  onResponse: ({ status, requestId, rateLimit, attempt }) => {
    console.log({ status, requestId, rateLimit, attempt });
  },
});
```

You can also configure `baseUrl`, additional `headers`, `keepAlive`, the native fetch `cache` mode,
a client-wide abort `signal`, or a custom `fetch` implementation. The SDK always sets
`Authorization` from the configured API key; additional headers cannot override it.

Following the same convention as `@upstash/redis`, a signal factory can provide a fresh timeout
signal for each request:

```typescript
const client = new Context7({
  apiKey: "YOUR_API_KEY",
  signal: () => AbortSignal.timeout(10_000),
});
```

Set `retry: false` to make exactly one request or `timeout: false` to disable the default timeout.

## Quick Start Example

```typescript
import { Context7 } from "@upstash/context7-sdk";

const client = new Context7();

// Search for libraries
const libraries = await client.searchLibrary(
  "I need to build a UI with components",
  "react"
);
console.log(`Found ${libraries.length} libraries`);
console.log(libraries[0].id); // "/facebook/react"

// Get documentation as JSON array (default)
const docs = await client.getContext(
  "How do I use hooks?",
  "/facebook/react"
);
console.log(docs[0].title, docs[0].content);

// Get documentation context as plain text
const context = await client.getContext("How do I use hooks?", "/facebook/react", {
  type: "txt",
  timeout: 5_000,
});
console.log(context);
```

## Error Handling

The SDK throws `Context7Error` for API errors:

```typescript
import { Context7, Context7Error } from "@upstash/context7-sdk";

const client = new Context7();

try {
  const context = await client.getContext("query", "/invalid/library");
} catch (error) {
  if (error instanceof Context7Error) {
    console.error("Context7 API Error:", {
      message: error.message,
      code: error.code,
      status: error.status,
      requestId: error.requestId,
      rateLimit: error.rateLimit,
      retryable: error.retryable,
    });
  } else {
    console.error("Unexpected error:", error);
  }
}
```

## Next Steps

Explore the SDK commands:

- [Search Library](/sdks/ts/commands/search-library) - Search for libraries
- [Get Context](/sdks/ts/commands/get-context) - Retrieve library documentation context