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.

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

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

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:

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.

Last updated

Was this helpful?