@watchforge/browser 0.1.1 → 0.1.4

package/CONFIGURATION_GUIDE.md

@@ -68,6 +68,36 @@ After installation, use it the same way:
 import { register, ErrorBoundary } from '@watchforge/browser';
 ```
 
+### Next.js Wizard Setup
+
+From your Next.js project root:
+
+```bash
+npx @watchforge/browser -i nextjs --dsn "https://PUBLIC_KEY@dev.watchforges.com/PROJECT_ID" --app-env production
+```
+
+With error-triggered Session Replay:
+
+```bash
+npx @watchforge/browser -i nextjs \
+  --dsn "https://PUBLIC_KEY@dev.watchforges.com/PROJECT_ID" \
+  --app-env production \
+  --replays-on-error 1
+```
+
+The wizard:
+
+1. Installs `@watchforge/browser`
+2. Creates `watchforge.config.ts`
+3. Creates `app/watchforge-init.tsx` (or `src/app/watchforge-init.tsx`)
+4. Patches `app/layout.tsx` to render `<WatchForgeInit />`
+
+If you only want file generation and no package install:
+
+```bash
+npx @watchforge/browser -i nextjs --dsn "..." --skip-install
+```
+
 ## Quick Testing
 
 ### Prerequisites
@@ -710,7 +740,11 @@ try {
 ```javascript
 // server.js
 const express = require('express');
-const { register, expressMiddleware } = require('@watchforge/browser');
+const {
+  register,
+  expressRequestMiddleware,
+  expressMiddleware,
+} = require('@watchforge/browser');
 
 const app = express();
 
@@ -719,6 +753,11 @@ register({
   app_env: process.env.NODE_ENV,
 });
 
+app.use(express.json());
+app.use(expressRequestMiddleware());
+
+// routes here
+
 // Add error handler (must be last middleware)
 app.use(expressMiddleware());
 
@@ -735,6 +774,11 @@ import App from './App';
 register({
   dsn: process.env.REACT_APP_WATCHFORGE_DSN,
   app_env: process.env.NODE_ENV,
+  // Optional: upload the last 60s of masked browser replay events when an error occurs.
+  replaysOnErrorSampleRate: 1.0,
+  // Optional: continuously sample full sessions. Keep 0 in production unless you need it.
+  replaysSessionSampleRate: 0,
+  maskAllInputs: true,
 });
 
 ReactDOM.render(
@@ -745,6 +789,95 @@ ReactDOM.render(
 );
 ```
 
+## Stack Trace Source Context
+
+The SDK enriches stack frames with Python-style source context when possible:
+
+| Field | Description |
+|-------|-------------|
+| `context_line` | The exact line where the error occurred |
+| `pre_context` | Up to 5 lines before the error |
+| `post_context` | Up to 5 lines after the error |
+
+### Node.js / Express
+
+For local project files, the SDK reads source from disk and attaches context lines automatically. No extra configuration is required.
+
+### Browser (development)
+
+In dev builds (Next.js, Vite, etc.), the SDK attempts to fetch same-origin script URLs from the stack trace and slice source lines around the reported line number.
+
+Works when stack frames point to readable URLs such as:
+
+```txt
+http://localhost:3000/_next/static/chunks/...
+http://localhost:3000/src/App.tsx
+```
+
+### Browser (production / minified bundles)
+
+Production bundles often report locations like:
+
+```txt
+https://your-app.com/_next/static/chunks/app-abc123.js:1:98432
+```
+
+The SDK still sends filename, line, and column, but **cannot** show original TypeScript/JSX source without **source maps**.
+
+**Current status:** source map upload and symbolication are not yet supported (planned for a future release).
+
+**Workarounds today:**
+
+1. Test with `npm run dev` / unminified builds to see source lines in WatchForge.
+2. Use `release` in `register()` so issues are grouped by deploy version.
+3. Rely on breadcrumbs and the Browser Event Summary in the dashboard to understand user actions before the error.
+
+When source map support ships, you will upload maps during deploy and WatchForge will resolve minified frames back to original files.
+
+## Session Replay
+
+The browser SDK can record a Sentry-style DOM replay using `rrweb`. Replays are **not videos**; they are masked DOM snapshots and incremental browser events that WatchForge can play back in the Issue Detail page.
+
+Enable replay capture when registering the SDK:
+
+```javascript
+register({
+  dsn: "https://PUBLIC_KEY@dev.watchforges.com/PROJECT_ID",
+  app_env: "production",
+  replaysOnErrorSampleRate: 1.0,
+  replaysSessionSampleRate: 0,
+  maskAllInputs: true,
+});
+```
+
+Replay behavior:
+
+- `replaysOnErrorSampleRate`: records in buffer mode and uploads the last 60 seconds when an error is captured.
+- `replaysSessionSampleRate`: continuously samples full browser sessions.
+- Text/input privacy is handled in the browser before upload.
+- Password, email, tel and text inputs are masked when `maskAllInputs` is true.
+- Elements with `.rr-block` are blocked.
+- Elements with `.rr-ignore` ignore input events.
+- Elements with `.rr-mask` mask text.
+
+When an error is captured, the SDK attaches:
+
+```json
+{
+  "replay_id": "...",
+  "session_id": "...",
+  "contexts": {
+    "replay": {
+      "replay_id": "...",
+      "session_id": "...",
+      "sampled": true
+    }
+  }
+}
+```
+
+The dashboard shows the linked replay in the Issue Detail **Session Replay** tab.
+
 ## Test Scripts
 
 Test scripts are included in the SDK directory:

package/README.md

@@ -18,6 +18,25 @@ Browser and Node SDK for WatchForge. **One call to `register()`** turns on autom
 npm install @watchforge/browser
 ```
 
+## Next.js one-line setup
+
+For Next.js apps, run the setup wizard from your app root:
+
+```bash
+npx @watchforge/browser -i nextjs --dsn "https://PUBLIC_KEY@your-host/PROJECT_ID" --app-env production
+```
+
+With Session Replay on errors:
+
+```bash
+npx @watchforge/browser -i nextjs \
+  --dsn "https://PUBLIC_KEY@your-host/PROJECT_ID" \
+  --app-env production \
+  --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`.
+
 ## Quick start (all most apps need)
 
 Call **`register()` once** as early as possible (e.g. app entry / main bundle), with your **DSN** from the WatchForge project settings.

package/bin/watchforge.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const HELP = `
+WatchForge setup wizard
+
+Usage:
+  npx @watchforge/browser -i nextjs --dsn <dsn> [options]
+  npx @watchforge/browser init nextjs --dsn <dsn> [options]
+
+Options:
+  -i, --integration <name>        Framework integration. Currently: nextjs
+  --dsn <dsn>                    WatchForge DSN
+  --app-env <env>                App environment (default: production)
+  --debug                        Enable SDK debug logging
+  --replays-on-error <rate>      Upload replay when errors happen (default: 0)
+  --replays-session <rate>       Continuously sample sessions (default: 0)
+  --skip-install                 Do not install @watchforge/browser
+  -h, --help                     Show help
+
+Example:
+  npx @watchforge/browser -i nextjs --dsn "https://PUBLIC_KEY@dev.watchforges.com/PROJECT_ID" --app-env development --replays-on-error 1
+`;
+
+function parseArgs(argv) {
+  const args = {
+    integration: null,
+    dsn: null,
+    appEnv: "production",
+    debug: false,
+    replaysOnError: "0",
+    replaysSession: "0",
+    skipInstall: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+
+    if (arg === "-h" || arg === "--help") args.help = true;
+    else if (arg === "-i" || arg === "--integration") {
+      args.integration = next;
+      i++;
+    } else if (arg === "init" || arg === "setup") {
+      args.integration = argv[i + 1] || args.integration;
+      i++;
+    } else if (arg === "--dsn") {
+      args.dsn = next;
+      i++;
+    } else if (arg === "--app-env" || arg === "--environment") {
+      args.appEnv = next || args.appEnv;
+      i++;
+    } else if (arg === "--debug") {
+      args.debug = true;
+    } else if (arg === "--replays-on-error") {
+      args.replaysOnError = next || "0";
+      i++;
+    } else if (arg === "--replays-session") {
+      args.replaysSession = next || "0";
+      i++;
+    } else if (arg === "--skip-install") {
+      args.skipInstall = true;
+    }
+  }
+
+  return args;
+}
+
+function log(message) {
+  console.log(`WatchForge: ${message}`);
+}
+
+function fail(message) {
+  console.error(`WatchForge setup failed: ${message}`);
+  process.exit(1);
+}
+
+function fileExists(filePath) {
+  return fs.existsSync(filePath) && fs.statSync(filePath).isFile();
+}
+
+function findNextLayout(cwd) {
+  const candidates = [
+    path.join(cwd, "src", "app", "layout.tsx"),
+    path.join(cwd, "src", "app", "layout.jsx"),
+    path.join(cwd, "app", "layout.tsx"),
+    path.join(cwd, "app", "layout.jsx"),
+  ];
+  return candidates.find(fileExists) || null;
+}
+
+function findPagesApp(cwd) {
+  const candidates = [
+    path.join(cwd, "src", "pages", "_app.tsx"),
+    path.join(cwd, "src", "pages", "_app.jsx"),
+    path.join(cwd, "pages", "_app.tsx"),
+    path.join(cwd, "pages", "_app.jsx"),
+  ];
+  return candidates.find(fileExists) || null;
+}
+
+function writeIfChanged(filePath, content) {
+  if (fileExists(filePath) && fs.readFileSync(filePath, "utf8") === content) {
+    return false;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  return true;
+}
+
+function createConfig(cwd, args) {
+  const configPath = path.join(cwd, "watchforge.config.ts");
+  const content = `export const watchforgeConfig = {
+  dsn: ${JSON.stringify(args.dsn)},
+  app_env: ${JSON.stringify(args.appEnv)},
+  debug: ${args.debug ? "true" : "false"},
+  replaysOnErrorSampleRate: ${Number(args.replaysOnError)},
+  replaysSessionSampleRate: ${Number(args.replaysSession)},
+  maskAllInputs: true,
+};
+`;
+  writeIfChanged(configPath, content);
+  log(`wrote ${path.relative(cwd, configPath)}`);
+}
+
+function installPackage(cwd, skipInstall) {
+  if (skipInstall) {
+    log("skipped npm install");
+    return;
+  }
+
+  const hasPnpm = fileExists(path.join(cwd, "pnpm-lock.yaml"));
+  const hasYarn = fileExists(path.join(cwd, "yarn.lock"));
+  const hasBun = fileExists(path.join(cwd, "bun.lockb"));
+
+  const command = hasPnpm
+    ? "pnpm add @watchforge/browser"
+    : hasYarn
+      ? "yarn add @watchforge/browser"
+      : hasBun
+        ? "bun add @watchforge/browser"
+        : "npm install @watchforge/browser";
+
+  log(`installing package: ${command}`);
+  execSync(command, { cwd, stdio: "inherit" });
+}
+
+function patchAppRouter(cwd, layoutPath) {
+  const appDir = path.dirname(layoutPath);
+  const isSrcApp = appDir.endsWith(path.join("src", "app"));
+  const configImport = isSrcApp ? "../../watchforge.config" : "../watchforge.config";
+  const initPath = path.join(appDir, "watchforge-init.tsx");
+
+  const initContent = `"use client";
+
+import { useEffect } from "react";
+import { register } from "@watchforge/browser";
+import { watchforgeConfig } from "${configImport}";
+
+export default function WatchForgeInit() {
+  useEffect(() => {
+    register(watchforgeConfig);
+  }, []);
+
+  return null;
+}
+`;
+
+  writeIfChanged(initPath, initContent);
+  log(`wrote ${path.relative(cwd, initPath)}`);
+
+  let layout = fs.readFileSync(layoutPath, "utf8");
+  if (!layout.includes("WatchForgeInit")) {
+    layout = `import WatchForgeInit from "./watchforge-init";\n${layout}`;
+  }
+
+  if (!layout.includes("<WatchForgeInit />")) {
+    layout = layout.replace(/<body([^>]*)>/, "<body$1>\n        <WatchForgeInit />\n        ");
+  }
+
+  fs.writeFileSync(layoutPath, layout);
+  log(`patched ${path.relative(cwd, layoutPath)}`);
+}
+
+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 content = fs.readFileSync(appPath, "utf8");
+
+  if (content.includes("register(watchforgeConfig)")) {
+    log(`${path.relative(cwd, appPath)} already contains WatchForge setup`);
+    return;
+  }
+
+  const patched = `import { useEffect } from "react";
+import { register } from "@watchforge/browser";
+import { watchforgeConfig } from "${configImport}";
+
+${content.replace(
+  /function\s+App\s*\(([^)]*)\)\s*{/,
+  "function App($1) {\n  useEffect(() => {\n    register(watchforgeConfig);\n  }, []);"
+)}`;
+
+  fs.writeFileSync(appPath, patched);
+  log(`patched ${path.relative(cwd, appPath)}`);
+}
+
+function initNextjs(args) {
+  const cwd = process.cwd();
+  if (!fileExists(path.join(cwd, "package.json"))) {
+    fail("run this command from the root of your Next.js project");
+  }
+
+  createConfig(cwd, args);
+  installPackage(cwd, args.skipInstall);
+
+  const layoutPath = findNextLayout(cwd);
+  if (layoutPath) {
+    patchAppRouter(cwd, layoutPath);
+    return;
+  }
+
+  const appPath = findPagesApp(cwd);
+  if (appPath) {
+    patchPagesRouter(cwd, appPath);
+    return;
+  }
+
+  fail("could not find app/layout.tsx or pages/_app.tsx");
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+if (args.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+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);
+log("setup complete");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watchforge/browser",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "main": "./src/index.js",
   "description": "WatchForge JavaScript SDK for Node.js, Express.js, and React",
   "license": "MIT",
@@ -22,12 +22,19 @@
     "./express": "./src/express.js",
     "./react": "./src/react.js"
   },
+  "bin": {
+    "watchforge": "bin/watchforge.js"
+  },
   "files": [
+    "bin/**/*.js",
     "src/**/*.js",
     "README.md",
     "CONFIGURATION_GUIDE.md",
     "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "peerDependencies": {
     "react": ">=16.8.0"
@@ -43,7 +50,8 @@
     "url": false
   },
   "dependencies": {
-    "express": "^5.2.1"
+    "express": "^5.2.1",
+    "rrweb": "^2.0.1"
   },
   "devDependencies": {
     "rollup": "^4.60.0"