Skip to content

Commit b21d20d

Browse files
sohankshirsagarsohankshirsagar
authored
feat: add Next.js support (#27)
* working nextjs-instrumentation * next config support + docs * remove log
1 parent 9bf2af8 commit b21d20d

16 files changed

Lines changed: 2200 additions & 13 deletions

‎docs/initialization.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,10 @@ Before setting up the SDK, ensure you have:
77
- Completed the [CLI wizard](https://github.com/Use-Tusk/tusk-drift-cli?tab=readme-ov-file#quick-start)
88
- Obtained an API key from the [Tusk Drift dashboard](https://usetusk.ai/app/settings/api-keys) (only required if using Tusk Cloud)
99

10-
Follow these steps in order to properly initialize the Tusk Drift SDK:
10+
> **📦 Using Next.js?** Next.js applications require a different initialization process.
11+
> **[Go to the Next.js Initialization Guide →](./nextjs-initialization.md)**
12+
13+
For **standard Node.js applications** (Express, Fastify, plain Node.js, etc.), follow these steps in order to properly initialize the Tusk Drift SDK:
1114

1215
## 1. Create SDK Initialization File
1316

@@ -36,12 +39,12 @@ ESM applications require additional setup to properly intercept module imports:
3639

3740
```typescript
3841
// tuskDriftInit.ts
39-
import { register } from 'node:module';
40-
import { pathToFileURL } from 'node:url';
42+
import { register } from "node:module";
43+
import { pathToFileURL } from "node:url";
4144

4245
// Register the ESM loader
4346
// This enables interception of ESM module imports
44-
register('@use-tusk/drift-node-sdk/hook.mjs', pathToFileURL('./'));
47+
register("@use-tusk/drift-node-sdk/hook.mjs", pathToFileURL("./"));
4548

4649
import { TuskDrift } from "@use-tusk/drift-node-sdk";
4750

‎docs/nextjs-initialization.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# Next.js Initialization
2+
3+
This guide explains how to set up Tusk Drift in your Next.js application.
4+
5+
## Step 1: Configure Next.js with `withTuskDrift`
6+
7+
Wrap your Next.js configuration with the `withTuskDrift` function in your `next.config.js` or `next.config.ts` file:
8+
9+
### Basic Configuration
10+
11+
```javascript
12+
// next.config.js
13+
const { withTuskDrift } = require("@use-tusk/drift-node-sdk");
14+
15+
module.exports = withTuskDrift({
16+
// Your Next.js config
17+
});
18+
```
19+
20+
### With Debug Logging for Next.js Integration
21+
22+
```javascript
23+
// next.config.js
24+
const { withTuskDrift } = require("@use-tusk/drift-node-sdk");
25+
26+
module.exports = withTuskDrift(
27+
{
28+
// Your Next.js config
29+
},
30+
{
31+
// Tusk Drift options
32+
debug: true, // Enable debug logging
33+
},
34+
);
35+
```
36+
37+
### What `withTuskDrift` Does
38+
39+
The `withTuskDrift` wrapper automatically:
40+
41+
- ✅ Enables the Next.js instrumentation hook (for Next.js < 15.0.0-rc.1)
42+
- ✅ Configures webpack externals for proper module interception
43+
- ✅ Detects your Next.js version and adjusts configuration accordingly
44+
- ✅ Preserves your existing Next.js configuration
45+
46+
### Configuration Options
47+
48+
<table>
49+
<thead>
50+
<tr>
51+
<th>Option</th>
52+
<th>Type</th>
53+
<th>Default</th>
54+
<th>Description</th>
55+
</tr>
56+
</thead>
57+
<tbody>
58+
<tr>
59+
<td><code>debug</code></td>
60+
<td><code>boolean</code></td>
61+
<td><code>false</code></td>
62+
<td>Enable debug logging to see what Tusk Drift is configuring during build.</td>
63+
</tr>
64+
<tr>
65+
<td><code>disableInstrumentationHook</code></td>
66+
<td><code>boolean</code></td>
67+
<td><code>false</code></td>
68+
<td>Disable automatic setting of <code>experimental.instrumentationHook</code>. Not recommended, will break Tusk Drift's Next.js integration.</td>
69+
</tr>
70+
<tr>
71+
<td><code>suppressWarnings</code></td>
72+
<td><code>boolean</code></td>
73+
<td><code>false</code></td>
74+
<td>Suppress all warnings from Tusk Drift's Next.js integration.</td>
75+
</tr>
76+
</tbody>
77+
</table>
78+
79+
## Step 2: Create Instrumentation File
80+
81+
Create an `instrumentation.ts` (or `.js`) file at the **root of your Next.js project**, at the same level as `next.config.js`:
82+
83+
```typescript
84+
// instrumentation.ts
85+
export async function register() {
86+
if (process.env.NEXT_RUNTIME === "nodejs") {
87+
const { TuskDrift } = await import("@use-tusk/drift-node-sdk");
88+
89+
TuskDrift.initialize({
90+
apiKey: process.env.TUSK_DRIFT_API_KEY,
91+
env: process.env.NODE_ENV,
92+
logLevel: "debug",
93+
});
94+
95+
// Mark app as ready immediately
96+
TuskDrift.markAppAsReady();
97+
}
98+
}
99+
```
100+
101+
More context on setting up instrumentations for Next.js apps can be found [here](https://nextjs.org/docs/app/guides/instrumentation).
102+
103+
### Initialization Parameters
104+
105+
<table>
106+
<thead>
107+
<tr>
108+
<th>Option</th>
109+
<th>Type</th>
110+
<th>Default</th>
111+
<th>Description</th>
112+
</tr>
113+
</thead>
114+
<tbody>
115+
<tr>
116+
<td><code>apiKey</code></td>
117+
<td><code>string</code></td>
118+
<td><b>Required if using Tusk Cloud</b></td>
119+
<td>Your Tusk Drift API key from the <a href="https://usetusk.ai/app/settings/api-keys">dashboard</a>.</td>
120+
</tr>
121+
<tr>
122+
<td><code>env</code></td>
123+
<td><code>string</code></td>
124+
<td><code>process.env.NODE_ENV</code></td>
125+
<td>The environment name (e.g., 'dev', 'staging', 'production').</td>
126+
</tr>
127+
<tr>
128+
<td><code>logLevel</code></td>
129+
<td><code>'silent' | 'error' | 'warn' | 'info' | 'debug'</code></td>
130+
<td><code>'info'</code></td>
131+
<td>The logging level for the Tusk Drift SDK.</td>
132+
</tr>
133+
</tbody>
134+
</table>
135+
136+
**Update your package.json scripts**:
137+
138+
```json
139+
{
140+
"scripts": {
141+
"dev": "next dev",
142+
"dev:record": "TUSK_DRIFT_MODE=RECORD next dev"
143+
}
144+
}
145+
```
146+
147+
## Step 3: Update Configuration File
148+
149+
Update the `.tusk/config.yaml` file in your project root to include recording configuration:
150+
151+
```yaml
152+
# ... existing configuration ...
153+
154+
recording:
155+
sampling_rate: 0.1
156+
export_spans: true
157+
enable_env_var_recording: true
158+
```
159+
160+
### Configuration Options
161+
162+
<table>
163+
<thead>
164+
<tr>
165+
<th>Option</th>
166+
<th>Type</th>
167+
<th>Default</th>
168+
<th>Description</th>
169+
</tr>
170+
</thead>
171+
<tbody>
172+
<tr>
173+
<td><code>sampling_rate</code></td>
174+
<td><code>number</code></td>
175+
<td><code>1.0</code></td>
176+
<td>The sampling rate (0.0 - 1.0). 1.0 means 100% of requests are recorded, 0.0 means no requests are recorded.</td>
177+
</tr>
178+
<tr>
179+
<td><code>export_spans</code></td>
180+
<td><code>boolean</code></td>
181+
<td><code>false</code></td>
182+
<td>Whether to export spans to the Tusk backend. If false, spans are only saved locally in <code>.tusk/traces</code>.</td>
183+
</tr>
184+
<tr>
185+
<td><code>enable_env_var_recording</code></td>
186+
<td><code>boolean</code></td>
187+
<td><code>false</code></td>
188+
<td>Whether to record and replay environment variables. Recommended for accurate replay behavior if your app's logic depends on environment variables.</td>
189+
</tr>
190+
</tbody>
191+
</table>
192+
193+
## Troubleshooting
194+
195+
### Instrumentation not working
196+
197+
If your packages aren't being instrumented:
198+
199+
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.
200+
201+
2. **Check runtime guard**: Make sure you have the `NEXT_RUNTIME === 'nodejs'` check in your `register()` function.
202+
203+
3. **Enable debug logging**: Set `debug: true` in your `withTuskDrift` options to see what's being configured.

0 commit comments

Comments
 (0)