nextjs-initialization.md

Next.js Initialization (Beta)

This guide explains how to set up Tusk Drift in your Next.js application.

Step 1: Configure Next.js with withTuskDrift

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

Basic Configuration

CommonJS (next.config.js)

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

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

ESM (next.config.mjs)

// next.config.mjs
import { withTuskDrift } from "@use-tusk/drift-node-sdk/next";

export default withTuskDrift({
  // Your Next.js config
});

With Debug Logging for Next.js Integration

CommonJS (next.config.js)

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

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

ESM (next.config.mjs)

// next.config.mjs
import { withTuskDrift } from "@use-tusk/drift-node-sdk/next";

export default 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.

Step 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_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.
samplingRate	number	1.0	Override sampling rate (0.0 - 1.0) for recording. Takes precedence over TUSK_SAMPLING_RATE env var and config file.

Update your package.json scripts:

{
  "scripts": {
    "dev": "next dev",
    "dev:record": "TUSK_DRIFT_MODE=RECORD next dev"
  }
}

Step 3: Configure Sampling Rate

The sampling rate determines what percentage of requests are recorded during replay tests. Tusk Drift supports three ways to configure the sampling rate, with the following precedence (highest to lowest):

1. Init Parameter
2. Environment Variable (TUSK_SAMPLING_RATE)
3. Configuration File (.tusk/config.yaml)

If not specified, the default sampling rate is 1.0 (100%).

Method 1: Init Parameter

Set the sampling rate directly in your initialization code:

// 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_API_KEY,
      env: process.env.NODE_ENV,
      samplingRate: 0.1, // 10% of requests
    });

    TuskDrift.markAppAsReady();
  }
}

Method 2: Environment Variable

Set the TUSK_SAMPLING_RATE environment variable:

# Development - record everything
TUSK_SAMPLING_RATE=1.0 npm run dev

# Production - sample 10% of requests
TUSK_SAMPLING_RATE=0.1 npm start

Method 3: Configuration File

Update the .tusk/config.yaml file in your project root to include recording configuration:

# ... existing configuration ...

recording:
  sampling_rate: 0.1
  export_spans: true
  enable_env_var_recording: true

Additional Recording 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.

Troubleshooting

Instrumentation not working

If 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.