> 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/recommended-configurations.md).

# Recommended Configurations

Complete, copy-paste slnodejs configurations for the most common setups: back-end services, web applications, full stack, containers, monorepos, and pull request builds.

Each configuration below is complete: it creates the token file, the build session, the scan, the runtime coverage and the test capture. Pick the one that matches your answers in [Choosing Your Setup](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/choosing-your-setup.md), then replace the names in angle brackets.

All examples assume:

* `slnodejs` is installed in the project (`npm install --save-dev slnodejs`); see [Installing the Node.js Agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/downloading-the-node.js-agent.md).
* The agent token is in the CI secret `SEALIGHTS_AGENT_TOKEN`.
* Commands run from the project root.

{% hint style="info" %}
`slnodejs` commands exit with status code 0 even when they fail, so SeaLights never breaks your pipeline. The examples add `--failOnError true` to `config` and `scan`, so that a build without a scan is noticed. Remove it if you prefer the default.
{% endhint %}

## Back-end service with Mocha unit tests <a href="#back-end-service-with-mocha-unit-tests" id="back-end-service-with-mocha-unit-tests"></a>

**Use when:** a Node.js service has Mocha unit or component tests that load the code in the test process.

**What you get:** per-test coverage, test results, and Test Impact Analysis (tests that SeaLights does not recommend are skipped).

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

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

npm ci
npm run build   # if the service has a build step

npx slnodejs config --tokenFile sltoken.txt --appName "<my-service>" \
  --branchName "$BRANCH_NAME" --buildName "$BUILD_NUMBER" --failOnError true
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir src --scmType git --failOnError true
npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --testStage "Unit Tests" -- --recursive test
npx slnodejs completeScan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --ok
```

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # full history for source control data
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: SeaLights build session and scan
        env:
          SEALIGHTS_AGENT_TOKEN: ${{ secrets.SEALIGHTS_AGENT_TOKEN }}
        run: |
          printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
          npx slnodejs config --tokenFile sltoken.txt --appName "${{ github.event.repository.name }}" \
            --branchName "${{ github.ref_name }}" --buildName "${{ github.run_id }}-${{ github.run_attempt }}" --failOnError true
          npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
            --scanDir src --scmType git --failOnError true
      - name: Unit tests with SeaLights
        run: npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests" -- --recursive test
      - name: Complete the build
        run: npx slnodejs completeScan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --ok
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
steps:
  - checkout: self
    fetchDepth: 0
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
  - script: npm ci
    displayName: Install
  - script: |
      printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
      npx slnodejs config --tokenFile sltoken.txt --appName "$(Build.Repository.Name)" \
        --branchName "$(Build.SourceBranchName)" --buildName "$(Build.BuildId)" --failOnError true
      npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
        --scanDir src --scmType git --failOnError true
      npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
        --testStage "Unit Tests" -- --recursive test
      npx slnodejs completeScan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --ok
    displayName: SeaLights build, scan and unit tests
    env:
      SEALIGHTS_AGENT_TOKEN: $(SEALIGHTS_AGENT_TOKEN)
```

{% endtab %}
{% endtabs %}

Notes:

* Scan the files that the tests load. For TypeScript run through `ts-node` or a Mocha TypeScript loader, scan `src` and set `SL_fileExtensions=.ts`. For code compiled before the tests run, scan the output folder.
* Keep your Mocha reporter: `-- --recursive test --reporter-options reporter=dot`. See [Mocha → Reporter options](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/mocha-tests-framework.md#reporter-options).
* Add `--es6Modules` to `scan` and `mocha` for ES modules code.

## Unit tests with an NYC report <a href="#unit-tests-with-an-nyc-report" id="unit-tests-with-an-nyc-report"></a>

**Use when:** your unit tests run with Karma, AVA, or another framework that writes an NYC (Istanbul) JSON report and a JUnit XML report. For Jest, prefer the [SeaLights Jest plugin](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-testing-plugins/jest-framework.md).

**What you get:** coverage and test results per test stage. No Test Impact Analysis.

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

npx slnodejs config --tokenFile sltoken.txt --appName "<my-app>" \
  --branchName "$BRANCH_NAME" --buildName "$BUILD_NUMBER" --failOnError true
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir src --scmType git --failOnError true

npx slnodejs openTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests"
npm test   # must write coverage/coverage-final.json and reports/junit.xml
npx slnodejs nycReport --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --report coverage/coverage-final.json
npx slnodejs uploadReports --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --file reports/junit.xml
npx slnodejs closeTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests"
```

Notes:

* The NYC report must cover the same files as the scan. Before the first run, check both with `npx slnodejs dryRun --scanDir src --hasNycReport --report coverage/coverage-final.json --verbose`.
* If the tests run in another directory than the scan (for example in a container), add `--projectRoot <path>` to `nycReport`.
* Framework-specific report setup: [Karma](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/karma-test-framework.md), [AVA](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/ava-framework.md).

## Back-end service under functional tests <a href="#back-end-service-under-functional-tests" id="back-end-service-under-functional-tests"></a>

**Use when:** a deployed Node.js service is exercised by API, integration or end-to-end tests that run in another process or machine.

**What you get:** coverage of the service per test stage, and per test when the test framework sends the test identity in HTTP headers.

**1. Build job:** create the build session and scan. Keep `buildSessionId` as a build artifact.

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npx slnodejs config --tokenFile sltoken.txt --appName "<my-service>" \
  --branchName "$BRANCH_NAME" --buildName "$BUILD_NUMBER" --failOnError true
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir dist --scmType git --failOnError true
npx slnodejs completeScan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --ok
```

**2. Test environment:** start the service with the test listener and a lab ID for this environment.

{% tabs %}
{% tab title="slnodejs run" %}

```bash
npx slnodejs run --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --labId qa-env --httpServerColoring --forwardSignals -- dist/server.js
```

{% endtab %}

{% tab title="Preload script (NODE\_OPTIONS)" %}

```bash
export SL_tokenFile="$PWD/sltoken.txt"
export SL_buildSessionIdFile="$PWD/buildSessionId"
export SL_labId=qa-env
export NODE_OPTIONS="--require $PWD/node_modules/slnodejs/lib/preload.js"
npm start
```

The preload script cannot turn on HTTP coloring (`--httpServerColoring`, `--httpClientColoring`). For per-test coverage, use `slnodejs run`.
{% endtab %}
{% endtabs %}

**3. Test job:** open a test stage on the same lab, run the tests, close it.

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npx slnodejs openTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId qa-env --testStage "API Tests"
npm run test:api   # your API tests against the qa-env service
npx slnodejs uploadReports --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId qa-env --file reports/junit.xml
npx slnodejs closeTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId qa-env --testStage "API Tests"
```

Notes:

* If the tests use a SeaLights test framework plugin (Jest, Playwright, Cypress, Cucumber.js), the plugin opens and closes the test stage and reports results; skip the `openTestStage`, `uploadReports` and `closeTestStage` commands and give the plugin the same lab ID. See [Node.js Testing Plugins](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-testing-plugins.md).
* `--httpServerColoring` attributes coverage to the test named in incoming request headers. Leave it out if the tests do not send them.
* Use the same lab ID for every replica of the service in the environment, and a different lab ID per environment.

## Web application under end-to-end tests <a href="#web-application-under-end-to-end-tests" id="web-application-under-end-to-end-tests"></a>

**Use when:** a React, Angular, Vue or other web application is tested in a browser by Playwright, Cypress, Selenium, or manual testers.

**What you get:** browser coverage per test stage, and per test when the test framework plugin sets the current test in the browser.

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

npm ci
npm run build   # must produce source maps (with columns) next to the bundles in dist/

npx slnodejs config --tokenFile sltoken.txt --appName "<my-web-app>" \
  --branchName "$BRANCH_NAME" --buildName "$BUILD_NUMBER" --failOnError true
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir dist --scmType git --es6Modules \
  --instrumentForBrowsers --outputPath sl_dist --labId qa-env \
  --excludeSourceMapFiles skipCopy --failOnError true
npx slnodejs completeScan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --ok

# Deploy the contents of sl_dist/ (not dist/) to the qa-env test environment.
```

Then run the tests with the same lab ID: through a SeaLights plugin, or between `openTestStage --labId qa-env` and `closeTestStage --labId qa-env` as in the previous configuration.

Notes:

* Framework-specific source map settings, output folders and `--es6Modules`: [Framework and Bundler Setups](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/framework-setups.md).
* Never deploy `sl_dist` to production.
* To check the agent in the browser, open the developer tools console on a page of the test environment; see [Setting Up Browser Coverage → Check that it works](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/setting-up-browser-coverage.md#check-that-it-works).
* Several test environments: instrument once per environment with its own `--labId` and `--outputPath`, or set the lab ID at runtime; see [Frontend Instrumentation → Multiple environments](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/frontend-instrumentation-static.md#multiple-test-environments).
* If the page has a content security policy or the token must not reach the browser, see [Browser Agent → Configuration](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md).

## Full stack: front end and back end <a href="#full-stack-front-end-and-back-end" id="full-stack-front-end-and-back-end"></a>

**Use when:** end-to-end tests drive a web application that calls an instrumented Node.js back end, and you want back-end coverage attributed to the same tests.

Each application has its own build session (its own `config` and `scan`). Both report on the **same lab ID**.

**Front end:** instrument with context propagation, listing the back-end origins (and the page's own origin).

```bash
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile web.buildSessionId \
  --scanDir dist --scmType git --es6Modules \
  --instrumentForBrowsers --outputPath sl_dist --labId qa-env \
  --enableOpenTelemetry --allowCORS "https://app.qa.example.com,https://api.qa.example.com"
```

**Back end:** accept the test identity from incoming requests.

```bash
npx slnodejs run --tokenFile sltoken.txt --buildSessionIdFile api.buildSessionId \
  --labId qa-env --httpServerColoring --forwardSignals -- dist/server.js
```

Notes:

* The back end must allow the `baggage` header in its CORS preflight response (`Access-Control-Allow-Headers`). See [Context Propagation](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/context-propagation.md).
* If the back end calls other instrumented services, also add `--httpClientColoring` to it.
* Pass `--allowCORS` to `scan --instrumentForBrowsers`, not to `instrument`: `instrument` currently drops the list.

## Containers and Kubernetes <a href="#containers-and-kubernetes" id="containers-and-kubernetes"></a>

**Use when:** the service under test runs in a container.

```dockerfile
FROM node:20
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
# buildSessionId is created in CI by `slnodejs config` and copied into the image with the code.
CMD ["npx", "slnodejs", "run", \
     "--tokenFile", "/run/secrets/sltoken/sltoken.txt", \
     "--buildSessionIdFile", "/app/buildSessionId", \
     "--labId", "qa-env", \
     "--forwardSignals", \
     "--", "dist/server.js"]
```

Kubernetes: mount the token from a secret.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: my-service
spec:
  terminationGracePeriodSeconds: 30
  containers:
    - name: my-service
      image: registry.example.com/my-service:qa
      volumeMounts:
        - name: sltoken
          mountPath: /run/secrets/sltoken
          readOnly: true
  volumes:
    - name: sltoken
      secret:
        secretName: sealights-agent-token   # key: sltoken.txt
```

Notes:

* `--forwardSignals` passes `SIGTERM` to the service when the container stops, so it shuts down cleanly. The preload script does not forward signals.
* If the image runs `npm ci --omit=dev`, install `slnodejs` as a regular dependency.
* To keep the image start command unchanged, use the preload script instead: set `SL_tokenFile`, `SL_buildSessionIdFile`, `SL_labId` and `NODE_OPTIONS=--require /app/node_modules/slnodejs/lib/preload.js` as container environment variables.
* Do not bake `sltoken.txt` into the image.

## Monorepo with several modules <a href="#monorepo-with-several-modules" id="monorepo-with-several-modules"></a>

**Use when:** several packages or apps of one repository ship and are tested as one build.

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npx slnodejs config --tokenFile sltoken.txt --appName "<my-product>" \
  --branchName "$BRANCH_NAME" --buildName "$BUILD_NUMBER" --failOnError true

npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir packages/api/dist --scmType git --moduleName api
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir packages/worker/dist --scmType git --moduleName worker

npx slnodejs completeScan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --ok
```

Notes:

* Module names must be unique within the build and stay the same between builds.
* Add `--useModulePrefix` when two modules contain files with the same relative path.
* If the packages are released and deployed independently, give each its own application (`config --appName`) instead, and combine them with an [integration build](https://docs.sealights.io/knowledgebase/setup-and-configuration/build-and-test-execution/integration-build.md).

## Low-overhead back-end coverage <a href="#low-overhead-back-end-coverage" id="low-overhead-back-end-coverage"></a>

**Use when:** the default agent makes the service run out of memory, start slowly, or slows down tests, and coverage per test stage is enough. Requires Node.js later than 20.6.0.

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npx slnodejs config --tokenFile sltoken.txt --appName "<my-service>" \
  --branchName "$BRANCH_NAME" --buildName "$BUILD_NUMBER" --failOnError true
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir dist --scmType git --rawCoverage --failOnError true

export SL_useLeanCoverageListener=true
npx slnodejs run --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --labId qa-env -- dist/server.js
```

See [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) for limitations and shutdown behavior.

## Pull request builds <a href="#pull-request-builds" id="pull-request-builds"></a>

**Use when:** a pipeline runs for each pull request.

Replace `config` with `prConfig`; the rest of the pipeline stays the same.

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npx slnodejs prConfig --tokenFile sltoken.txt --appName "<my-service>" \
  --targetBranch "$PR_TARGET_BRANCH" --latestCommit "$PR_HEAD_SHA" \
  --pullRequestNumber "$PR_NUMBER" --repositoryUrl "https://github.com/<org>/<repo>" --failOnError true
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir src --scmType git --failOnError true
```

## Behind a proxy, a Collector, or TLS inspection <a href="#network-constraints" id="network-constraints"></a>

Add these to any configuration above:

```bash
# Corporate proxy
npx slnodejs scan ... --proxy http://proxy.example.com:3128
export SL_proxy=http://proxy.example.com:3128          # preload script

# TLS-inspecting proxy: verify certificates against your corporate CA
export SL_TLS_VERIFY=true
export SL_CA_FILE=/etc/ssl/certs/corporate-ca.pem

# SeaLights Collector in the test environment
npx slnodejs run ... --collectorUrl https://collector.example.com:16500/api -- dist/server.js
```

See [Troubleshooting → TLS and proxy issues](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md#tls-and-proxy-issues).


---

# 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/recommended-configurations.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.
