trickle-observe 0.2.73 → 0.2.74

package/dist/next-loader.d.ts

@@ -13,6 +13,8 @@ interface LoaderOptions {
     exclude?: string[];
     debug?: boolean;
     traceVars?: boolean;
+    isServer?: boolean;
+    ingestPort?: number;
 }
 export default function trickleNextLoader(this: {
     resourcePath: string;

package/dist/next-loader.js

@@ -35,12 +35,15 @@ function trickleNextLoader(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 isServer = options.isServer ?? true;
+    const ingestPort = options.ingestPort ?? 4889;
     const moduleName = path_1.default.basename(resourcePath).replace(/\.[jt]sx?$/, '');
     try {
-        // Next.js SSR renders all components on the server, so use SSR mode (node:fs)
-        const transformed = (0, vite_plugin_1.transformEsmSource)(source, resourcePath, moduleName, backendUrl, debug, traceVars, source, true);
+        // Server: use node:fs for writing. Client: use fetch() to ingest server.
+        const ingestUrl = isServer ? null : `http://localhost:${ingestPort}/__trickle_vars`;
+        const transformed = (0, vite_plugin_1.transformEsmSource)(source, resourcePath, moduleName, backendUrl, debug, traceVars, source, isServer, ingestUrl);
         if (debug && transformed !== source) {
-            console.log(`[trickle/next] Instrumented ${resourcePath}`);
+            console.log(`[trickle/next] Instrumented ${resourcePath} [${isServer ? 'server' : 'client'}]`);
         }
         return transformed;
     }

package/dist/next-plugin.d.ts

@@ -38,6 +38,8 @@ export interface TrickleNextOptions {
     debug?: boolean;
     /** Enable variable tracing (default: true) */
     traceVars?: boolean;
+    /** Port for the client-side ingest server (default: 4889) */
+    ingestPort?: number;
 }
 type NextConfig = Record<string, unknown> & {
     webpack?: (config: WebpackConfig, context: WebpackContext) => WebpackConfig;
@@ -58,6 +60,7 @@ interface WebpackContext {
  *
  * Adds a webpack loader that instruments all .tsx/.jsx component files at build
  * time with render tracking, useState change tracking, and hook observability.
+ * Also starts a tiny HTTP ingest server for client-side variable data.
  */
 export declare function withTrickle(nextConfig?: NextConfig, options?: TrickleNextOptions): NextConfig;
 export {};

package/dist/next-plugin.js

@@ -34,14 +34,78 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.withTrickle = withTrickle;
 const path_1 = __importDefault(require("path"));
+const http_1 = __importDefault(require("http"));
+const fs_1 = __importDefault(require("fs"));
+/** Track whether the ingest server is already running (avoid starting twice) */
+let ingestServerStarted = false;
+/**
+ * Start a tiny HTTP server that receives variable data from browser clients
+ * and writes it to .trickle/variables.jsonl.
+ */
+function startIngestServer(port, debug) {
+    if (ingestServerStarted)
+        return;
+    ingestServerStarted = true;
+    const dir = process.env.TRICKLE_LOCAL_DIR || path_1.default.join(process.cwd(), '.trickle');
+    try {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    const varsFile = path_1.default.join(dir, 'variables.jsonl');
+    const server = http_1.default.createServer((req, res) => {
+        // CORS headers for browser fetch
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/__trickle_vars') {
+            let body = '';
+            req.on('data', (chunk) => { body += chunk; });
+            req.on('end', () => {
+                try {
+                    if (body) {
+                        fs_1.default.appendFileSync(varsFile, body);
+                    }
+                }
+                catch { }
+                res.writeHead(200);
+                res.end('ok');
+            });
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+    });
+    server.listen(port, () => {
+        if (debug) {
+            console.log(`[trickle/next] Ingest server listening on http://localhost:${port} → ${varsFile}`);
+        }
+    });
+    server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+            // Another trickle instance already has the port — that's fine
+            if (debug)
+                console.log(`[trickle/next] Ingest port ${port} already in use (OK)`);
+        }
+    });
+    // Don't keep the process alive just for this server
+    server.unref();
+}
 /**
  * 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.
+ * Also starts a tiny HTTP ingest server for client-side variable data.
  */
 function withTrickle(nextConfig = {}, options = {}) {
     const loaderPath = path_1.default.resolve(__dirname, './next-loader.js');
+    const ingestPort = options.ingestPort ?? 4889;
+    const debug = options.debug ?? (process.env.TRICKLE_DEBUG === '1');
     return {
         ...nextConfig,
         webpack(config, context) {
@@ -49,13 +113,19 @@ function withTrickle(nextConfig = {}, options = {}) {
             if (typeof nextConfig.webpack === 'function') {
                 config = nextConfig.webpack(config, context);
             }
+            // Start the ingest server for client-side data (once)
+            startIngestServer(ingestPort, debug);
             config.module.rules.push({
                 test: /\.(tsx?|jsx?)$/,
-                exclude: /node_modules/,
+                exclude: /node_modules|trickle-observe|client-js/,
                 use: [
                     {
                         loader: loaderPath,
-                        options,
+                        options: {
+                            ...options,
+                            isServer: context.isServer,
+                            ingestPort,
+                        },
                     },
                 ],
             });

package/dist/vite-plugin.d.ts

@@ -40,5 +40,7 @@ export declare function tricklePlugin(options?: TricklePluginOptions): {
         map: null;
     } | null;
 };
-export declare function transformEsmSource(source: string, filename: string, moduleName: string, backendUrl: string, debug: boolean, traceVars: boolean, originalSource?: string | null, isSSR?: boolean): string;
+export declare function transformEsmSource(source: string, filename: string, moduleName: string, backendUrl: string, debug: boolean, traceVars: boolean, originalSource?: string | null, isSSR?: boolean, 
+/** URL for fetch-based browser transport (Next.js client). When set and isSSR=false, uses fetch() instead of import.meta.hot */
+ingestUrl?: string | null): string;
 export default tricklePlugin;

package/dist/vite-plugin.js

@@ -894,7 +894,9 @@ function findOriginalLineDestructured(origLines, varNames, transformedLine) {
 function escapeRegexStr(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource, isSSR) {
+function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource, isSSR, 
+/** URL for fetch-based browser transport (Next.js client). When set and isSSR=false, uses fetch() instead of import.meta.hot */
+ingestUrl) {
     // Detect React files for component render tracking
     const isReactFile = /\.(tsx|jsx)$/.test(filename);
     // Match top-level and nested function declarations (including async, export, export default)
@@ -1339,9 +1341,13 @@ function transformEsmSource(source, filename, moduleName, backendUrl, debug, tra
             // SSR/Node.js mode — write directly to file system
             prefixLines.push(`let __trickle_varsFile = null;`, `function __trickle_send(line) {`, `  try {`, `    if (!__trickle_varsFile) {`, `      const dir = process.env.TRICKLE_LOCAL_DIR || __trickle_join(process.cwd(), '.trickle');`, `      try { __trickle_mkdirSync(dir, { recursive: true }); } catch(e) {}`, `      __trickle_varsFile = __trickle_join(dir, 'variables.jsonl');`, `    }`, `    __trickle_appendFileSync(__trickle_varsFile, line + '\\n');`, `  } catch(e) {}`, `}`);
         }
+        else if (ingestUrl) {
+            // Browser mode with fetch transport (Next.js client)
+            prefixLines.push(`const __trickle_sendBuf = [];`, `let __trickle_sendTimer = null;`, `function __trickle_flush() {`, `  if (__trickle_sendBuf.length === 0) return;`, `  const lines = __trickle_sendBuf.join('\\n') + '\\n';`, `  __trickle_sendBuf.length = 0;`, `  try { fetch(${JSON.stringify(ingestUrl)}, { method: 'POST', body: lines, headers: { 'Content-Type': 'text/plain' } }).catch(function(){}); } catch(e) {}`, `}`, `function __trickle_send(line) {`, `  __trickle_sendBuf.push(line);`, `  if (!__trickle_sendTimer) {`, `    __trickle_sendTimer = setTimeout(function() { __trickle_sendTimer = null; __trickle_flush(); }, 300);`, `  }`, `}`);
+        }
         else {
             // Browser mode — buffer and send via Vite HMR WebSocket
-            prefixLines.push(`const __trickle_sendBuf = [];`, `let __trickle_sendTimer = null;`, `function __trickle_flush() {`, `  if (__trickle_sendBuf.length === 0) return;`, `  const lines = __trickle_sendBuf.join('\\n') + '\\n';`, `  __trickle_sendBuf.length = 0;`, `  try { if (import.meta.hot) import.meta.hot.send('trickle:vars', { lines }); } catch(e) {}`, `}`, `function __trickle_send(line) {`, `  __trickle_sendBuf.push(line);`, `  if (!__trickle_sendTimer) {`, `    __trickle_sendTimer = setTimeout(() => { __trickle_sendTimer = null; __trickle_flush(); }, 300);`, `  }`, `}`);
+            prefixLines.push(`const __trickle_sendBuf = [];`, `let __trickle_sendTimer = null;`, `function __trickle_flush() {`, `  if (__trickle_sendBuf.length === 0) return;`, `  const lines = __trickle_sendBuf.join('\\n') + '\\n';`, `  __trickle_sendBuf.length = 0;`, `  try { if (import.meta.hot) import.meta.hot.send('trickle:vars', { lines }); } catch(e) {}`, `}`, `function __trickle_send(line) {`, `  __trickle_sendBuf.push(line);`, `  if (!__trickle_sendTimer) {`, `    __trickle_sendTimer = setTimeout(function() { __trickle_sendTimer = null; __trickle_flush(); }, 300);`, `  }`, `}`);
         }
     }
     // Add variable tracing if needed — inlined to avoid import resolution issues in Vite SSR.
@@ -1453,6 +1459,14 @@ function transformEsmSource(source, filename, moduleName, backendUrl, debug, tra
     for (const { position, code } of allInsertions) {
         result = result.slice(0, position) + code + result.slice(position);
     }
-    return prefix + result;
+    // Preserve 'use client' / 'use server' directives — they must be the first expression
+    // in the file (before any imports or code). Extract them from result and prepend before prefix.
+    let directive = '';
+    const directiveMatch = result.match(/^(\s*(?:'use client'|"use client"|'use server'|"use server")\s*;?\s*\n?)/);
+    if (directiveMatch) {
+        directive = directiveMatch[1];
+        result = result.slice(directiveMatch[0].length);
+    }
+    return directive + prefix + result;
 }
 exports.default = tricklePlugin;

package/dist-esm/vite-plugin.js

@@ -887,7 +887,9 @@ function findOriginalLineDestructured(origLines, varNames, transformedLine) {
 function escapeRegexStr(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-export function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource, isSSR) {
+export function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource, isSSR, 
+/** URL for fetch-based browser transport (Next.js client). When set and isSSR=false, uses fetch() instead of import.meta.hot */
+ingestUrl) {
     // Detect React files for component render tracking
     const isReactFile = /\.(tsx|jsx)$/.test(filename);
     // Match top-level and nested function declarations (including async, export, export default)
@@ -1332,9 +1334,13 @@ export function transformEsmSource(source, filename, moduleName, backendUrl, deb
             // SSR/Node.js mode — write directly to file system
             prefixLines.push(`let __trickle_varsFile = null;`, `function __trickle_send(line) {`, `  try {`, `    if (!__trickle_varsFile) {`, `      const dir = process.env.TRICKLE_LOCAL_DIR || __trickle_join(process.cwd(), '.trickle');`, `      try { __trickle_mkdirSync(dir, { recursive: true }); } catch(e) {}`, `      __trickle_varsFile = __trickle_join(dir, 'variables.jsonl');`, `    }`, `    __trickle_appendFileSync(__trickle_varsFile, line + '\\n');`, `  } catch(e) {}`, `}`);
         }
+        else if (ingestUrl) {
+            // Browser mode with fetch transport (Next.js client)
+            prefixLines.push(`const __trickle_sendBuf = [];`, `let __trickle_sendTimer = null;`, `function __trickle_flush() {`, `  if (__trickle_sendBuf.length === 0) return;`, `  const lines = __trickle_sendBuf.join('\\n') + '\\n';`, `  __trickle_sendBuf.length = 0;`, `  try { fetch(${JSON.stringify(ingestUrl)}, { method: 'POST', body: lines, headers: { 'Content-Type': 'text/plain' } }).catch(function(){}); } catch(e) {}`, `}`, `function __trickle_send(line) {`, `  __trickle_sendBuf.push(line);`, `  if (!__trickle_sendTimer) {`, `    __trickle_sendTimer = setTimeout(function() { __trickle_sendTimer = null; __trickle_flush(); }, 300);`, `  }`, `}`);
+        }
         else {
             // Browser mode — buffer and send via Vite HMR WebSocket
-            prefixLines.push(`const __trickle_sendBuf = [];`, `let __trickle_sendTimer = null;`, `function __trickle_flush() {`, `  if (__trickle_sendBuf.length === 0) return;`, `  const lines = __trickle_sendBuf.join('\\n') + '\\n';`, `  __trickle_sendBuf.length = 0;`, `  try { if (import.meta.hot) import.meta.hot.send('trickle:vars', { lines }); } catch(e) {}`, `}`, `function __trickle_send(line) {`, `  __trickle_sendBuf.push(line);`, `  if (!__trickle_sendTimer) {`, `    __trickle_sendTimer = setTimeout(() => { __trickle_sendTimer = null; __trickle_flush(); }, 300);`, `  }`, `}`);
+            prefixLines.push(`const __trickle_sendBuf = [];`, `let __trickle_sendTimer = null;`, `function __trickle_flush() {`, `  if (__trickle_sendBuf.length === 0) return;`, `  const lines = __trickle_sendBuf.join('\\n') + '\\n';`, `  __trickle_sendBuf.length = 0;`, `  try { if (import.meta.hot) import.meta.hot.send('trickle:vars', { lines }); } catch(e) {}`, `}`, `function __trickle_send(line) {`, `  __trickle_sendBuf.push(line);`, `  if (!__trickle_sendTimer) {`, `    __trickle_sendTimer = setTimeout(function() { __trickle_sendTimer = null; __trickle_flush(); }, 300);`, `  }`, `}`);
         }
     }
     // Add variable tracing if needed — inlined to avoid import resolution issues in Vite SSR.
@@ -1446,6 +1452,14 @@ export function transformEsmSource(source, filename, moduleName, backendUrl, deb
     for (const { position, code } of allInsertions) {
         result = result.slice(0, position) + code + result.slice(position);
     }
-    return prefix + result;
+    // Preserve 'use client' / 'use server' directives — they must be the first expression
+    // in the file (before any imports or code). Extract them from result and prepend before prefix.
+    let directive = '';
+    const directiveMatch = result.match(/^(\s*(?:'use client'|"use client"|'use server'|"use server")\s*;?\s*\n?)/);
+    if (directiveMatch) {
+        directive = directiveMatch[1];
+        result = result.slice(directiveMatch[0].length);
+    }
+    return directive + prefix + result;
 }
 export default tricklePlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-observe",
-  "version": "0.2.73",
+  "version": "0.2.74",
   "description": "Runtime type observability for JavaScript applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/next-loader.ts

@@ -17,6 +17,8 @@ interface LoaderOptions {
   exclude?: string[];
   debug?: boolean;
   traceVars?: boolean;
+  isServer?: boolean;
+  ingestPort?: number;
 }
 
 // webpack loader — `this` is the LoaderContext (must not be an arrow function)
@@ -40,13 +42,16 @@ export default function trickleNextLoader(this: { resourcePath: string; getOptio
   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 isServer = options.isServer ?? true;
+  const ingestPort = options.ingestPort ?? 4889;
   const moduleName = path.basename(resourcePath).replace(/\.[jt]sx?$/, '');
 
   try {
-    // Next.js SSR renders all components on the server, so use SSR mode (node:fs)
-    const transformed = transformEsmSource(source, resourcePath, moduleName, backendUrl, debug, traceVars, source, true);
+    // Server: use node:fs for writing. Client: use fetch() to ingest server.
+    const ingestUrl = isServer ? null : `http://localhost:${ingestPort}/__trickle_vars`;
+    const transformed = transformEsmSource(source, resourcePath, moduleName, backendUrl, debug, traceVars, source, isServer, ingestUrl);
     if (debug && transformed !== source) {
-      console.log(`[trickle/next] Instrumented ${resourcePath}`);
+      console.log(`[trickle/next] Instrumented ${resourcePath} [${isServer ? 'server' : 'client'}]`);
     }
     return transformed;
   } catch {

package/src/next-plugin.ts

@@ -29,6 +29,8 @@
  */
 
 import path from 'path';
+import http from 'http';
+import fs from 'fs';
 
 export interface TrickleNextOptions {
   /** Backend URL (default: http://localhost:4888 or TRICKLE_BACKEND_URL env var) */
@@ -41,6 +43,8 @@ export interface TrickleNextOptions {
   debug?: boolean;
   /** Enable variable tracing (default: true) */
   traceVars?: boolean;
+  /** Port for the client-side ingest server (default: 4889) */
+  ingestPort?: number;
 }
 
 type NextConfig = Record<string, unknown> & {
@@ -58,14 +62,80 @@ interface WebpackContext {
   [key: string]: unknown;
 }
 
+/** Track whether the ingest server is already running (avoid starting twice) */
+let ingestServerStarted = false;
+
+/**
+ * Start a tiny HTTP server that receives variable data from browser clients
+ * and writes it to .trickle/variables.jsonl.
+ */
+function startIngestServer(port: number, debug: boolean): void {
+  if (ingestServerStarted) return;
+  ingestServerStarted = true;
+
+  const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  const varsFile = path.join(dir, 'variables.jsonl');
+
+  const server = http.createServer((req, res) => {
+    // CORS headers for browser fetch
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    if (req.method === 'POST' && req.url === '/__trickle_vars') {
+      let body = '';
+      req.on('data', (chunk: string) => { body += chunk; });
+      req.on('end', () => {
+        try {
+          if (body) {
+            fs.appendFileSync(varsFile, body);
+          }
+        } catch {}
+        res.writeHead(200);
+        res.end('ok');
+      });
+      return;
+    }
+
+    res.writeHead(404);
+    res.end();
+  });
+
+  server.listen(port, () => {
+    if (debug) {
+      console.log(`[trickle/next] Ingest server listening on http://localhost:${port} → ${varsFile}`);
+    }
+  });
+
+  server.on('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'EADDRINUSE') {
+      // Another trickle instance already has the port — that's fine
+      if (debug) console.log(`[trickle/next] Ingest port ${port} already in use (OK)`);
+    }
+  });
+
+  // Don't keep the process alive just for this server
+  server.unref();
+}
+
 /**
  * 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.
+ * Also starts a tiny HTTP ingest server for client-side variable data.
  */
 export function withTrickle(nextConfig: NextConfig = {}, options: TrickleNextOptions = {}): NextConfig {
   const loaderPath = path.resolve(__dirname, './next-loader.js');
+  const ingestPort = options.ingestPort ?? 4889;
+  const debug = options.debug ?? (process.env.TRICKLE_DEBUG === '1');
 
   return {
     ...nextConfig,
@@ -75,13 +145,20 @@ export function withTrickle(nextConfig: NextConfig = {}, options: TrickleNextOpt
         config = nextConfig.webpack(config, context);
       }
 
+      // Start the ingest server for client-side data (once)
+      startIngestServer(ingestPort, debug);
+
       config.module.rules.push({
         test: /\.(tsx?|jsx?)$/,
-        exclude: /node_modules/,
+        exclude: /node_modules|trickle-observe|client-js/,
         use: [
           {
             loader: loaderPath,
-            options,
+            options: {
+              ...options,
+              isServer: context.isServer,
+              ingestPort,
+            },
           },
         ],
       });

package/src/vite-plugin.ts

@@ -889,6 +889,8 @@ export function transformEsmSource(
   traceVars: boolean,
   originalSource?: string | null,
   isSSR?: boolean,
+  /** URL for fetch-based browser transport (Next.js client). When set and isSSR=false, uses fetch() instead of import.meta.hot */
+  ingestUrl?: string | null,
 ): string {
   // Detect React files for component render tracking
   const isReactFile = /\.(tsx|jsx)$/.test(filename);
@@ -1370,6 +1372,24 @@ export function transformEsmSource(
         `  } catch(e) {}`,
         `}`,
       );
+    } else if (ingestUrl) {
+      // Browser mode with fetch transport (Next.js client)
+      prefixLines.push(
+        `const __trickle_sendBuf = [];`,
+        `let __trickle_sendTimer = null;`,
+        `function __trickle_flush() {`,
+        `  if (__trickle_sendBuf.length === 0) return;`,
+        `  const lines = __trickle_sendBuf.join('\\n') + '\\n';`,
+        `  __trickle_sendBuf.length = 0;`,
+        `  try { fetch(${JSON.stringify(ingestUrl)}, { method: 'POST', body: lines, headers: { 'Content-Type': 'text/plain' } }).catch(function(){}); } catch(e) {}`,
+        `}`,
+        `function __trickle_send(line) {`,
+        `  __trickle_sendBuf.push(line);`,
+        `  if (!__trickle_sendTimer) {`,
+        `    __trickle_sendTimer = setTimeout(function() { __trickle_sendTimer = null; __trickle_flush(); }, 300);`,
+        `  }`,
+        `}`,
+      );
     } else {
       // Browser mode — buffer and send via Vite HMR WebSocket
       prefixLines.push(
@@ -1384,7 +1404,7 @@ export function transformEsmSource(
         `function __trickle_send(line) {`,
         `  __trickle_sendBuf.push(line);`,
         `  if (!__trickle_sendTimer) {`,
-        `    __trickle_sendTimer = setTimeout(() => { __trickle_sendTimer = null; __trickle_flush(); }, 300);`,
+        `    __trickle_sendTimer = setTimeout(function() { __trickle_sendTimer = null; __trickle_flush(); }, 300);`,
         `  }`,
         `}`,
       );
@@ -1643,7 +1663,16 @@ export function transformEsmSource(
     result = result.slice(0, position) + code + result.slice(position);
   }
 
-  return prefix + result;
+  // Preserve 'use client' / 'use server' directives — they must be the first expression
+  // in the file (before any imports or code). Extract them from result and prepend before prefix.
+  let directive = '';
+  const directiveMatch = result.match(/^(\s*(?:'use client'|"use client"|'use server'|"use server")\s*;?\s*\n?)/);
+  if (directiveMatch) {
+    directive = directiveMatch[1];
+    result = result.slice(directiveMatch[0].length);
+  }
+
+  return directive + prefix + result;
 }
 
 export default tricklePlugin;