@watchforge/browser 0.1.3 → 0.1.5

package/CONFIGURATION_GUIDE.md

@@ -2,10 +2,51 @@
 
 ## Overview
 
-The WatchForge JavaScript SDK automatically captures errors and events in:
+The WatchForge JavaScript SDK is one npm package with typed framework entry points for:
+
+- **Browser JavaScript** applications
+- **Next.js** App Router applications
+- **React** frontend applications
 - **Node.js** applications
 - **Express.js** web servers
-- **React** frontend applications
+
+This package intentionally stays unified instead of splitting into separate `watchforge-next-sdk`, `watchforge-node-sdk`, `watchforge-react-sdk`, and `watchforge-express-sdk` packages. The shared package keeps DSN handling, event transport, breadcrumbs, stack traces, source context, and session replay consistent across JavaScript runtimes.
+
+## Supported Imports
+
+```ts
+// Browser JavaScript, React client, and shared APIs
+import { register, captureException, captureMessage } from "@watchforge/browser";
+
+// Next.js App Router client provider
+import { WatchForgeProvider } from "@watchforge/browser/next";
+
+// Next.js server route handlers
+import { withWatchForgeRouteHandler } from "@watchforge/browser/next/server";
+
+// React error boundary
+import { ErrorBoundary } from "@watchforge/browser/react";
+
+// Express middleware
+import {
+  expressRequestMiddleware,
+  expressMiddleware,
+} from "@watchforge/browser/express";
+
+// Explicit Node.js import
+import { register as registerNode } from "@watchforge/browser/node";
+```
+
+## Support Matrix
+
+| Runtime / Framework | Entry point | Recommended setup |
+| --- | --- | --- |
+| Browser JavaScript | `@watchforge/browser` | Call `register()` once in the main browser bundle |
+| React | `@watchforge/browser` + `@watchforge/browser/react` | Call `register()` once and wrap the app with `ErrorBoundary` |
+| Next.js App Router client | `@watchforge/browser/next` | Use the wizard or render `WatchForgeProvider` from a client component |
+| Next.js App Router server | `@watchforge/browser/next/server` | Wrap route handlers with `withWatchForgeRouteHandler()` |
+| Node.js | `@watchforge/browser/node` | Call `register()` once during process startup |
+| Express.js | `@watchforge/browser/express` | Add request middleware before routes and error middleware after routes |
 
 ## Installation
 
@@ -64,8 +105,39 @@ npm install ../watchforge-javascript-sdk
 ```
 
 After installation, use it the same way:
-```javascript
-import { register, ErrorBoundary } from '@watchforge/browser';
+```ts
+import { register } from "@watchforge/browser";
+import { ErrorBoundary } from "@watchforge/browser/react";
+```
+
+### 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
@@ -158,11 +230,92 @@ See the React setup section below for complete examples.
 
 ## Quick Start
 
+### Browser JavaScript
+
+```ts
+import { register } from "@watchforge/browser";
+
+register({
+  dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+  app_env: "production",
+});
+```
+
+This captures uncaught browser errors, unhandled promise rejections, breadcrumbs, page context, browser/device/OS details, and performance context.
+
+### Next.js App Router
+
+Create `watchforge.config.ts` in your project root:
+
+```ts
+export const watchforgeConfig = {
+  dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+  app_env: "production",
+  replaysOnErrorSampleRate: 1,
+  maskAllInputs: true,
+};
+```
+
+Create a client init component beside your frontend layout, for example `src/app/watchforge-init.tsx` or `src/app/(frontend)/watchforge-init.tsx`:
+
+```tsx
+"use client";
+
+import { WatchForgeProvider } from "@watchforge/browser/next";
+import { watchforgeConfig } from "../watchforge.config";
+
+export default function WatchForgeInit() {
+  return <WatchForgeProvider options={watchforgeConfig} />;
+}
+```
+
+Render it once in the matching `layout.tsx`:
+
+```tsx
+import WatchForgeInit from "./watchforge-init";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <WatchForgeInit />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+For route-group projects like `src/app/(frontend)/layout.tsx`, put `watchforge-init.tsx` in that same route group and adjust the config import path if needed.
+
+For Next.js route handlers, use the server entry point:
+
+```ts
+// app/api/example/route.ts
+import {
+  register,
+  withWatchForgeRouteHandler,
+} from "@watchforge/browser/next/server";
+
+register({
+  dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+  app_env: "production",
+});
+
+export const GET = withWatchForgeRouteHandler(async () => {
+  throw new Error("Next.js API route test error");
+});
+```
+
 ### 1. Node.js Application
 
-```javascript
+```ts
 // app.js
-const { register, captureException, captureMessage } = require('@watchforge/browser');
+import {
+  register,
+  captureException,
+  captureMessage,
+} from "@watchforge/browser/node";
 
 // Initialize SDK
 // API URL is automatically derived from DSN host
@@ -184,10 +337,14 @@ captureMessage("User logged in", "info");
 
 ### 2. Express.js Application
 
-```javascript
+```ts
 // server.js
-const express = require('express');
-const { register, expressMiddleware } = require('@watchforge/browser');
+import express from "express";
+import { register } from "@watchforge/browser/node";
+import {
+  expressRequestMiddleware,
+  expressMiddleware,
+} from "@watchforge/browser/express";
 
 const app = express();
 
@@ -710,7 +867,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 +880,12 @@ register({
   app_env: process.env.NODE_ENV,
 });
 
+app.use(express.json());
+app.use(expressRequestMiddleware());
+app.use(expressRequestMiddleware());
+
+// routes here
+
 // Add error handler (must be last middleware)
 app.use(expressMiddleware());
 
@@ -735,6 +902,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 +917,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

@@ -1,6 +1,18 @@
 # WatchForge JavaScript SDK (`@watchforge/browser`)
 
-Browser and Node SDK for WatchForge. **One call to `register()`** turns on automatic error reporting—no manual `try/catch` required for typical crashes.
+Browser, Next.js, React, Node.js, and Express SDK for WatchForge. **One call to `register()`** turns on automatic error reporting for typical crashes, and framework entry points add richer context where needed.
+
+## Runtime Support
+
+| 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 |
+| 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 |
+
+The package is intentionally shipped as **one npm package** with typed subpath exports instead of separate SDK packages. This keeps DSN setup, replay, stack traces, breadcrumbs, and event transport consistent across JavaScript runtimes.
 
 ## What this package does *not* require
 
@@ -18,6 +30,150 @@ 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`.
+
+## Framework Imports
+
+WatchForge ships as one JavaScript SDK package with typed framework entry points:
+
+```ts
+// Browser / React client / Node global handlers
+import { register } from "@watchforge/browser";
+
+// Next.js App Router client provider
+import { WatchForgeProvider } from "@watchforge/browser/next";
+
+// Next.js App Router server route helper
+import { withWatchForgeRouteHandler } from "@watchforge/browser/next/server";
+
+// React error boundary
+import { ErrorBoundary } from "@watchforge/browser/react";
+
+// Express middleware
+import {
+  expressRequestMiddleware,
+  expressMiddleware,
+} from "@watchforge/browser/express";
+
+// Optional explicit Node import
+import { captureException } from "@watchforge/browser/node";
+```
+
+## Next.js Manual Setup
+
+Use the wizard when possible. For manual setup in App Router projects, create a client init component for browser-side errors:
+
+```tsx
+"use client";
+
+import { WatchForgeProvider } from "@watchforge/browser/next";
+import { watchforgeConfig } from "../watchforge.config";
+
+export default function WatchForgeInit() {
+  return <WatchForgeProvider options={watchforgeConfig} />;
+}
+```
+
+Then render it once in your frontend `layout.tsx`:
+
+```tsx
+import WatchForgeInit from "./watchforge-init";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <WatchForgeInit />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+For route groups, place the init component beside the frontend layout, for example `src/app/(frontend)/watchforge-init.tsx`, and import `watchforge.config.ts` using the correct relative path.
+
+For server route handlers, initialize once in server code and wrap handlers:
+
+```ts
+import {
+  register,
+  withWatchForgeRouteHandler,
+} from "@watchforge/browser/next/server";
+
+register({
+  dsn: "https://PUBLIC_KEY@your-host/PROJECT_ID",
+  app_env: "production",
+});
+
+export const GET = withWatchForgeRouteHandler(async () => {
+  throw new Error("Next.js route handler test error");
+});
+```
+
+## Express Setup
+
+```ts
+import express from "express";
+import { register } from "@watchforge/browser/node";
+import {
+  expressRequestMiddleware,
+  expressMiddleware,
+} from "@watchforge/browser/express";
+
+register({
+  dsn: "https://PUBLIC_KEY@your-host/PROJECT_ID",
+  app_env: "production",
+});
+
+const app = express();
+app.use(express.json());
+app.use(expressRequestMiddleware());
+
+app.get("/error", () => {
+  throw new Error("Express test error");
+});
+
+app.use(expressMiddleware());
+```
+
+## React Setup
+
+```tsx
+import { register } from "@watchforge/browser";
+import { ErrorBoundary } from "@watchforge/browser/react";
+
+register({
+  dsn: "https://PUBLIC_KEY@your-host/PROJECT_ID",
+  app_env: "production",
+});
+
+export function AppRoot() {
+  return (
+    <ErrorBoundary fallback={<div>Something went wrong.</div>}>
+      <App />
+    </ErrorBoundary>
+  );
+}
+```
+
 ## 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.