@watchforge/browser 0.1.6 → 0.1.7

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
@@ -140,8 +145,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 +208,7 @@ function createConfig(cwd, args) {
 `;
   writeIfChanged(configPath, content);
   log(`wrote ${path.relative(cwd, configPath)}`);
+  return configPath;
 }
 
 function installPackage(cwd, skipInstall) {
@@ -179,13 +235,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 +268,102 @@ 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 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 +384,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"))) {
@@ -249,6 +523,8 @@ function initNextjs(args) {
   const layoutPath = findNextLayout(cwd);
   if (layoutPath) {
     patchAppRouter(cwd, layoutPath);
+    createNextGlobalError(cwd, layoutPath);
+    createNextInstrumentation(cwd, layoutPath);
     return;
   }
 
@@ -272,13 +548,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.7",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "description": "WatchForge JavaScript SDK for browser JavaScript, Next.js, React, Node.js, and Express.js",