Getting started

ReplayStack records what happened on your backend—requests, responses, failures, and context—so you can inspect and replay them in the dashboard. Your app only talks to the ReplayStack API; nothing is sent straight to the browser UI.

How this guide is organized

Use the left nav in order: Authentication and env vars → TypeScript & JavaScript for the client → your framework (Express, Next.js, NestJS) for automatic HTTP capture. Prefer Send Events API only if you are not using the Node SDK.

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, so a minimal setup can be just the key and (if needed) endpoint.

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 ReplayStack default host
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).	true (REPLAYSTACK_CAPTURE_SUCCESS)
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).	none beyond defaults
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

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.

Install the SDK

Pick one package manager:

Installbash

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

Configure environment variables
Set at least REPLAYSTACK_API_KEY and REPLAYSTACK_ENDPOINT. Full list is on the Authentication page.

Send one test event (optional)

Minimal client setup

Only apiKey is strictly required. See Client options reference above for every field, defaults, and environment fallbacks.

Confirms your key and URL before you wire a framework:

Minimal manual eventtypescript

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

const replayStack = new ReplayStackClient({
  // Required — project key from the dashboard.
  apiKey: process.env.REPLAYSTACK_API_KEY!,
  // Optional — API base; omit if REPLAYSTACK_ENDPOINT is set in the environment.
  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
Open Express, Next.js, or NestJS in this guide and add the middleware or wrappers there— that is where most of the code lives.

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.