> 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/scanning-your-application.md).

# Scanning Your Application

Scan your build with slnodejs scan: what to scan for each kind of code, source maps, monorepos, integration builds, excluding files, and source control data.

`slnodejs scan` reports the structure of a build (files, methods and branches) to SeaLights, so that coverage collected later can be attributed to the right code. Run it once per build, after your build produces its output and before the code runs in tests.

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

These prerequisites apply to every page that follows (runtime coverage, tests).

* `slnodejs` installed; 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).
* An agent token in a file (`sltoken.txt`); see [Configuration → Token](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#token).
* A build session ID from `config`; see [Generating a Session ID](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/generating-a-session-id.md).
* For source control data: a Git checkout with history (in CI, a full clone, for example `fetch-depth: 0` in GitHub Actions).

## What to scan <a href="#what-to-scan" id="what-to-scan"></a>

**Scan the files that actually run.** Runtime coverage is matched to the scan by file path and by the position of each method in the file. If the files that run differ from the files you scanned, coverage cannot be matched.

| Your code                                                       | Scan                                                                       | Flags                                                                                                                             |
| --------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Plain JavaScript (CommonJS) that runs as is                     | The source folder                                                          | `--scanDir src` (or `.` with a `.slignore`)                                                                                       |
| ES modules (`"type": "module"` or `.mjs`)                       | The source folder                                                          | add `--es6Modules`                                                                                                                |
| TypeScript or Babel compiled to an output folder                | The output folder, with source maps                                        | `--scanDir dist`; see [TypeScript and transpiled code](#typescript-and-transpiled-code)                                           |
| TypeScript run with `ts-node` or a TypeScript loader            | The `.ts` source folder                                                    | `SL_fileExtensions=.ts`, `--scanDir src`                                                                                          |
| Front-end bundles (webpack, Vite, Rollup, esbuild, Angular CLI) | The bundle output folder, with source maps that include column information | `--scanDir dist --es6Modules`, usually with `--instrumentForBrowsers`; see [Front-end builds](#scanning-a-frontend-build-bundled) |

## Scan a back-end build <a href="#scanning-a-backend-build" id="scanning-a-backend-build"></a>

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

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npx slnodejs scan \
  --tokenFile sltoken.txt \
  --buildSessionIdFile buildSessionId \
  --scanDir src \
  --scmType git
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
npx slnodejs scan `
  --tokenFile sltoken.txt `
  --buildSessionIdFile buildSessionId `
  --scanDir src `
  --scmType git
```

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
- name: SeaLights scan
  run: |
    npx slnodejs scan \
      --tokenFile sltoken.txt \
      --buildSessionIdFile buildSessionId \
      --scanDir src \
      --scmType git
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- script: |
    npx slnodejs scan \
      --tokenFile sltoken.txt \
      --buildSessionIdFile buildSessionId \
      --scanDir src \
      --scmType git
  displayName: SeaLights scan
```

{% endtab %}
{% endtabs %}

To scan the project root, use `--scanDir .` and exclude `node_modules`, tests and build tooling in a [`.slignore`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#ignore-files) file.

## TypeScript and transpiled code <a href="#typescript-and-transpiled-code" id="typescript-and-transpiled-code"></a>

**Compiled before it runs** (`tsc`, Babel, SWC): scan the output folder, with source maps, so that SeaLights reports methods on your original `.ts` files.

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "sourceMap": true
  }
}
```

```bash
npm run build   # writes dist/ and dist/**/*.js.map
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --scanDir dist --scmType git
```

Use the same `--projectRoot` (default: the working directory) for the scan and for the test listener that runs the code. If coverage stays at 0% while the agent sends data, a project root mismatch is the most likely cause; see [Troubleshooting → Coverage is missing or low](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md#coverage-is-missing-or-low).

**Run directly with `ts-node`** (or another TypeScript loader): scan the `.ts` files.

```bash
export SL_fileExtensions=.ts
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --scanDir src --scmType git
```

`SL_fileExtensions` replaces the list of scanned extensions. Include every extension you need, for example `SL_fileExtensions=.ts,.js`.

## Scan a front-end build <a href="#scanning-a-frontend-build-bundled" id="scanning-a-frontend-build-bundled"></a>

Front-end code is bundled and often minified, so SeaLights needs **source maps with column information** to map the bundles back to your source files. Line-only ("cheap") source maps are not enough.

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

```js
// webpack.config.js
module.exports = {
  devtool: 'source-map',
};
```

{% endtab %}

{% tab title="Vite" %}

```js
// vite.config.js
export default {
  build: { sourcemap: true },
};
```

{% endtab %}

{% tab title="Angular" %}

```jsonc
// angular.json → projects.<app>.architect.build.configurations.<config>
{
  "sourceMap": true
}
```

{% endtab %}

{% tab title="TypeScript" %}

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "sourceMap": true
  }
}
```

{% endtab %}
{% endtabs %}

Valid source maps:

1. are **available at scan time**, next to the bundles (inline or as `.map` files) in `--scanDir`;
2. list in `sources` the **files that are in your repository**;
3. use **correct relative paths** to those source files.

To check them, open the application in the browser developer tools: the original sources must be listed and readable. Without column information, the SeaLights dashboard shows the warning `Detected source-maps without column information. Source maps information might be incorrect and may result in inaccurate coverage`. `dryRun` reports the same problem as `Column information`.

Then scan and instrument in one step. This writes an instrumented copy to `--outputPath`, which you deploy to the test environment instead of the original:

```bash
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir dist --scmType git --es6Modules \
  --instrumentForBrowsers --outputPath sl_dist \
  --excludeSourceMapFiles skipCopy
```

* `--excludeSourceMapFiles skipCopy` keeps the source maps out of `sl_dist`, so they are not deployed. `skipAndDelete` also deletes them from `dist`.
* If you instrument later or once per environment with the `instrument` command, scan with `--useRelativeSlMapping` (and without `--instrumentForBrowsers`).
* Lab ID, Collector, token exposure and the other instrumentation options are described in [Frontend Instrumentation (static)](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/frontend-instrumentation-static.md).

{% hint style="warning" %}
Do not delete source maps with a recursive `find ... -name "*.js.map" -delete` from the project root: it also deletes the maps in `node_modules`. Use `--excludeSourceMapFiles`.
{% endhint %}

## Monorepo and multi-module builds <a href="#monorepo--multi-module-builds" id="monorepo--multi-module-builds"></a>

To report several directories as one build, scan each one into the same build session with its own `--moduleName`, then report the end of the build once with `completeScan`.

```bash
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/web/dist --scmType git --moduleName web --instrumentForBrowsers --outputPath packages/web/sl_dist
npx slnodejs completeScan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --ok
```

* Without `--moduleName`, a build session can be scanned only once; a second scan fails.
* Module names are case-sensitive and must stay the same between builds.
* Add `--useModulePrefix` when two modules contain files with the same relative path.

For server-side rendering frameworks, see [Next.js (Multi-Module Scan)](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/next.js-with-sealights-node-and-browser-agents-multi-module-scan.md).

## Integration builds <a href="#integration-builds" id="integration-builds"></a>

An integration build is made of the builds of other applications (for example the microservices of a release). It has no code of its own: pass the components instead of `--scanDir`.

```bash
npx slnodejs config --tokenFile sltoken.txt --appName "my-release" --branchName main --buildName "$RELEASE_VERSION"
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --dependency "billing@main@2.3.1;orders@main@5.0.0"
```

To change the components later, use [`componentUpdate` and `componentDelete`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#componentupdate-and-componentdelete). See [Integration Build](https://docs.sealights.io/knowledgebase/setup-and-configuration/build-and-test-execution/integration-build.md).

## Exclude files <a href="#excluding-files-and-folders" id="excluding-files-and-folders"></a>

Exclude tests, vendor bundles, generated code and build tooling, so that coverage percentages reflect the code your team maintains. Use a `.slignore` file (`.gitignore` syntax) in the scanned directory or one of its parents:

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

`.slignore.instrument` and `.slignore.generated`, and a known issue with `--excludeFiles`, are described in [Configuration → Ignore files](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#ignore-files).

## Source control data <a href="#source-control-data" id="source-control-data"></a>

With `--scmType git`, the scan reports commits and contributors from the local Git repository. Without it, no source control data is sent.

| Situation                                                        | Flag                                                |
| ---------------------------------------------------------------- | --------------------------------------------------- |
| The checkout has no `origin` remote, or its URL is not browsable | `--repositoryUrl https://github.com/my-org/my-app`  |
| Bitbucket or GitLab                                              | `--scmProvider Bitbucket` or `--scmProvider Gitlab` |
| On-premises SCM server                                           | `--scmVersion <server version>`                     |
| The scan does not run in a Git checkout                          | `--commit <sha>` and leave out `--scmType`          |

## Check the scan before CI <a href="#check-before-ci" id="check-before-ci"></a>

Run `dryRun` locally to see which files are scanned and how source maps resolve, without reporting a build:

```bash
npx slnodejs dryRun --scanDir dist --verbose
```

See [dryRun Command: Troubleshooting and Validation](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/dryrun-command-troubleshooting-and-validation.md).

## Report the end of the build <a href="#complete-the-build" id="complete-the-build"></a>

After all scans of the build session, report that the build is complete:

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

Use `--failed` instead of `--ok` when the build failed.

## Key flags <a href="#key-parameters" id="key-parameters"></a>

| Flag                                         | When to use                                                           |
| -------------------------------------------- | --------------------------------------------------------------------- |
| `--scanDir`                                  | Always (except integration builds). The folder of the code that runs. |
| `--scmType git`                              | Whenever the scan runs in a Git checkout.                             |
| `--es6Modules`                               | ES module code and most front-end bundles.                            |
| `--babylonPlugins jsx` / `decorators-legacy` | Scanning JSX or decorator syntax that is not transpiled.              |
| `--projectRoot`                              | When the scan runs from another directory than the test listener.     |
| `--instrumentForBrowsers --outputPath`       | Web applications.                                                     |
| `--useRelativeSlMapping`                     | When you instrument later with the `instrument` command.              |
| `--moduleName`                               | Several scans in one build session.                                   |
| `--rawCoverage`                              | Lightweight V8 coverage mode.                                         |
| `--awsConfigure`                             | AWS Lambda functions.                                                 |
| `--failOnError true`                         | When a failed scan must fail the pipeline.                            |

Every flag is in the [Command Reference → scan](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#scan).

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

| Symptom                                                            | Likely cause and fix                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The scan reports 0 files or files are missing                      | `--scanDir` points to the wrong folder, or files are excluded by `.slignore` or the NYC `exclude` patterns. Run `dryRun` and check `included-files.json`. See also [JS: Files Missing from Build Scan](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript/js-files-missing-from-build-scan.md). |
| `Module already exists`                                            | The build session was already scanned. Create a new build session with a unique `--buildName`, or give each scan its own `--moduleName`.                                                                                                                                                                                                         |
| Front-end methods are reported on bundle files or with wrong names | Source maps are missing or line-only. Generate full source maps, keep them next to the bundles during the scan.                                                                                                                                                                                                                                  |
| Parse errors                                                       | The code uses syntax the parser does not expect: add `--es6Modules`, or `--babylonPlugins jsx` / `decorators-legacy`.                                                                                                                                                                                                                            |
| `JavaScript heap out of memory`                                    | Exclude vendor and generated files; see [NodeJS - JavaScript heap out of memory](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript/nodejs-javascript-heap-out-of-memory.md).                                                                                                                   |
| The command fails but the pipeline passes                          | By default `slnodejs` exits with 0. Add `--failOnError true`.                                                                                                                                                                                                                                                                                    |

More in [Troubleshooting](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md).

## Next step <a href="#next-step" id="next-step"></a>

Make the application report coverage: [Capturing Runtime Coverage](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage.md). For unit tests only, go to [Capturing Tests](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests.md).


---

# 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/scanning-your-application.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.
