@nexttrace/next 0.1.0 → 0.1.1

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 (2) hide show
  1. package/README.md +116 -16
  2. package/package.json +1 -1
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:
78
+
79
+ ### Step 1: Enable the Instrumentation Hook in Next.js
44
80
 
45
- To capture outgoing `fetch` calls made inside Server Components, Server Actions, or Route Handlers:
81
+ In your `next.config.js` or `next.config.mjs`, enable `instrumentationHook`:
46
82
 
47
- 1. Enable the instrumentation hook in `next.config.js`:
48
83
  ```js
49
84
  /** @type {import('next').NextConfig} */
50
85
  const nextConfig = {
@@ -56,23 +91,88 @@ const nextConfig = {
56
91
  module.exports = nextConfig;
57
92
  ```
58
93
 
59
- 2. Register server tracing in `instrumentation.ts` in your project root:
94
+ *(Note: In Next.js 15+, `instrumentationHook` is stable and enabled by default).*
95
+
96
+ ---
97
+
98
+ ### Step 2: Register Server Tracing in `instrumentation.ts`
99
+
100
+ Create an `instrumentation.ts` file in the root of your project (or inside `src/` if you use a `src` directory):
101
+
60
102
  ```ts
61
103
  export async function register() {
62
- if (process.env.NEXT_RUNTIME === 'nodejs') {
104
+ // Only trace in Node.js runtime and in development
105
+ if (process.env.NEXT_RUNTIME === 'nodejs' && process.env.NODE_ENV === 'development') {
63
106
  const { traceNextServer } = await import('@nexttrace/next/server');
64
107
  traceNextServer();
65
108
  }
66
109
  }
67
110
  ```
68
111
 
69
- 3. Expose the dev-only collector route at `app/api/__nexttrace/route.ts`:
112
+ This intercepts outgoing server `fetch()` requests without altering their responses and stores them in a local, bounded FIFO ring buffer.
113
+
114
+ ---
115
+
116
+ ### Step 3: Expose the Dev-Only Collector Route
117
+
118
+ Create a Route Handler at `app/api/__nexttrace/route.ts`:
119
+
70
120
  ```ts
71
121
  import { createNextTraceRouteHandler } from '@nexttrace/next/server';
72
122
 
73
123
  export const { GET, POST } = createNextTraceRouteHandler();
74
124
  ```
75
125
 
126
+ > **Security Note:**
127
+ > This handler automatically returns `403 Forbidden` if `NODE_ENV === 'production'`. In development, it allows the browser overlay to poll server-side network events seamlessly.
128
+
129
+ ---
130
+
131
+ ## Optional Adapters
132
+
133
+ ### Axios Adapter
134
+ To trace Axios instances:
135
+
136
+ ```bash
137
+ npm install --save-dev @nexttrace/adapter-axios
138
+ ```
139
+
140
+ ```ts
141
+ import axios from 'axios';
142
+ import { traceAxios } from '@nexttrace/adapter-axios';
143
+
144
+ export const api = axios.create({ baseURL: 'https://api.example.com' });
145
+ traceAxios(api);
146
+ ```
147
+
148
+ ### TanStack Query (React Query) Adapter
149
+ To inspect query keys, cache events, and retries:
150
+
151
+ ```bash
152
+ npm install --save-dev @nexttrace/adapter-tanstack
153
+ ```
154
+
155
+ ```ts
156
+ import { QueryClient } from '@tanstack/react-query';
157
+ import { traceTanStackQuery } from '@nexttrace/adapter-tanstack';
158
+
159
+ export const queryClient = new QueryClient();
160
+ traceTanStackQuery(queryClient);
161
+ ```
162
+
163
+ ---
164
+
165
+ ## Overlay Props
166
+
167
+ | Prop | Type | Default | Description |
168
+ | :--- | :--- | :--- | :--- |
169
+ | `defaultPosition` | `'bottom' \| 'right' \| 'floating'` | `'bottom'` | Initial dock position for the overlay |
170
+ | `defaultTheme` | `'dark' \| 'light'` | `'dark'` | Visual theme |
171
+ | `initialOpen` | `boolean` | `true` | Whether the panel is expanded on initial page load |
172
+ | `serverPollIntervalMs` | `number` | `1000` | Background server event sync frequency (ms) |
173
+
174
+ ---
175
+
76
176
  ## License
77
177
 
78
178
  MIT © NextTrace Team
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nexttrace/next",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
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",