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.

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.

Prerequisites

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. 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

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

Bash

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

GitHub Actions

PowerShell

Azure DevOps

For TypeScript, scan the source folder (e.g. ./src), not the compiled dist. Use SL_fileExtensions to tell the scanner which extensions to include.

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

Scanning a frontend build (bundled)

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

"Cheap" (line-only) source maps are not enough — SeaLights needs both line and column data.

Webpack

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

TypeScript

Run the scan

Bash

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

GitHub Actions

PowerShell

Azure DevOps

Clean up source maps before production

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

Bash

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

PowerShell

Monorepo / multi-module builds

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

Bash

# 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

GitHub Actions

PowerShell

Azure DevOps

Excluding files and folders

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.).

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

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

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

Whitelist approach — ignore everything except specific files:

*
!*main*.js

Before writing ignore rules, list the JS/TS files in your build to see what would be scanned:

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

Key parameters

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

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 (frontend apps) · Backend Instrumentation (backend services)