> 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/legacy-commands-deprecated/scanning-a-build.md).

# Scanning a Build

The `slnodejs scan` command scans your Node.js source files to prepare build metadata for the SeaLights platform.\
This page explains how to execute it for **backend** and **frontend** projects, including **TypeScript**, **ES6**, and **monorepo** setups.

## TL;DR – Quick Reference

<table><thead><tr><th width="161">Use Case</th><th width="403.6666259765625">Typical Command</th><th>Notes</th></tr></thead><tbody><tr><td><strong>Backend (CommonJS)</strong></td><td><code>npx slnodejs scan --tokenFile ./sltoken.txt --buildSessionIdFile buildSessionId --scanDir "." --scm git</code></td><td>Default mode for standard Node.js apps.</td></tr><tr><td><strong>Backend (ES6 / import-export)</strong></td><td><code>npx slnodejs scan --tokenFile ./sltoken.txt --buildSessionIdFile buildSessionId --scanDir "." --scmType git --es6Modules</code></td><td>Add <code>--es6Modules</code> if using <code>import/export</code> syntax.</td></tr><tr><td><strong>Backend (TypeScript / ts-node)</strong></td><td><code>set SL_fileExtensions=".ts,.tsx" &#x26;&#x26; npx slnodejs scan --tokenFile ./sltoken.txt --buildSessionIdFile buildSessionId --scanDir "./src" --scmType git</code></td><td>Set <code>SL_fileExtensions</code> for <code>.ts</code> files before scanning.</td></tr><tr><td><strong>Frontend (bundled app)</strong></td><td><code>npx slnodejs scan --tokenFile ./sltoken.txt --buildSessionIdFile buildSessionId --scanDir dist --outputPath sl_dist --scmType git --es6Modules --useRelativeSlMapping</code></td><td>Requires <code>.js.map</code> files with correct source references.</td></tr><tr><td><strong>Monorepo / Multi-Module</strong></td><td><code>bash\nfor module in moduleA moduleB; do\n npx slnodejs scan --tokenFile ./sltoken.txt --buildSessionIdFile buildSessionId --scanDir "apps/$module" --scmtype git --uniqueModuleId $module\ndone\nnpx slnodejs buildend --tokenFile ./sltoken.txt --buildSessionIdFile buildSessionId --ok\n</code></td><td>Loop over modules and signal build completion.</td></tr></tbody></table>

## Common Prerequisites

Before running `slnodejs scan`, make sure you have:

* ✅ A valid **SeaLights token file** (`sltoken.txt`)
* ✅ A **build session ID file** (`buildSessionId`)
* ✅ Access to the **source or build output** to be scanned
* ✅ Node.js **v12+** (recommended v16+)

## Backend Application

### Prerequisites

Check if any of these apply to your backend project:

* ✅ Using **ES6 syntax (`import/export`)** → add `--es6Modules`
* ✅ Using **TypeScript / ts-node** → set `SL_fileExtensions=".ts,.tsx"` before running the scan
* ✅ Working in a **monorepo** → assign `--uniqueModuleId` for each sub-module and run a single `buildend` after all scans
* ✅ Standard CommonJS app → no special flags needed

### Scan command

Use this command for Node.js backend or server applications. to scan your project source and uploads metadata to SeaLights.

{% tabs %}
{% tab title="Basic Scan" %}

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

{% endtab %}

{% tab title="With ES6 Modules" %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
`--es6Modules` is **optional** — only add it if your backend uses ES6 `import/export` syntax.
{% endhint %}

### TypeScript / ts-node Subcase

For TypeScript projects or those executed via `ts-node`, specify file extensions.

{% hint style="warning" %}
*Ensure that* `--scanDir` *points to the TypeScript source folder, not the compiled output.*
{% endhint %}

{% tabs %}
{% tab title="Unix / macOS" %}

<pre class="language-bash"><code class="lang-bash">export SL_fileExtensions=".ts,.tsx"

<strong>npx slnodejs scan \
</strong>  --tokenFile /path/to/sltoken.txt \
  --buildSessionIdFile buildSessionId \
  --scanDir "./src" \
  --scmType git
</code></pre>

{% endtab %}

{% tab title="Windows CMD" %}

```cmd
set SL_fileExtensions=".ts,.tsx"

npx slnodejs scan ^
  --tokenFile \path\to\sltoken.txt ^
  --buildSessionIdFile buildSessionId ^
  --scanDir ".\src" ^
  --scmType git
```

{% endtab %}
{% endtabs %}

## Frontend Application

Use this mode when scanning bundled or transpiled frontend applications.

### Prerequisites

Before running the scan:

* Source map (`.js.map`) files must exist and be properly generated by your build tool (Webpack, Rollup, etc.).
* Source maps must include **column mapping** and reference the correct original source paths.
* The scan runs on the **bundled output folder** (e.g., `dist` or `build`)
* Add `--useRelativeSlMapping` for accurate coverage mapping
* Include `--es6Modules` if using ES6 syntax

### Scan Command

{% tabs %}
{% tab title="Unix / macOS" %}

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

{% endtab %}

{% tab title="Windows CMD" %}

```cmd
npx slnodejs scan ^
  --tokenFile \path\to\sltoken.txt ^
  --buildSessionIdFile buildSessionId ^
  --scanDir dist ^
  --scmType git ^
  --es6Modules ^
  --useRelativeSlMapping
```

{% endtab %}
{% endtabs %}

**Expected Output**

* A folder (default: `sl_dist`) is generated with processed files.
* Console logs display scanned methods and branches.
* Coverage results are mapped correctly to your original source code.

## Common Options

| Flag                          | Description                                                                              |
| ----------------------------- | ---------------------------------------------------------------------------------------- |
| `--tokenFile <file>`          | Path to the SeaLights token file.                                                        |
| `--buildSessionIdFile <file>` | Path to the file containing the build session ID.                                        |
| `--scanDir <path>`            | Root directory of your application’s source.                                             |
| `--scmType <git\|none>`       | Source control metadata collection mode.                                                 |
| `--es6Modules`                | Optional; include if your project uses ES6 `import/export` syntax (backend or frontend). |
| `--outputPath <path>`         | Path to output processed files (frontend only).                                          |
| `--useRelativeSlMapping`      | **Frontend only:** enables relative source map paths for accurate coverage mapping.      |
| `--uniqueModuleId <id>`       | Unique identifier for a module in multi-module (monorepo) setups.                        |

## Multi-Module / Monorepo Support

For repositories containing multiple applications or packages, use the `--uniqueModuleId` flag to scan each sub-module under the same build session.

In the example below, we're looping over a list of modules folders:

{% tabs %}
{% tab title="Unix / macOS" %}

```bash
for module in moduleA moduleB; do
  npx slnodejs scan \
    --tokenFile ./sltoken.txt \
    --buildSessionIdFile buildSessionId \
    --scanDir "apps/$module" \
    --scmType git \
    --uniqueModuleId $module
done

# Signal the end of all module scans
npx slnodejs buildend --ok \
  --tokenFile ./sltoken.txt \
  --buildSessionIdFile buildSessionId 
```

{% endtab %}

{% tab title="Windows PowerShell" %}

```powershell
foreach ($module in "moduleA", "moduleB") {
  npx slnodejs scan `
    --tokenFile .\sltoken.txt `
    --buildSessionIdFile buildSessionId `
    --scanDir "apps\$module" `
    --scmType git `
    --uniqueModuleId $module
}

# Signal the end of all module scans
npx slnodejs buildend --ok `
  --tokenFile .\sltoken.txt `
  --buildSessionIdFile buildSessionId  
```

{% endtab %}
{% endtabs %}

**Notes**

* Use a **unique module ID** for each subproject to ensure accurate reporting.
* All modules in a single build must share the same `buildSessionId`.
* Run `buildend` only once after scanning all modules to signal build completion.

## Troubleshooting and Best Practices

<table><thead><tr><th width="291.333251953125">Issue</th><th>Recommendation</th></tr></thead><tbody><tr><td>Missing coverage mapping</td><td>Ensure <code>.js.map</code> files exist and contain correct source references.</td></tr><tr><td>Slow scan time</td><td>Exclude large folders (e.g., <code>node_modules</code>) using <code>--excludedpaths</code>.</td></tr><tr><td>Missing files in dashboard</td><td>Check that <code>--scanDir</code> points to the correct source directory.</td></tr><tr><td>Unexpected results in ES6 projects</td><td>Add the <code>--es6Modules</code> flag.</td></tr><tr><td>Multi-module reports not merged</td><td>Use consistent <code>buildSessionId</code> and unique <code>--uniqueModuleId</code> per module.</td></tr></tbody></table>


---

# 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/legacy-commands-deprecated/scanning-a-build.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.