Skip to main content

​
1. Configure Next.js with withTuskDrift

Wrap your Next.js configuration with the withTuskDrift function in your next.config.js or next.config.mjs file:

​
Basic Configuration

const { withTuskDrift } = require("@use-tusk/drift-node-sdk/next");

module.exports = withTuskDrift({
  // Your Next.js config
});

​
With Debug Logging for Next.js Integration

const { withTuskDrift } = require("@use-tusk/drift-node-sdk/next");

module.exports = withTuskDrift(
  {
    // Your Next.js config
  },
  {
    // Tusk Drift options
    debug: true, // Enable debug logging
  },
);

​
What withTuskDrift Does

The withTuskDrift wrapper automatically:
  • Enables the Next.js instrumentation hook (for Next.js < 15.0.0-rc.1)
  • Configures webpack externals for proper module interception
  • Detects your Next.js version and adjusts configuration accordingly
  • Preserves your existing Next.js configuration

​
Configuration Options

OptionTypeDefaultDescription
debugbooleanfalseEnable debug logging to see what Tusk Drift is configuring during build.
disableInstrumentationHookbooleanfalseDisable automatic setting of experimental.instrumentationHook. Not recommended, will break Tusk Drift’s Next.js integration.
suppressWarningsbooleanfalseSuppress all warnings from Tusk Drift’s Next.js integration.

​
2. Create instrumentation file

Create an instrumentation.ts (or .js) file at the root of your Next.js project (or inside the src folder if using one): 
// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { TuskDrift } = await import("@use-tusk/drift-node-sdk");

    TuskDrift.initialize({
      // Add API key once you are initializing Cloud
      // apiKey: process.env.TUSK_DRIFT_API_KEY,
      env: process.env.NODE_ENV,
      logLevel: "debug",
    });

    // Mark app as ready immediately
    TuskDrift.markAppAsReady();
  }
}
More context on setting up instrumentations for Next.js apps can be found here.

​
Initialization Parameters

OptionTypeDefaultDescription
apiKeystringRequired if using Tusk CloudYour Tusk Drift API key from the dashboard.
envstringprocess.env.NODE_ENVThe environment name (e.g., ‘dev’, ‘staging’, ‘production’).
logLevel’silent’ | ‘error’ | ‘warn’ | ‘info’ | ‘debug''info’The logging level for the Tusk Drift SDK.
samplingRatenumber1.0Override the base sampling rate (0.0 - 1.0) for recording. Takes precedence over TUSK_RECORDING_SAMPLING_RATE and config file base-rate settings.

​
3. Update package.json scripts

In your package.json file, manually add a script for "dev:record" that allows you to start the service with Tusk Drift in record mode. 
{
  "scripts": {
    "dev": "next dev",
    "dev:record": "TUSK_DRIFT_MODE=RECORD next dev"
  }
}

​
4. Update recording configurations

Update the .tusk/config.yaml file in your project root to include recording configurations. If you’re testing Tusk Drift out locally for the first time, use fixed mode with a base rate of 1.0. After testing, we generally recommend adaptive mode with a base rate between 0.01 and 0.1. 
# ... existing configuration ...

recording:
  sampling:
    mode: adaptive
    base_rate: 0.1
    min_rate: 0.01
    log_transitions: true
  export_spans: true
  enable_env_var_recording: true
TUSK_RECORDING_SAMPLING_RATE overrides recording.sampling.base_rate. TUSK_SAMPLING_RATE is still supported as a legacy alias, and recording.sampling_rate remains a legacy config alias.

​
Configuration Options

OptionTypeDefaultDescription
sampling.modestring”fixed”Selects constant sampling or adaptive load shedding.
sampling.base_ratenumber1.0The base sampling rate (0.0 - 1.0). In fixed mode this is the effective rate. In adaptive mode the SDK may temporarily reduce below this base rate.
sampling.min_ratenumber0.001 in adaptive modeThe minimum steady-state sampling rate for adaptive mode. In critical conditions the SDK can still temporarily pause recording.
sampling.log_transitionsbooleantrueControls whether the SDK emits adaptive-sampling transition logs. Can also be overridden by TUSK_RECORDING_SAMPLING_LOG_TRANSITIONS.
sampling_ratenumberNoneLegacy alias for recording.sampling.base_rate. Still supported for backward compatibility.
export_spansbooleanfalseWhether to export spans to the Tusk backend. If false, spans are only saved locally in .tusk/traces.
enable_env_var_recordingbooleanfalseWhether to record and replay environment variables. Recommended for accurate replay behavior if your app’s logic depends on environment variables.
To record your first set of API tests with Tusk Drift, view this guide.

​
Troubleshooting

If logs are showing that your packages aren’t being instrumented:
  1. Check file location: Ensure instrumentation.ts is at the project root (same level as next.config.js), not in the app or pages directory.
  2. Check runtime guard: Make sure you have the NEXT_RUNTIME === 'nodejs' check in your register() function.
  3. Enable debug logging: Set debug: true in your withTuskDrift options to see what’s being configured.