Deployment Guide

The Core Constraint: SSE Needs Long-Lived Connections

All apps in this library expose Server-Sent Events (SSE) for real-time tag invalidation. SSE is a long-lived HTTP response that the server writes to over time. This shapes every hosting decision.

Pick Your Path

The right setup depends on whether you need horizontal scaling and how your app is structured.

Single Instance

The default createTagInvalidationSystem() call uses an in-process EventEmitter. No Redis, no external store — just Node.js.

// src/lib/tag-system.server.ts
import { createTagInvalidationSystem } from "@tanstack-tools/query-tags/server"

// Zero-config: in-process EventEmitter, no external dependencies
export const tagInvalidation = createTagInvalidationSystem()

Multi-Instance + Redis

The default in-process broadcast only reaches clients connected to the same process. To scale horizontally, pass a BroadcastAdapter backed by Redis pub/sub and a shared Keyv store so the path registry is consistent across all instances.

// src/lib/tag-system.server.ts
import { createTagInvalidationSystem } from "@tanstack-tools/query-tags/server"
import { createRedisBroadcast } from "@tanstack-tools/query-tags/redis"
import Keyv from "keyv"

export const tagInvalidation = createTagInvalidationSystem({
  // Redis pub/sub: invalidations on any instance reach all connected clients
  broadcast: createRedisBroadcast({ url: process.env.REDIS_URL }),

  // Shared Keyv store: path registry is consistent across instances
  store: new Keyv({ uri: process.env.REDIS_URL }),
})

SPA + Separate Backend

For Vite SPAs without TanStack Start, build the SPA as a static site and pair it with any Node/Bun backend using a framework adapter. The SPA connects via createHTTPInvalidatorClient from the /http-client entry.

# Build the SPA frontend (Vite, no SSR)
pnpm --filter @tanstack-tools/example-spa build
# Output: apps/example-spa/dist/  — serve as a static site

// src/lib/invalidator-client.ts
import { createHTTPInvalidatorClient } from "@tanstack-tools/query-tags/http-client"

// For SPAs: use /http-client, not /client (which requires TanStack Start)
export const invalidatorClient = createHTTPInvalidatorClient({
  basePath: "/api/invalidator",
})

// package.json additions for production readiness
{
  "scripts": {
    "build": "tsup src/server.ts --format esm --out-dir dist",
    "start": "node dist/server.js"
  }
}

// Lock CORS origin instead of wildcard
app.use(cors({ origin: "https://your-spa.example.com" }))

// Add a health endpoint
app.get("/healthz", (_req, res) => res.status(200).send("ok"))

Docker (TanStack Start Apps)

The repository includes a multi-stage Dockerfile for docs-webapp. The runner image has no node_modules — Nitro's node-server bundle includes all runtime dependencies inline. Final image is typically under 200 MB.

# Build from repo root — selects docs-webapp
docker build \
  -f apps/docs-webapp/Dockerfile \
  -t query-tags-docs \
  .

docker run --rm \
  -p 3000:3000 \
  -e NODE_ENV=production \
  -e PORT=3000 \
  -e HOST=0.0.0.0 \
  query-tags-docs

Heartbeat and Idle Timeouts

The server sends a : ping SSE comment every 30 seconds to keep the connection alive. If a load balancer or proxy has a shorter idle timeout, it will sever SSE connections. Either increase the proxy timeout or reduce the heartbeat interval.

// Reduce heartbeat if your proxy idle timeout is < 35 s
export const tagInvalidation = createTagInvalidationSystem({
  heartbeatInterval: 15_000, // ping every 15 s instead of the default 30 s
})

Reverse Proxy Configuration

The library already sets X-Accel-Buffering: no and Content-Encoding: identity on every SSE response to signal proxies not to buffer. Most setups work out of the box — but explicit proxy configuration is recommended for production.

server {
    listen 80;
    server_name docs.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # SSE: disable buffering so events stream immediately
    location /api/invalidator/sse {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_buffering off;          # critical — disables response buffering
        proxy_cache off;
        proxy_read_timeout 86400s;    # must exceed heartbeatInterval
        add_header X-Accel-Buffering no;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        gzip off;
    }
}

SSE Diagnostics

The fastest way to rule out proxy issues is to probe the SSE endpoint directly with curl from outside the proxy. You should see headers and an event: connected frame within ~1 second.

curl -N -i --max-time 5 "https://your.domain/api/invalidator/sse?scopeKey=global"

# Expected within ~1 second:
# HTTP/1.1 200 OK
# Content-Type: text/event-stream
# X-Accel-Buffering: no
# Content-Encoding: identity
#
# event: connected
# data: {"scopeKey":"global"}

FAQ