Next.js

Learn how to initialize Tusk Drift in a Next.js application

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)

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)

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

Option	Type	Default	Description
debug	boolean	false	Enable debug logging to see what Tusk Drift is configuring during build.
disableInstrumentationHook	boolean	false	Disable automatic setting of experimental.instrumentationHook. Not recommended, will break Tusk Drift’s Next.js integration.
suppressWarnings	boolean	false	Suppress 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

Option	Type	Default	Description
apiKey	string	Required if using Tusk Cloud	Your Tusk Drift API key from the dashboard.
env	string	process.env.NODE_ENV	The 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

Option	Type	Default	Description
sampling_rate	number	1.0	The sampling rate (0.0 - 1.0). 1.0 means 100% of requests are recorded, 0.0 means no requests are recorded.
export_spans	boolean	false	Whether to export spans to the Tusk backend. If false, spans are only saved locally in .tusk/traces.
enable_env_var_recording	boolean	false	Whether 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

My packages aren't being instrumented

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.