@nexttrace/next 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +114 -16
  2. package/dist/server.d.mts +15 -3
  3. package/dist/server.d.ts +15 -3
  4. package/dist/server.js +10 -3
  5. package/dist/server.mjs +8 -2
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -2,49 +2,84 @@
2
2
 
3
3
  > Next.js integration for **NextTrace** — the local-first, privacy-respecting API debugging overlay and developer observability toolkit.
4
4
 
5
+ [![npm version](https://img.shields.io/npm/v/@nexttrace/next.svg?style=flat-square&color=38bdf8)](https://www.npmjs.com/package/@nexttrace/next)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
7
+
5
8
  ## Features
6
9
 
7
- - ⚡ **Zero External Telemetry**: All events remain in local browser/server memory.
8
- - 🔒 **Deep Secret Redaction**: Automatically redacts Bearer tokens, API keys, passwords, and custom sensitive fields.
10
+ - ⚡ **Zero External Telemetry**: All events remain in local browser/server memory. No cloud accounts, no third-party endpoints.
11
+ - 🔒 **Deep Secret Redaction**: Automatically redacts Bearer tokens, API keys, passwords, cookies, and sensitive payload keys.
9
12
  - 🎯 **App Router Native**: Seamlessly captures client-side `fetch` and outgoing server-side `fetch` via Next.js instrumentation.
10
- - 🛠️ **Dev-Only Gating**: Tree-shaken in production; renders `null` unless `NODE_ENV === 'development'`.
13
+ - 🛠️ **Dev-Only Gating**: Zero production footprint; automatically tree-shaken and renders `null` when `NODE_ENV !== 'development'`.
14
+ - 🪟 **Dockable & Movable Overlay**: Dock to bottom, dock to right, or detach into a floating resizable window.
15
+
16
+ ---
11
17
 
12
18
  ## Installation
13
19
 
14
20
  ```bash
15
- # npm
21
+ # Using npm
16
22
  npm install --save-dev @nexttrace/next @nexttrace/core
17
23
 
18
- # pnpm
24
+ # Using pnpm
19
25
  pnpm add -D @nexttrace/next @nexttrace/core
26
+
27
+ # Using yarn
28
+ yarn add -D @nexttrace/next @nexttrace/core
29
+
30
+ # Using bun
31
+ bun add -d @nexttrace/next @nexttrace/core
20
32
  ```
21
33
 
22
- ## Quick Start
34
+ ---
35
+
36
+ ## Quick Start (Client-Side Tracing)
23
37
 
24
- ### 1. Mount the Client Overlay
38
+ ### 1. Mount the Overlay in Your Root Layout
25
39
 
26
- Add `<NextTraceOverlay />` to your root layout (`app/layout.tsx`):
40
+ Add `<NextTraceOverlay />` to your `app/layout.tsx`:
27
41
 
28
42
  ```tsx
29
43
  import { NextTraceOverlay } from '@nexttrace/next';
30
44
 
31
- export default function RootLayout({ children }: { children: React.ReactNode }) {
45
+ export default function RootLayout({
46
+ children,
47
+ }: {
48
+ children: React.ReactNode;
49
+ }) {
32
50
  return (
33
51
  <html lang="en">
34
52
  <body>
35
53
  {children}
36
- <NextTraceOverlay defaultPosition="bottom" />
54
+
55
+ {/* NextTrace DevTools Overlay (renders only in development) */}
56
+ <NextTraceOverlay
57
+ defaultPosition="bottom"
58
+ defaultTheme="dark"
59
+ />
37
60
  </body>
38
61
  </html>
39
62
  );
40
63
  }
41
64
  ```
42
65
 
43
- ### 2. (Optional) Trace Server-Side `fetch`
66
+ Now start your app with `npm run dev`. You'll see a sleek, minimalist launcher button in the bottom corner of your screen! Press **`Ctrl+Shift+X`** (or **`Cmd+Shift+X`**) to toggle the overlay.
67
+
68
+ ---
69
+
70
+ ## Server-Side `fetch` Instrumentation
71
+
72
+ NextTrace can capture outgoing HTTP requests originating from:
73
+ - **React Server Components (RSC)**
74
+ - **Server Actions**
75
+ - **Route Handlers (`app/api/...`)**
76
+
77
+ Follow these 3 simple steps:
44
78
 
45
- To capture outgoing `fetch` calls made inside Server Components, Server Actions, or Route Handlers:
79
+ ### Step 1: Next.js Configuration
46
80
 
47
- 1. Enable the instrumentation hook in `next.config.js`:
81
+ - **Next.js 15+**: `instrumentation.ts` is **stable and enabled by default**! You can skip directly to Step 2 without touching your `next.config`.
82
+ - **Next.js 14 & 13**: Enable `instrumentationHook` in `next.config.js` or `next.config.mjs`:
48
83
  ```js
49
84
  /** @type {import('next').NextConfig} */
50
85
  const nextConfig = {
@@ -56,23 +91,86 @@ const nextConfig = {
56
91
  module.exports = nextConfig;
57
92
  ```
58
93
 
59
- 2. Register server tracing in `instrumentation.ts` in your project root:
94
+ ---
95
+
96
+ ### Step 2: Register Server Tracing in `instrumentation.ts`
97
+
98
+ Create an `instrumentation.ts` file in the root of your project (or inside `src/` if you use a `src` directory):
99
+
60
100
  ```ts
61
101
  export async function register() {
62
- if (process.env.NEXT_RUNTIME === 'nodejs') {
102
+ // Only trace in Node.js runtime and in development
103
+ if (process.env.NEXT_RUNTIME === 'nodejs' && process.env.NODE_ENV === 'development') {
63
104
  const { traceNextServer } = await import('@nexttrace/next/server');
64
105
  traceNextServer();
65
106
  }
66
107
  }
67
108
  ```
68
109
 
69
- 3. Expose the dev-only collector route at `app/api/__nexttrace/route.ts`:
110
+ This intercepts outgoing server `fetch()` requests without altering their responses and stores them in a local, bounded FIFO ring buffer.
111
+
112
+ ---
113
+
114
+ ### Step 3: Expose the Dev-Only Collector Route
115
+
116
+ Create a Route Handler at `app/api/__nexttrace/route.ts`:
117
+
70
118
  ```ts
71
119
  import { createNextTraceRouteHandler } from '@nexttrace/next/server';
72
120
 
73
121
  export const { GET, POST } = createNextTraceRouteHandler();
74
122
  ```
75
123
 
124
+ > **Security Note:**
125
+ > This handler automatically returns `403 Forbidden` if `NODE_ENV === 'production'`. In development, it allows the browser overlay to poll server-side network events seamlessly.
126
+
127
+ ---
128
+
129
+ ## Optional Adapters
130
+
131
+ ### Axios Adapter
132
+ To trace Axios instances:
133
+
134
+ ```bash
135
+ npm install --save-dev @nexttrace/adapter-axios
136
+ ```
137
+
138
+ ```ts
139
+ import axios from 'axios';
140
+ import { traceAxios } from '@nexttrace/adapter-axios';
141
+
142
+ export const api = axios.create({ baseURL: 'https://api.example.com' });
143
+ traceAxios(api);
144
+ ```
145
+
146
+ ### TanStack Query (React Query) Adapter
147
+ To inspect query keys, cache events, and retries:
148
+
149
+ ```bash
150
+ npm install --save-dev @nexttrace/adapter-tanstack
151
+ ```
152
+
153
+ ```ts
154
+ import { QueryClient } from '@tanstack/react-query';
155
+ import { traceTanStackQuery } from '@nexttrace/adapter-tanstack';
156
+
157
+ export const queryClient = new QueryClient();
158
+ traceTanStackQuery(queryClient);
159
+ ```
160
+
161
+ ---
162
+
163
+ ## Overlay Props
164
+
165
+ | Prop | Type | Default | Description |
166
+ | :--- | :--- | :--- | :--- |
167
+ | `defaultPosition` | `'bottom' \| 'right' \| 'floating'` | `'bottom'` | Initial dock position for the overlay |
168
+ | `defaultTheme` | `'dark' \| 'light'` | `'dark'` | Visual theme |
169
+ | `initialOpen` | `boolean` | `true` | Whether the panel is expanded on initial page load |
170
+ | `serverPollIntervalMs` | `number` | `1000` | Background server event sync frequency (ms) |
171
+
172
+ ---
173
+
76
174
  ## License
77
175
 
78
176
  MIT © NextTrace Team
package/dist/server.d.mts CHANGED
@@ -6,10 +6,22 @@
6
6
  * Instruments globalThis.fetch on the Node.js server side in development
7
7
  */
8
8
  declare function instrumentServerFetch(): () => void;
9
+ /**
10
+ * Alias for instrumentServerFetch (used in documentation and standard naming)
11
+ */
12
+ declare const traceNextServer: typeof instrumentServerFetch;
13
+ type NextTraceRouteHandlerFn = () => Promise<Response>;
14
+ interface NextTraceRouteHandlers extends NextTraceRouteHandlerFn {
15
+ GET: NextTraceRouteHandlerFn;
16
+ POST: NextTraceRouteHandlerFn;
17
+ }
9
18
  /**
10
19
  * Next.js App Router Route Handler for `app/api/__nexttrace/route.ts`
11
- * Exposes server events in dev mode only.
20
+ * Supports both:
21
+ * export const { GET, POST } = createNextTraceRouteHandler();
22
+ * and:
23
+ * export const GET = createNextTraceRouteHandler();
12
24
  */
13
- declare function createNextTraceRouteHandler(): () => Promise<Response>;
25
+ declare function createNextTraceRouteHandler(): NextTraceRouteHandlers;
14
26
 
15
- export { createNextTraceRouteHandler, instrumentServerFetch };
27
+ export { type NextTraceRouteHandlerFn, type NextTraceRouteHandlers, createNextTraceRouteHandler, instrumentServerFetch, traceNextServer };
package/dist/server.d.ts CHANGED
@@ -6,10 +6,22 @@
6
6
  * Instruments globalThis.fetch on the Node.js server side in development
7
7
  */
8
8
  declare function instrumentServerFetch(): () => void;
9
+ /**
10
+ * Alias for instrumentServerFetch (used in documentation and standard naming)
11
+ */
12
+ declare const traceNextServer: typeof instrumentServerFetch;
13
+ type NextTraceRouteHandlerFn = () => Promise<Response>;
14
+ interface NextTraceRouteHandlers extends NextTraceRouteHandlerFn {
15
+ GET: NextTraceRouteHandlerFn;
16
+ POST: NextTraceRouteHandlerFn;
17
+ }
9
18
  /**
10
19
  * Next.js App Router Route Handler for `app/api/__nexttrace/route.ts`
11
- * Exposes server events in dev mode only.
20
+ * Supports both:
21
+ * export const { GET, POST } = createNextTraceRouteHandler();
22
+ * and:
23
+ * export const GET = createNextTraceRouteHandler();
12
24
  */
13
- declare function createNextTraceRouteHandler(): () => Promise<Response>;
25
+ declare function createNextTraceRouteHandler(): NextTraceRouteHandlers;
14
26
 
15
- export { createNextTraceRouteHandler, instrumentServerFetch };
27
+ export { type NextTraceRouteHandlerFn, type NextTraceRouteHandlers, createNextTraceRouteHandler, instrumentServerFetch, traceNextServer };
package/dist/server.js CHANGED
@@ -21,7 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
21
21
  var server_exports = {};
22
22
  __export(server_exports, {
23
23
  createNextTraceRouteHandler: () => createNextTraceRouteHandler,
24
- instrumentServerFetch: () => instrumentServerFetch
24
+ instrumentServerFetch: () => instrumentServerFetch,
25
+ traceNextServer: () => traceNextServer
25
26
  });
26
27
  module.exports = __toCommonJS(server_exports);
27
28
  var import_core = require("@nexttrace/core");
@@ -182,8 +183,9 @@ function instrumentServerFetch() {
182
183
  }
183
184
  };
184
185
  }
186
+ var traceNextServer = instrumentServerFetch;
185
187
  function createNextTraceRouteHandler() {
186
- return async function GET() {
188
+ const handler = async function GET() {
187
189
  if (process.env.NODE_ENV !== "development") {
188
190
  return new Response(JSON.stringify({ error: "Forbidden in production" }), {
189
191
  status: 403,
@@ -201,9 +203,14 @@ function createNextTraceRouteHandler() {
201
203
  }
202
204
  });
203
205
  };
206
+ const routeHandler = handler;
207
+ routeHandler.GET = handler;
208
+ routeHandler.POST = handler;
209
+ return routeHandler;
204
210
  }
205
211
  // Annotate the CommonJS export names for ESM import in node:
206
212
  0 && (module.exports = {
207
213
  createNextTraceRouteHandler,
208
- instrumentServerFetch
214
+ instrumentServerFetch,
215
+ traceNextServer
209
216
  });
package/dist/server.mjs CHANGED
@@ -164,8 +164,9 @@ function instrumentServerFetch() {
164
164
  }
165
165
  };
166
166
  }
167
+ var traceNextServer = instrumentServerFetch;
167
168
  function createNextTraceRouteHandler() {
168
- return async function GET() {
169
+ const handler = async function GET() {
169
170
  if (process.env.NODE_ENV !== "development") {
170
171
  return new Response(JSON.stringify({ error: "Forbidden in production" }), {
171
172
  status: 403,
@@ -183,8 +184,13 @@ function createNextTraceRouteHandler() {
183
184
  }
184
185
  });
185
186
  };
187
+ const routeHandler = handler;
188
+ routeHandler.GET = handler;
189
+ routeHandler.POST = handler;
190
+ return routeHandler;
186
191
  }
187
192
  export {
188
193
  createNextTraceRouteHandler,
189
- instrumentServerFetch
194
+ instrumentServerFetch,
195
+ traceNextServer
190
196
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nexttrace/next",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Next.js integration for NextTrace with dev-only gating, server fetch collection, and overlay component",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -34,7 +34,7 @@
34
34
  },
35
35
  "dependencies": {
36
36
  "@nexttrace/core": "0.1.0",
37
- "@nexttrace/devtools": "0.1.0"
37
+ "@nexttrace/devtools": "0.1.2"
38
38
  },
39
39
  "peerDependencies": {
40
40
  "next": ">=13.0.0 || >=14.0.0 || >=15.0.0",