Skip to main content
Tusk Drift is in private beta. Reach out to support@usetusk.ai for cloud access.

​
Prerequisites

  • Node.js service (backend) where the SDK will be installed
  • Tusk account with Team or Enterprise access
  • Dev/staging environment for initial rollout (recommended)

​
Overview

Tusk Drift SDK captures real API calls from your service and deterministically replays them to detect regressions. During replay, outbound requests are intercepted and served from recorded data so results are stable, side-effect free, and fast enough for CI.

​
Supported technologies

  • HTTP/HTTPS: All versions (Node.js built-in)
  • PG: pg@8.x, pg-pool@2.x–3.x
  • Postgres: postgres@3.x
  • JSON Web Tokens: jsonwebtoken@5.x–9.x
  • JWKS RSA: jwks-rsa@1.x–3.x
  • GraphQL: graphql@15.x–16.x
View the complete list of supported packages and versions in our public repo.

​
Setup

1

Install the Tusk CLI

Build the CLI locally and verify installation:
# Go 1.25+
git clone https://github.com/Use-Tusk/tusk-drift-cli.git
cd tusk-drift-cli
make deps
make build
./tusk --help
2

Set up the Tusk Drift config

Create your .tusk/config.yaml in the root of your service using the onboarding wizard:
cd <path/to/your/service>
tusk init
The wizard will generate .tusk/config.yaml. You can also create the .tusk directory and config file manually in your service root. See the configuration docs for details.
3

Install the Drift SDK

Install the SDK in your service:
npm install @use-tusk/drift-node-sdk
4

Obtain a Tusk Drift API key

Sign in to the Tusk web app, navigate to Settings > API Keys and click Create key. Name the key (e.g., “Tusk Drift”), copy it on creation, and store it securely.
5

Initialize and import SDK

1. For CommonJS Applications:Create a tdInit.ts file to initialize the Tusk Drift SDK.
// tdInit.ts
import { TuskDrift } from "@use-tusk/drift-node-sdk";

// Initialize SDK immediately
TuskDrift.initialize({
  apiKey: process.env.TUSK_DRIFT_API_KEY,
  env: process.env.ENV,
  logLevel: process.env.TUSK_DRIFT_LOG_LEVEL,
});

export { TuskDrift };
In your main server file (e.g., server.ts, index.ts, app.ts), import this file at the very top before any other imports. This ensures proper instrumentation of all dependencies.
// server.ts (or index.ts/app.ts)
import { TuskDrift } from "./tdInit"; // MUST be the first import

// ... other imports ...

// Your application setup ...
2. For ESM ApplicationsESM applications require additional setup to properly intercept module imports:
// tdInit.ts
import { register } from 'node:module';
import { pathToFileURL } from 'node:url';

// Register the ESM loader
// This enables interception of ESM module imports
register('@use-tusk/drift-node-sdk/hook.mjs', pathToFileURL('./'));

import { TuskDrift } from "@use-tusk/drift-node-sdk";

// Initialize SDK immediately
TuskDrift.initialize({
  apiKey: process.env.TUSK_DRIFT_API_KEY,
  env: process.env.ENV,
  logLevel: process.env.TUSK_DRIFT_LOG_LEVEL,
});

export { TuskDrift };
For ESM applications, you cannot control import order within your application code because all imports are hoisted. Instead, use the —import flag:Update your package.json scripts:
{
  "scripts": {
    "dev": "node --import ./dist/tdInit.js dist/server.js"
    "dev:record": "TUSK_DRIFT_MODE=RECORD node --import ./dist/tdInit.js dist/server.js"
  }
}
--import is required because all import statements in ESM are hoisted and evaluated before any code runs, making it impossible to control import order within a file. The --import flag ensures the SDK initialization (including loader registration) happens in a separate phase before your application code loads, guaranteeing proper module interception.
6

Mark the app as ready

Once your server is listening, signal readiness so recording/replay begins only after initialization completes:
// server.ts
import { TuskDrift } from "./tdInit";

// ... other imports ...

const app = express();

// Your application setup...

app.listen(8000, () => {
  // Mark app as ready for recording/replay
  TuskDrift.markAppAsReady();
  console.log("Server started and ready for Tusk Drift");
});
7

Configure recording policies

In .tusk/config.yaml, add or adjust a recording section. These controls help enterprises manage data capture and cost:
recording:
  sampling_rate: 0.1             # 10% of requests recorded (set 1.0 to capture all)
  export_spans: true              # export spans to Tusk backend and local files
  enable_env_var_recording: true  # record/replay env vars that affect behavior
  • sampling_rate: 0.0–1.0. Use lower rates for production, increase temporarily during onboarding.
  • export_spans: If disabled, spans are written locally under .tusk/traces only.
  • enable_env_var_recording: Recommended when business logic depends on environment configuration.
⌘I