Node.js

Use Upstash Redis SDK in Node.js applications

The Upstash Redis SDK works seamlessly in Node.js environments, including serverless functions, AWS Lambda, and traditional Node.js applications.

Installation

npm install @upstash/redis

Quick Start

1. Import the SDK

   The default export is optimized for Node.js:

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

   You can also use the explicit Node.js import:

   import { Redis } from "@upstash/redis/node";
   
2. Create a Redis instance

   From Environment

   Use fromEnv() to automatically load credentials from environment variables:

   const redis = Redis.fromEnv();
   

   This will read from:

   • UPSTASH_REDIS_REST_URL or KV_REST_API_URL
   • UPSTASH_REDIS_REST_TOKEN or KV_REST_API_TOKEN

   The fallback variables (KV_REST_API_URL and KV_REST_API_TOKEN) provide compatibility with Vercel KV and other platforms.

   With Credentials

   const redis = new Redis({
     url: "<UPSTASH_REDIS_REST_URL>",
     token: "<UPSTASH_REDIS_REST_TOKEN>",
   });
   
3. Use Redis commands

   const count = await redis.incr("counter");
   console.log("Counter:", count);
   

Configuration Options

The Node.js SDK supports several configuration options:

const redis = new Redis({
  url: "<UPSTASH_REDIS_REST_URL>",
  token: "<UPSTASH_REDIS_REST_TOKEN>",
  
  // Node.js specific: HTTP(S) agent for connection pooling
  agent: new https.Agent({ keepAlive: true }),
  
  // Or use the simplified keepAlive option
  keepAlive: true,
  
  // Abort requests using AbortSignal
  signal: abortController.signal,
  
  // Enable latency logging
  latencyLogging: true,
  
  // Automatic deserialization of JSON values
  automaticDeserialization: true,
  
  // Read-your-writes consistency
  readYourWrites: true,
  
  // Enable telemetry (default: true)
  enableTelemetry: true,
  
  // Configure retry behavior
  retry: {
    retries: 3,
    backoff: (retryCount) => Math.exp(retryCount) * 50,
  },
  
  // Response encoding
  responseEncoding: "base64",
  
  // Cache control
  cache: "no-store",
});

Connection Pooling with Agent

For optimal performance in Node.js applications with multiple sequential requests, use an HTTP(S) agent:

import https from "https";
import { Redis } from "@upstash/redis";

const redis = new Redis({
  url: "<UPSTASH_REDIS_REST_URL>",
  token: "<UPSTASH_REDIS_REST_TOKEN>",
  agent: new https.Agent({ keepAlive: true }),
});

The agent option is Node.js specific and not supported in edge runtimes like Vercel Edge Functions or Cloudflare Workers.

Using fromEnv() with Options

You can combine fromEnv() with additional configuration:

const redis = Redis.fromEnv({
  keepAlive: true,
  latencyLogging: true,
  automaticDeserialization: true,
});

Example Application

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

const redis = Redis.fromEnv();

async function run() {
  const count = await redis.incr("counter");
  console.log("Counter:", count);
}

run();

Platform Detection

The SDK automatically detects the runtime environment and sets appropriate telemetry:

• Node.js: Reports as node@<version> (e.g., node@18.17.0)
• Edge Runtime: Reports as edge-light when running in Vercel Edge Functions
• Platform: Detects Vercel, AWS, or Upstash Console environments

Environment Variables

When using Redis.fromEnv(), the SDK looks for these environment variables via process.env:

Variable	Fallback	Description
UPSTASH_REDIS_REST_URL	KV_REST_API_URL	Your Redis REST URL
UPSTASH_REDIS_REST_TOKEN	KV_REST_API_TOKEN	Your Redis REST token
UPSTASH_DISABLE_TELEMETRY	-	Set to disable telemetry

If process.env is not available (e.g., in Cloudflare Workers), use the platform-specific import instead: @upstash/redis/cloudflare

Related

• Vercel Guide - Using Redis with Vercel Functions
• Configuration - Complete configuration reference
• Examples - Node.js examples on GitHub