@sailfish-ai/sf-veritas-nextjs

NextJS Backend Package

Middleware for JavaScript and TypeScript to intercept and log API requests, console outputs, and exceptions, while persisting trace data for frameworks such as Next.js, Nuxt.js and more.

Installation

To install from our repository, you need to configure your npm or yarn registry settings. Here's how to do it:

npmrc Configuration

// Add this to your .npmrc
@sailfishai:registry=https://us-npm.pkg.dev/futureself-world/sailfishai-npm/

Install the Package

npm install --save @sailfish/sf-veritas-nextjs
# or
yarn add @sailfish/sf-veritas-nextjs

Usage and Example Integration

---

Arguments/Parameters

1. Below are the configuration parameters for @sailfish/sf-veritas-nextjs. These options are passed as an object to the setupInterceptors function. All parameters are non-mandatory.

• serviceIdentifier: string

  • Associates logs with a specific service. Use simple, clear strings for easy identification.

• serviceVersion: string

  • Useful for distinguishing between service versions, particularly in CI/CD environments.

• serviceAdditionalMetadata: Record<string, string | number | boolean | null>

  • Add extra metadata such as cluster information or environment details.

• domainsToNotPropagateHeadersTo: string[]

  • Prevents adding tracing headers (X-Sf3-Rid) to certain domains.

• siteAndNodeModulesToCollectLocalVariablesOn: string[]

  • Specify packages or modules for capturing local variable values during errors or exceptions. Use ['all'] to capture local variables globally.`

Example of setup

For Next.js projects running on Vercel Edge Functions, there is special instrumentation.ts|js file on which integration should be done. The file should be located in the root directory of the project.

/**
 * Initializes instrumentation for both client-side (browser) and server-side (Node.js).
 *
 * - In **Node.js runtime**, it sets up API interceptors using `setupInterceptors()`
 * - In **browser (client-side)**, it starts event recording using `startRecording()`
 *
 * This ensures that:
 * - The correct logic runs based on the environment (client vs. server)
 * - There are no runtime errors in unsupported environments
 */

export async function register() {
  /**
   * ✅ Server-Side (Node.js) Instrumentation
   * ---------------------------------------
   * - Uses `@sailfish/sf-veritas-nextjs` to intercept API requests
   * - Ensures this logic **only runs on the server**, avoiding client-side errors
   */
  if (process.env.NEXT_RUNTIME === "nodejs") {
    console.log("[Instrumentation] Initializing server-side interceptors...");

    try {
      // Dynamically import to ensure it's only loaded in a Node.js environment
      const { setupInterceptors } = await import("@sailfish/sf-veritas-nextjs");

      setupInterceptors({
      serviceIdentifier: "your-service-name",
      serviceVersion: "1.0.0",
      serviceAdditionalMetadata: {
        environment: "production",
        cluster: "east-coast",
      },
      domainsToNotPropagateHeadersTo: ["example.com"],
      nodeModulesToCollectLocalVariablesOn: ["@your-org/your-package"],
    });

      console.log(
        "[Instrumentation] Server-side interceptors initialized successfully.",
      );
    } catch (error) {
      console.error(
        "[Instrumentation] Error importing setupInterceptors:",
        error,
      );
    }
  }
}