@nextscope/next 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vercel Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# NextScope
+
+NextScope is a local OpenTelemetry trace inspector for `next dev`.
+
+It is designed for Next.js 16 apps that already use `@vercel/otel >= 2.1`.
+The development plugin starts an in-process OTLP/HTTP JSON trace receiver,
+points `@vercel/otel` at it, and exposes a Next-native inspector at
+`/_nextscope`.
+
+The MVP is intentionally narrow:
+
+- Next.js 16 only
+- development server only
+- traces only
+- in-memory storage only
+- no external collector, database, or dashboard process
+
+## Why
+
+Local OpenTelemetry inspection usually means running something outside the app:
+Jaeger, Grafana LGTM, Aspire Dashboard, or Vercel's collector dev setup. Those
+tools work, but they add a second system to configure and keep in view while
+debugging a Next.js request.
+
+NextScope keeps the local debugging loop inside `next dev`. Open your app, make
+a request, then inspect the recent request trace at `/_nextscope`.
+
+## Installation
+
+```sh
+pnpm add @nextscope/next @vercel/otel
+```
+
+Peer requirements:
+
+- `next >=16.0.0 <17.0.0`
+- `@vercel/otel >=2.1.0`
+
+## Usage
+
+Wrap your Next config with `withNextScope`:
+
+```js
+// next.config.mjs
+import { withNextScope } from '@nextscope/next/config'
+
+const nextConfig = {}
+
+export default withNextScope(nextConfig)
+```
+
+Register `@vercel/otel` from your app instrumentation file:
+
+```ts
+// instrumentation.ts
+import { registerOTel } from '@vercel/otel'
+
+export function register() {
+  registerOTel({ serviceName: 'my-next-app' })
+}
+```
+
+Start the app:
+
+```sh
+pnpm dev
+```
+
+Then open:
+
+```text
+http://localhost:3000/_nextscope
+```
+
+## Verify It Works
+
+After setup, keep the app running with `pnpm dev`.
+
+1. Request one page in the app, for example `http://localhost:3000/`.
+2. Open `http://localhost:3000/_nextscope`.
+3. Expect at least one trace row in the recent requests list.
+
+If no trace row appears, check these common misses:
+
+- The app is missing `instrumentation.ts`, or it does not call `registerOTel`
+  from `@vercel/otel`.
+- The app is not running through `next dev`. NextScope is disabled for normal
+  builds and production starts by default.
+- An existing OTLP exporter uses an unsupported protocol. NextScope captures
+  locally, but forwarding only supports OTLP/HTTP JSON.
+- `withNextScope` uses a custom `route`, so the inspector is available at that
+  route instead of `/_nextscope`.
+- Another rewrite or route collides with the inspector route.
+- The app has not received any non-NextScope traffic yet. Open a real app page
+  before checking the inspector.
+
+## Options
+
+```ts
+withNextScope(nextConfig, {
+  enabled: true,
+  route: '/_nextscope',
+  maxTraces: 200,
+})
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `enabled` | dev auto-detection | Set `false` to disable. Set `true` to force-enable for a non-standard dev runtime. |
+| `route` | `/_nextscope` | Public route where the inspector UI is mounted. |
+| `maxTraces` | `200` | Maximum number of trace groups retained in memory. |
+
+By default, NextScope enables itself only for `next dev`. It no-ops for build,
+start, and type generation.
+
+## How It Works
+
+During development, the config plugin:
+
+1. Starts a singleton HTTP sidecar on `127.0.0.1:0`.
+2. Sets `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/json`.
+3. Sets `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` to the sidecar's `/v1/traces`
+   endpoint.
+4. Adds a Next rewrite from `/_nextscope/:path*` to the local sidecar.
+
+The sidecar:
+
+- accepts `POST /v1/traces` OTLP/HTTP JSON batches;
+- normalizes spans and groups them by `traceId`;
+- keeps recent traces in memory with a retention cap;
+- serves the inspector UI assets;
+- exposes `GET /api/traces` and `GET /api/traces/:traceId` for the UI.
+
+The inspector highlights request-oriented traces, especially
+`next.span_type=BaseServer.handleRequest`, and shows:
+
+- route or target path;
+- method and status code;
+- duration and start time;
+- span count;
+- nested span waterfall with a tree column and timeline column;
+- service-colored span bars, status and error markers, and event markers;
+- trace-level filtering by text, status, method, newest, slowest, errors, and
+  fielded filters such as `route:`, `service:`, `duration:>500ms`, and
+  `errors:true`;
+- optional trace list grouping by route with per-route count, latest request,
+  slowest request, p50/p95 duration, and error rate;
+- span search across names, service names, span types, status, attributes,
+  resource attributes, events, and links;
+- zoomable timing view with `Cmd`/`Ctrl` + mouse wheel, reset zoom, and cursor
+  crosshair timing;
+- selected span details with timing, parent/child context, attributes, resource
+  attributes, events, and links.
+
+The public setup and options are unchanged. The React inspector is bundled into
+static sidecar assets and does not require a separate dashboard process.
+
+## Existing Exporters
+
+If an OTLP trace exporter is already configured, NextScope snapshots the previous
+trace endpoint, protocol, and headers before overriding the active trace endpoint.
+
+When the previous exporter is compatible with OTLP/HTTP JSON, NextScope forwards
+captured batches to it after local filtering. Unsupported protocols are warned
+once and skipped.
+
+Supported forwarding protocol:
+
+```text
+http/json
+```
+
+Unsupported examples include gRPC exporters or non-JSON protocols.
+
+## Self-Trace Suppression
+
+Requests made by the inspector itself are filtered out before storage and before
+forwarding. This prevents the tool from filling the trace list with its own UI,
+static asset, or polling requests.
+
+Suppressed requests include:
+
+- `/_nextscope`
+- `/_nextscope/app.js`
+- `/_nextscope/style.css`
+- `/_nextscope/api/traces`
+- direct sidecar requests for the same UI and API paths
+
+## Fixture App
+
+The repository includes a Next.js 16 fixture app at
+`fixtures/next16-app`. It is intentionally heavier than a smoke test so the
+inspector has varied traces to display.
+
+Run it with:
+
+```sh
+pnpm --filter nextscope-next16-fixture dev
+```
+
+Useful routes:
+
+- `/traced` - minimal traced page
+- `/stress` - fixture dashboard
+- `/stress/nested` - nested spans
+- `/stress/parallel` - parallel spans
+- `/stress/slow` - slow span timing
+- `/stress/error` - recorded exception and error status
+- `/stress/attributes` - large and high-cardinality attributes
+- `/stress/fetch` - fetch-shaped span scenario
+- `/stress/siblings` - many sibling spans
+- `/stress/services` - spans annotated with several service-style peers
+- `/stress/waterfall` - richer sequential and parallel fetch waterfall
+- `/stress/not-found` - traced `notFound()` / 404 route
+- `/stress/long-route-name-with-many-segments/and-a-very-long-leaf` - long route label
+- `/api/stress/attributes` - traced route handler
+- `POST /api/stress/waterfall` - traced POST route handler
+- `/stress/catch/a/b/c` - optional catch-all route
+
+Then open:
+
+```text
+http://localhost:3016/_nextscope
+```
+
+## Development
+
+Install dependencies:
+
+```sh
+pnpm install
+```
+
+Run tests:
+
+```sh
+pnpm test
+```
+
+Typecheck:
+
+```sh
+pnpm typecheck
+```
+
+Build the package:
+
+```sh
+pnpm build
+```
+
+Build the fixture app:
+
+```sh
+pnpm --filter nextscope-next16-fixture build
+```
+
+Run the opt-in fixture runtime check:
+
+```sh
+NEXTSCOPE_RUN_RUNTIME=1 pnpm exec vitest run test/fixture-runtime.test.ts
+```
+
+## Current Limitations
+
+- Development-only MVP.
+- Trace data is process-local and lost when the dev server exits.
+- No logs or metrics.
+- No persistence, search index, or cross-session history.
+- Forwarding only supports prior OTLP/HTTP JSON trace exporters.
+- The UI is optimized for recent request debugging, not full observability
+  workflows.

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+import type { NextConfig, Rewrites } from './next-types';
+import { type NextScopeServer, type NextScopeServerOptions } from './server';
+export interface NextScopeOptions {
+    enabled?: boolean;
+    route?: string;
+    maxTraces?: number;
+}
+export interface NextScopeRuntime {
+    command?: string;
+    dev?: boolean;
+}
+export interface NextConfigContext {
+    defaultConfig: NextConfig;
+    command?: string;
+    dev?: boolean;
+}
+export type NextConfigFactory = (phase: string, context?: NextConfigContext) => Promise<NextConfig>;
+export type NextConfigInputFactory = (phase: string, context: NextConfigContext) => NextConfig | Promise<NextConfig>;
+export declare function withNextScope(nextConfig?: NextConfig, options?: NextScopeOptions): NextConfigFactory;
+export declare function withNextScope(nextConfig: NextConfigInputFactory, options?: NextScopeOptions): NextConfigFactory;
+export declare function resetNextScopeForTests(): void;
+export declare function shouldEnable(runtime: NextScopeRuntime, options?: NextScopeOptions): boolean;
+export declare function normalizeRoute(route: string): string;
+export declare function resolveRewrites(rewrites: NextConfig['rewrites']): Promise<Rewrites>;
+export declare function mergeRewrites(existing: Rewrites | undefined, nextScopeRewrite: Rewrite): Rewrite[] | {
+    beforeFiles: Rewrite[];
+    afterFiles?: import("./next-types").Rewrite[];
+    fallback?: import("./next-types").Rewrite[];
+};
+export declare function ensureServer(options: NextScopeServerOptions): Promise<NextScopeServer | undefined>;
+export declare function configureTelemetryEnv(nextScopeEndpoint: string): void;
+export declare function snapshotTraceExporterEnv(): {
+    endpoint: string | undefined;
+    protocol: string | undefined;
+    headers: string | undefined;
+};
+export declare function isSupportedHttpJson(protocol?: string): boolean;
+interface Rewrite {
+    source: string;
+    destination: string;
+    basePath?: false;
+}
+export {};

package/dist/config.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withNextScope = withNextScope;
+exports.resetNextScopeForTests = resetNextScopeForTests;
+exports.shouldEnable = shouldEnable;
+exports.normalizeRoute = normalizeRoute;
+exports.resolveRewrites = resolveRewrites;
+exports.mergeRewrites = mergeRewrites;
+exports.ensureServer = ensureServer;
+exports.configureTelemetryEnv = configureTelemetryEnv;
+exports.snapshotTraceExporterEnv = snapshotTraceExporterEnv;
+exports.isSupportedHttpJson = isSupportedHttpJson;
+const server_1 = require("./server");
+let singletonServer;
+let warnedUnsupportedExporter = false;
+let warnedStartupFailure = false;
+const DEFAULT_ROUTE = '/_nextscope';
+const DEFAULT_MAX_TRACES = 200;
+function withNextScope(nextConfig = {}, options = {}) {
+    const wrapped = async (phase, context = { defaultConfig: {} }) => {
+        const resolvedConfig = typeof nextConfig === 'function'
+            ? await nextConfig(phase, context)
+            : nextConfig;
+        const runtime = inferRuntime(phase, context);
+        if (!shouldEnable(runtime, options)) {
+            return resolvedConfig;
+        }
+        const server = await ensureServer({
+            route: normalizeRoute(options.route ?? DEFAULT_ROUTE),
+            maxTraces: options.maxTraces ?? DEFAULT_MAX_TRACES,
+        });
+        if (!server) {
+            return resolvedConfig;
+        }
+        configureTelemetryEnv(server.url);
+        return {
+            ...resolvedConfig,
+            rewrites: async () => {
+                const existing = await resolveRewrites(resolvedConfig.rewrites);
+                return mergeRewrites(existing, {
+                    source: `${server.route}/:path*`,
+                    destination: `${server.url}/:path*`,
+                    basePath: false,
+                });
+            },
+        };
+    };
+    return wrapped;
+}
+function resetNextScopeForTests() {
+    singletonServer = undefined;
+    warnedUnsupportedExporter = false;
+    warnedStartupFailure = false;
+}
+function shouldEnable(runtime, options = {}) {
+    if (options.enabled === false) {
+        return false;
+    }
+    if (options.enabled === true) {
+        return true;
+    }
+    return runtime.dev === true || runtime.command === 'dev';
+}
+function normalizeRoute(route) {
+    const trimmed = route.trim();
+    const withSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    return withSlash.length > 1 ? withSlash.replace(/\/+$/, '') : withSlash;
+}
+async function resolveRewrites(rewrites) {
+    if (!rewrites) {
+        return [];
+    }
+    return typeof rewrites === 'function' ? await rewrites() : rewrites;
+}
+function mergeRewrites(existing, nextScopeRewrite) {
+    if (!existing) {
+        return [nextScopeRewrite];
+    }
+    if (Array.isArray(existing)) {
+        return [nextScopeRewrite, ...existing];
+    }
+    return {
+        ...existing,
+        beforeFiles: [nextScopeRewrite, ...(existing.beforeFiles ?? [])],
+    };
+}
+async function ensureServer(options) {
+    if (singletonServer) {
+        return singletonServer;
+    }
+    try {
+        singletonServer = await (0, server_1.startNextScopeServer)(options);
+        return singletonServer;
+    }
+    catch (error) {
+        if (!warnedStartupFailure) {
+            warnedStartupFailure = true;
+            console.warn(`[nextscope] Failed to start local trace inspector: ${formatError(error)}`);
+        }
+        return undefined;
+    }
+}
+function configureTelemetryEnv(nextScopeEndpoint) {
+    const nextScopeTraceEndpoint = `${nextScopeEndpoint}/v1/traces`;
+    const previous = snapshotTraceExporterEnv();
+    if (previous.endpoint !== nextScopeTraceEndpoint) {
+        process.env.NEXTSCOPE_FORWARD_TRACES_ENDPOINT = previous.endpoint ?? '';
+        process.env.NEXTSCOPE_FORWARD_TRACES_PROTOCOL = previous.protocol ?? '';
+        process.env.NEXTSCOPE_FORWARD_TRACES_HEADERS = previous.headers ?? '';
+    }
+    if (previous.endpoint && !isSupportedHttpJson(previous.protocol)) {
+        warnUnsupportedExporter(previous.protocol);
+    }
+    process.env.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL = 'http/json';
+    process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = nextScopeTraceEndpoint;
+}
+function snapshotTraceExporterEnv() {
+    return {
+        endpoint: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ??
+            process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+        protocol: process.env.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL ??
+            process.env.OTEL_EXPORTER_OTLP_PROTOCOL,
+        headers: process.env.OTEL_EXPORTER_OTLP_TRACES_HEADERS ??
+            process.env.OTEL_EXPORTER_OTLP_HEADERS,
+    };
+}
+function isSupportedHttpJson(protocol) {
+    return !protocol || protocol === 'http/json';
+}
+function inferRuntime(phase, context) {
+    return {
+        command: typeof context.defaultConfig === 'object' &&
+            context.defaultConfig !== null &&
+            'command' in context.defaultConfig &&
+            typeof context.defaultConfig.command === 'string'
+            ? context.defaultConfig.command
+            : typeof context.command === 'string'
+                ? context.command
+                : undefined,
+        dev: typeof context.dev === 'boolean'
+            ? context.dev
+            : phase === 'phase-development-server',
+    };
+}
+function warnUnsupportedExporter(protocol) {
+    if (warnedUnsupportedExporter) {
+        return;
+    }
+    warnedUnsupportedExporter = true;
+    console.warn(`[nextscope] Existing OTLP trace exporter uses unsupported protocol "${protocol ?? 'unset'}"; capturing locally but forwarding is disabled.`);
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/forwarder.d.ts

@@ -0,0 +1,26 @@
+export interface ForwarderEnv {
+    endpoint?: string;
+    protocol?: string;
+    headers?: string;
+}
+export interface ForwarderStatus {
+    configured: boolean;
+    enabled: boolean;
+    protocol?: string;
+    endpoint?: string;
+    lastSuccessAt?: string;
+    lastError?: string;
+}
+export declare class TraceForwarder {
+    private readonly env;
+    private warned;
+    private lastSuccessAt;
+    private lastError;
+    constructor(env?: ForwarderEnv);
+    forward(body: string): Promise<void>;
+    getStatus(): ForwarderStatus;
+    private warnOnce;
+}
+export declare function readForwarderEnv(): ForwarderEnv;
+export declare function isForwardableProtocol(protocol?: string): boolean;
+export declare function parseHeaders(headerString?: string): Record<string, string>;

package/dist/forwarder.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceForwarder = void 0;
+exports.readForwarderEnv = readForwarderEnv;
+exports.isForwardableProtocol = isForwardableProtocol;
+exports.parseHeaders = parseHeaders;
+class TraceForwarder {
+    env;
+    warned = false;
+    lastSuccessAt;
+    lastError;
+    constructor(env = readForwarderEnv()) {
+        this.env = env;
+    }
+    async forward(body) {
+        if (!this.env.endpoint || !isForwardableProtocol(this.env.protocol)) {
+            return;
+        }
+        try {
+            const response = await fetch(this.env.endpoint, {
+                method: 'POST',
+                body,
+                headers: {
+                    'content-type': 'application/json',
+                    ...parseHeaders(this.env.headers),
+                },
+            });
+            if (!response.ok) {
+                throw new Error(`forwarding failed with HTTP ${response.status}`);
+            }
+            this.lastSuccessAt = Date.now();
+            this.lastError = undefined;
+        }
+        catch (error) {
+            this.lastError = formatError(error);
+            this.warnOnce(error);
+        }
+    }
+    getStatus() {
+        return {
+            configured: Boolean(this.env.endpoint),
+            enabled: Boolean(this.env.endpoint && isForwardableProtocol(this.env.protocol)),
+            protocol: this.env.protocol,
+            endpoint: this.env.endpoint,
+            lastSuccessAt: this.lastSuccessAt
+                ? new Date(this.lastSuccessAt).toISOString()
+                : undefined,
+            lastError: this.lastError,
+        };
+    }
+    warnOnce(error) {
+        if (this.warned) {
+            return;
+        }
+        this.warned = true;
+        console.warn(`[nextscope] Failed to forward trace batch to existing exporter: ${formatError(error)}`);
+    }
+}
+exports.TraceForwarder = TraceForwarder;
+function readForwarderEnv() {
+    return {
+        endpoint: process.env.NEXTSCOPE_FORWARD_TRACES_ENDPOINT || undefined,
+        protocol: process.env.NEXTSCOPE_FORWARD_TRACES_PROTOCOL || undefined,
+        headers: process.env.NEXTSCOPE_FORWARD_TRACES_HEADERS || undefined,
+    };
+}
+function isForwardableProtocol(protocol) {
+    return !protocol || protocol === 'http/json';
+}
+function parseHeaders(headerString) {
+    const headers = {};
+    if (!headerString) {
+        return headers;
+    }
+    for (const part of headerString.split(',')) {
+        const [rawKey, ...rawValue] = part.split('=');
+        const key = rawKey?.trim();
+        const value = rawValue.join('=').trim();
+        if (key && value) {
+            headers[key] = value;
+        }
+    }
+    return headers;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=forwarder.js.map

package/dist/forwarder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwarder.js","sourceRoot":"","sources":["../src/forwarder.ts"],"names":[],"mappings":"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"}