> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md).

# Configuration

How slnodejs gets its settings: configuration sources and precedence, token, build session ID, labs and test stages, ignore files, and every environment variable.

This page explains where `slnodejs` reads its settings from, the concepts that connect the commands (token, build session, lab, test stage), how to exclude files, and every setting that is available only as an environment variable. For command-line flags, see the [Command Reference](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md).

## Configuration sources and precedence <a href="#configuration-sources-and-precedence" id="configuration-sources-and-precedence"></a>

`slnodejs` reads settings from these sources:

1. **Command-line flags**, for example `--tokenFile sltoken.txt`.
2. **Environment variables**, named `SL_<flagName>`, for example `SL_tokenFile=sltoken.txt`. The names are **case-sensitive**: `SL_tokenFile` works, `SL_tokenfile` and `SL_TOKENFILE` do not. Not every flag has an environment variable.
3. **Remote configuration**: settings that SeaLights applies to your account from the SeaLights server.
4. **Defaults.**

For a command, a flag takes precedence over its environment variable, and both take precedence over the default.

Remote configuration takes precedence over flags and environment variables:

* for every setting of `slnodejs run` and `slnodejs mocha`;
* for most settings of the other commands. Some build scanning and browser instrumentation settings that SeaLights configures remotely by design (for example `--compressSlMapping` and `--allowedDomains`) keep the flag and the environment variable ahead of remote configuration.

Some settings always take the remote value when SeaLights sets one, whatever you pass, for example `--overrideServer`, `--useBranchCoverage` and `--awsConfigure`. If one of them does not take the value you pass, ask SeaLights support whether it is set remotely for your account.

To apply remote configuration only to the settings that SeaLights configures remotely by design, set `SL_acceptAllRemoteParams=false`.

## Token <a href="#token" id="token"></a>

The agent token authenticates `slnodejs` to SeaLights and tells it which SeaLights server to use. Get it from the SeaLights dashboard; see [Generating an Agent token](https://docs.sealights.io/knowledgebase/settings/token-access-and-management#token-list-and-token-creation-2).

Provide it in one of these ways:

* **In a file, with `--tokenFile` (recommended).** The default file is `sltoken.txt` in the working directory.
* **Directly, with `--token`.** The token is then visible in the process list and in CI logs.

In CI, create the file from a secret variable. For example, with the token in the secret `SEALIGHTS_AGENT_TOKEN`:

{% tabs %}
{% tab title="Bash" %}

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
Set-Content -Path sltoken.txt -Value $env:SEALIGHTS_AGENT_TOKEN -NoNewline
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Add `sltoken.txt` and `buildSessionId` to `.gitignore`. Never commit the token.
{% endhint %}

## Build session ID <a href="#build-session-id" id="build-session-id"></a>

The build session ID identifies one build of an application. [`config`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#config) or [`prConfig`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#prconfig) creates it and writes it to a file, `buildSessionId` in the working directory by default. Later commands of the same build read it:

* from a file, with `--buildSessionIdFile` (recommended in pipelines: keep the file as a CI artifact), or
* directly, with `--buildSessionId`.

`scan`, `instrument`, `mocha`, `run`, `uploadReports` and `nycReport` read `buildSessionId` in the working directory when neither flag is set.

`mocha`, `openTestStage`, `closeTestStage` and `uploadReports` can also find the build session from the lab: pass `--labId` and no build session flag. `run` and `nycReport` cannot:

* `run --labId` still reads `buildSessionId` in the working directory. If that file does not exist, the program runs without SeaLights.
* `nycReport --labId` without a build session flag fails.

Always pass a build session flag together with `--labId` to `run` and `nycReport`.

## Labs and test stages <a href="#labs-and-test-stages" id="labs-and-test-stages"></a>

These two concepts decide where coverage ends up.

* A **lab** is a test environment, identified by a **lab ID**. Every agent that collects coverage (the test listener started by `run` or the preload script, the browser agent in instrumented front-end code) reports with a lab ID. When you do not set one, the lab ID is the build session ID.
* A **test stage** (for example `Unit Tests`, `Integration Tests`, `E2E Tests`) is opened on a lab with [`openTestStage`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#openteststage), or by `slnodejs mocha` and the SeaLights test framework plugins. While it is open, the coverage of every agent on that lab is attributed to it.

```
 Test runner                         openTestStage --labId qa-env   ─┐
 Back-end service                    slnodejs run  --labId qa-env    ├─►  SeaLights: coverage of lab "qa-env"
 Front end (instrumented)            built with    --labId qa-env   ─┘     goes to the test stage open on "qa-env"
```

Rules of thumb:

* Use **one lab ID per test environment** (for example `qa-env`, `staging-env`), and the **same lab ID** for every component and replica in that environment.
* Do not run two test stages on the same lab at the same time. To run test stages in parallel, give each its own environment and lab ID; see [Parallel Test Stages - Unique Lab IDs](https://docs.sealights.io/knowledgebase/setup-and-configuration/running-parallel-tests-lab-id/parallel-test-stages-unique-lab-ids.md).
* For unit tests, the code runs inside the test process, so no lab ID is needed: use the build session ID.

## Ignore files <a href="#ignore-files" id="ignore-files"></a>

Ignore files exclude files from scanning and instrumentation. They use `.gitignore` syntax. `slnodejs` looks for each file in the scanned directory (`--scanDir`) and then in its parent directories, and uses the first one it finds.

| File                   | Effect                                                                                                                                                                     |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.slignore`            | Matching files are not scanned and not instrumented.                                                                                                                       |
| `.slignore.instrument` | Matching files are scanned but not instrumented for browser coverage. Patterns match package paths inside bundles, as resolved from source maps (for example `@angular/`). |
| `.slignore.generated`  | Matching source files, as resolved from source maps, are removed from the scan result. Use it for framework-generated sources, for example `webpack:/**`.                  |

Rules:

* When there is no `.slignore`, `slnodejs` uses the `exclude` patterns of your NYC configuration (`.nycrc`, `.nycrc.json`, or the `nyc` section of `package.json`).
* When there is no `.slignore.instrument`, `slnodejs` uses built-in patterns that skip common framework packages (for example Angular, React, Vue, Svelte, `core-js` and `tslib`).
* `--excludeFiles` adds patterns on top of `.slignore`. The instrumentation output directory is always excluded.

{% hint style="warning" %}
**Known issue:** in a `slnodejs scan` without `--outputPath`, `--excludeFiles` can turn a pattern into a directory-only pattern, so files it should exclude are scanned. This affects the last pattern of `.slignore` (or of the NYC `exclude` patterns) when the file does not end with a newline, and, without `.slignore`, the first `--excludeFiles` pattern when you pass more than one. Until this is fixed, put the patterns in `.slignore`, end the file with a newline, and do not pass `--excludeFiles`.
{% endhint %}

Example `.slignore` in the project root:

```gitignore
coverage/
node_modules/
test/
**/*.spec.js
**/*.test.js
```

Example `.slignore` for an Angular build output, which skips vendor and runtime bundles and the legacy ES5 copies built for older browsers (see [Angular 8+: Duplicate Method Reporting](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript/angular-8+-duplicate-method-reporting.md)):

```gitignore
**/*vendor*.js
**/*runtime*.js
**/*inline*.js
**/*polyfills*.js
**/es5/**
**/*-es5.js
```

Example `.slignore` that scans only some files (allow list):

```gitignore
# Ignore everything except the files matching the patterns that start with !
*
!*main*.js
```

Example `.slignore.generated`, which removes images and HTML listed in source maps, and test sources:

```gitignore
*.html
*.png
*.svg
**/*.spec.ts
```

Example `.slignore.instrument`:

```gitignore
@angular/
zone.js
rxjs
tslib
```

The pattern format is the [Git ignore format](https://git-scm.com/docs/gitignore).

To see which files a scan includes before you write rules, run [`dryRun`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/dryrun-command-troubleshooting-and-validation.md) and open `sl-dry-run-output/included-files.json`.

The `slnodejs-installer` package creates template versions of the three files when they do not exist. The templates exclude files, so review them before the first scan.

## Environment variables <a href="#environment-variables" id="environment-variables"></a>

These settings have no flag, so `--help` does not show them. Names are case-sensitive.

### Test listener (`run`, `mocha`, preload script)

Inside the program started by `slnodejs run`, `slnodejs mocha` or the preload script, the test listener reads `SL_<name>` environment variables, for example `SL_labId`. They override the values passed by the command.

| Variable                        | Effect                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SL_useLeanCoverageListener`    | `true` collects coverage with the [lightweight V8 coverage mode](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode.md) instead of NYC.                                                                                                                                                |
| `SL_useIstanbul`                | `true` uses the Istanbul coverage engine instead of NYC.                                                                                                                                                                                                                                                                                                                                      |
| `SL_useOtelAgent`               | `true` loads the SeaLights OpenTelemetry agent into the program. SeaLights remote configuration can also turn it on.                                                                                                                                                                                                                                                                          |
| `SL_enableChildProcessPatcher`  | `true` also starts the agent in the Node.js child processes that the program spawns. Use when the program forks workers that run your code. The lightweight V8 mode uses it differently; see [its configuration](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode/configuration.md). |
| `SL_httpListeningPort`          | A port number other than `0` opens an HTTP server on that port, through which an external process sets the current test.                                                                                                                                                                                                                                                                      |
| `SL_newUniqueId`                | `true` uses the newer method ID format. Set the same value for `slnodejs scan` (or `instrument`) and for the test listener.                                                                                                                                                                                                                                                                   |
| `SL_enabled`                    | `false` makes the test listener collect and send nothing, while the program still runs. Use to turn SeaLights off in an environment without changing the start command.                                                                                                                                                                                                                       |
| `SL_disableHookDependencyGuard` | `true` turns off the `SLEmptyTest` placeholder that `slnodejs mocha` adds when Test Impact Analysis skips every test of a suite with hooks.                                                                                                                                                                                                                                                   |
| `SL_logSubmissionMode`          | `0` sends no logs to SeaLights, `1` sends errors only, `2` sends all logs.                                                                                                                                                                                                                                                                                                                    |

### Preload script

The preload script reads its settings from environment variables only. Each variable also has an upper-case spelling; the camel-case name is read first.

| Variable                | Upper-case spelling        | Default            |
| ----------------------- | -------------------------- | ------------------ |
| `SL_token`              | `SL_TOKEN`                 |                    |
| `SL_tokenFile`          | `SL_TOKEN_FILE`            | `./sltoken.txt`    |
| `SL_buildSessionId`     | `SL_BUILD_SESSION_ID`      |                    |
| `SL_buildSessionIdFile` | `SL_BUILD_SESSION_ID_FILE` | `./buildSessionId` |
| `SL_labId`              | `SL_LAB_ID`                | build session ID   |
| `SL_projectRoot`        | `SL_PROJECT_ROOT`          | working directory  |
| `SL_collectorUrl`       | `SL_COLLECTOR_URL`         |                    |
| `SL_proxy`              | `SL_PROXY`                 |                    |

Any other spelling, for example `SL_tokenfile` or `SL_labid`, is ignored. All other `SL_*` variables are passed to the test listener (see the table above), except `SL_httpServerColoring` and `SL_httpClientColoring`: HTTP coloring can be turned on only with the `--httpServerColoring` and `--httpClientColoring` flags of `slnodejs run` or `slnodejs mocha`.

{% hint style="info" %}
The upper-case spellings are read only by the preload script. CLI commands read only `SL_<flagName>`, for example `SL_buildSessionId`.
{% endhint %}

### Connection and TLS (every command, test listener, preload script)

| Variable                            | Effect                                                                                                                                                                              |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SL_TLS_VERIFY` (or `SL_tlsVerify`) | `true`, `1` or `yes` verifies the TLS certificates of all SeaLights connections, including connections through a proxy. When not set, connections through a proxy are not verified. |
| `SL_CA_FILE` (or `SL_caFile`)       | PEM file with additional CA certificates, trusted on top of the Node.js defaults and the operating system store. Takes effect only when `SL_TLS_VERIFY` is on.                      |
| `SL_httpTimeout`                    | Timeout of one HTTP request to SeaLights, in milliseconds.                                                                                                                          |
| `SL_httpMaxAttempts`                | Maximum attempts per HTTP request.                                                                                                                                                  |
| `SL_httpAttemptInterval`            | Milliseconds between attempts.                                                                                                                                                      |
| `SL_acceptAllRemoteParams`          | `false` applies remote configuration only to the settings SeaLights configures remotely by design.                                                                                  |
| `SL_DisableCockpitMessages`         | `true` stops sending agent warnings and errors to the SeaLights dashboard.                                                                                                          |

### Logging

| Variable             | Effect                                                                                                                  |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `NODE_DEBUG`         | `sl` (or `sl-console`) logs to the console; `sl-file` logs to a file. Combine them: `NODE_DEBUG=sl,sl-file`.            |
| `SL_LOG_LEVEL`       | `error`, `warn`, `info` (default), `http`, `verbose`, `debug`, `silly`, or `off`. `off` also turns off the TLS notices. |
| `SL_LOG_OUTPUT_FILE` | Log file path with `NODE_DEBUG=sl-file`. Default: `sl.node.log` in the working directory.                               |

### Build scanning and browser instrumentation

Read by `scan` and `instrument`.

| Variable                        | Effect                                                                                                                                                                                                                                                                                                                       |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SL_fileExtensions`             | Replaces the list of file extensions that are scanned and instrumented. Comma-separated, with the dot, for example `SL_fileExtensions=.js,.mjs`.                                                                                                                                                                             |
| `SL_minifyInstrumentedOutput`   | `true` minifies the instrumented output.                                                                                                                                                                                                                                                                                     |
| `SL_inProcessInstrumentation`   | `true` instruments in the `slnodejs` process instead of a pool of child processes. Use when child processes are restricted in the build environment.                                                                                                                                                                         |
| `SL_reduceInstrumentedFileSize` | `true` instruments without line-level counters, which makes files much smaller and pages load faster. `instrument` does this by default (`--reduceFileSize`); `scan --instrumentForBrowsers` does it only with this variable or when SeaLights sets it remotely. Use when tests time out on page load after instrumentation. |
| `SL_newUniqueId`                | See [Test listener](#test-listener-run-mocha-preload-script).                                                                                                                                                                                                                                                                |

Browser agent settings that are written into the instrumented build (for example `SL_blockBrowserHttpTraffic`) are listed in [Browser Agent → Configuration](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md#settings-read-from-the-instrumentation-environment).

### Lightweight V8 coverage mode

`NODE_V8_COVERAGE`, `SL_COVERAGE_INTERVAL`, `SL_footprintsSendIntervalSecs`, `SL_footprintsQueueSize` and `SL_IN_PROCESS_COVERAGE_COLLECTION` are described in [Lightweight V8 Coverage Mode → Configuration](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode/configuration.md).

### Deprecated

`slnodejs scan` warns when it finds a deprecated variable. `SL_httpMaxAttempts` replaces `SL_HttpMaxAttempts`, and `SL_httpAttemptInterval` replaces `SL_HttpAttemptInterval`. `SL_scmPrefix` is no longer supported and is ignored; use `--projectRoot` instead.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
