# slnodejs

> Sealights Node.js Agent

Latest version **6.2.78** (published 2026-09-29) · ISC license · 0 weekly downloads

## Install

```sh
npm install slnodejs
pnpm add slnodejs
yarn add slnodejs
bun add slnodejs
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 6.2.78 |
| Published | 2026-09-29 |
| First published | 2016-12-25 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | sealights |

## Links

- npm: https://www.npmjs.com/package/slnodejs
- npm.io page: https://npm.io/package/slnodejs

## Recent versions

- 6.2.78 (latest) — 2026-09-29
- 6.2.77 — 2026-09-28
- 6.2.76 — 2026-09-27
- 6.2.73 — 2026-09-14
- 6.2.72 — 2026-09-07
- 6.2.70 — 2026-09-07
- 6.2.69 — 2026-09-03
- 6.2.63 — 2026-08-26
- 6.2.62 — 2026-08-25
- 6.2.59 — 2026-08-17
- 6.2.47 — 2026-08-09
- 6.2.46 — 2026-08-05
- 6.2.44 — 2026-08-04
- 6.2.43 — 2026-07-23
- 6.2.42 — 2026-07-21
- … 468 more at https://npm.io/package/slnodejs/versions

## README

Sealights Node.js Agent

> **Lean coverage listener — GA target (not current behavior):**  
> See [`lightweight-agent/docs/RUNTIME_CONTRACT.md`](lightweight-agent/docs/RUNTIME_CONTRACT.md) for the **intended end-state** contract (ship inside `slnodejs` only). That doc is a planning/alignment artifact — **not** documentation of current agent behavior. Do not confuse it with the preload / CLI behavior described below.

# Preload Script

## Overview

The `preload.js` script serves as an automatic loader for the Sealights Node agent, eliminating the need to explicitly wrap your commands with `slnodejs run`. This script intercepts the normal Node.js execution flow and injects the necessary Sealights installation logic.

---

## Installation

First, install the Sealights Node.js package:

```bash
npm install slnodejs
```

The preload script will be available at:

```
./node_modules/slnodejs/lib/preload.js
```

---

## Usage

### Method 1: Using `-r` flag

```bash
node -r ./node_modules/slnodejs/lib/preload.js your-script.js
```

### Method 2: Using `NODE_OPTIONS`

```bash
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
node your-script.js
```

Or inline:

```bash
NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js" node your-script.js
```

> Using `NODE_OPTIONS` allows you to persist the preloader configuration across multiple Node.js executions without explicitly specifying the `-r` flag each time.

---

## Environment Variables Configuration

| Variable                   | Description                                 | Default                   |
| -------------------------- | ------------------------------------------- | ------------------------- |
| `SL_TOKEN`                 | Direct Sealights agent authentication token |                           |
| `SL_TOKEN_FILE`            | Path to file containing the Sealights token | `./sltoken.txt`           |
| `SL_BUILD_SESSION_ID`      | Direct build session ID                     |                           |
| `SL_BUILD_SESSION_ID_FILE` | Path to file containing build session ID    | `./buildSessionId`        |
| `SL_PROJECT_ROOT`          | Root directory of your project              | Current working directory |
| `SL_COLLECTOR_URL`         | URL to Sealights collector                  |                           |
| `SL_LAB_ID`                | Lab ID for test execution                   |                           |

---

## Error Handling

The script includes robust error handling mechanisms:

- **Primary Execution:** Attempts to run the target script with Sealights agent configuration
- **Fallback Mechanism:** If the primary execution fails, it falls back to running the original command
- **Uncaught Exception Handler:** Captures and logs any uncaught exceptions

---

## Examples

### Using `-r` Flag

```bash
node -r ./node_modules/slnodejs/lib/preload.js server.js
```

### Using `NODE_OPTIONS`

```bash
# Set for current session
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
node server.js

# Or inline
NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js" node server.js
```

### Using Environment Variables with `NODE_OPTIONS`

```bash
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
SL_TOKEN="your-token-here" node server.js
```

### Specifying Custom Paths with `NODE_OPTIONS`

```bash
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
SL_TOKEN_FILE="/custom/path/token.txt" SL_projectRoot="/path/to/project" node server.js
```

### Using Collector URL and Lab ID with `NODE_OPTIONS`

```bash
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
SL_TOKEN="your-token-here" SL_COLLECTOR_URL="https://your-collector-url.com" SL_LAB_ID="your-lab-id" node server.js
```

### Debug Mode with `NODE_OPTIONS`

```bash
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
NODE_DEBUG=sl node server.js
```

---

## Troubleshooting

If you encounter issues:

- Check if the token and build session ID files exist and are readable
- Verify environment variables are set correctly
- Check console output for error messages (turn on `NODE_DEBUG=sl`)
- Ensure the script has necessary permissions to execute

---

## Limitations

- **When using `-r` flag**: Must be explicitly included in each Node.js command
- **When using `NODE_OPTIONS`**: Affects all Node.js processes in the current environment

---

## Best Practices

### Choosing Between `-r` and `NODE_OPTIONS`

#### Use `-r` flag when:

- You want to explicitly control which scripts use the preloader
- You're running in an environment where global Node.js settings should not be modified
- You're running multiple Node.js applications with different configurations

#### Use `NODE_OPTIONS` when:

- You want to ensure all Node.js executions in your session include the preloader
- You're working in a dedicated development environment
- You want to reduce command verbosity
- You're setting up CI/CD pipelines where all Node.js executions should include the preloader and Sealights Agent

---

## Integration Tests

PRs to `main` automatically trigger the JS Agent Integration Tests, which validate the agent works correctly with the plugins and example apps across Node.js 18, 20, and 22.

The tests are defined in [`SL.JavaScript.AgentTests`](https://github.com/Sealights/SL.JavaScript.AgentTests) and run via a reusable workflow (`validate-agent.yml`).

### Cross-Repo Branch Resolution

When working on a feature that spans multiple repos, create branches with the **same name** across repos. The CI automatically detects matching branches and tests them together.

For example, if your PR branch is `feature/new-scanner` and a branch with the same name exists in the Plugins or ExampleApps repos, the integration tests will use those branches instead of the defaults.

This is handled via the `feature-branch` input — see the [AgentTests README](https://github.com/Sealights/SL.JavaScript.AgentTests#cross-repo-branch-resolution) for details.

### Manual Dispatch

You can also trigger integration tests manually via the **Actions** tab → **JS Agent Integration Tests** → **Run workflow**, with options for:

- `plugins-branch` — test against a specific plugins branch
- `feature-branch` — try this branch in every repo (falls back to defaults where not found)
- `node-versions` — JSON array of Node.js versions to test

---
_Source: https://npm.io/package/slnodejs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._