> 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

Scanning is the **first step after `config`** and is required for both frontend and backend applications. The `scan` command analyzes your JavaScript/TypeScript files and uploads a method-level map of the build to SeaLights, so coverage collected later can be attributed to the correct code.

Run `scan` **after** your build produces its output and **before** you instrument a frontend app or `run` a backend service.

{% hint style="info" %}
**Parameter naming (Agent 6.2.1+):** all examples use the standardized camelCase parameters (`--tokenFile`, `--buildSessionIdFile`, `--labId`, `--scanDir`, `--outputPath`, …). Older lowercase aliases (`--tokenfile`, `--labid`, `--workspacepath`, …) still work but are slated for deprecation.
{% endhint %}

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

> These prerequisites apply to every command on the following pages (Instrumentation, Run, Capturing Tests). They are stated here once — later pages link back to this section.

* A SeaLights **agent token** (`sltoken.txt` locally, or an `SL_TOKEN` secret in CI).
* A **Build Session ID** generated with `config` — see [Generating a Session ID](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/generating-a-session-id.md). In CI, `config` writes a `buildSessionId` file that every later command reuses via `--buildSessionIdFile buildSessionId`.
* The SeaLights agent installed (`npm install slnodejs`).
* **Node.js v12+** (v16+ recommended).

## Scanning a backend build <a href="#scanning-a-backend-build" id="scanning-a-backend-build"></a>

For a backend Node.js service, point `--scanDir` at the project root (or the folder containing your server source).

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

```sh
# CommonJS
npx slnodejs scan \
  --tokenFile ./sltoken.txt \
  --buildSessionIdFile buildSessionId \
  --scanDir "." \
  --scmType git
```

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
- name: SeaLights scan 
  env:
    SL_TOKEN: ${{ secrets.SL_TOKEN }}
  run: |
    npx slnodejs scan \
      --token "$SL_TOKEN" \
      --buildSessionIdFile buildSessionId \
      --scanDir "." \
      --scmType git
```

{% endtab %}

{% tab title="PowerShell" %}

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

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- script: |
    npx slnodejs scan \
      --token "$(SL_TOKEN)" \
      --buildSessionIdFile buildSessionId \
      --scanDir "." \
      --scmType git
  displayName: SeaLights scan (backend)
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For **TypeScript**, scan the source folder (e.g. `./src`), not the compiled `dist`. Use `SL_fileExtensions` to tell the scanner which extensions to include.

{% code overflow="wrap" expandable="true" %}

```bash
# ES6 / TypeScript — scan the SOURCE folder, not the compiled output
export SL_fileExtensions=".ts,.tsx"
npx slnodejs scan [...]  --scanDir "./src" 
```

{% endcode %}
{% endhint %}

## Scanning a frontend build (bundled) <a href="#scanning-a-frontend-build-bundled" id="scanning-a-frontend-build-bundled"></a>

Frontend apps are minified/bundled, so SeaLights needs **source maps with column information** to map the bundle back to your original source. The scan reads `dist`, and writes a SeaLights-mapped copy to `--outputPath` (e.g. `sl_dist`).

### Produce source maps with column info <a href="#produce-source-maps-with-column-info" id="produce-source-maps-with-column-info"></a>

{% hint style="warning" %}
"Cheap" (line-only) source maps are not enough — SeaLights needs both line **and** column data.
{% endhint %}

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

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

{% endtab %}

{% tab title="TypeScript" %}

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

{% endtab %}
{% endtabs %}

### Run the scan <a href="#run-the-scan" id="run-the-scan"></a>

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

```sh
npx slnodejs scan \
  --tokenFile ./sltoken.txt \
  --buildSessionIdFile buildSessionId \
  --scanDir dist \
  --scmType git \
  --es6Modules \
  --useRelativeSlMapping
```

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
- name: SeaLights scan (frontend)
  env:
    SL_TOKEN: ${{ secrets.SL_TOKEN }}
  run: |
    npx slnodejs scan \
      --token "$SL_TOKEN" \
      --buildSessionIdFile buildSessionId \
      --scanDir dist \
      --scmType git \
      --es6Modules \
      --useRelativeSlMapping
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
npx slnodejs scan `
  --tokenFile .\sltoken.txt `
  --buildSessionIdFile buildSessionId `
  --scanDir dist `
  --scmType git `
  --es6Modules `
  --useRelativeSlMapping
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- script: |
    npx slnodejs scan \
      --token "$(SL_TOKEN)" \
      --buildSessionIdFile buildSessionId \
      --scanDir dist \
      --scmType git \
      --es6Modules \
      --useRelativeSlMapping
  displayName: SeaLights scan (frontend)
```

{% endtab %}
{% endtabs %}

### Clean up source maps before production <a href="#clean-up-source-maps-before-production" id="clean-up-source-maps-before-production"></a>

Once scanning is done, the `.js.map` files are no longer needed and should not ship to production.

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

```sh
find . -name "*.js.map" -exec rm {} \;
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
Get-ChildItem -Recurse -Filter *.js.map | Remove-Item
```

{% endtab %}
{% endtabs %}

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

Scan each module under the **same** Build Session ID, giving each a distinct module identifier, then signal completion once with `buildend`.

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

```sh
# scan module A, then module B under the same build session
npx slnodejs scan \
  --tokenFile ./sltoken.txt \
  --buildSessionIdFile buildSessionId \
  --scanDir ./packages/a \
  --scmType git \
  --moduleName module-a

npx slnodejs scan \
  --tokenFile ./sltoken.txt \
  --buildSessionIdFile buildSessionId \
  --scanDir ./packages/b \
  --scmType git \
  --moduleName module-b

# after ALL modules are scanned
npx slnodejs buildend \
  --tokenFile ./sltoken.txt \
  --buildSessionIdFile buildSessionId \
  --ok
```

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
- name: SeaLights scan multi-module build
  env:
    SL_TOKEN: ${{ secrets.SL_TOKEN }}
  run: |
    # scan module A, then module B under the same build session
    npx slnodejs scan \
      --token "$SL_TOKEN" \
      --buildSessionIdFile buildSessionId \
      --scanDir ./packages/a \
      --scmType git \
      --moduleName module-a

    npx slnodejs scan \
      --token "$SL_TOKEN" \
      --buildSessionIdFile buildSessionId \
      --scanDir ./packages/b \
      --scmType git \
      --moduleName module-b

    # after ALL modules are scanned
    npx slnodejs buildend \
      --token "$SL_TOKEN" \
      --buildSessionIdFile buildSessionId \
      --ok
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
# scan module A, then module B under the same build session
npx slnodejs scan `
  --tokenFile .\sltoken.txt `
  --buildSessionIdFile buildSessionId `
  --scanDir .\packages\a `
  --scmType git `
  --moduleName module-a

npx slnodejs scan `
  --tokenFile .\sltoken.txt `
  --buildSessionIdFile buildSessionId `
  --scanDir .\packages\b `
  --scmType git `
  --moduleName module-b

# after ALL modules are scanned
npx slnodejs buildend `
  --tokenFile .\sltoken.txt `
  --buildSessionIdFile buildSessionId `
  --ok
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- script: |
    # scan module A, then module B under the same build session
    npx slnodejs scan \
      --token "$(SL_TOKEN)" \
      --buildSessionIdFile buildSessionId \
      --scanDir ./packages/a \
      --scmType git \
      --moduleName module-a

    npx slnodejs scan \
      --token "$(SL_TOKEN)" \
      --buildSessionIdFile buildSessionId \
      --scanDir ./packages/b \
      --scmType git \
      --moduleName module-b

    # after ALL modules are scanned
    npx slnodejs buildend \
      --token "$(SL_TOKEN)" \
      --buildSessionIdFile buildSessionId \
      --ok
  displayName: SeaLights scan multi-module build
```

{% endtab %}
{% endtabs %}

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

Use ignore files to keep test files, vendor bundles, and mapped assets out of coverage. Patterns follow `.gitignore` glob syntax.

* **`.slignore`** — excludes files from scanning.
* **`.slignore.generated`** — excludes original files referenced by source maps (images, HTML, etc.).

```gitignore
# .slignore — common exclusions
**/*test.js
**/*.spec.ts

# Angular bundles
**/vendor*.js
**/runtime*.js
**/inline*.js
**/polyfills*.js
**/*-es5.js
**/es5/**
```

```gitignore
# .slignore.generated — assets referenced by source maps
*.html
*.png
*.svg
```

**Whitelist approach** — ignore everything except specific files:

```gitignore
*
!*main*.js
```

{% hint style="info" %}
Before writing ignore rules, list the JS/TS files in your build to see what would be scanned:

{% code overflow="wrap" expandable="true" %}

```bash
tree --du -h -I 'node_modules|sl-dry-run-output|sl_dist' -P "*.[jt]s*" 
```

{% endcode %}
{% endhint %}

## Key parameters <a href="#troubleshooting" id="troubleshooting"></a>

| Parameter                                   | Purpose                                                              |
| ------------------------------------------- | -------------------------------------------------------------------- |
| `--tokenFile` / `--token`                   | SeaLights authentication (file locally, secret in CI)                |
| `--buildSessionIdFile` / `--buildSessionId` | Build session identifier                                             |
| `--scanDir`                                 | Root of the source / build output to scan                            |
| `--outputPath`                              | Destination for the SeaLights-mapped copy (frontend, e.g. `sl_dist`) |
| `--scmType`                                 | Source-control type (`git` / `none`)                                 |
| `--es6Modules`                              | Handle ES6 `import`/`export` syntax                                  |
| `--useRelativeSlMapping`                    | Map coverage to source using relative paths (frontend)               |
| `--excludeFiles`                            | Exclude paths from the scan (see below)                              |
| `--moduleName`                              | Module identifier for monorepo scans                                 |

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

| Symptom                                       | Likely cause / fix                                                                         |
| --------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Files missing from the dashboard              | `--scanDir` points to the wrong folder, or files are excluded by `.slignore`.              |
| No coverage mapping (frontend)                | Missing/`cheap` source maps — regenerate with full column info.                            |
| Warning about source maps lacking column data | Build tool is emitting line-only maps — set `devtool: 'source-map'` / `"sourceMap": true`. |
| Slow scans                                    | Exclude large folders with `--excludeFiles` or entries in `.slignore`.                     |

***

**Next step →** [Frontend Instrumentation](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/frontend-instrumentation.md) *(frontend apps)* · [Backend Instrumentation](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/backend-instrumentation.md) *(backend services)*


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.