NestJS

@interfere/nest connects your NestJS backend to Interfere. Once it's wired in, unhandled exceptions across your controllers and providers are captured with full server-side stack traces, and you get manual capture and tracing when you want them.

Set your surface public key (INTERFERE_PUBLIC_KEY, interfere_pub_<region>_…) from Surfaces so telemetry routes to your project. For readable stack traces you'll also upload source maps with the CLI, which needs your Interfere API key (INTERFERE_API_KEY).

Prerequisites

A NestJS app
Node.js >= 20

Install

1npm install @interfere/nest

Setup

Start the SDK before Nest loads
Create instrument.ts and call init(). This file must run before any @nestjs/* import so the SDK can instrument the runtime.
src/instrument.ts
import { init } from "@interfere/nest/instrument"; init({ serviceName: "my-api" });

Import it first in your entry file

Make instrument the very first import in main.ts, ahead of everything else.

src/main.ts

12345678910import "./instrument";

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

InterfereModule.forRoot() installs a global exception filter, so unhandled exceptions are captured automatically.

src/app.module.ts

12345import { Module } from "@nestjs/common";
import { InterfereModule } from "@interfere/nest/module";

@Module({ imports: [InterfereModule.forRoot()] })
export class AppModule {}

Throw an error from a route and it shows up in your workspace within seconds, already grouped and triaged.

Source maps and releases

A backend has no bundler plugin, so use the CLI to upload source maps and register each deploy as a release. Add a postbuild step:

package.json

123456{
  "scripts": {
    "build": "nest build",
    "postbuild": "interfere sourcemaps upload ./dist"
  }
}

Without an uploaded release, the collector has nothing to attach your telemetry to. See the CLI page for CI setup and the INTERFERE_API_KEY.

Configuration

Pass options to init(). Most apps only set serviceName.

path serviceNamestringdefault: node-app

The name your telemetry is grouped under. Give each process a distinct value (an API, a worker, a cron) when they share one public key.

path serviceNamespacestring

Group related services under one product surface, for example checkout across an API and its workers.

path environmentstring

Environment label such as production or staging. Falls back to INTERFERE_ENVIRONMENT, then VERCEL_ENV, then NODE_ENV.

path debugbooleandefault: false

Log lifecycle events to stdout. Also enabled by INTERFERE_DEBUG=1.

The SDK also installs handlers for uncaught exceptions and unhandled rejections by default. Pass captureUncaughtException: false or captureUnhandledRejection: false to use your own.

Report a handled error

Unhandled exceptions are captured by the module's filter. To report an error you catch yourself, or to trace a specific operation, import from @interfere/nest:

12345678910import { captureError, withSpan } from "@interfere/nest";

try {
  await chargeCard();
} catch (error) {
  captureError(error);
  throw error;
}

const order = await withSpan("checkout.submit", () => submitOrder(cart));

Environment variables

Variable	Required	Description
`INTERFERE_PUBLIC_KEY`	Yes	Your surface public key (`interfere_pub_<region>_…`). Routes telemetry to your project.
`INTERFERE_API_KEY`	For releases	Used by the CLI to upload source maps (`interfere_secret_<region>_…`). A build-time secret; keep it in CI.
`INTERFERE_ENVIRONMENT`	No	Labels this process's telemetry and releases (`production`, `staging`, or a label you choose). Falls back to `VERCEL_ENV`, then `NODE_ENV`, then `development`. Interfere drops the `development`, `local`, and `test` environments before ingestion, so set a real one to capture from it.
`INTERFERE_DEBUG`	No	Set to `1` for lifecycle logs while setting up.

Ask AI about this page