# Lightweight Mode | Sentry for Node.js

Lightweight mode is experimental and may have breaking changes in minor or patch releases.

Are you unsure if you should use this installation method? Review our [installation methods](https://docs.sentry.io/platforms/javascript/guides/node/install.md).

If you don't need automatic spans/transactions, you can use `@sentry/node-core/light` which doesn't require OpenTelemetry dependencies. This mode is ideal when:

* You only need error tracking, logs, or metrics without tracing data (no automatic span creation)
* You want to minimize bundle size and runtime overhead
* You don't need spans emitted by OpenTelemetry instrumentation

You still get error tracking, logs, metrics, breadcrumbs, context/user data, local variables capture, distributed tracing (via `sentry-trace` and `baggage` headers), and automatic request isolation (Node.js 22+).

If needed, you can still manually create spans by using Sentry's [custom instrumentation APIs](https://docs.sentry.io/platforms/javascript/guides/node/tracing/instrumentation.md) like `startSpan`.

## [Prerequisites](https://docs.sentry.io/platforms/javascript/guides/node/install/lightweight.md#prerequisites)

* **Node.js 22.12.0+** is recommended for full functionality (automatic request isolation)
* Lower Node.js versions work but with limited capabilities (see [Request Isolation](https://docs.sentry.io/platforms/javascript/guides/node/install/lightweight.md#request-isolation) below)

## [Step 1: Install](https://docs.sentry.io/platforms/javascript/guides/node/install/lightweight.md#step-1-install)

```bash
npm install @sentry/node-core --save
```

## [Step 2: Configure](https://docs.sentry.io/platforms/javascript/guides/node/install/lightweight.md#step-2-configure)

Import from `@sentry/node-core/light` and call `Sentry.init()` as early as possible in your application lifecycle:

```javascript
import * as Sentry from "@sentry/node-core/light";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
});

// Now create your HTTP server or framework app
```

## [Step 3: Verify](https://docs.sentry.io/platforms/javascript/guides/node/install/lightweight.md#step-3-verify)

To verify that Sentry is working, capture a test error:

```javascript
Sentry.captureException(new Error("Sentry lightweight mode test"));
```

After running your application, you should see this error appear in your [Sentry dashboard](https://sentry.io).

## [Request Isolation](https://docs.sentry.io/platforms/javascript/guides/node/install/lightweight.md#request-isolation)

Request isolation ensures that errors, breadcrumbs, and context are correctly scoped to individual requests.

### [Node.js 22.12.0+](https://docs.sentry.io/platforms/javascript/guides/node/install/lightweight.md#nodejs-22120)

Request isolation works automatically. No additional setup is needed — just make sure `Sentry.init()` is called before you create your HTTP server.

### [Node.js < 22](https://docs.sentry.io/platforms/javascript/guides/node/install/lightweight.md#nodejs--22)

You need to manually wrap your request handler with `Sentry.withIsolationScope()`:

```javascript
import * as Sentry from "@sentry/node-core/light";
import http from "http";

const server = http.createServer((req, res) => {
  Sentry.withIsolationScope(() => {
    // Your request handling code
    Sentry.setUser({ id: "user-id" });
    res.end("OK");
  });
});
```

When using manual isolation on Node.js < 22, distributed tracing will not work correctly.

## [When to Use Lightweight Mode vs `@sentry/node`](https://docs.sentry.io/platforms/javascript/guides/node/install/lightweight.md#when-to-use-lightweight-mode-vs-sentrynode)

|                                 | `@sentry/node`     | `@sentry/node-core/light`                     |
| ------------------------------- | ------------------ | --------------------------------------------- |
| **Error tracking**              | Yes                | Yes                                           |
| **Logs and metrics**            | Yes                | Yes                                           |
| **Automatic spans**             | Yes                | No                                            |
| **OpenTelemetry auto-included** | Yes                | No                                            |
| **Dependency footprint**        | Larger             | Minimal                                       |
| **Best for**                    | Full observability | No auto-instrumentation, manual tracing setup |

If you need automatic spans for HTTP requests, database queries, and other operations, use `@sentry/node` (the default). If you don't need automatically created spans and want minimal dependencies, use lightweight mode.