Running scripts using dependencies from npm

[jyoungbt]

What's the best way to use packages from npm in an event script?

[jhuckaby]

Yes, absolutely. The main thing to understand is that xyOps deliberately does not manage language-specific dependencies for Event Plugins. It is designed to be language-agnostic. At launch time, xyOps essentially starts the command configured in the Plugin, optionally supplies an inline script, sends the job data to the process over STDIN, and reads status messages and results from STDOUT. That is really the whole arrangement.

This is what allows an Event Plugin to be written in Node.js, Python, Go, Ruby, PHP, a shell language, or virtually anything else. The tradeoff is that installing the program and its dependencies is left to the Plugin author or the administrator of the target server.

So there is no special xyOps syntax for importing an npm package into an inline script. A statement such as:

const library = require('some-library');

will only work if Node.js can resolve some-library in the normal way. In particular, I would not rely on packages found inside xyOps' own node_modules directory. Those packages are implementation details of xyOps, can change between releases, and may not be visible to a job at all. Also bear in mind that each job receives its own temporary working directory, which becomes the current working directory of the Plugin process.

There are three good ways to handle this, depending on how you plan to distribute and operate the event.

Option 1: Package the event as an npm CLI and launch it with npx

For a portable Plugin, this is generally the cleanest approach. It is also how Node.js Plugins in the xyOps Marketplace are designed to work.

Instead of putting the full program in xyOps' inline Script field, create a small npm package with a command-line entry point. Declare all of the libraries you use in the package's dependencies, and expose your entry point through the bin field in package.json. For example:

{
	"name": "@myorg/xyops-report-event",
	"version": "1.0.0",
	"bin": {
		"xyops-report-event": "bin/event.js"
	},
	"dependencies": {
		"some-library": "1.2.3"
	}
}

Then your bin/event.js could begin like this:

#!/usr/bin/env node

const library = require('some-library');

// Read the xyOps job document from STDIN.
const chunks = [];
process.stdin.setEncoding('utf8');

process.stdin.on('data', function(chunk) {
	chunks.push(chunk);
});

process.stdin.on('end', async function() {
	try {
		const job = JSON.parse( chunks.join('') );
		
		// Do the real work here, using job.params, job.input, and so on.
		await library.doSomething(job.params);
		
		// This must be a compact, single-line JSON record on STDOUT.
		console.log( JSON.stringify({ xy: 1, code: 0 }) );
	}
	catch (err) {
		console.log( JSON.stringify({
			xy: 1,
			code: 1,
			description: err.message
		}) );
		process.exitCode = 1;
	}
});

Make the entry point executable, publish the package, and use a pinned version in the Plugin's Launch Command:

npx -y @myorg/xyops-report-event@1.0.0

npx obtains that package and its declared dependencies, places its command on the executable path, and launches it. STDIN, STDOUT, STDERR, command-line arguments, environment variables, and the process exit code continue to work normally, so this fits the xyOps Plugin protocol nicely.

The package does not necessarily have to be published in the public npm registry. It can live in a GitHub repository with a release tag:

npx -y github:myorg/xyops-report-event#v1.0.0

That form also requires the git CLI to be on the target server. A private npm package or private Git repository can work too, but every server eligible to run the event will need suitable non-interactive credentials.

I strongly recommend pinning a version or commit instead of launching latest. That makes a scheduled event reproducible and prevents an upstream release from silently changing the code used by the next job. Publishing a new version also gives you a clear upgrade and rollback path.

This same pattern is not specific to JavaScript. The Marketplace supports the general idea of a self-downloading launch command, with equivalents such as uvx for Python, go run for Go, and docker run for a containerized tool. See the Plugin Marketplace documentation for examples, including the important docker run --rm -i form that keeps STDIN connected.

The operational considerations for npx are:

• Node.js and npx must be installed on every possible target server.
• The target servers need network access to the package source, at least when the package is not already cached.
• Private sources require credentials that work without an interactive prompt.
• The job's operating-system user needs permission to use the npm cache.
• The first launch may be slower while npm downloads the package.

The official xyOps Docker image includes the common Marketplace prerequisites, but for other installations it is up to the administrator to install them.

Option 2: Install the project on each target server ahead of time

For an internal event, especially one that runs frequently or on servers without outbound network access, it may be better to deploy the Node.js application separately. For example, your deployment process could maintain this directory on every eligible target:

/opt/my-company/xyops-events/report-event/
├── package.json
├── package-lock.json
├── node_modules/
└── event.js

During deployment, install its production dependencies once:

cd /opt/my-company/xyops-events/report-event
npm ci --omit=dev

Then configure the xyOps Plugin command to invoke the entry point by absolute path:

node /opt/my-company/xyops-events/report-event/event.js

Node resolves ordinary require() calls relative to the JavaScript file and its parent directories, so the per-job xyOps working directory does not prevent /opt/my-company/xyops-events/report-event/event.js from finding the adjacent node_modules directory.

This approach gives fast, predictable job startup and does not require an npm download during every run. Its cost is operational: you must deploy the same version to every server that may be selected for the event, keep permissions correct for the job user, and coordinate upgrades yourself.

I would generally avoid running npm install directly inside every event execution. It can be useful for a quick experiment, but it adds latency, requires network access, makes failures dependent on the registry, and can produce different results over time if versions are not completely controlled. It can also create races or permission problems if multiple jobs share an installation directory.

Option 3: Bundle the script and its dependencies into one JavaScript file

Bundling is a very good fit when you want to keep using xyOps' inline Script field. A bundler follows your require() and import statements at build time, incorporates the reachable JavaScript from your dependencies, and emits one standalone JavaScript file. You build that file on your development machine or in CI, then paste or import the generated file into the Plugin's Script field and keep the Launch Command set to:

node

For example, using webpack, a minimal project could have this configuration:

// webpack.config.js
const Path = require('path');

module.exports = {
	mode: 'production',
	target: 'node',
	entry: './src/event.js',
	output: {
		path: Path.resolve(__dirname, 'dist'),
		filename: 'event.js'
	},
	devtool: false,
	optimization: {
		// Keeping the output readable makes job stack traces easier to diagnose.
		minimize: false
	}
};

Install webpack as a development dependency and build the artifact:

npm install --save-dev webpack webpack-cli
npx webpack --config webpack.config.js

Your source file, src/event.js, remains normal Node.js code and may import packages listed in dependencies. The generated dist/event.js is the file you provide to xyOps. The development dependencies are only needed where you build the bundle, not on the xyOps target servers.

Parcel, Rollup, and esbuild can all accomplish the same thing. For example, the core esbuild command is particularly compact:

npx esbuild src/event.js --bundle --platform=node --format=cjs --target=node20 --outfile=dist/event.js

Choose a --target compatible with the Node.js version installed on your xyOps targets. Whichever bundler you choose, build the artifact before deployment and commit or release it just as you would any other compiled artifact. Do not ask the production event to perform the bundle step on every run.

Bundling works very well for dependencies written entirely in JavaScript, but it is not universal. Check the generated file carefully if a package:

• Loads modules dynamically using a computed require() path.
• Depends on native .node addons compiled for a particular operating system or CPU.
• Expects templates, certificates, browser binaries, WASM files, or other assets beside the package.
• Locates resources using __dirname or package directory structure.
• Starts helper executables that are normally shipped with the package.

Those dependencies may need special bundler configuration, may need additional files deployed alongside the bundle, or may be better suited to the npx, pre-installation, or Docker approach. Also test the final bundled file itself, not only the original source. At minimum, pipe a representative job document into it and verify that it produces the final one-line xyOps result record.

Summary

So, my recommendation would be:

1. For a reusable or shareable Node.js Plugin, package it as a CLI and use npx with an explicit version.
2. For a private, frequently executed tool where startup speed and offline reliability matter, deploy it to a stable directory and invoke it by absolute path.
3. For a modest inline script with JavaScript-only dependencies, bundle it into one file during development and paste the artifact into xyOps.
4. For native dependencies or a complex runtime with supporting files, consider a container image and use docker run --rm -i.

In every case, the program ultimately follows the same small xyOps contract: read the job JSON from STDIN, write ordinary log text as needed, and finish by writing a compact JSON line such as { "xy": 1, "code": 0 } to STDOUT. The Plugin documentation covers progress updates, status messages, job input files, environment variables, and richer result data.

So the short answer is that xyOps does not install npm dependencies on behalf of an Event Plugin, by design. It executes the software you specify. npx is usually the most convenient way to make that software self-installing, while a single-file bundle is an excellent option when you specifically want the code to remain inline.

Hope this helps!