6.2.78 • Published yesterday

slnodejs

Licence

ISC

Version

6.2.78

Deps

Vulns

Weekly

Summary Dependency Versions

Sealights Node.js Agent

Lean coverage listener — GA target (not current behavior):
See lightweight-agent/docs/RUNTIME_CONTRACT.md for the intended end-state contract (ship inside slnodejs only). That doc is a planning/alignment artifact — not documentation of current agent behavior. Do not confuse it with the preload / CLI behavior described below.

The preload.js script serves as an automatic loader for the Sealights Node agent, eliminating the need to explicitly wrap your commands with slnodejs run. This script intercepts the normal Node.js execution flow and injects the necessary Sealights installation logic.

Installation

First, install the Sealights Node.js package:

npm install slnodejs

The preload script will be available at:

./node_modules/slnodejs/lib/preload.js

Usage

Method 1: Using `-r` flag

node -r ./node_modules/slnodejs/lib/preload.js your-script.js

Method 2: Using `NODE_OPTIONS`

export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
node your-script.js

Or inline:

NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js" node your-script.js

Using NODE_OPTIONS allows you to persist the preloader configuration across multiple Node.js executions without explicitly specifying the -r flag each time.

Environment Variables Configuration

Variable	Description	Default
`SL_TOKEN`	Direct Sealights agent authentication token
`SL_TOKEN_FILE`	Path to file containing the Sealights token	`./sltoken.txt`
`SL_BUILD_SESSION_ID`	Direct build session ID
`SL_BUILD_SESSION_ID_FILE`	Path to file containing build session ID	`./buildSessionId`
`SL_PROJECT_ROOT`	Root directory of your project	Current working directory
`SL_COLLECTOR_URL`	URL to Sealights collector
`SL_LAB_ID`	Lab ID for test execution

Error Handling

The script includes robust error handling mechanisms:

Primary Execution: Attempts to run the target script with Sealights agent configuration
Fallback Mechanism: If the primary execution fails, it falls back to running the original command
Uncaught Exception Handler: Captures and logs any uncaught exceptions

Examples

Using `-r` Flag

node -r ./node_modules/slnodejs/lib/preload.js server.js

Using `NODE_OPTIONS`

# Set for current session
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
node server.js

# Or inline
NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js" node server.js

Using Environment Variables with `NODE_OPTIONS`

export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
SL_TOKEN="your-token-here" node server.js

Specifying Custom Paths with `NODE_OPTIONS`

export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
SL_TOKEN_FILE="/custom/path/token.txt" SL_projectRoot="/path/to/project" node server.js

Using Collector URL and Lab ID with `NODE_OPTIONS`

export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
SL_TOKEN="your-token-here" SL_COLLECTOR_URL="https://your-collector-url.com" SL_LAB_ID="your-lab-id" node server.js

Debug Mode with `NODE_OPTIONS`

export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
NODE_DEBUG=sl node server.js

Troubleshooting

If you encounter issues:

Check if the token and build session ID files exist and are readable
Verify environment variables are set correctly
Check console output for error messages (turn on NODE_DEBUG=sl)
Ensure the script has necessary permissions to execute

Limitations

When using -r flag: Must be explicitly included in each Node.js command
When using NODE_OPTIONS: Affects all Node.js processes in the current environment

Best Practices

Choosing Between `-r` and `NODE_OPTIONS`

Use `-r` flag when:

You want to explicitly control which scripts use the preloader
You're running in an environment where global Node.js settings should not be modified
You're running multiple Node.js applications with different configurations

Use `NODE_OPTIONS` when:

You want to ensure all Node.js executions in your session include the preloader
You're working in a dedicated development environment
You want to reduce command verbosity
You're setting up CI/CD pipelines where all Node.js executions should include the preloader and Sealights Agent

Integration Tests

PRs to main automatically trigger the JS Agent Integration Tests, which validate the agent works correctly with the plugins and example apps across Node.js 18, 20, and 22.

The tests are defined in SL.JavaScript.AgentTests and run via a reusable workflow (validate-agent.yml).

Cross-Repo Branch Resolution

When working on a feature that spans multiple repos, create branches with the same name across repos. The CI automatically detects matching branches and tests them together.

For example, if your PR branch is feature/new-scanner and a branch with the same name exists in the Plugins or ExampleApps repos, the integration tests will use those branches instead of the defaults.

This is handled via the feature-branch input — see the AgentTests README for details.

Manual Dispatch

You can also trigger integration tests manually via the Actions tab → JS Agent Integration Tests → Run workflow, with options for:

plugins-branch — test against a specific plugins branch
feature-branch — try this branch in every repo (falls back to defaults where not found)
node-versions — JSON array of Node.js versions to test