Skip to main content

​
1. Create init file

ESM applications require additional setup to properly intercept module imports: 
// tuskDriftInit.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.NODE_ENV,
});

export { TuskDrift };
Why the ESM loader is needed: ESM imports are statically analyzed and hoisted, meaning all imports are resolved before any code runs. The register() call sets up Node.js loader hooks that intercept module imports, allowing the SDK to instrument packages like postgres, http, etc. Without this, the SDK cannot patch ESM modules.

​
Initialization Parameters

OptionTypeDefaultDescription
apiKeystringRequired if using Tusk CloudYour Tusk Drift API key.
envstringprocess.env.NODE_ENVThe environment name.
logLevel’silent’ | ‘error’ | ‘warn’ | ‘info’ | ‘debug''info’The logging level.

​
2. Import SDK at application entry point

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/tuskDriftInit.js dist/server.js",
    "dev:record": "TUSK_DRIFT_MODE=RECORD node --import ./dist/tuskDriftInit.js dist/server.js"
  }
}
Why --import is required for ESM: In ESM, all import statements 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.

​
3. Update recording configurations

Update the configuration file .tusk/config.yaml to include a recording section. Example recording configuration: 
# ... existing configuration ...

recording:
  sampling_rate: 0.1
  export_spans: true
  enable_env_var_recording: true

​
Configuration Options

OptionTypeDefaultDescription
sampling_ratenumber1.0The sampling rate (0.0 - 1.0). 1.0 means 100% of requests are recorded, 0.0 means 0% of requests are recorded.
export_spansbooleanfalseWhether to export spans to Tusk backend or local files (.tusk/traces). If false, spans are only exported to local files.
enable_env_var_recordingbooleanfalseWhether to enable environment variable recording and replaying. Recommended if your application’s business logic depends on environment variables, as this ensures the most accurate replay behavior.

​
4. Mark the app as ready

Once your application is ready to accept requests, mark it as ready: 
// server.ts
import { TuskDrift } from "./tuskDriftInit";

// ... 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");
});
⌘I