Index of every page on this site: llms.txt
All skills
upstash avatar

/upstash-redis-js

@2326f1a
by upstashupstash/skills37 stars
7
Run it yourself

Work with the @upstash/redis TypeScript/JavaScript SDK, a serverless HTTP-based Redis client for Next.js, Vercel, Cloudflare Workers, edge runtimes, and Node.js. Use when adding a cache (cache-aside, TTL strategies), session storage, a key-value store, leaderboards with sorted sets, counters, distributed locks, queues, streams and consumer groups, ring buffers and sparse arrays (ARSET, ARRING), vector search inside Redis (redis.vector), JSON documents, pipelines and transactions, Lua scripting, read replicas, or full-text search, facets and aggregations with Upstash Redis Search (not FT.SEARCH; TCP clients use @upstash/search-redis or @upstash/search-ioredis). Also use when migrating from ioredis or node-redis, connecting from serverless without pooling, building AI agents with Upstash AgentKit (agent memory, chat history, RAG tools, resumable streams) for the Vercel AI SDK, TanStack AI, or Vercel Eve, or when the user says Redis cache, KV store, session store, serverless Redis, or Upstash Redis.

Use this Skill: https://skilld.dev/gh/upstash/skills/upstash-redis-js

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈257 tokens for metadata: the name and description. ≈1.9k when used: this file. ≈26k more on demand in 31 files.

Description uses 12.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈1030 characters, or 12.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Upstash Redis SDK - Complete Skills Guide

This directory contains comprehensive guides for using the @upstash/redis SDK. These skill files are designed to help developers and AI assistants understand and use the SDK effectively.

Bundled docs and source

Before writing or debugging SDK code, check node_modules/@upstash/redis/docs/ for bundled docs and node_modules/@upstash/redis/src/ for readable TypeScript source. Read and search the relevant files when present; otherwise use the references in this skill.

Installation

npm install @upstash/redis

Quick Start

Basic Initialization

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

// Initialize with explicit credentials
const redis = new Redis({
  url: "UPSTASH_REDIS_REST_URL",
  token: "UPSTASH_REDIS_REST_TOKEN",
});

// Or initialize from environment variables
const redis = Redis.fromEnv();

Environment Variables

Set these in your .env file:

UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token-here

No credentials yet? If you're an agent that needs scratch Redis and the user hasn't provided a database, you can mint a temporary one with a single POST to https://upstash.com/start-redis (3-day TTL, no signup).

Skill Files Overview

Data Structures (data-structures/)

Redis data types with auto-serialization examples:

  • strings.md - GET, SET, INCR, DECR, APPEND with automatic type handling
  • hashes.md - HSET, HGET, HMGET with object serialization
  • lists.md - LPUSH, RPUSH, LRANGE with array handling
  • sets.md - SADD, SMEMBERS, set operations
  • sorted-sets.md - ZADD, ZRANGE, ZRANK, leaderboard patterns
  • json.md - JSON.SET, JSON.GET, JSONPath queries for nested objects
  • streams.md - XADD, XREAD, XGROUP, consumer groups
  • arrays.md - ARSET, ARINSERT, ARSCAN, ARGREP, AROP, ring buffers with ARRING on sparse index-addressed arrays
  • vector-indexes.md - VECTOR.CREATE, VECTOR.ADD, VECTOR.QUERY nearest-neighbour search inside Redis via redis.vector

Advanced Features (advanced-features/)

Complex operations and optimizations:

  • auto-pipeline.md - Automatic request batching, performance optimization
  • pipeline-and-transactions.md - Manual pipelines, MULTI/EXEC for atomic operations
  • scripting.md - Lua scripts, EVAL, EVALSHA for server-side logic

Patterns (patterns/)

Common use cases and architectural patterns:

  • caching.md - Cache-aside, write-through, TTL strategies
  • rate-limiting.md - Integration with @upstash/ratelimit package
  • session-management.md - Session storage and user state management
  • distributed-locks.md - Lock implementations, deadlock prevention
  • leaderboard.md - Sorted set leaderboards, real-time rankings

Performance (performance/)

Optimization techniques and best practices. For rules on batching, big keys, TTLs, scripts and connections at scale, see the redis-best-practices skill.

  • batching-operations.md - MGET, MSET, batch operations
  • pipeline-optimization.md - When to use pipelines, performance tips
  • ttl-expiration.md - Key expiration strategies, memory management
  • data-serialization.md - Deep dive into auto serialization, custom serializers, edge cases
  • error-handling.md - Error types, retry strategies, timeout handling, debugging tips
  • redis-replicas.md - Global database setup, read replicas, read-your-writes consistency

Search (search/)

Full-text search, filtering, and aggregation extension for Redis:

  • overview.md - Schema definition, field types, pitfalls, package overview
  • commands/querying.md - Query and count with filters, pagination, sorting, highlighting
  • commands/aggregating.md - Metric aggregations ($avg, $sum, $stats), bucket aggregations ($terms, $range, $histogram, $facet)
  • commands/index-management.md - Create, describe, drop indexes (including stream indexes over XADD entries), waitIndexing
  • commands/aliases.md - Index aliases for zero-downtime reindexing
  • adapters.md - Using search with node-redis and ioredis via @upstash/search-redis and @upstash/search-ioredis

Migrations (migrations/)

Migration guides from other libraries:

  • from-ioredis.md - Migration from ioredis, key differences, serialization changes
  • from-redis-node.md - Migration from node-redis, API differences

Common Mistakes (Especially for LLMs)

❌ Mistake 1: Treating Everything as Strings

// ❌ WRONG - Don't do this with @upstash/redis
await redis.set("count", "42"); // Stored as string "42"
const count = await redis.get("count");
const incremented = parseInt(count) + 1; // Manual parsing needed

// ✅ CORRECT - Let the SDK handle it
await redis.set("count", 42); // Stored as number
const count = await redis.get("count");
const incremented = count + 1; // Just use it

❌ Mistake 2: Manual JSON Serialization

// ❌ WRONG - Unnecessary with @upstash/redis
await redis.set("user", JSON.stringify({ name: "Alice" }));
const user = JSON.parse(await redis.get("user"));

// ✅ CORRECT - Automatic handling
await redis.set("user", { name: "Alice" });
const user = await redis.get("user");

Quick Command Reference

// Strings
await redis.set("key", "value");
await redis.get("key");
await redis.incr("counter");
await redis.decr("counter");

// Hashes
await redis.hset("user:1", { name: "Alice", age: 30 });
await redis.hget("user:1", "name");
await redis.hgetall("user:1");

// Lists
await redis.lpush("tasks", "task1", "task2");
await redis.rpush("tasks", "task3");
await redis.lrange("tasks", 0, -1);

// Sets
await redis.sadd("tags", "javascript", "redis");
await redis.smembers("tags");

// Sorted Sets
await redis.zadd("leaderboard", { score: 100, member: "player1" });
await redis.zrange("leaderboard", 0, -1);

// JSON
await redis.json.set("user:1", "$", { name: "Alice", address: { city: "NYC" } });
await redis.json.get("user:1");

// Expiration
await redis.setex("session", 3600, { userId: "123" });
await redis.expire("key", 60);
await redis.ttl("key");

Best Practices

  1. Use environment variables for credentials, never hardcode
  2. Leverage auto-serialization - pass native JavaScript types
  3. Use TypeScript types for better type safety
  4. Set appropriate TTLs to manage memory
  5. Use pipelines for multiple operations
  6. Namespace your keys (e.g., user:123, session:abc)

AI agents: use AgentKit

For agent state on Redis — memory, chat history, RAG search tools, tool caching, rate limiting, chat persistence, resumable streams, locks — use Upstash AgentKit instead of hand-rolling it on @upstash/redis. Pick the adapter for the framework and follow its docs page:

Framework Package Docs
Vercel AI SDK @upstash/agentkit-ai-sdk https://upstash.com/docs/redis/sdks/agentkit/ai-sdk
TanStack AI @upstash/agentkit-tanstack-ai https://upstash.com/docs/redis/sdks/agentkit/tanstack-ai
Vercel Eve @upstash/agentkit-eve, @upstash/agentkit-eve-extension https://upstash.com/docs/redis/sdks/agentkit/eve

Resources

Getting Help

For detailed information on specific topics, refer to the individual skill files in the skills/ directory. Each file contains comprehensive examples, use cases, and best practices for its topic.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert2d3 checks · Risk SAFE
  • Gen Agent Trust Hub3d

    The skill is a comprehensive documentation suite for the official Upstash Redis JavaScript/TypeScript SDK. It provides guidance on using various Redis data structures, search functionality, and performance optimizations. All referenced packages and URLs belong to the verified Upstash organization. No security risks or malicious patterns were identified.

  • Socket2d

    1 alert: gptSecurity

  • Snyk3d

    Risk: CRITICAL · 1 issue

Signed by skilld at 2326f1a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated last week
metadata
{
  "author": "Upstash",
  "homepage": "https://upstash.com"
}

README badge

README badge for upstash/skills/upstash-redis-js