@hawk.so/nextjs 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,75 +1,315 @@
 /// <reference path="../global.d.ts" />
-import { NextConfig } from 'next';
+import { HawkInitialSettings } from '@hawk.so/browser';
+import { CatcherMessagePayload, EventContext, AffectedUser } from '@hawk.so/types';
+export { AffectedUser, EventContext } from '@hawk.so/types';
+import { BreadcrumbsAPI } from '@hawk.so/core';
+export { BreadcrumbsAPI } from '@hawk.so/core';
+import { Component, ReactNode, ErrorInfo, ReactElement } from 'react';
 
 /**
- * Options of the commits collecting
+ * Event passed to `beforeSend`: from the browser or from the server
  */
-interface CommitsOptions {
+type HawkEvent = CatcherMessagePayload<'errors/javascript'> | CatcherMessagePayload<'errors/nodejs'>;
+/**
+ * Options of `init()`. The same options are accepted in the browser and on the server,
+ * options of the browser catcher are ignored on the server
+ */
+interface HawkInitOptions extends Pick<HawkInitialSettings, 'user' | 'debug' | 'breadcrumbs' | 'consoleTracking' | 'issues' | 'reconnectionTimeout' | 'transport'> {
+    /**
+     * Hawk Integration Token. Default is the NEXT_PUBLIC_HAWK_TOKEN environment variable,
+     * on the server HAWK_TOKEN is checked first
+     */
+    token?: string;
+    /**
+     * Release id. Default is `process.env.HAWK_RELEASE` set by `withHawkConfig`
+     */
+    release?: string;
     /**
-     * Path to the repository with `.git` directory. Default is the Next.js project directory
+     * Collector endpoint overwrite: WebSocket URL in the browser, HTTP URL on the server
      */
-    repo?: string;
+    collectorEndpoint?: string;
     /**
-     * How many recent commits to send. Default is 5
+     * Data sent with every event
      */
-    number?: number;
+    context?: EventContext;
+    /**
+     * Filters or modifies events before sending. Return the event to send it or `false` to drop it
+     */
+    beforeSend?: (event: HawkEvent) => HawkEvent | false | void;
+    /**
+     * Disables catching of uncaught errors and unhandled rejections: `window` handlers in the browser,
+     * `process` handlers in Node.js
+     */
+    disableGlobalErrorsHandling?: boolean;
 }
 
 /**
- * Options of the Hawk Next.js integration
+ * Request passed by Next.js to `onRequestError`
  */
-interface HawkNextOptions {
+interface RequestErrorRequest {
     /**
-     * Hawk Integration Token. Default is the HAWK_TOKEN environment variable
+     * Request path with the query string
      */
-    token?: string;
+    path: string;
     /**
-     * Unique identifier of the release.
-     * Default is HAWK_RELEASE environment variable, commit SHA from CI or git, or the build time
+     * HTTP method
      */
-    release?: string | number;
+    method: string;
     /**
-     * Whether to remove client source maps after sending. Default is true
+     * Request headers
      */
-    removeSourceMaps?: boolean;
+    headers: Record<string, string | string[] | undefined>;
+}
+/**
+ * Context passed by Next.js to `onRequestError`. Fields differ between Next.js versions, so they are loose strings
+ */
+interface RequestErrorContext {
     /**
-     * Options for sending recent commits with the release, or false to skip. Enabled by default
+     * `App Router` or `Pages Router`
      */
-    commits?: boolean | CommitsOptions;
+    routerKind: string;
     /**
-     * Collector endpoint overwrite
+     * Route file path, e.g. `/blog/[slug]`
      */
-    collectorEndpoint?: string;
+    routePath: string;
+    /**
+     * `render`, `route`, `action`, `middleware` or `proxy`
+     */
+    routeType: string;
+    /**
+     * Rendering phase of the App Router
+     */
+    renderSource?: string;
+    /**
+     * Revalidation reason: `on-demand` or `stale`
+     */
+    revalidateReason?: string;
+    /**
+     * Render type of the App Router in Next.js 15: `dynamic` or `dynamic-resume`
+     */
+    renderType?: string;
 }
 /**
- * Context passed by Next.js to the config function
+ * Next.js data sent with events in `addons.nextjs`
  */
-interface NextConfigContext {
+interface NextjsAddons {
+    /**
+     * Where the error happened: `nodejs`, `edge` or `browser`
+     */
+    runtime?: string;
+    /**
+     * Error page that caught the error: `error`, `global-error` or `boundary`
+     */
+    boundary?: string;
     /**
-     * Default Next.js config
+     * React component stack of the error caught by `HawkErrorBoundary`
      */
-    defaultConfig: NextConfig;
+    componentStack?: string;
+    /**
+     * Digest of the server error. The same digest is shown on the error page in the browser
+     */
+    digest?: string;
+    /**
+     * `App Router` or `Pages Router`
+     */
+    routerKind?: string;
+    /**
+     * Route file path, e.g. `/blog/[slug]`
+     */
+    routePath?: string;
+    /**
+     * `render`, `route`, `action`, `middleware` or `proxy`
+     */
+    routeType?: string;
+    /**
+     * Rendering phase of the App Router
+     */
+    renderSource?: string;
+    /**
+     * Revalidation reason
+     */
+    revalidateReason?: string;
+    /**
+     * Render type of the App Router
+     */
+    renderType?: string;
+    /**
+     * HTTP method
+     */
+    method?: string;
+    /**
+     * Request path with the query string
+     */
+    path?: string;
+    /**
+     * Request headers that don't contain credentials
+     */
+    headers?: Record<string, string>;
 }
+
+/**
+ * Sends the error or message to Hawk. Next.js errors of `redirect()` and `notFound()` are skipped
+ * @param error - error or message
+ * @param context - data sent with the event
+ * @param user - user affected by the error, used on the server only. In the browser use `setUser()`
+ */
+declare function send(error: unknown, context?: EventContext, user?: AffectedUser): void;
+/**
+ * Sets the user sent with every event in the browser.
+ * Ignored on the server: it handles requests of many users at once, so pass the user to `send()` there
+ * @param _user - current user
+ */
+declare function setUser(_user: AffectedUser): void;
+/**
+ * Removes the user set with `setUser()`. Does nothing on the server
+ */
+declare function clearUser(): void;
+/**
+ * Sets data sent with every event. On the server it is shared by all requests of the process
+ * @param context - data to send
+ */
+declare function setContext(context: EventContext | undefined): void;
 /**
- * Next.js config exported as a function
+ * Breadcrumbs sent with the events: actions that happened before the error.
+ * Collected in the browser only: on the server requests of different users would be mixed
  */
-type NextConfigFunction = (phase: string, context: NextConfigContext) => NextConfig | Promise<NextConfig>;
+declare const breadcrumbs: BreadcrumbsAPI;
 /**
- * Wraps Next.js config to send releases with source maps to Hawk.
- *
- * - exposes the release id to the app code as `process.env.HAWK_RELEASE`
- * - enables client source maps for production builds
- * - after `next build` sends client source maps and recent commits to Hawk and removes the maps
- * @param nextConfig - Next.js config object
- * @param options - Hawk plugin options
+ * Waits for the events in progress, e.g. before a serverless function is frozen.
+ * `onRequestError` already waits for its events. In the browser resolves at once
+ * @param timeout - max time to wait, in milliseconds
+ * @returns false when the timeout is reached or the catcher is not created
  */
-declare function withHawkConfig(nextConfig: NextConfig, options?: HawkNextOptions): NextConfig;
+declare function flush(timeout?: number): Promise<boolean>;
+/**
+ * Sends errors of server components, route handlers, server actions and middleware, on the server only.
+ * Export it from `instrumentation.ts`: `export const onRequestError = Hawk.onRequestError`
+ * @param error - caught error
+ * @param request - failed request
+ * @param context - route data
+ */
+declare function onRequestError(error: unknown, request: Readonly<RequestErrorRequest>, context: Readonly<RequestErrorContext>): Promise<void>;
+/**
+ * Adds a breadcrumb for every navigation of the App Router, in the browser only.
+ * Export it from `instrumentation-client.ts`: `export const onRouterTransitionStart = Hawk.onRouterTransitionStart`
+ * @param _url - target URL
+ * @param _navigationType - `push`, `replace` or `traverse`
+ */
+declare function onRouterTransitionStart(_url: string, _navigationType: string): void;
+
+/**
+ * Error passed by Next.js to the error pages
+ */
+type ErrorWithDigest = Error & {
+    /**
+     * Digest of the server error. Server errors have a generic message in production
+     */
+    digest?: string;
+};
+/**
+ * Props passed by Next.js to `error.tsx` and `global-error.tsx`
+ */
+interface HawkErrorPageProps {
+    /**
+     * Caught error
+     */
+    error: ErrorWithDigest;
+    /**
+     * Renders the segment again
+     */
+    reset?: () => void;
+}
+/**
+ * Props passed to the fallback of `HawkErrorBoundary`
+ */
+interface HawkErrorBoundaryFallbackProps {
+    /**
+     * Caught error
+     */
+    error: unknown;
+    /**
+     * Renders the children again
+     */
+    reset: () => void;
+}
+/**
+ * Content, fallback and error callback of `HawkErrorBoundary`
+ */
+interface HawkErrorBoundaryProps {
+    /**
+     * Content to protect
+     */
+    children?: ReactNode;
+    /**
+     * Shown instead of the children after an error
+     */
+    fallback?: ReactNode | ((props: HawkErrorBoundaryFallbackProps) => ReactNode);
+    /**
+     * Called after the error is sent
+     */
+    onError?: (error: unknown, info: ErrorInfo) => void;
+}
+/**
+ * Whether `HawkErrorBoundary` shows the fallback, and the error it caught
+ */
+interface HawkErrorBoundaryState {
+    /**
+     * Whether an error is caught
+     */
+    hasError: boolean;
+    /**
+     * Caught error
+     */
+    error: unknown;
+}
+/**
+ * Sends the error shown by `error.tsx` to Hawk.
+ * Next.js only logs errors caught by error boundaries, so the catcher doesn't get them otherwise
+ * @param error - error passed to the error page
+ */
+declare function useHawkError(error: unknown): void;
+/**
+ * Ready `app/global-error.tsx`: sends the error and shows a minimal error page.
+ * Use it as `export { HawkGlobalError as default } from '@hawk.so/nextjs'`
+ * @param props - props passed by Next.js
+ */
+declare function HawkGlobalError({ error, reset }: HawkErrorPageProps): ReactElement;
+/**
+ * Error boundary that sends errors of its children to Hawk and shows the fallback.
+ * Errors Next.js uses for `redirect()` and `notFound()` are passed to the Next.js boundaries
+ */
+declare class HawkErrorBoundary extends Component<HawkErrorBoundaryProps, HawkErrorBoundaryState> {
+    /**
+     * Initial state
+     */
+    state: HawkErrorBoundaryState;
+    /**
+     * Shows the fallback after an error
+     * @param error - caught error
+     */
+    static getDerivedStateFromError(error: unknown): HawkErrorBoundaryState;
+    /**
+     * Sends the caught error
+     * @param error - caught error
+     * @param info - component stack
+     */
+    componentDidCatch(error: unknown, info: ErrorInfo): void;
+    /**
+     * Renders the children again
+     */
+    reset: () => void;
+    /**
+     * Renders the children or the fallback
+     */
+    render(): ReactNode;
+}
+
 /**
- * Wraps Next.js config function to send releases with source maps to Hawk
- * @param nextConfig - function returning Next.js config
- * @param options - Hawk plugin options
+ * Initializes Hawk. Call it in `instrumentation-client.ts` for the browser
+ * and in `register()` of `instrumentation.ts` for the server
+ * @param options - token, release and other options
  */
-declare function withHawkConfig(nextConfig: NextConfigFunction, options?: HawkNextOptions): NextConfigFunction;
+declare function init(options?: HawkInitOptions): void;
 
-export { withHawkConfig };
-export type { CommitsOptions, HawkNextOptions, NextConfigFunction };
+export { HawkErrorBoundary, HawkGlobalError, breadcrumbs, clearUser, flush, init, onRequestError, onRouterTransitionStart, send, setContext, setUser, useHawkError };
+export type { HawkErrorBoundaryFallbackProps, HawkErrorBoundaryProps, HawkErrorPageProps, HawkEvent, HawkInitOptions, NextjsAddons, RequestErrorContext, RequestErrorRequest };

package/dist/react.cjs

@@ -0,0 +1,199 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react/index.tsx
+var react_exports = {};
+__export(react_exports, {
+  HawkErrorBoundary: () => HawkErrorBoundary,
+  HawkGlobalError: () => HawkGlobalError,
+  useHawkError: () => useHawkError
+});
+module.exports = __toCommonJS(react_exports);
+var import_react = require("react");
+
+// src/common/carrier.ts
+var CARRIER_KEY = /* @__PURE__ */ Symbol.for("hawk.nextjs");
+function getCarrier() {
+  const store = globalThis;
+  store[CARRIER_KEY] ??= {};
+  return store[CARRIER_KEY];
+}
+
+// src/common/control-flow.ts
+var CONTROL_FLOW_DIGEST_PREFIXES = [
+  "NEXT_REDIRECT",
+  "NEXT_HTTP_ERROR_FALLBACK;",
+  "NEXT_NOT_FOUND",
+  "BAILOUT_TO_CLIENT_SIDE_RENDERING",
+  "DYNAMIC_SERVER_USAGE",
+  "NEXT_PRERENDER_INTERRUPTED",
+  "HANGING_PROMISE_REJECTION"
+];
+var STATIC_GEN_BAILOUT_CODE = "NEXT_STATIC_GEN_BAILOUT";
+var REACT_POSTPONE_TYPE = /* @__PURE__ */ Symbol.for("react.postpone");
+var MAX_CAUSE_DEPTH = 5;
+function isControlFlowDigest(value) {
+  return typeof value === "string" && CONTROL_FLOW_DIGEST_PREFIXES.some((prefix) => value.startsWith(prefix));
+}
+function isNextControlFlowError(error) {
+  let current = error;
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth++) {
+    if (typeof current !== "object" || current === null) {
+      return false;
+    }
+    const value = current;
+    if (isControlFlowDigest(value.digest) || isControlFlowDigest(value.message) || value.code === STATIC_GEN_BAILOUT_CODE || value.$$typeof === REACT_POSTPONE_TYPE) {
+      return true;
+    }
+    current = value.cause;
+  }
+  return false;
+}
+function getDigest(error) {
+  if (typeof error === "object" && error !== null) {
+    const { digest } = error;
+    if (typeof digest === "string" && digest !== "") {
+      return digest;
+    }
+  }
+  return void 0;
+}
+
+// src/react/index.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function captureBoundaryError(error, boundary, componentStack) {
+  if (isNextControlFlowError(error) || getDigest(error) !== void 0) {
+    return;
+  }
+  getCarrier().capture?.(error, {
+    boundary,
+    ...typeof componentStack === "string" ? { componentStack } : {}
+  });
+}
+function useHawkError(error) {
+  (0, import_react.useEffect)(() => {
+    captureBoundaryError(error, "error");
+  }, [error]);
+}
+var globalErrorStyles = {
+  container: {
+    fontFamily: "system-ui, sans-serif",
+    minHeight: "100vh",
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 16,
+    textAlign: "center"
+  },
+  title: {
+    fontSize: 14,
+    fontWeight: 400,
+    margin: 0
+  },
+  digest: {
+    fontSize: 12,
+    opacity: 0.6,
+    margin: 0
+  },
+  button: {
+    fontSize: 14,
+    padding: "6px 14px",
+    cursor: "pointer"
+  }
+};
+function HawkGlobalError({ error, reset }) {
+  (0, import_react.useEffect)(() => {
+    captureBoundaryError(error, "global-error");
+  }, [error]);
+  const side = error.digest === void 0 ? "client" : "server";
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("html", { lang: "en", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("body", { children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("main", { style: globalErrorStyles.container, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("h2", { style: globalErrorStyles.title, children: [
+      "Application error: a ",
+      side,
+      "-side exception has occurred."
+    ] }),
+    error.digest !== void 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: globalErrorStyles.digest, children: [
+      "Digest: ",
+      error.digest
+    ] }),
+    reset !== void 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", style: globalErrorStyles.button, onClick: reset, children: "Try again" })
+  ] }) }) });
+}
+var HawkErrorBoundary = class extends import_react.Component {
+  /**
+   * Initial state
+   */
+  state = {
+    hasError: false,
+    error: null
+  };
+  /**
+   * Shows the fallback after an error
+   * @param error - caught error
+   */
+  static getDerivedStateFromError(error) {
+    return {
+      hasError: true,
+      error
+    };
+  }
+  /**
+   * Sends the caught error
+   * @param error - caught error
+   * @param info - component stack
+   */
+  componentDidCatch(error, info) {
+    if (isNextControlFlowError(error)) {
+      return;
+    }
+    captureBoundaryError(error, "boundary", info.componentStack);
+    this.props.onError?.(error, info);
+  }
+  /**
+   * Renders the children again
+   */
+  reset = () => {
+    this.setState({
+      hasError: false,
+      error: null
+    });
+  };
+  /**
+   * Renders the children or the fallback
+   */
+  render() {
+    const { hasError, error } = this.state;
+    if (!hasError) {
+      return this.props.children;
+    }
+    if (isNextControlFlowError(error)) {
+      throw error;
+    }
+    const { fallback } = this.props;
+    if (typeof fallback === "function") {
+      return fallback({
+        error,
+        reset: this.reset
+      });
+    }
+    return fallback ?? null;
+  }
+};