Skip to main content
Install the Upstash Redis SDK for your platform using your preferred package manager.

​
Package managers

npm install @upstash/redis

​
Platform-specific imports

The SDK provides optimized entry points for different platforms. Choose the right import for your environment.

​
Node.js

The default export is optimized for Node.js: 
import { Redis } from '@upstash/redis';

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
});
Supports Node.js 14 and above. The SDK automatically detects your Node.js version and adjusts accordingly.

​
Cloudflare Workers

Use the Cloudflare-specific import for Workers: 
import { Redis } from '@upstash/redis/cloudflare';

export interface Env {
  UPSTASH_REDIS_REST_URL: string;
  UPSTASH_REDIS_REST_TOKEN: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const redis = Redis.fromEnv(env);
    
    const count = await redis.incr('counter');
    return new Response(JSON.stringify({ count }));
  },
};
The Cloudflare import is optimized for Workers and removes Node.js-specific code for smaller bundle sizes.

​
Fastly Compute@Edge

Use the Fastly-specific import: 
import { Redis } from '@upstash/redis/fastly';

const redis = new Redis({
  url: 'your_upstash_redis_rest_url',
  token: 'your_upstash_redis_rest_token',
});

const result = await redis.get('key');

​
Deno

Import directly from esm.sh: 
import { Redis } from 'https://esm.sh/@upstash/redis';

const redis = new Redis({
  url: Deno.env.get('UPSTASH_REDIS_REST_URL')!,
  token: Deno.env.get('UPSTASH_REDIS_REST_TOKEN')!,
});

const value = await redis.get('key');
Alternatively, use deno.land/x: 
import { Redis } from 'https://deno.land/x/upstash_redis/mod.ts';

​
Environment variables

The SDK automatically reads credentials from environment variables when using Redis.fromEnv().

​
Standard environment variables

Set these variables in your .env file:
.env
UPSTASH_REDIS_REST_URL="https://your-redis-url.upstash.io"
UPSTASH_REDIS_REST_TOKEN="your_token_here"

​
Vercel KV compatibility

The SDK also supports Vercel KV environment variable names:
.env
KV_REST_API_URL="https://your-redis-url.upstash.io"
KV_REST_API_TOKEN="your_token_here"
If both sets of variables are present, UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN take precedence.

​
Using fromEnv()

import { Redis } from '@upstash/redis';

// Automatically reads from process.env
const redis = Redis.fromEnv();

​
Configuration options

When creating a Redis client, you can configure various options: 
interface RedisConfigNodejs {
  /**
   * UPSTASH_REDIS_REST_URL
   */
  url: string;
  
  /**
   * UPSTASH_REDIS_REST_TOKEN
   */
  token: string;
  
  /**
   * Enable automatic pipelining to batch commands
   * @default true
   */
  enableAutoPipelining?: boolean;
  
  /**
   * Enable read-your-writes consistency
   * @default false
   */
  readYourWrites?: boolean;
  
  /**
   * Automatically deserialize JSON responses
   * @default true
   */
  automaticDeserialization?: boolean;
  
  /**
   * Enable telemetry for analytics
   * @default true
   */
  enableTelemetry?: boolean;
  
  /**
   * Configure retry behavior
   */
  retry?: {
    retries: number;
    backoff: (retryCount: number) => number;
  };
  
  /**
   * HTTP agent for connection pooling (Node.js only)
   */
  agent?: unknown;
  
  /**
   * Enable HTTP keep-alive (Node.js only)
   */
  keepAlive?: boolean;
  
  /**
   * AbortSignal for request cancellation
   */
  signal?: AbortSignal;
}

​
Example with options

import { Redis } from '@upstash/redis';

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
  
  // Performance optimizations
  enableAutoPipelining: true,
  keepAlive: true,
  
  // Consistency
  readYourWrites: true,
  
  // Privacy
  enableTelemetry: false,
  
  // Retry configuration
  retry: {
    retries: 3,
    backoff: (retryCount) => Math.exp(retryCount) * 100,
  },
});

​
TypeScript configuration

The SDK is written in TypeScript and includes type definitions. No additional @types package is needed. If you’re using TypeScript, ensure your tsconfig.json includes:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true
  }
}

​
CommonJS vs ES Modules

The SDK supports both CommonJS and ES Modules: 
const { Redis } = require('@upstash/redis');

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
});

​
Bundler configuration

The SDK works with all major bundlers without additional configuration.

​
Webpack

No configuration needed. The SDK uses standard exports that Webpack handles automatically.

​
Vite

No configuration needed. Vite will tree-shake unused code automatically.

​
esbuild

No configuration needed. The SDK includes proper exports for esbuild.

​
Rollup

No configuration needed. The SDK is compatible with Rollup’s ES module handling.

​
Disabling telemetry

The SDK sends anonymous telemetry data by default. To disable it:

​
Via environment variable

.env
UPSTASH_DISABLE_TELEMETRY=1

​
Via configuration

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
  enableTelemetry: false,
});
Telemetry helps improve the SDK by collecting:
  • SDK version
  • Platform (Cloudflare, Vercel, AWS, etc.)
  • Runtime version (e.g., [email protected])
No personal data or Redis commands are collected.

​
Verify installation

Test your installation with this simple script:
test.ts
import { Redis } from '@upstash/redis';

const redis = Redis.fromEnv();

async function test() {
  const result = await redis.ping();
  console.log('Ping result:', result); // Should print: Ping result: PONG
}

test().catch(console.error);
Run it: 
node test.ts
If you see Ping result: PONG, your installation is successful!

​
Troubleshooting

Make sure you’ve installed the package:
npm install @upstash/redis
If using Cloudflare or Fastly, use the correct import:
import { Redis } from '@upstash/redis/cloudflare';
// or
import { Redis } from '@upstash/redis/fastly';
Ensure your .env file is in the project root and you’re loading it correctly:
npm install dotenv

import 'dotenv/config';
import { Redis } from '@upstash/redis';

const redis = Redis.fromEnv();
Make sure you’re using TypeScript 4.5 or higher:
npm install -D typescript@latest
Update your tsconfig.json:
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}
Use the Cloudflare-specific import and ensure you’re passing the env object:
import { Redis } from '@upstash/redis/cloudflare';

export default {
  async fetch(request: Request, env: Env) {
    const redis = Redis.fromEnv(env); // Pass env here
    // ...
  },
};

​
Next steps

Quick start

Create your first Redis client

API reference

Explore all available commands

Build docs developers (and LLMs) love

Get started for freeTalk to us