Redis

Configure a Redis host for resumable streams and shared rate limits

ChatJS uses one Node Redis client with a standard Redis TCP/TLS connection. You do not select a Redis host in the CLI or install a host-specific package. Your Postgres host and Redis host are independent.

Set up a connection

Create a Redis database, then put its connection URL in .env.local at your generated app’s root, or apps/chat in this repository:

REDIS_URL=rediss://default:password@your-redis-host:6379/0

Use rediss:// for verified TLS and your host’s certificate trust settings. A redis:// URL sends credentials and data without encryption. Use it only on local or trusted private networks. The app honors the configured transport and does not automatically upgrade plaintext connections. redis://localhost:6379 works for a local server without TLS. Connection attempts use a 10-second socket timeout. The running app retains Node Redis’s automatic reconnection behavior after startup. If initial connection fails or takes more than 10 seconds, both clients are closed and the app starts without Redis. Restart the app after correcting the connection to enable Redis again.

Host	What to provide
Upstash	Copy the Redis TCP/TLS connection credentials from your database, not `UPSTASH_REDIS_REST_URL` or a REST token
Redis Cloud	Use your database endpoint, port, username, password, and TLS settings
Another managed host or local Redis	Use a standard Redis URL reachable from your app’s runtime

See Node Redis connections and Upstash security for client and transport details. HTTP-only endpoints and cluster-mode endpoints requiring Redis Cluster routing are outside this client configuration.

Verify your provider

After configuring the URL, run:

bun redis:connect

The generated command also runs with npm, pnpm, or Yarn. It verifies two connections, key/value reads and writes, counters, expiry, exact-key lookup, and pub/sub. It uses the same connection options as the app, with reconnect retries disabled and a 15-second overall deadline for the check. Diagnostics do not print the URL or provider error text.

The check writes one uniquely named key under <appPrefix>:connection-check:* with a 60-second expiry, publishes a probe on the same named channel, and deletes the key on success. On failure the key expires. Allow this prefix in your test credentials. The check does not read application values or modify existing keys. It exits unsuccessfully on a failed check and reports an unconfigured optional Redis connection without connecting.

A successful probe confirms the tested capabilities. It does not establish provider capacity, availability guarantees, or permission to every application key prefix.

Required capabilities

Redis currently serves resumable-stream coordination and anonymous rate limits. It is not a general query-result cache. The existing implementation uses SET (with expiry), GET, INCR, EXPIRE, KEYS, PUBLISH, SUBSCRIBE, and UNSUBSCRIBE. The check uses EXISTS instead of scanning keys. It also uses DEL to clean up its temporary key.

Resumable streams require a separate subscriber connection. Provider credentials must allow the relevant commands, application key prefixes, and pub/sub channels. A REST endpoint or a service supporting only basic key/value commands is not a drop-in replacement for this connection.

Without Redis

You may leave REDIS_URL blank. Normal chat streaming remains available, but streams cannot resume after disconnection and Redis-backed anonymous rate-limit counters are not enforced. Other database-backed limits retain their behavior.

See Environment variables for the rest of the app’s configuration.