The Upstash Redis SDK works seamlessly with Vercel, supporting both Vercel Functions (Node.js runtime) and Vercel Edge Functions.
Installation
npm install @upstash/redis
Quick Start
API Route (Edge Runtime)
// app/api/hello/route.ts
import { Redis } from "@upstash/redis";
import { NextResponse } from "next/server";
const redis = Redis.fromEnv();
export async function GET() {
const count = await redis.incr("counter");
return NextResponse.json({ count });
}
export const runtime = "edge";
API Route (Node.js Runtime)
// app/api/hello/route.ts
import { Redis } from "@upstash/redis";
import { NextResponse } from "next/server";
const redis = Redis.fromEnv();
export async function GET() {
const count = await redis.incr("counter");
return NextResponse.json({ count });
}
// Node.js runtime (default)
API Route
// pages/api/hello.ts
import { Redis } from "@upstash/redis";
import type { NextApiRequest, NextApiResponse } from "next";
const redis = Redis.fromEnv();
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
const count = await redis.incr("counter");
res.status(200).json({ count });
}
Choosing the Right Import
The Upstash Redis SDK automatically works with both Node.js and Edge runtimes:
import { Redis } from "@upstash/redis";
- Vercel Functions (Node.js runtime)
- Vercel Edge Functions (Edge runtime)
- The SDK automatically detects the runtime and adjusts accordingly
You don’t need different imports for different runtimes when using Vercel. The default import handles both!
Configuration
Using fromEnv() (Recommended)
The easiest way to configure Redis is using fromEnv(), which automatically reads from environment variables:
const redis = Redis.fromEnv();
UPSTASH_REDIS_REST_URL or KV_REST_API_URLUPSTASH_REDIS_REST_TOKEN or KV_REST_API_TOKEN
Using Vercel KV Integration
If you’re using the Vercel KV integration, the environment variables are automatically set as:
KV_REST_API_URLKV_REST_API_TOKEN
The SDK automatically falls back to these, so Redis.fromEnv() works out of the box!
Manual Configuration
const redis = new Redis({
url: process.env.UPSTASH_REDIS_REST_URL!,
token: process.env.UPSTASH_REDIS_REST_TOKEN!,
});
With Options
const redis = Redis.fromEnv({
automaticDeserialization: true,
latencyLogging: true,
});
Environment Variables
Add environment variables to your Vercel project
- Go to your project settings in Vercel
- Navigate to Environment Variables
- Add:
UPSTASH_REDIS_REST_URL: Your Redis REST URLUPSTASH_REDIS_REST_TOKEN: Your Redis REST token
Or use .env.local for local development
# .env.local
UPSTASH_REDIS_REST_URL=https://your-redis-url.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token-here
Never commit .env.local to version control. Add it to .gitignore.
Or use the Vercel KV Integration
Configuration Options
Node.js Runtime (Vercel Functions)
const redis = new Redis({
url: process.env.UPSTASH_REDIS_REST_URL!,
token: process.env.UPSTASH_REDIS_REST_TOKEN!,
// Connection pooling (Node.js only)
keepAlive: true,
// Latency logging
latencyLogging: true,
// Automatic deserialization
automaticDeserialization: true,
// Read-your-writes consistency
readYourWrites: true,
// Cache control
cache: "no-store",
// Retry configuration
retry: {
retries: 3,
backoff: (retryCount) => Math.exp(retryCount) * 50,
},
});
Edge Runtime (Vercel Edge Functions)
const redis = new Redis({
url: process.env.UPSTASH_REDIS_REST_URL!,
token: process.env.UPSTASH_REDIS_REST_TOKEN!,
// Keep-alive (Edge compatible)
keepAlive: true,
// Automatic deserialization
automaticDeserialization: true,
// Read-your-writes consistency
readYourWrites: true,
// Retry configuration
retry: {
retries: 3,
backoff: (retryCount) => Math.exp(retryCount) * 50,
},
});
The agent option is not supported in Edge Runtime. Use keepAlive: true instead.
Complete Examples
Next.js App Router with Edge Runtime
// app/api/counter/route.ts
import { Redis } from "@upstash/redis";
import { NextResponse } from "next/server";
const redis = Redis.fromEnv();
export async function GET() {
const count = await redis.incr("page-views");
return NextResponse.json({ count });
}
export async function POST(request: Request) {
const { key, value } = await request.json();
await redis.set(key, value);
return NextResponse.json({ success: true });
}
export const runtime = "edge";
Next.js App Router with Node.js Runtime
// app/api/data/route.ts
import { Redis } from "@upstash/redis";
import { NextResponse } from "next/server";
const redis = Redis.fromEnv({
keepAlive: true,
});
export async function GET() {
const count = await redis.incr("counter");
const data = await redis.get("mydata");
return NextResponse.json({ count, data });
}
Next.js Pages Router
// pages/api/hello.ts
import { Redis } from "@upstash/redis";
import type { NextApiRequest, NextApiResponse } from "next";
const redis = Redis.fromEnv();
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
if (req.method === "GET") {
const count = await redis.incr("counter");
res.status(200).json({ count });
} else if (req.method === "POST") {
const { key, value } = req.body;
await redis.set(key, value);
res.status(200).json({ success: true });
} else {
res.status(405).json({ error: "Method not allowed" });
}
}
Runtime Detection
The SDK automatically detects the Vercel runtime:
- Edge Runtime: Reports as
edge-light in telemetry
- Node.js Runtime: Reports as
node@<version> in telemetry
- Platform: Automatically detected as
vercel
1. Enable Keep-Alive
const redis = Redis.fromEnv({ keepAlive: true });
export const runtime = "edge";
3. Enable Auto-Pipelining
const redis = Redis.fromEnv({ enableAutoPipelining: true });
Troubleshooting
”Unable to find environment variable”
Make sure environment variables are set in your Vercel project settings or .env.local file.
Edge Runtime Errors
If using the agent option, remove it for Edge Runtime:
// ❌ Don't use in Edge Runtime
const redis = new Redis({
url: process.env.UPSTASH_REDIS_REST_URL!,
token: process.env.UPSTASH_REDIS_REST_TOKEN!,
agent: new https.Agent({ keepAlive: true }), // Not supported in Edge
});
// ✅ Use this instead
const redis = new Redis({
url: process.env.UPSTASH_REDIS_REST_URL!,
token: process.env.UPSTASH_REDIS_REST_TOKEN!,
keepAlive: true,
});