> ## Documentation Index
> Fetch the complete documentation index at: https://interfere.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js

> Capture server errors and custom spans in Node.js services and workers.

`@interfere/node` captures errors and custom spans from Node.js processes. For NestJS or Next.js, use the [NestJS](/docs/sdk/nestjs) or [Next.js](/docs/sdk/next-js) integration.

## Install

```bash theme={null}
npm install @interfere/node
```

Set `INTERFERE_PUBLIC_KEY` to the public key from your [surface](/docs/product/surfaces).

## Initialize

Call `init()` before the work you want to capture:

```ts theme={null}
import { init } from "@interfere/node";

init({
  serviceName: "checkout-worker",
  environment: "production",
});
```

Repeated initialization does not create additional providers. Without a public key, the SDK logs a warning and stays disabled.

## Capture handled errors and spans

```ts theme={null}
import { captureError, withSpan } from "@interfere/node";

try {
  await withSpan("checkout.fulfill", () => fulfill(order));
} catch (error) {
  captureError(error);
  throw error;
}
```

The SDK installs handlers for uncaught exceptions and unhandled rejections by default. Set `captureUncaughtException: false` or `captureUnhandledRejection: false` when your application owns those handlers. The uncaught-exception handler flushes telemetry and exits the process.

## Configuration

| Option | Purpose |
| - | - |
| `serviceName` | Identify the process. Defaults to `OTEL_SERVICE_NAME`, then `node-app`. |
| `serviceNamespace` | Group related services. |
| `environment` | Set the deployment environment. Otherwise reads `INTERFERE_ENVIRONMENT`, `VERCEL_ENV`, then `NODE_ENV`. |
| `debug` | Print initialization and exporter diagnostics. Also enabled with `INTERFERE_DEBUG=1`. |

## Releases and shutdown

Use the [TypeScript SDK](/docs/platform-sdk/typescript#register-releases-and-upload-source-maps) to publish release metadata and source maps from a custom build pipeline. Build and runtime must use the same commit SHA. Set `INTERFERE_SOURCE_ID` in both when git metadata is unavailable.

For a short-lived process, await `flush()` before it exits. Use `close()` when shutting down the SDK and its provider:

```ts theme={null}
import { close, flush } from "@interfere/node";

await flush();
await close();
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.