How to Integrate Bolt.new with Redis (via Upstash)

Upstash is a serverless Redis provider that offers an HTTP-based client specifically designed for environments where TCP connections are unavailable — including Bolt.new's WebContainer, Vercel Edge Functions, and Cloudflare Workers. Setting up is quick and the free tier is generous enough for development and small production workloads. Create your database: go to console.upstash.com and sign in with GitHub or Google. Click Create Database. Choose a name (e.g., 'my-bolt-app-cache'), select the region closest to your deployment target (if using Netlify with a US region, pick us-east-1 or us-west-1), and choose the free tier. Click Create. The database provisions in seconds. After creation, you land on the database detail page. You need two values from the REST API section: the UPSTASH_REDIS_REST_URL (looks like https://us1-example-12345.upstash.io) and the UPSTASH_REDIS_REST_TOKEN (a long JWT-like string). Copy both. These are the only credentials you need — Upstash does not use a separate username/password for the HTTP client. Add both to your .env file in Bolt. Do not use NEXT_PUBLIC_ prefix — these are server-side only credentials. The REST URL is not a sensitive value (it is just a URL), but the token is effectively a password and must never be committed to Git or exposed in client-side code. The @upstash/redis package installation is straightforward: it is pure JavaScript with no native modules, so it installs without issues in Bolt's WebContainer and is ready to use immediately after install.

1// lib/redis.ts
2import { Redis } from '@upstash/redis';
3
4const url = process.env.UPSTASH_REDIS_REST_URL;
5const token = process.env.UPSTASH_REDIS_REST_TOKEN;
6
7if (!url) {
8  throw new Error(
9    'UPSTASH_REDIS_REST_URL is not set. ' +
10    'Get it from console.upstash.com → your database → REST API section.'
11  );
12}
13if (!token) {
14  throw new Error(
15    'UPSTASH_REDIS_REST_TOKEN is not set. ' +
16    'Get it from console.upstash.com → your database → REST API section.'
17  );
18}
19
20export const redis = new Redis({ url, token });
21export default redis;
22
23// Type-safe cache helpers
24export async function getCached<T>(key: string): Promise<T | null> {
25  return redis.get<T>(key);
26}
27
28export async function setCached<T>(
29  key: string,
30  value: T,
31  ttlSeconds?: number
32): Promise<void> {
33  if (ttlSeconds) {
34    await redis.set(key, value, { ex: ttlSeconds });
35  } else {
36    await redis.set(key, value);
37  }
38}
39
40export async function deleteCached(key: string): Promise<void> {
41  await redis.del(key);
42}

Caching is the most impactful use of Redis in most web applications. The pattern is simple: before executing an expensive operation (database query, external API call, complex computation), check if a cached result exists in Redis. If it does, return it immediately. If not, execute the operation, store the result in Redis with a TTL, and return it. The TTL (Time to Live) is a key design decision. It represents how stale your data can be. For product listings on an e-commerce site, 60 seconds might be acceptable — a new product appearing up to a minute late is fine. For real-time stock prices, you might want 5 seconds or no caching at all. For rarely-changing data like navigation menus or configuration, 3600 seconds (1 hour) is appropriate. Cache keys should be predictable, unique, and human-readable. A good naming convention is `resource:identifier:variant` — for example, `products:all:v1`, `user:123:profile`, `search:query:typescript:page:2`. Including a version suffix (`:v1`) is useful when you change the data structure — you can bust the entire cache by incrementing the version without deleting keys manually. For Next.js API routes, add the cache check near the top of the handler, before any database calls. The pattern is so common that extracting it into a `withCache` higher-order function pays off quickly — you can wrap any async function to get automatic caching with a single line of code change. Cache invalidation (deleting or updating cached values when the underlying data changes) is the harder problem. For write operations (creating or updating a product), delete the corresponding cache keys as part of the write transaction so the next read fetches fresh data.

1// app/api/products/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { redis } from '@/lib/redis';
4
5const CACHE_KEY = 'products:list:v1';
6const CACHE_TTL = 60; // seconds
7
8export async function GET() {
9  // Check cache first
10  const cached = await redis.get<unknown[]>(CACHE_KEY);
11  if (cached) {
12    return NextResponse.json(cached, {
13      headers: { 'Cache-Status': 'HIT', 'X-Cache-TTL': CACHE_TTL.toString() },
14    });
15  }
16
17  // Cache miss — fetch from database
18  // Replace this with your actual data source (Supabase, etc.)
19  const products = await fetchProductsFromDatabase();
20
21  // Store in Redis with TTL
22  await redis.set(CACHE_KEY, products, { ex: CACHE_TTL });
23
24  return NextResponse.json(products, {
25    headers: { 'Cache-Status': 'MISS' },
26  });
27}
28
29export async function POST(request: NextRequest) {
30  const body = await request.json();
31
32  // Create the product in your database
33  const newProduct = await createProductInDatabase(body);
34
35  // Invalidate the cached product list
36  await redis.del(CACHE_KEY);
37
38  return NextResponse.json(newProduct, { status: 201 });
39}
40
41// Placeholder — replace with your actual database query
42async function fetchProductsFromDatabase() {
43  return [{ id: 1, name: 'Example Product', price: 29.99 }];
44}
45
46async function createProductInDatabase(data: unknown) {
47  return { id: Date.now(), ...((data as object) || {}) };
48}

Rate limiting protects your API routes from abuse — brute-force login attempts, contact form spam, and excessive AI API usage. A sliding window rate limiter is more accurate than a fixed window approach because it tracks requests in a rolling time window rather than resetting at fixed intervals (which can allow 2x the rate at window boundaries). The sliding window algorithm uses Redis sorted sets. Each element in the set is a unique request ID (UUID or timestamp + random), and the score is the Unix timestamp of the request. To count requests in the last N seconds: remove all elements with scores older than `now - windowSeconds`, then count the remaining elements. If the count is below the limit, add the new request to the set (with an expiry on the key to avoid storing stale sets forever) and allow it. If not, reject it with a 429 response. For identifying clients, use the request's IP address. In Next.js with Netlify, the real client IP is in the `x-forwarded-for` or `x-nf-client-connection-ip` header — read it from the request headers. For authenticated routes, use the user ID instead of IP for more accurate per-user limiting. The rate limit configuration should be externalizable — different routes need different limits. A login endpoint might allow 5 attempts per minute, a contact form 3 per minute, and an AI generation endpoint 10 per hour. Build the rateLimit function to accept these parameters so you can configure each route appropriately. Always include `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers in rate-limited responses. These headers let client-side code display helpful messages like 'Please wait 45 seconds before trying again' rather than a generic error.

1// lib/rate-limit.ts
2import { redis } from './redis';
3
4interface RateLimitResult {
5  allowed: boolean;
6  remaining: number;
7  limit: number;
8  resetAt: number;
9}
10
11export async function rateLimit(
12  identifier: string,
13  limit: number,
14  windowSeconds: number
15): Promise<RateLimitResult> {
16  const now = Date.now();
17  const windowStart = now - windowSeconds * 1000;
18  const key = `rate_limit:${identifier}`;
19
20  // Use a pipeline for atomic operations
21  const pipeline = redis.pipeline();
22  pipeline.zremrangebyscore(key, 0, windowStart); // Remove expired entries
23  pipeline.zcard(key);                              // Count current entries
24  pipeline.zadd(key, { score: now, member: `${now}-${Math.random()}` }); // Add this request
25  pipeline.expire(key, windowSeconds * 2);          // Auto-cleanup key
26
27  const results = await pipeline.exec();
28  const currentCount = (results[1] as number) ?? 0;
29
30  const allowed = currentCount < limit;
31  const remaining = Math.max(0, limit - currentCount - 1);
32  const resetAt = Math.ceil((now + windowSeconds * 1000) / 1000);
33
34  return { allowed, remaining, limit, resetAt };
35}
36
37// Helper to get client IP from Next.js request
38export function getClientIp(request: Request): string {
39  const forwarded = request.headers.get('x-forwarded-for');
40  const nfIp = request.headers.get('x-nf-client-connection-ip');
41  return nfIp ?? (forwarded ? forwarded.split(',')[0].trim() : 'unknown');
42}

Upstash Redis works identically in development (Bolt.new WebContainer) and production (Netlify, Vercel) because both environments use the same HTTP-based @upstash/redis client. The underlying transport is always HTTPS fetch calls — there is no TCP socket to configure differently between environments. This is the key advantage over traditional Redis setups: with ioredis, you would need to configure different connection strings for local, staging, and production, and handle connection pooling. With Upstash, the same two environment variables work everywhere. To deploy: click Deploy in Bolt.new and connect to Netlify. After deployment, go to Netlify Dashboard → Site Configuration → Environment Variables and add UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN with the same values from your Upstash console. Trigger a redeploy. For production, consider creating a separate Upstash database for each environment (development, staging, production) — this prevents development testing from polluting your production cache or consuming your production command quota. Upstash's free tier allows multiple databases. Monitor your Redis usage in the Upstash console: it shows command counts, data transfer, and latency graphs. If you approach the free tier limit of 10,000 commands/day, review your caching strategy — you may be calling Redis more frequently than necessary, or your TTLs are too short, causing excessive cache misses. Note: Upstash Redis is the right choice for serverless deployments (Netlify Functions, Vercel Functions) even after deploying. If you migrate to a long-running server (Railway, Render, Fly.io), you can switch to ioredis with a standard Redis URL — ioredis works in any environment with TCP access.

1// app/api/health/route.ts
2import { NextResponse } from 'next/server';
3import { redis } from '@/lib/redis';
4
5export async function GET() {
6  try {
7    const result = await redis.ping();
8    return NextResponse.json({
9      status: 'ok',
10      redis: result === 'PONG' ? 'connected' : 'unexpected response',
11      timestamp: new Date().toISOString(),
12    });
13  } catch (error) {
14    return NextResponse.json(
15      {
16        status: 'error',
17        redis: error instanceof Error ? error.message : 'unknown error',
18        timestamp: new Date().toISOString(),
19      },
20      { status: 503 }
21    );
22  }
23}