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

Use Case	Typical Command	Notes
Backend (CommonJS)	npx slnodejs scan --tokenfile ./sltoken.txt --buildsessionidfile buildSessionId --workspacepath "." --scm git	Default mode for standard Node.js apps.
Backend (ES6 / import-export)	npx slnodejs scan --tokenfile ./sltoken.txt --buildsessionidfile buildSessionId --workspacepath "." --scm git --es6Modules	Add --es6Modules if using import/export syntax.
Backend (TypeScript / ts-node)	set SL_fileExtensions=".ts,.tsx" && npx slnodejs scan --tokenfile ./sltoken.txt --buildsessionidfile buildSessionId --workspacepath "./src" --scm git	Set SL_fileExtensions for .ts files before scanning.
Frontend (bundled app)	npx slnodejs scan --tokenfile ./sltoken.txt --buildsessionidfile buildSessionId --workspacepath dist --outputpath sl_dist --scm git --es6Modules --useRelativeSlMapping	Requires .js.map files with correct source references.
Monorepo / Multi-Module	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	Loop over modules and signal build completion.

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.

Basic Scan

npx slnodejs scan \
  --tokenfile ./sltoken.txt \
  --buildsessionidfile buildSessionId \
  --workspacepath "." \
  --scm git

With ES6 Modules

--es6Modules is optional — only add it if your backend uses ES6 import/export syntax.

TypeScript / ts-node Subcase

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

Ensure that workspacepath points to the TypeScript source folder, not the compiled output.

Unix / macOS

export SL_fileExtensions=".ts,.tsx"

npx slnodejs scan \
  --tokenfile /path/to/sltoken.txt \
  --buildsessionidfile buildSessionId \
  --workspacepath "./src" \
  --scm git

Windows CMD

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

Unix / macOS

npx slnodejs scan \
  --tokenfile /path/to/sltoken.txt --buildsessionidfile buildSessionId \
  --workspacepath dist --scm git \
  --es6Modules --useRelativeSlMapping

Windows CMD

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:

Unix / macOS

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 

Windows PowerShell

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

Issue	Recommendation
Missing coverage mapping	Ensure .js.map files exist and contain correct source references.
Slow scan time	Exclude large folders (e.g., node_modules) using --excludedpaths.
Missing files in dashboard	Check that workspacepath points to the correct source directory.
Unexpected results in ES6 projects	Add the --es6Modules flag.
Multi-module reports not merged	Use consistent buildSessionId and unique --uniqueModuleId per module.