> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usetusk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CommonJS

> Learn how to initialize Tusk Drift in a CJS application

<Note>
  The code examples in this guide use `import`/`export` syntax. If your project
  is JavaScript, adapt the examples to use `require()`/`module.exports` instead.
</Note>

## 1. Create init file

Create a `tuskDriftInit.ts` or `tuskDriftInit.js` file to initialize the Tusk Drift SDK.

```ts theme={null}
import { TuskDrift } from "@use-tusk/drift-node-sdk";

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

export { TuskDrift };
```

### Initialization Parameters

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Type</th>
      <th>Default</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>apiKey</code>
      </td>

      <td>
        <code>string</code>
      </td>

      <td>
        <b>Required if using Tusk Cloud</b>
      </td>

      <td>Your Tusk Drift API key.</td>
    </tr>

    <tr>
      <td>
        <code>env</code>
      </td>

      <td>
        <code>string</code>
      </td>

      <td>
        <code>process.env.NODE\_ENV</code>
      </td>

      <td>The environment name.</td>
    </tr>

    <tr>
      <td>
        <code>logLevel</code>
      </td>

      <td>
        <code>'silent' | 'error' | 'warn' | 'info' | 'debug'</code>
      </td>

      <td>
        <code>'info'</code>
      </td>

      <td>The logging level.</td>
    </tr>

    <tr>
      <td>
        <code>samplingRate</code>
      </td>

      <td>
        <code>number</code>
      </td>

      <td>
        <code>1.0</code>
      </td>

      <td>
        Override the base sampling rate (0.0 - 1.0) for recording. Takes
        precedence over <code>TUSK\_RECORDING\_SAMPLING\_RATE</code> and config file base-rate
        settings.
      </td>
    </tr>

    <tr>
      <td>
        <code>registerEsmLoaderHooks</code>
      </td>

      <td>
        <code>boolean</code>
      </td>

      <td>
        <code>true</code>
      </td>

      <td>
        Automatically register ESM loader hooks for module interception. Set to{" "}
        <code>false</code> to disable if you encounter issues with specific
        instrumented packages.
      </td>
    </tr>
  </tbody>
</table>

## 2. Import SDK at application entry point

In your main server file (e.g., `server.ts`, `index.ts`, `app.ts`), import this file at the very top before any other imports. This ensures proper instrumentation of all dependencies.

```ts theme={null}
// e.g. server.ts
import { TuskDrift } from "./tuskDriftInit"; // MUST be the first import

// ... other imports ...

// Your application setup ...
```

## 3. Update recording configurations

Update the configuration file `.tusk/config.yaml` to include a `recording` section.

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

```yaml theme={null}
# ... 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

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Type</th>
      <th>Default</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>sampling.mode</code>
      </td>

      <td>
        <code>string</code>
      </td>

      <td>
        <code>"fixed"</code>
      </td>

      <td>
        Selects constant sampling or adaptive load shedding.
      </td>
    </tr>

    <tr>
      <td>
        <code>sampling.base\_rate</code>
      </td>

      <td>
        <code>number</code>
      </td>

      <td>
        <code>1.0</code>
      </td>

      <td>
        The base sampling rate (0.0 - 1.0). In <code>fixed</code> mode this is
        the effective rate. In <code>adaptive</code> mode the SDK may
        temporarily reduce below this base rate.
      </td>
    </tr>

    <tr>
      <td>
        <code>sampling.min\_rate</code>
      </td>

      <td>
        <code>number</code>
      </td>

      <td>
        <code>0.001</code> in <code>adaptive</code> mode
      </td>

      <td>
        The minimum steady-state sampling rate for adaptive mode. In critical
        conditions the SDK can still temporarily pause recording.
      </td>
    </tr>

    <tr>
      <td>
        <code>sampling.log\_transitions</code>
      </td>

      <td>
        <code>boolean</code>
      </td>

      <td>
        <code>true</code>
      </td>

      <td>
        Controls whether the SDK emits adaptive-sampling transition logs. Can
        also be overridden by{" "}
        <code>TUSK\_RECORDING\_SAMPLING\_LOG\_TRANSITIONS</code>.
      </td>
    </tr>

    <tr>
      <td>
        <code>sampling\_rate</code>
      </td>

      <td>
        <code>number</code>
      </td>

      <td>
        <code>None</code>
      </td>

      <td>
        Legacy alias for <code>recording.sampling.base\_rate</code>. Still
        supported for backward compatibility.
      </td>
    </tr>

    <tr>
      <td>
        <code>export\_spans</code>
      </td>

      <td>
        <code>boolean</code>
      </td>

      <td>
        <code>false</code>
      </td>

      <td>
        Whether to export spans to Tusk backend or local files (
        <code>.tusk/traces</code>). If false, spans are only exported to local
        files.
      </td>
    </tr>

    <tr>
      <td>
        <code>enable\_env\_var\_recording</code>
      </td>

      <td>
        <code>boolean</code>
      </td>

      <td>
        <code>false</code>
      </td>

      <td>
        Whether 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.
      </td>
    </tr>
  </tbody>
</table>

## 4. Mark the app as ready

Once your application is ready to accept requests, mark it as ready:

```typescript theme={null}
// e.g. 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");
});
```

To record your first set of API tests with Tusk Drift, view [this guide](/api-tests/record-replay-tests).