# 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 --workspacepath "." --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 --workspacepath "." --scm 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 --workspacepath "./src" --scm 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 --workspacepath dist --outputpath sl_dist --scm 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 --workspacepath "apps/$module" --scm 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 \
  --workspacepath "." \
  --scm git
```

{% endtab %}

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

```bash
npx slnodejs scan \
  --tokenfile ./sltoken.txt \
  --buildsessionidfile buildSessionId \
  --workspacepath "." \
  --scm 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 `workspacepath` 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 \
  --workspacepath "./src" \
  --scm git
</code></pre>

{% endtab %}

{% tab title="Windows CMD" %}

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

npx slnodejs scan ^
  --tokenfile \path\to\sltoken.txt ^
  --buildsessionidfile buildSessionId ^
  --workspacepath ".\src" ^
  --scm 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 \
  --workspacepath dist --scm git \
  --es6Modules --useRelativeSlMapping
```

{% endtab %}

{% tab title="Windows CMD" %}

```cmd
npx slnodejs scan ^
  --tokenfile \path\to\sltoken.txt --buildsessionidfile buildSessionId ^
  --workspacepath dist --scm 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.                                        |
| `--workspacepath <path>`      | Root directory of your application’s source.                                             |
| `--scm <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 \
    --workspacepath "apps/$module" --scm 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 `
    --workspacepath "apps\$module" --scm 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 & 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>workspacepath</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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.