# How to Install headroom.js: The Complete TypeScript/JavaScript SDK Setup Guide

> Install headroom.js easily with npm and set up essential environment variables for seamless integration. Get started with this quick TypeScript/JavaScript SDK guide.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: getting-started
- Published: 2026-06-17

---

**Install headroom.js by running `npm install headroom-ai` and configure the `HEADROOM_BASE_URL` and `HEADROOM_API_KEY` environment variables to connect to your Headroom proxy or Cloud service.**

The [`headroom.js`](https://github.com/chopratejas/headroom/blob/main/headroom.js) SDK—maintained in the `chopratejas/headroom` repository—provides a lightweight HTTP client that forwards compression requests to the Headroom proxy. This guide explains exactly what happens during installation and how to configure the SDK to start saving tokens immediately.

## What Gets Installed with headroom.js

When you execute `npm install headroom-ai`, npm pulls the package from the public registry and installs a **dependency-free** TypeScript/JavaScript SDK. The installation is fast because the client performs no local compression; all heavy processing runs in the Headroom proxy (Python/Rust) or Headroom Cloud.

### Core Package Structure

According to the source code in [`sdk/typescript/package.json`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/package.json), the package declares the name `headroom-ai` and exposes these key components:

- **[`sdk/typescript/src/compress.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/compress.ts)** – Contains the `compress()` function that forwards requests to the proxy's `POST /v1/compress` endpoint.
- **`sdk/typescript/src/adapters/`** – Optional adapters for OpenAI, Anthropic, and Vercel AI that convert SDK-specific formats to the OpenAI-compatible shape expected by the proxy.
- **[`wiki/typescript-sdk.md`](https://github.com/chopratejas/headroom/blob/main/wiki/typescript-sdk.md)** – Documentation mirroring the installation steps found in the repository's [`README.md`](https://github.com/chopratejas/headroom/blob/main/README.md).

## Step-by-Step Installation Guide

### Prerequisites

Before installing headroom.js, you need either:

1. A running Headroom proxy (started via `headroom proxy …`), or
2. A valid Headroom Cloud API key.

### Install the Package

Run the installation command in your project root:

```bash
npm install headroom-ai

```

This command resolves the package from the npm registry and places the source files in your `node_modules/headroom-ai/` directory. The SDK is designed to work in any Node environment, including serverless platforms and browsers (via bundlers), because it ships no native binaries.

### Configure Environment Variables

The SDK reads configuration at runtime. Create a `.env` file or export these variables in your shell:

```bash
export HEADROOM_BASE_URL=http://localhost:8787   # Your proxy address

export HEADROOM_API_KEY=hr_…                     # Required for Cloud, optional for local proxy

```

Alternatively, pass these values directly to the `compress()` function or adapter constructors.

## Verifying Your Installation

Test the installation by importing the `compress` function from `headroom-ai` and sending a request to your configured proxy.

### Basic Compression Example

```typescript
import { compress } from 'headroom-ai';

const messages = [
  { role: 'user', content: 'Explain the difference between TCP and UDP.' },
];

async function run() {
  const result = await compress(messages, { model: 'gpt-4o' });
  console.log(`Saved ${result.tokensSaved} tokens`);
  // result.messages contains the compressed payload ready for your LLM provider
}
run();

```

### Using the OpenAI Adapter

If you use the OpenAI SDK, import the `withHeadroom` wrapper from `headroom-ai/openai` to automatically compress requests:

```typescript
import { withHeadroom } from 'headroom-ai/openai';
import OpenAI from 'openai';

const client = withHeadroom(new OpenAI());

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'Write a concise summary of the latest RFC 9000.' },
  ],
});
console.log(response.choices[0].message.content);

```

### Fallback Configuration

Enable fallback mode to ensure your application continues working if the proxy is unreachable:

```typescript
const result = await compress(messages, {
  model: 'gpt-4o',
  fallback: true,   // Returns uncompressed messages on error
});

```

## Summary

- **Install headroom.js** using `npm install headroom-ai` to get the dependency-free TypeScript SDK.
- The SDK consists of a thin HTTP client in [`sdk/typescript/src/compress.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/compress.ts) that requires a running Headroom proxy or Cloud API key.
- Configure the connection using `HEADROOM_BASE_URL` and `HEADROOM_API_KEY` environment variables or constructor options.
- Optional adapters in `sdk/typescript/src/adapters/` provide drop-in integration with OpenAI, Anthropic, and Vercel AI SDKs.
- The package works in Node.js, serverless environments, and browsers without additional binaries.

## Frequently Asked Questions

### What is the exact npm package name for headroom.js?

The package is published as **`headroom-ai`** in the npm registry, as defined in [`sdk/typescript/package.json`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/package.json). Do not install `headroom` (which is a different library); use `npm install headroom-ai` specifically.

### Do I need to install the Headroom proxy locally to use headroom.js?

No, you can use headroom.js with **Headroom Cloud** by setting `HEADROOM_API_KEY` to your Cloud key and pointing `HEADROOM_BASE_URL` to the Cloud endpoint. Local proxy installation is only required if you want to self-host the compression service.

### Can I use headroom.js without environment variables?

Yes. While the SDK automatically reads `HEADROOM_BASE_URL` and `HEADROOM_API_KEY` from the environment, you can pass `baseUrl` and `apiKey` explicitly in the options object when calling `compress()` or initializing adapters.

### Is headroom.js compatible with browser environments?

Yes. Because the SDK is dependency-free and contains only TypeScript/JavaScript source files (no native binaries), it bundles correctly with Vite, Webpack, or Rollup for browser deployment. Ensure your bundler handles the `HEADROOM_BASE_URL` configuration at build time or runtime.