@watchforge/browser 0.1.6 → 0.1.9

package/README.md

@@ -7,8 +7,9 @@ Browser, Next.js, React, Node.js, and Express SDK for WatchForge. **One call to
 | Runtime / Framework | Import | What it captures |
 | --- | --- | --- |
 | Browser JavaScript | `@watchforge/browser` | Uncaught errors, unhandled promise rejections, breadcrumbs, browser/device/page/performance context |
-| React | `@watchforge/browser` + `@watchforge/browser/react` | Browser errors plus React `ErrorBoundary` component stack context |
-| Next.js App Router | `@watchforge/browser/next` | Client-side Next.js errors through a client provider; wizard patches the app layout |
+| React / Vite / Vue / Angular | `@watchforge/browser` | Browser errors, unhandled promise rejections, breadcrumbs, replay, browser/device/page/performance context |
+| React | `@watchforge/browser/react` | Optional React `ErrorBoundary` component stack context |
+| Next.js App Router | `@watchforge/browser/next` + `@watchforge/browser/next/server` | Client-side errors, replay, global app render errors, Node runtime unhandled errors, route handler helper |
 | Node.js | `@watchforge/browser` or `@watchforge/browser/node` | `uncaughtException`, `unhandledRejection`, Node runtime/server context |
 | Express.js | `@watchforge/browser/express` | Express request errors, request URL/method/headers/body/query, user/IP, route, duration |
 
@@ -47,7 +48,39 @@ npx @watchforge/browser -i nextjs \
   --replays-on-error 1
 ```
 
-The wizard installs `@watchforge/browser`, writes `watchforge.config.ts`, creates a client init component, and patches `app/layout.tsx` or `pages/_app.tsx`.
+The wizard installs `@watchforge/browser` and writes the files needed for a full Next.js setup:
+
+- `watchforge.config.ts` or `watchforge.config.js`
+- `app/**/watchforge-init.tsx` / `.jsx` for browser errors and session replay
+- `app/**/global-error.tsx` / `.jsx` for Next.js app render errors surfaced through Next's error boundary
+- `src/instrumentation.ts` / `.js` or `instrumentation.ts` / `.js` for server runtime registration
+- patches `app/layout.tsx` / `.jsx` or `pages/_app.tsx` / `.jsx`
+
+For route handlers, wrap handlers with `withWatchForgeRouteHandler` from `@watchforge/browser/next/server`.
+
+## One-line setup for other JavaScript projects
+
+```bash
+# React
+npx @watchforge/browser -i react --dsn "https://PUBLIC_KEY@your-host/PROJECT_ID" --replays-on-error 1
+
+# Vite
+npx @watchforge/browser -i vite --dsn "https://PUBLIC_KEY@your-host/PROJECT_ID" --replays-on-error 1
+
+# Vue
+npx @watchforge/browser -i vue --dsn "https://PUBLIC_KEY@your-host/PROJECT_ID" --replays-on-error 1
+
+# Angular
+npx @watchforge/browser -i angular --dsn "https://PUBLIC_KEY@your-host/PROJECT_ID" --replays-on-error 1
+
+# Express
+npx @watchforge/browser -i express --dsn "https://PUBLIC_KEY@your-host/PROJECT_ID"
+
+# Node.js
+npx @watchforge/browser -i node --dsn "https://PUBLIC_KEY@your-host/PROJECT_ID"
+```
+
+For React/Vite/Vue/Angular, the wizard creates a browser init module and imports it from the detected entry file. For Express and Node.js, it creates a server setup file and prints the one or two lines to add to your server entry because middleware placement depends on each app.
 
 ## Framework Imports
 

package/bin/watchforge.js

@@ -10,10 +10,15 @@ WatchForge setup wizard
 
 Usage:
   npx @watchforge/browser -i nextjs --dsn <dsn> [options]
-  npx @watchforge/browser init nextjs --dsn <dsn> [options]
+  npx @watchforge/browser -i react --dsn <dsn> [options]
+  npx @watchforge/browser -i vite --dsn <dsn> [options]
+  npx @watchforge/browser -i vue --dsn <dsn> [options]
+  npx @watchforge/browser -i angular --dsn <dsn> [options]
+  npx @watchforge/browser -i express --dsn <dsn> [options]
+  npx @watchforge/browser -i node --dsn <dsn> [options]
 
 Options:
-  -i, --integration <name>        Framework integration. Currently: nextjs
+  -i, --integration <name>        Framework integration: nextjs, react, vite, vue, angular, express, node
   --dsn <dsn>                    WatchForge DSN
   --app-env <env>                App environment (default: production)
   --debug                        Enable SDK debug logging
@@ -131,6 +136,16 @@ function findPagesApp(cwd) {
   return candidates.find(fileExists) || null;
 }
 
+function findNextConfig(cwd) {
+  const candidates = [
+    "next.config.ts",
+    "next.config.mts",
+    "next.config.js",
+    "next.config.mjs",
+  ];
+  return candidates.map((candidate) => path.join(cwd, candidate)).find(fileExists) || null;
+}
+
 function writeIfChanged(filePath, content) {
   if (fileExists(filePath) && fs.readFileSync(filePath, "utf8") === content) {
     return false;
@@ -140,8 +155,58 @@ function writeIfChanged(filePath, content) {
   return true;
 }
 
+function toImportPath(fromDir, targetPath) {
+  let importPath = path.relative(fromDir, targetPath).replace(/\\/g, "/");
+  importPath = importPath.replace(/\.(ts|tsx|js|jsx)$/, "");
+  if (!importPath.startsWith(".")) {
+    importPath = `./${importPath}`;
+  }
+  return importPath;
+}
+
+function toNodeImportPath(fromDir, targetPath) {
+  let importPath = path.relative(fromDir, targetPath).replace(/\\/g, "/");
+  importPath = importPath.replace(/\.(ts|tsx)$/, "");
+  if (!importPath.startsWith(".")) {
+    importPath = `./${importPath}`;
+  }
+  return importPath;
+}
+
+function projectUsesTypeScript(cwd) {
+  if (fileExists(path.join(cwd, "tsconfig.json"))) return true;
+
+  const srcDir = path.join(cwd, "src");
+  if (!fs.existsSync(srcDir) || !fs.statSync(srcDir).isDirectory()) return false;
+
+  const stack = [srcDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const entryPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== "node_modules" && entry.name !== ".next") {
+          stack.push(entryPath);
+        }
+      } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+function getConfigPath(cwd) {
+  const tsConfig = path.join(cwd, "watchforge.config.ts");
+  const jsConfig = path.join(cwd, "watchforge.config.js");
+  if (fileExists(tsConfig)) return tsConfig;
+  if (fileExists(jsConfig)) return jsConfig;
+  return projectUsesTypeScript(cwd) ? tsConfig : jsConfig;
+}
+
 function createConfig(cwd, args) {
-  const configPath = path.join(cwd, "watchforge.config.ts");
+  const configPath = getConfigPath(cwd);
   const content = `export const watchforgeConfig = {
   dsn: ${JSON.stringify(args.dsn)},
   app_env: ${JSON.stringify(args.appEnv)},
@@ -153,6 +218,7 @@ function createConfig(cwd, args) {
 `;
   writeIfChanged(configPath, content);
   log(`wrote ${path.relative(cwd, configPath)}`);
+  return configPath;
 }
 
 function installPackage(cwd, skipInstall) {
@@ -179,13 +245,12 @@ function installPackage(cwd, skipInstall) {
 
 function patchAppRouter(cwd, layoutPath) {
   const appDir = path.dirname(layoutPath);
-  const configPath = path.join(cwd, "watchforge.config.ts");
-  let configImport = path.relative(appDir, configPath).replace(/\\/g, "/");
-  configImport = configImport.replace(/\.ts$/, "");
-  if (!configImport.startsWith(".")) {
-    configImport = `./${configImport}`;
-  }
-  const initPath = path.join(appDir, "watchforge-init.tsx");
+  const configPath = getConfigPath(cwd);
+  const configImport = toImportPath(appDir, configPath);
+  const initPath = path.join(
+    appDir,
+    projectUsesTypeScript(cwd) ? "watchforge-init.tsx" : "watchforge-init.jsx"
+  );
 
   const initContent = `"use client";
 
@@ -213,10 +278,135 @@ export default function WatchForgeInit() {
   log(`patched ${path.relative(cwd, layoutPath)}`);
 }
 
+function createNextGlobalError(cwd, layoutPath) {
+  const appDir = path.dirname(layoutPath);
+  const usesTs = projectUsesTypeScript(cwd);
+  const globalErrorPath = path.join(appDir, usesTs ? "global-error.tsx" : "global-error.jsx");
+
+  if (fileExists(globalErrorPath)) {
+    const content = fs.readFileSync(globalErrorPath, "utf8");
+    if (content.includes("@watchforge/browser") || content.includes("captureException")) {
+      log(`${path.relative(cwd, globalErrorPath)} already contains WatchForge setup`);
+      return;
+    }
+    log(`skipped ${path.relative(cwd, globalErrorPath)} because it already exists`);
+    log("add captureException(error) there manually to report Next.js render errors");
+    return;
+  }
+
+  const propsSignature = usesTs
+    ? `{\n  error,\n}: {\n  error: Error & { digest?: string };\n}`
+    : `{ error }`;
+
+  const content = `"use client";
+
+import { useEffect } from "react";
+import { captureException } from "@watchforge/browser";
+
+export default function GlobalError(${propsSignature}) {
+  useEffect(() => {
+    void captureException(error, {
+      tags: {
+        framework: "nextjs",
+        runtime: "error-boundary",
+      },
+      extra: {
+        digest: error.digest,
+      },
+      contexts: {
+        nextjs: {
+          error_boundary: "global-error",
+          digest: error.digest || null,
+        },
+      },
+    });
+  }, [error]);
+
+  return (
+    <html>
+      <body>
+        <h2>Something went wrong.</h2>
+      </body>
+    </html>
+  );
+}
+`;
+
+  writeIfChanged(globalErrorPath, content);
+  log(`wrote ${path.relative(cwd, globalErrorPath)}`);
+}
+
+function createNextInstrumentation(cwd, layoutPath) {
+  const appRoot = path.dirname(layoutPath).includes(`${path.sep}src${path.sep}app`)
+    ? path.join(cwd, "src")
+    : cwd;
+  const instrumentationPath = path.join(
+    appRoot,
+    projectUsesTypeScript(cwd) ? "instrumentation.ts" : "instrumentation.js"
+  );
+  const configImport = toImportPath(path.dirname(instrumentationPath), getConfigPath(cwd));
+
+  if (fileExists(instrumentationPath)) {
+    const content = fs.readFileSync(instrumentationPath, "utf8");
+    if (content.includes("@watchforge/browser/next/server")) {
+      log(`${path.relative(cwd, instrumentationPath)} already contains WatchForge setup`);
+      return;
+    }
+    log(`skipped ${path.relative(cwd, instrumentationPath)} because it already exists`);
+    log("add registerWatchForge(watchforgeConfig) there manually to report Next.js server runtime errors");
+    return;
+  }
+
+  const content = `import { register as registerWatchForge } from "@watchforge/browser/next/server";
+import { watchforgeConfig } from "${configImport}";
+
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    registerWatchForge(watchforgeConfig);
+  }
+}
+`;
+
+  writeIfChanged(instrumentationPath, content);
+  log(`wrote ${path.relative(cwd, instrumentationPath)}`);
+}
+
+function patchNextConfig(cwd) {
+  const configPath = findNextConfig(cwd);
+  if (!configPath) {
+    log("could not find next.config.* to patch for compiler error capture");
+    log('wrap your Next config with withWatchForgeConfig(config, watchforgeConfig) from "@watchforge/browser/next/config"');
+    return;
+  }
+
+  let content = fs.readFileSync(configPath, "utf8");
+  if (content.includes("withWatchForgeConfig")) {
+    log(`${path.relative(cwd, configPath)} already contains WatchForge compiler setup`);
+    return;
+  }
+
+  const configImport = toImportPath(path.dirname(configPath), getConfigPath(cwd));
+  content = `import { withWatchForgeConfig } from "@watchforge/browser/next/config";\nimport { watchforgeConfig } from "${configImport}";\n${content}`;
+
+  const exportDefaultMatch = content.match(/export\s+default\s+([^;]+);/);
+  if (!exportDefaultMatch) {
+    log(`skipped ${path.relative(cwd, configPath)} because export default could not be patched automatically`);
+    log('wrap your exported config with withWatchForgeConfig(config, watchforgeConfig)');
+    return;
+  }
+
+  content = content.replace(
+    exportDefaultMatch[0],
+    `export default withWatchForgeConfig(${exportDefaultMatch[1]}, watchforgeConfig);`
+  );
+
+  fs.writeFileSync(configPath, content);
+  log(`patched ${path.relative(cwd, configPath)} for compiler error capture`);
+}
+
 function patchPagesRouter(cwd, appPath) {
   const pagesDir = path.dirname(appPath);
-  const isSrcPages = pagesDir.endsWith(path.join("src", "pages"));
-  const configImport = isSrcPages ? "../../watchforge.config" : "../watchforge.config";
+  const configImport = toImportPath(pagesDir, getConfigPath(cwd));
   const content = fs.readFileSync(appPath, "utf8");
 
   if (content.includes("register(watchforgeConfig)")) {
@@ -237,6 +427,133 @@ ${content.replace(
   log(`patched ${path.relative(cwd, appPath)}`);
 }
 
+function findFirstFile(cwd, candidates) {
+  return candidates.map((candidate) => path.join(cwd, candidate)).find(fileExists) || null;
+}
+
+function prependImportOnce(filePath, importLine) {
+  const content = fs.readFileSync(filePath, "utf8");
+  if (content.includes(importLine)) return false;
+  fs.writeFileSync(filePath, `${importLine}\n${content}`);
+  return true;
+}
+
+function createBrowserInit(cwd, initRelativePath = null) {
+  const defaultPath = projectUsesTypeScript(cwd)
+    ? "src/watchforge-init.ts"
+    : "src/watchforge-init.js";
+  const initPath = path.join(cwd, initRelativePath || defaultPath);
+  const configImport = toImportPath(path.dirname(initPath), getConfigPath(cwd));
+  const content = `import { register } from "@watchforge/browser";
+import { watchforgeConfig } from "${configImport}";
+
+register(watchforgeConfig);
+`;
+
+  writeIfChanged(initPath, content);
+  log(`wrote ${path.relative(cwd, initPath)}`);
+  return initPath;
+}
+
+function initBrowserFramework(args, integration) {
+  const cwd = process.cwd();
+  if (!fileExists(path.join(cwd, "package.json"))) {
+    fail(`run this command from the root of your ${integration} project`);
+  }
+
+  createConfig(cwd, args);
+  installPackage(cwd, args.skipInstall);
+
+  const entryPath = findFirstFile(cwd, [
+    "src/main.tsx",
+    "src/main.jsx",
+    "src/main.ts",
+    "src/main.js",
+    "src/index.tsx",
+    "src/index.jsx",
+    "src/index.ts",
+    "src/index.js",
+    "main.ts",
+    "main.js",
+    "index.ts",
+    "index.js",
+  ]);
+
+  const initPath = createBrowserInit(cwd);
+  if (!entryPath) {
+    log("could not find a browser entry file to patch");
+    log(`import "./${path.relative(cwd, initPath).replace(/\\/g, "/").replace(/\.(ts|js)$/, "")}" from your app entry`);
+    return;
+  }
+
+  const initImport = toImportPath(path.dirname(entryPath), initPath);
+  if (prependImportOnce(entryPath, `import "${initImport}";`)) {
+    log(`patched ${path.relative(cwd, entryPath)}`);
+  } else {
+    log(`${path.relative(cwd, entryPath)} already imports WatchForge`);
+  }
+}
+
+function initExpress(args) {
+  const cwd = process.cwd();
+  if (!fileExists(path.join(cwd, "package.json"))) {
+    fail("run this command from the root of your Express project");
+  }
+
+  createConfig(cwd, args);
+  installPackage(cwd, args.skipInstall);
+
+  const setupPath = path.join(
+    cwd,
+    projectUsesTypeScript(cwd) ? "watchforge-express.ts" : "watchforge-express.js"
+  );
+  const configImport = toNodeImportPath(path.dirname(setupPath), getConfigPath(cwd));
+  const content = `import { register } from "@watchforge/browser/node";
+import {
+  expressMiddleware,
+  expressRequestMiddleware,
+} from "@watchforge/browser/express";
+import { watchforgeConfig } from "${configImport}";
+
+register(watchforgeConfig);
+
+export { expressMiddleware, expressRequestMiddleware };
+`;
+
+  writeIfChanged(setupPath, content);
+  log(`wrote ${path.relative(cwd, setupPath)}`);
+  log("add this near the top of your Express app:");
+  log('  import { expressRequestMiddleware, expressMiddleware } from "./watchforge-express";');
+  log("  app.use(expressRequestMiddleware());");
+  log("and add this after your routes:");
+  log("  app.use(expressMiddleware());");
+}
+
+function initNode(args) {
+  const cwd = process.cwd();
+  if (!fileExists(path.join(cwd, "package.json"))) {
+    fail("run this command from the root of your Node.js project");
+  }
+
+  createConfig(cwd, args);
+  installPackage(cwd, args.skipInstall);
+
+  const setupPath = path.join(
+    cwd,
+    projectUsesTypeScript(cwd) ? "watchforge-node.ts" : "watchforge-node.js"
+  );
+  const configImport = toNodeImportPath(path.dirname(setupPath), getConfigPath(cwd));
+  const content = `import { register } from "@watchforge/browser/node";
+import { watchforgeConfig } from "${configImport}";
+
+register(watchforgeConfig);
+`;
+
+  writeIfChanged(setupPath, content);
+  log(`wrote ${path.relative(cwd, setupPath)}`);
+  log('import "./watchforge-node"; as early as possible in your server entry file');
+}
+
 function initNextjs(args) {
   const cwd = process.cwd();
   if (!fileExists(path.join(cwd, "package.json"))) {
@@ -248,12 +565,16 @@ function initNextjs(args) {
 
   const layoutPath = findNextLayout(cwd);
   if (layoutPath) {
+    patchNextConfig(cwd);
     patchAppRouter(cwd, layoutPath);
+    createNextGlobalError(cwd, layoutPath);
+    createNextInstrumentation(cwd, layoutPath);
     return;
   }
 
   const appPath = findPagesApp(cwd);
   if (appPath) {
+    patchNextConfig(cwd);
     patchPagesRouter(cwd, appPath);
     return;
   }
@@ -272,13 +593,24 @@ if (!args.integration) {
   fail("missing integration. Use: -i nextjs");
 }
 
-if (args.integration !== "nextjs") {
-  fail(`unsupported integration "${args.integration}". Currently supported: nextjs`);
-}
-
 if (!args.dsn) {
   fail("missing --dsn");
 }
 
-initNextjs(args);
+const integration = args.integration.toLowerCase();
+
+if (integration === "nextjs" || integration === "next") {
+  initNextjs(args);
+} else if (["react", "vite", "vue", "angular", "browser"].includes(integration)) {
+  initBrowserFramework(args, integration);
+} else if (integration === "express") {
+  initExpress(args);
+} else if (integration === "node" || integration === "nodejs") {
+  initNode(args);
+} else {
+  fail(
+    `unsupported integration "${args.integration}". Supported: nextjs, react, vite, vue, angular, express, node`
+  );
+}
+
 log("setup complete");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watchforge/browser",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "description": "WatchForge JavaScript SDK for browser JavaScript, Next.js, React, Node.js, and Express.js",
@@ -33,6 +33,10 @@
       "types": "./src/next-server.d.ts",
       "default": "./src/next-server.js"
     },
+    "./next/config": {
+      "types": "./src/next-config.d.ts",
+      "default": "./src/next-config.js"
+    },
     "./express": {
       "types": "./src/express.d.ts",
       "default": "./src/express.js"

package/src/contexts.js

@@ -73,10 +73,14 @@ export function getPerformanceContext() {
 
 let nodeOsPromise = null;
 
+// Hide from bundlers (Next.js/webpack) so client builds don't resolve Node built-ins.
+const importNodeBuiltin = (specifier) =>
+  new Function("specifier", "return import(specifier)")(specifier);
+
 async function getNodeOs() {
   if (!isNode) return null;
   if (!nodeOsPromise) {
-    nodeOsPromise = import("os").catch(() => null);
+    nodeOsPromise = importNodeBuiltin("os").catch(() => null);
   }
   return nodeOsPromise;
 }

package/src/next-config.d.ts

@@ -0,0 +1,6 @@
+import type { WatchForgeRegisterOptions } from "./index";
+
+export function withWatchForgeConfig<T extends Record<string, unknown>>(
+  nextConfig?: T,
+  watchforgeOptions?: WatchForgeRegisterOptions
+): T;

package/src/next-config.js

@@ -0,0 +1,135 @@
+import { captureException, register } from "./client.js";
+
+const PLUGIN_NAME = "WatchForgeNextCompilerPlugin";
+const sentCompilerErrors = new Set();
+let registeredDsn = null;
+
+function getLoc(rawError) {
+  const loc = rawError?.loc || rawError?.module?.loc;
+
+  if (typeof loc === "string") {
+    const match = loc.match(/(\d+)(?::(\d+))?/);
+    if (match) {
+      return {
+        line: Number(match[1]),
+        column: Number(match[2] || 1),
+      };
+    }
+  }
+
+  if (loc && typeof loc === "object") {
+    const start = loc.start || loc;
+    return {
+      line: Number(start.line || start.lineNumber || 1),
+      column: Number(start.column || start.col || 1),
+    };
+  }
+
+  return { line: 1, column: 1 };
+}
+
+function getModulePath(rawError) {
+  return (
+    rawError?.module?.resource ||
+    rawError?.module?.resourceResolveData?.path ||
+    rawError?.file ||
+    rawError?.moduleName ||
+    null
+  );
+}
+
+function createCompilerException(rawError) {
+  const message =
+    rawError?.message ||
+    rawError?.details ||
+    String(rawError || "Next.js compiler error");
+  const error = new Error(message);
+  error.name = rawError?.name || "NextWebpackCompilationError";
+
+  const filePath = getModulePath(rawError);
+  if (filePath) {
+    const { line, column } = getLoc(rawError);
+    error.stack = `${error.name}: ${message}\n    at Next.js compilation (${filePath}:${line}:${column})`;
+    if (rawError?.stack) {
+      error.stack += `\n${String(rawError.stack).split("\n").slice(1).join("\n")}`;
+    }
+  } else if (rawError?.stack) {
+    error.stack = rawError.stack;
+  }
+
+  return error;
+}
+
+function getCompilerErrorFingerprint(rawError, compilerName, hash) {
+  const filePath = getModulePath(rawError) || "";
+  const loc = getLoc(rawError);
+  const message = rawError?.message || String(rawError || "");
+  return [hash || "", compilerName || "", filePath, loc.line, loc.column, message].join("|");
+}
+
+function createCompilerPlugin() {
+  return {
+    name: PLUGIN_NAME,
+    apply(compiler) {
+      compiler.hooks.done.tapPromise(PLUGIN_NAME, async (stats) => {
+        if (!stats?.hasErrors?.()) return;
+
+        const errors = stats.compilation?.errors || [];
+        const compilerName = compiler.name || stats.compilation?.name || null;
+
+        for (const rawError of errors) {
+          const fingerprint = getCompilerErrorFingerprint(rawError, compilerName, stats.hash);
+          if (sentCompilerErrors.has(fingerprint)) continue;
+          sentCompilerErrors.add(fingerprint);
+
+          await captureException(createCompilerException(rawError), {
+            tags: {
+              framework: "nextjs",
+              runtime: "compiler",
+              compiler: compilerName,
+            },
+            contexts: {
+              nextjs: {
+                compiler_error: true,
+                module: getModulePath(rawError),
+                loc: rawError?.loc || rawError?.module?.loc || null,
+              },
+            },
+            extra: {
+              details: rawError?.details || null,
+              module_identifier: rawError?.module?.identifier?.() || null,
+              module_name: rawError?.module?.readableIdentifier?.({}) || rawError?.moduleName || null,
+            },
+          });
+        }
+      });
+    },
+  };
+}
+
+function ensureRegistered(options) {
+  if (!options?.dsn || registeredDsn === options.dsn) return;
+  registeredDsn = options.dsn;
+  register(options);
+}
+
+export function withWatchForgeConfig(nextConfig = {}, watchforgeOptions = {}) {
+  ensureRegistered(watchforgeOptions);
+
+  const userWebpack = nextConfig.webpack;
+
+  return {
+    ...nextConfig,
+    webpack(config, options) {
+      const finalConfig = userWebpack ? userWebpack(config, options) || config : config;
+      finalConfig.plugins = finalConfig.plugins || [];
+
+      const hasPlugin = finalConfig.plugins.some((plugin) => plugin?.name === PLUGIN_NAME);
+      if (!hasPlugin) {
+        finalConfig.plugins.push(createCompilerPlugin());
+      }
+
+      return finalConfig;
+    },
+  };
+}