Skip to main content
Next.js support is currently in beta. Reach out to Support if you have questions.

​
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

  • CommonJS (next.config.js)
  • ESM (next.config.mjs)
const { withTuskDrift } = require("@use-tusk/drift-node-sdk");

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

​
With Debug Logging for Next.js Integration

  • CommonJS (next.config.js)
  • ESM (next.config.mjs)
const { withTuskDrift } = require("@use-tusk/drift-node-sdk");

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({
      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.

​
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, set sampling rate to 1.0. After testing, we recommend a sampling rate between 0.01-0.1. 
# ... 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 no requests are recorded.
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.