trickle-observe 0.2.63 → 0.2.64

package/dist/next-loader.d.ts

@@ -0,0 +1,21 @@
+/**
+ * trickle/next-loader — Webpack loader for Next.js component instrumentation.
+ *
+ * Applied via withTrickle() in next.config.js. Instruments .tsx/.jsx files
+ * with render tracking, useState change tracking, and hook observability —
+ * the same transforms the Vite plugin provides, but via webpack's loader API.
+ *
+ * Do not use directly. Use withTrickle() from 'trickle-observe/next-plugin' instead.
+ */
+interface LoaderOptions {
+    backendUrl?: string;
+    include?: string[];
+    exclude?: string[];
+    debug?: boolean;
+    traceVars?: boolean;
+}
+export default function trickleNextLoader(this: {
+    resourcePath: string;
+    getOptions(): LoaderOptions;
+}, source: string): string;
+export {};

package/dist/next-loader.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * trickle/next-loader — Webpack loader for Next.js component instrumentation.
+ *
+ * Applied via withTrickle() in next.config.js. Instruments .tsx/.jsx files
+ * with render tracking, useState change tracking, and hook observability —
+ * the same transforms the Vite plugin provides, but via webpack's loader API.
+ *
+ * Do not use directly. Use withTrickle() from 'trickle-observe/next-plugin' instead.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = trickleNextLoader;
+const path_1 = __importDefault(require("path"));
+const vite_plugin_1 = require("./vite-plugin");
+// webpack loader — `this` is the LoaderContext (must not be an arrow function)
+function trickleNextLoader(source) {
+    const options = (this.getOptions && this.getOptions()) || {};
+    const resourcePath = this.resourcePath;
+    // Skip node_modules and trickle internals
+    if (resourcePath.includes('node_modules') || resourcePath.includes('trickle-observe')) {
+        return source;
+    }
+    // Include/exclude filters
+    if (options.include && options.include.length > 0) {
+        if (!options.include.some(p => resourcePath.includes(p)))
+            return source;
+    }
+    if (options.exclude && options.exclude.length > 0) {
+        if (options.exclude.some(p => resourcePath.includes(p)))
+            return source;
+    }
+    const backendUrl = options.backendUrl ?? process.env.TRICKLE_BACKEND_URL ?? 'http://localhost:4888';
+    const debug = options.debug ?? (process.env.TRICKLE_DEBUG === '1');
+    const traceVars = options.traceVars ?? true;
+    const moduleName = path_1.default.basename(resourcePath).replace(/\.[jt]sx?$/, '');
+    try {
+        const transformed = (0, vite_plugin_1.transformEsmSource)(source, resourcePath, moduleName, backendUrl, debug, traceVars, source);
+        if (debug && transformed !== source) {
+            console.log(`[trickle/next] Instrumented ${resourcePath}`);
+        }
+        return transformed;
+    }
+    catch {
+        // Never crash the build
+        return source;
+    }
+}

package/dist/next-plugin.d.ts

@@ -0,0 +1,63 @@
+/**
+ * trickle/next-plugin — Next.js observability via withTrickle().
+ *
+ * Wraps your Next.js config to add trickle's webpack loader, which instruments
+ * all React components (.tsx/.jsx) with render tracking, useState change tracking,
+ * and hook observability — the same hints you see when using the Vite plugin,
+ * but for Next.js (App Router and Pages Router, Client and Server Components).
+ *
+ * Setup in next.config.js:
+ *
+ *   const { withTrickle } = require('trickle-observe/next-plugin');
+ *
+ *   module.exports = withTrickle({
+ *     // ...your existing Next.js config
+ *   });
+ *
+ * Or with options:
+ *
+ *   module.exports = withTrickle({
+ *     reactStrictMode: true,
+ *   }, {
+ *     backendUrl: process.env.TRICKLE_BACKEND_URL,
+ *     debug: process.env.TRICKLE_DEBUG === '1',
+ *   });
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — Backend URL (default: http://localhost:4888)
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+export interface TrickleNextOptions {
+    /** Backend URL (default: http://localhost:4888 or TRICKLE_BACKEND_URL env var) */
+    backendUrl?: string;
+    /** Only instrument files whose paths contain one of these substrings */
+    include?: string[];
+    /** Skip files whose paths contain one of these substrings */
+    exclude?: string[];
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Enable variable tracing (default: true) */
+    traceVars?: boolean;
+}
+type NextConfig = Record<string, unknown> & {
+    webpack?: (config: WebpackConfig, context: WebpackContext) => WebpackConfig;
+};
+interface WebpackConfig {
+    module: {
+        rules: unknown[];
+    };
+    [key: string]: unknown;
+}
+interface WebpackContext {
+    isServer: boolean;
+    nextRuntime?: string;
+    [key: string]: unknown;
+}
+/**
+ * Wrap your Next.js config with trickle observability.
+ *
+ * Adds a webpack loader that instruments all .tsx/.jsx component files at build
+ * time with render tracking, useState change tracking, and hook observability.
+ */
+export declare function withTrickle(nextConfig?: NextConfig, options?: TrickleNextOptions): NextConfig;
+export {};

package/dist/next-plugin.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * trickle/next-plugin — Next.js observability via withTrickle().
+ *
+ * Wraps your Next.js config to add trickle's webpack loader, which instruments
+ * all React components (.tsx/.jsx) with render tracking, useState change tracking,
+ * and hook observability — the same hints you see when using the Vite plugin,
+ * but for Next.js (App Router and Pages Router, Client and Server Components).
+ *
+ * Setup in next.config.js:
+ *
+ *   const { withTrickle } = require('trickle-observe/next-plugin');
+ *
+ *   module.exports = withTrickle({
+ *     // ...your existing Next.js config
+ *   });
+ *
+ * Or with options:
+ *
+ *   module.exports = withTrickle({
+ *     reactStrictMode: true,
+ *   }, {
+ *     backendUrl: process.env.TRICKLE_BACKEND_URL,
+ *     debug: process.env.TRICKLE_DEBUG === '1',
+ *   });
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — Backend URL (default: http://localhost:4888)
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTrickle = withTrickle;
+const path_1 = __importDefault(require("path"));
+/**
+ * Wrap your Next.js config with trickle observability.
+ *
+ * Adds a webpack loader that instruments all .tsx/.jsx component files at build
+ * time with render tracking, useState change tracking, and hook observability.
+ */
+function withTrickle(nextConfig = {}, options = {}) {
+    const loaderPath = path_1.default.resolve(__dirname, './next-loader.js');
+    return {
+        ...nextConfig,
+        webpack(config, context) {
+            // Preserve existing webpack config
+            if (typeof nextConfig.webpack === 'function') {
+                config = nextConfig.webpack(config, context);
+            }
+            config.module.rules.push({
+                test: /\.(tsx?|jsx?)$/,
+                exclude: /node_modules/,
+                use: [
+                    {
+                        loader: loaderPath,
+                        options,
+                    },
+                ],
+            });
+            return config;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-observe",
-  "version": "0.2.63",
+  "version": "0.2.64",
   "description": "Runtime type observability for JavaScript applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,11 +18,13 @@
     },
     "./trace-var": "./dist/trace-var.js",
     "./lambda": "./dist/lambda.js",
-    "./metro-transformer": "./dist/metro-transformer.js"
+    "./metro-transformer": "./dist/metro-transformer.js",
+    "./next-plugin": "./dist/next-plugin.js",
+    "./next-loader": "./dist/next-loader.js"
   },
   "scripts": {
     "build": "tsc && tsc -p tsconfig.esm.json",
-    "test": "npm run build && node --experimental-strip-types --test src/vite-plugin.test.ts src/lambda.test.ts src/metro-transformer.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test src/vite-plugin.test.ts src/lambda.test.ts src/metro-transformer.test.ts src/next-plugin.test.ts",
     "prepublishOnly": "npm run build"
   },
   "optionalDependencies": {

package/src/next-loader.ts

@@ -0,0 +1,55 @@
+/**
+ * trickle/next-loader — Webpack loader for Next.js component instrumentation.
+ *
+ * Applied via withTrickle() in next.config.js. Instruments .tsx/.jsx files
+ * with render tracking, useState change tracking, and hook observability —
+ * the same transforms the Vite plugin provides, but via webpack's loader API.
+ *
+ * Do not use directly. Use withTrickle() from 'trickle-observe/next-plugin' instead.
+ */
+
+import path from 'path';
+import { transformEsmSource } from './vite-plugin';
+
+interface LoaderOptions {
+  backendUrl?: string;
+  include?: string[];
+  exclude?: string[];
+  debug?: boolean;
+  traceVars?: boolean;
+}
+
+// webpack loader — `this` is the LoaderContext (must not be an arrow function)
+export default function trickleNextLoader(this: { resourcePath: string; getOptions(): LoaderOptions }, source: string): string {
+  const options: LoaderOptions = (this.getOptions && this.getOptions()) || {};
+  const resourcePath = this.resourcePath;
+
+  // Skip node_modules and trickle internals
+  if (resourcePath.includes('node_modules') || resourcePath.includes('trickle-observe')) {
+    return source;
+  }
+
+  // Include/exclude filters
+  if (options.include && options.include.length > 0) {
+    if (!options.include.some(p => resourcePath.includes(p))) return source;
+  }
+  if (options.exclude && options.exclude.length > 0) {
+    if (options.exclude.some(p => resourcePath.includes(p))) return source;
+  }
+
+  const backendUrl = options.backendUrl ?? process.env.TRICKLE_BACKEND_URL ?? 'http://localhost:4888';
+  const debug = options.debug ?? (process.env.TRICKLE_DEBUG === '1');
+  const traceVars = options.traceVars ?? true;
+  const moduleName = path.basename(resourcePath).replace(/\.[jt]sx?$/, '');
+
+  try {
+    const transformed = transformEsmSource(source, resourcePath, moduleName, backendUrl, debug, traceVars, source);
+    if (debug && transformed !== source) {
+      console.log(`[trickle/next] Instrumented ${resourcePath}`);
+    }
+    return transformed;
+  } catch {
+    // Never crash the build
+    return source;
+  }
+}

package/src/next-plugin.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Unit tests for the Next.js plugin and loader (withTrickle, next-loader).
+ *
+ * Tests the transformation logic directly using transformEsmSource,
+ * mirroring what the webpack loader applies to Next.js component files.
+ *
+ * Run with: node --experimental-strip-types --test src/next-plugin.test.ts
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { transformEsmSource } from '../dist/vite-plugin.js';
+
+const BACKEND = 'http://localhost:4888';
+
+function transformNextTsx(code: string, filename = '/app/components/MyComponent.tsx'): string {
+  return transformEsmSource(code, filename, 'MyComponent', BACKEND, false, false);
+}
+
+function transformNextTs(code: string, filename = '/app/utils/helper.ts'): string {
+  return transformEsmSource(code, filename, 'helper', BACKEND, false, false);
+}
+
+// ── Next.js component patterns ─────────────────────────────────────────────
+
+describe('Next.js Client Component tracking', () => {
+  it('tracks a "use client" component with useState', () => {
+    const code = [
+      `'use client';`,
+      `import { useState } from 'react';`,
+      `export default function Counter() {`,
+      `  const [count, setCount] = useState(0);`,
+      `  return <div>{count}</div>;`,
+      `}`,
+    ].join('\n');
+    const out = transformNextTsx(code);
+    assert.ok(out.includes('__trickle_rc'), 'should track render count');
+    assert.ok(out.includes('__trickle_ss'), 'should track useState');
+  });
+
+  it('tracks a "use client" arrow component with hooks', () => {
+    const code = [
+      `'use client';`,
+      `import { useState, useEffect } from 'react';`,
+      `const ProductCart: React.FC<Props> = ({ items }) => {`,
+      `  const [open, setOpen] = useState(false);`,
+      `  useEffect(() => { syncCart(); }, [items]);`,
+      `  return <div />;`,
+      `};`,
+    ].join('\n');
+    const out = transformNextTsx(code);
+    assert.ok(out.includes('__trickle_rc'), 'should track render');
+    assert.ok(out.includes('__trickle_ss'), 'should track useState');
+    assert.ok(out.includes('__trickle_hw'), 'should track useEffect');
+  });
+});
+
+describe('Next.js Server Component tracking', () => {
+  it('tracks a Server Component (no use client directive)', () => {
+    const code = [
+      `import { db } from '@/lib/db';`,
+      `export default async function ProductPage({ params }: { params: { id: string } }) {`,
+      `  const product = await db.product.findUnique({ where: { id: params.id } });`,
+      `  return <div>{product?.name}</div>;`,
+      `}`,
+    ].join('\n');
+    const out = transformNextTsx(code);
+    assert.ok(out.includes('__trickle_rc'), 'should track Server Component renders');
+  });
+
+  it('tracks a named Server Component export', () => {
+    const code = [
+      `export function Navbar({ user }: { user: User }) {`,
+      `  return <nav>{user.name}</nav>;`,
+      `}`,
+    ].join('\n');
+    const out = transformNextTsx(code);
+    assert.ok(out.includes('__trickle_rc'), 'should track named export server component');
+  });
+});
+
+describe('Next.js App Router component patterns', () => {
+  it('tracks export default function (most common Next.js page pattern)', () => {
+    const code = `export default function Page() { return <main />; }`;
+    const out = transformNextTsx(code);
+    assert.ok(out.includes('__trickle_rc'), 'should track default page export');
+  });
+
+  it('tracks React.memo wrapped component in Next.js', () => {
+    const code = [
+      `const ProductCard = React.memo(({ product }: { product: Product }) => {`,
+      `  return <div>{product.name}</div>;`,
+      `});`,
+    ].join('\n');
+    const out = transformNextTsx(code);
+    assert.ok(out.includes('__trickle_rc'), 'should track memo-wrapped Next.js component');
+  });
+
+  it('tracks React.FC typed component in Next.js', () => {
+    const code = [
+      `const SiteHeader: React.FC<{ title: string }> = ({ title }) => {`,
+      `  return <header>{title}</header>;`,
+      `};`,
+    ].join('\n');
+    const out = transformNextTsx(code);
+    assert.ok(out.includes('__trickle_rc'), 'should track React.FC component');
+  });
+});
+
+describe('Next.js: withTrickle plugin registration', () => {
+  it('withTrickle returns an object with a webpack function', async () => {
+    const { withTrickle } = await import('../dist/next-plugin.js');
+    const result = withTrickle({ reactStrictMode: true });
+    assert.ok(result, 'withTrickle should return a config object');
+    assert.equal(typeof result.webpack, 'function', 'should add webpack function');
+    assert.equal(result.reactStrictMode, true, 'should preserve existing config');
+  });
+
+  it('withTrickle webpack function returns config with trickle loader rule', async () => {
+    const { withTrickle } = await import('../dist/next-plugin.js');
+    const result = withTrickle({});
+    const mockConfig = { module: { rules: [] } };
+    const updatedConfig = result.webpack(mockConfig, { isServer: false });
+    assert.ok(updatedConfig.module.rules.length > 0, 'should add at least one rule');
+    const rule = updatedConfig.module.rules[0] as { test: RegExp; use: { loader: string }[] };
+    assert.ok(rule.test instanceof RegExp, 'rule should have a test regex');
+    assert.ok(rule.test.test('Component.tsx'), 'rule should match .tsx files');
+    assert.ok(rule.test.test('Component.jsx'), 'rule should match .jsx files');
+    assert.ok(!rule.test.test('helper.py'), 'rule should not match .py files');
+  });
+
+  it('withTrickle preserves existing webpack config', async () => {
+    const { withTrickle } = await import('../dist/next-plugin.js');
+    let calledWith = false;
+    const originalWebpack = (_config: unknown, _ctx: unknown) => { calledWith = true; return { module: { rules: [] } }; };
+    const result = withTrickle({ webpack: originalWebpack });
+    result.webpack({ module: { rules: [] } }, { isServer: false });
+    assert.ok(calledWith, 'should call original webpack function');
+  });
+
+  it('withTrickle works with no arguments', async () => {
+    const { withTrickle } = await import('../dist/next-plugin.js');
+    assert.doesNotThrow(() => withTrickle(), 'withTrickle() with no args should not throw');
+  });
+});
+
+describe('Next.js: does not instrument non-React files', () => {
+  it('does not inject render tracker in .ts utility files', () => {
+    const code = `export function formatPrice(amount: number): string { return '$' + amount; }`;
+    const out = transformNextTs(code);
+    assert.ok(!out.includes('__trickle_rc'), 'should not inject render tracker in .ts files');
+  });
+
+  it('does not inject useState tracker in .ts files', () => {
+    const code = `function helper() { const [x, setX] = useState(0); return x; }`;
+    const out = transformNextTs(code);
+    assert.ok(!out.includes('__trickle_ss'), 'should not track useState in .ts files');
+  });
+});

package/src/next-plugin.ts

@@ -0,0 +1,92 @@
+/**
+ * trickle/next-plugin — Next.js observability via withTrickle().
+ *
+ * Wraps your Next.js config to add trickle's webpack loader, which instruments
+ * all React components (.tsx/.jsx) with render tracking, useState change tracking,
+ * and hook observability — the same hints you see when using the Vite plugin,
+ * but for Next.js (App Router and Pages Router, Client and Server Components).
+ *
+ * Setup in next.config.js:
+ *
+ *   const { withTrickle } = require('trickle-observe/next-plugin');
+ *
+ *   module.exports = withTrickle({
+ *     // ...your existing Next.js config
+ *   });
+ *
+ * Or with options:
+ *
+ *   module.exports = withTrickle({
+ *     reactStrictMode: true,
+ *   }, {
+ *     backendUrl: process.env.TRICKLE_BACKEND_URL,
+ *     debug: process.env.TRICKLE_DEBUG === '1',
+ *   });
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — Backend URL (default: http://localhost:4888)
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+
+import path from 'path';
+
+export interface TrickleNextOptions {
+  /** Backend URL (default: http://localhost:4888 or TRICKLE_BACKEND_URL env var) */
+  backendUrl?: string;
+  /** Only instrument files whose paths contain one of these substrings */
+  include?: string[];
+  /** Skip files whose paths contain one of these substrings */
+  exclude?: string[];
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Enable variable tracing (default: true) */
+  traceVars?: boolean;
+}
+
+type NextConfig = Record<string, unknown> & {
+  webpack?: (config: WebpackConfig, context: WebpackContext) => WebpackConfig;
+};
+
+interface WebpackConfig {
+  module: { rules: unknown[] };
+  [key: string]: unknown;
+}
+
+interface WebpackContext {
+  isServer: boolean;
+  nextRuntime?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Wrap your Next.js config with trickle observability.
+ *
+ * Adds a webpack loader that instruments all .tsx/.jsx component files at build
+ * time with render tracking, useState change tracking, and hook observability.
+ */
+export function withTrickle(nextConfig: NextConfig = {}, options: TrickleNextOptions = {}): NextConfig {
+  const loaderPath = path.resolve(__dirname, './next-loader.js');
+
+  return {
+    ...nextConfig,
+    webpack(config: WebpackConfig, context: WebpackContext) {
+      // Preserve existing webpack config
+      if (typeof nextConfig.webpack === 'function') {
+        config = nextConfig.webpack(config, context);
+      }
+
+      config.module.rules.push({
+        test: /\.(tsx?|jsx?)$/,
+        exclude: /node_modules/,
+        use: [
+          {
+            loader: loaderPath,
+            options,
+          },
+        ],
+      });
+
+      return config;
+    },
+  };
+}