slnodejs

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.

Preload Script

Overview

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