Getting started

ReplayStack captures requests, responses, failures, and context from your backend so you can inspect timelines and replay in the dashboard. Your services call the ReplayStack API only—no production traffic flows through visitors' browsers.

Install

Pick your runtime below. Official SDKs cover Node.js (@replaystack/sdk), Python (replaystack-sdk on PyPI), and PHP (replaystack/sdk on Packagist). Framework-specific wiring for Express, Next.js, and NestJS lives under Frameworks after you install the Node package. Anything else can still POST JSON to the same ingest URL—see Send events (HTTP API).

Official TypeScript/JavaScript SDK for Node 18+. Includes Express, Next.js, and NestJS helpers in the same package.

Node.js — installbash

npm install @replaystack/sdk
# or: yarn add @replaystack/sdk
# or: pnpm add @replaystack/sdk

Repositories: replaystack-sdk (Node), replaystack-python-sdk, replaystack-php-sdk. Use Python and PHP in the sidebar for copy-paste clients and capture examples.

How this guide is organized

Use the left nav: Authentication for env vars → TypeScript & JavaScript, Python, or PHP for your SDK → Frameworks (Express, Next.js, NestJS) when you are on Node. Prefer Send Events API only for a thin HTTP client or languages without a published SDK yet.

Node SDK (v1.0.7 on npm): npm install @replaystack/sdk. Import paths: @replaystack/sdk for the client and Express; @replaystack/sdk/nextjs for Next.js; @replaystack/sdk/nestjs for NestJS interceptors/filters. Nest/Next are not on the root entry so Express apps do not need @nestjs/common.

Runnable example apps

Clone the reference servers that mirror each other—they hit the same ingest API as your app: health probe, success routes, Bearer-protected order flow, and TypeError stack-frame demo. Optional REPLAYSTACK_SELF_TEST=1 runs checks after listen.

replaystack-express-example — Express + replayStackExpressMiddleware (default port 3456, @replaystack/sdk@^1.0.7).
replaystack-nestjs-example — NestJS + factories from @replaystack/sdk/nestjs (default port 3556).
Node on npm: @replaystack/sdk · source & README.
Python on PyPI: replaystack-sdk · replaystack-python-sdk.
PHP on Packagist: replaystack/sdk · replaystack-php-sdk.

Copy .env.example to .env, set REPLAYSTACK_API_KEY, then follow each repo's README for install and start commands.

Client options reference

Only apiKey is required. Everything else is optional—the SDK fills many values from environment variables when you do not pass them explicitly. For ReplayStack Cloud, you usually only need the key—omit endpoint to use the default host https://api.replaystack.co.

Field		What it does	If you omit it
apiKey	Required	Project key from the ReplayStack dashboard. Keep server-side only.	—
endpoint	Optional	API base URL (no /api/v1/... path). The SDK posts to /api/v1/ingest/events under this host.	REPLAYSTACK_ENDPOINT env, else https://api.replaystack.co
serviceName	Optional	Logical service name in the UI (filters, grouping).	REPLAYSTACK_SERVICE_NAME env, or set per event
environment	Optional	Label for where this process runs (production, staging, …).	NODE_ENV, else development
appVersion	Optional	Release or build version shown on events.	REPLAYSTACK_APP_VERSION / APP_VERSION env when not set on the client
commitHash	Optional	Git/deploy SHA for tying events to a revision.	REPLAYSTACK_COMMIT_HASH / COMMIT_HASH env when not set on the client
enabled	Optional	Turns all SDK sends off without removing code.	true unless REPLAYSTACK_ENABLED=false
timeoutMs	Optional	How long to wait on each ingest HTTP request.	2500 (overridable via REPLAYSTACK_TIMEOUT_MS)
retries	Optional	Retries if the ingest request fails transiently.	1 (REPLAYSTACK_RETRIES)
sampleRate	Optional	Random sample of events, 0–1. Use to reduce volume on success paths.	1 (capture all)
captureSuccess	Optional	Whether successful HTTP-style events are sent (failures are still captured).	false — set true or REPLAYSTACK_CAPTURE_SUCCESS=true for 2xx traffic (examples often enable this)
captureLogs	Optional	Attach application log lines to events (e.g. error log on exceptions).	true — set false or REPLAYSTACK_CAPTURE_LOGS=false to disable
logLevel	Optional	Minimum log level stored when captureLogs is on.	error (REPLAYSTACK_LOG_LEVEL)
maxLogs	Optional	Max log lines kept per request context.	50
batchFlushIntervalMs	Optional	When > 0, buffer events and POST to /api/v1/ingest/bulk-events on an interval.	0 (disabled; REPLAYSTACK_BATCH_FLUSH_INTERVAL_MS)
batchMaxEvents	Optional	Max events per bulk flush batch.	20 (REPLAYSTACK_BATCH_MAX_EVENTS)
maxPayloadSizeBytes	Optional	Truncates very large JSON bodies/headers before send.	512 KiB
maskFields	Optional	Extra field names to redact in payloads and headers (built-in sensitive list always applies).	built-in list always on (authorization, password, passwd, token, access_token, refresh_token, …)
ignoredPaths	Optional	URL paths to skip for client-level capture. Express middleware also merges its own defaults (/health, /metrics, /favicon.ico).	none
maxBreadcrumbs	Optional	Max breadcrumbs kept per request/client context.	50
fetchImpl	Optional	Inject fetch for tests or runtimes without global fetch.	globalThis.fetch
onError	Optional	Called if the SDK fails internally (network, parsing). Does not replace your app error handling.	none
offlineQueueMax	Optional	Max prepared events to keep in memory when ingest is down after retries. Oldest dropped when full. 0 = disable queueing.	0 — set REPLAYSTACK_OFFLINE_QUEUE_MAX to buffer failed sends in RAM
flushIntervalMs	Optional	If > 0, periodically calls flush() to drain the offline queue when the API recovers.	0 / disabled (REPLAYSTACK_FLUSH_INTERVAL_MS)
onQueueDrop	Optional	Callback when the offline queue exceeds offlineQueueMax and drops the oldest event.	none

maskFields: optional extra JSON/header keys to redact. Passwords, tokens, cookies, and card fields are masked even when you omit this option. See Security & masking for the full built-in name list.

Lifecycle and reliability: call flush() to drain the in-memory queue after failed sends. close() stops new capture, cancels periodic flush, then drains. In Node, installReplayStackProcessGuards(client) from @replaystack/sdk registers optional hooks (unhandled rejection, uncaught exception, beforeExit) to flush best-effort—crash capture is not guaranteed.

Follow these steps

Create a project and API key
In the ReplayStack dashboard, create a project and copy the ingestion key. You will store it only in server-side environment variables.
Configure environment variables
Set REPLAYSTACK_API_KEY (required). REPLAYSTACK_ENDPOINT is optional—the SDK defaults to https://api.replaystack.co. Full list is on the Authentication page.

Send one test event (optional)

Minimal client setup (Node)

Only apiKey is strictly required. Use createReplayStackClient (shown here) or new ReplayStackClient—same class. See Client options reference above for every field, defaults, and environment fallbacks. For Python or PHP, open those guide pages for an equivalent first event.

Confirms your key and URL before you wire a framework:

Minimal manual eventtypescript

import { createReplayStackClient } from "@replaystack/sdk";

const replayStack = createReplayStackClient({
  // Required — project key from the dashboard.
  apiKey: process.env.REPLAYSTACK_API_KEY!,
  // Optional — API base; omit to use REPLAYSTACK_ENDPOINT env or SDK default https://api.replaystack.co.
  endpoint: process.env.REPLAYSTACK_ENDPOINT!,
  // Optional — helps filter events by service in the UI.
  serviceName: process.env.REPLAYSTACK_SERVICE_NAME || "my-service",
  // Optional — defaults to NODE_ENV.
  environment: process.env.NODE_ENV || "development",
  // Optional — ties events to a deploy.
  appVersion: process.env.APP_VERSION,
  commitHash: process.env.COMMIT_HASH,
});

await replayStack.captureEvent({
  eventType: "custom",
  endpoint: "health-check",
  status: "success",
  statusCode: 200,
});

Add automatic capture for HTTP
On Node, open Express, Next.js, or NestJS in this guide and add the middleware or wrappers there—that is where most of the framework code lives. Python and PHP ship their own middleware in the respective repositories.

Dashboard first. If you do not have a project yet, create one and generate a key before copying any snippets.

Core ideas

Three terms you will see everywhere:

Events

One unit of “something happened”: an API call, a queue job, a server action you logged manually, etc.

Timeline

The dashboard orders events and shows duration, status, and breadcrumbs so you can see what led to a failure.

Replay

Re-run a captured scenario (often with a changed payload) to verify a fix without guessing.

Failed requests are usually worth capturing in full; you can sample successful traffic when volume is high (see TypeScript & JavaScript).
Never block your app if ReplayStack is slow or down—treat ingestion as best-effort on your side.