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

# Server-Side Setup

> Add Limelight to your Node.js server to capture incoming HTTP requests and enable full-stack tracing.

Limelight runs on Node.js servers too. Add the middleware to capture every incoming request and response — with headers, bodies, status codes, and timing — and view them alongside your client-side data.

When you have Limelight on both the client and server, requests are **automatically traced end-to-end** using a shared trace ID.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @getlimelight/sdk
  ```

  ```bash yarn theme={null}
  yarn add @getlimelight/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @getlimelight/sdk
  ```

  ```bash bun theme={null}
  bun add @getlimelight/sdk
  ```
</CodeGroup>

## Connect

Initialize Limelight in your server's entry point, before setting up routes:

```ts theme={null}
import { Limelight } from "@getlimelight/sdk";

Limelight.connect({
  platform: "node",

  // Optional: only required for hosted dashboard
  projectKey: "your-project-key",
});
```

## Express / Connect

Use `Limelight.middleware()` to capture all incoming requests. Place it **after** body-parser middleware so request bodies are available:

```ts theme={null}
import express from "express";
import { Limelight } from "@getlimelight/sdk";

Limelight.connect({ platform: "node" });

const app = express();

// Body parser first
app.use(express.json());

// Limelight middleware second
app.use(Limelight.middleware());

app.get("/api/users", (req, res) => {
  res.json({ users: [] });
});

app.listen(3000);
```

### Middleware Options

```ts theme={null}
app.use(
  Limelight.middleware({
    maxBodySize: 128 * 1024, // Capture up to 128KB of body (default: 64KB)
  })
);
```

| Option        | Type     | Default        | Description                                                                                        |
| ------------- | -------- | -------------- | -------------------------------------------------------------------------------------------------- |
| `maxBodySize` | `number` | `65536` (64KB) | Maximum request/response body size to capture in bytes. Bodies exceeding this limit are truncated. |

## Next.js Pages Router

For Next.js **Pages Router** API routes (`pages/api/`), wrap your handler with `Limelight.withLimelight()`:

```ts theme={null}
// lib/limelight.ts
import { Limelight } from "@getlimelight/sdk";

Limelight.connect({ platform: "node" });

export { Limelight };
```

```ts theme={null}
// pages/api/users.ts
import { Limelight } from "../../lib/limelight";

export default Limelight.withLimelight((req, res) => {
  res.status(200).json({ users: [] });
});
```

<Warning>
  `withLimelight` works with **Pages Router** API routes (`pages/api/`) which use the Node.js `(req, res)` signature. It does not work with App Router route handlers (`app/api/`) which use the Web Standard `Request`/`Response` objects. App Router support is coming soon.
</Warning>

## Full-Stack Tracing

When Limelight is installed on both your client and server, requests are automatically correlated using a trace header.

**How it works:**

1. The client SDK attaches an `x-limelight-trace-id` header to every outgoing request
2. The server middleware reads this header and links the incoming request to the same trace
3. Limelight groups both sides together in the UI so you can see the full request lifecycle

No extra configuration is needed — this works automatically.

### Custom Trace Header

If `x-limelight-trace-id` conflicts with your infrastructure, you can customize the header name. Set the same name on both client and server:

```ts theme={null}
// Client
Limelight.connect({
  traceHeaderName: "x-my-trace-id",
});

// Server
Limelight.connect({
  platform: "node",
  traceHeaderName: "x-my-trace-id",
});
```

## Configuration

All standard `Limelight.connect()` options work on the server. The most relevant ones for server-side usage:

```ts theme={null}
Limelight.connect({
  // Identifies this as a Node.js app
  platform: "node",

  // Optional: required for hosted dashboard
  projectKey: "your-project-key",

  // Optional: only enable in development
  enabled: process.env.NODE_ENV === "development",

  // Optional: name your server in the dashboard
  appName: "api-server",

  // Optional: skip capturing request/response bodies
  disableBodyCapture: false,

  // Optional: filter or modify events before sending
  beforeSend: (event) => {
    // Drop health check requests
    if (event.url?.includes("/health")) {
      return null;
    }
    return event;
  },
});
```

## Security

Limelight automatically redacts sensitive headers (like `authorization`, `cookie`, and `set-cookie`) from captured data. You can further control what gets captured:

* Use `disableBodyCapture: true` to skip all request/response bodies
* Use `beforeSend` to filter out specific routes or redact fields
* Use `maxBodySize` on the middleware to limit how much body data is captured

```ts theme={null}
Limelight.connect({
  platform: "node",
  beforeSend: (event) => {
    // Don't capture payment endpoints
    if (event.url?.includes("/api/payments")) {
      return null;
    }
    return event;
  },
});
```

## Verify It's Working

Once connected, make a request to your server and check the Limelight desktop app or dashboard. You should see:

* The incoming request with method, URL, headers, and body
* The outgoing response with status code, headers, body, and duration
* If the client SDK is also connected, both sides linked under the same trace ID