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

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 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, the package declares the name headroom-ai and exposes these key components:

• 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 – Documentation mirroring the installation steps found in the repository's 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:

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:

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

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:

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:

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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}