Skip to main content
xspec is not yet published to npm. You install it by cloning the source repository, building it locally, and making the xspec binary available on your system PATH. This page covers the prerequisites, the build steps, and the two ways to invoke the CLI once it is built.

​
Prerequisites

You need Node.js version 22 or later. xspec uses native TypeScript execution features and ESM patterns that require a modern Node.js runtime. Check your current version:
If the output is below v22.0.0, install a newer release from nodejs.org or through a version manager such as nvm or fnm before continuing.

​
Clone and build

Run the following commands to fetch the source, install dependencies, and compile the project:
npm ci installs the exact dependency tree recorded in package-lock.json. npm run build compiles the TypeScript source to the dist/ directory and produces the CLI entry point.

​
Put xspec on your PATH

You have two options for invoking xspec after building it. npm link creates a global symlink from your system’s node binaries directory to the xspec executable inside the repository. After running it, you can invoke xspec from any directory on your machine:
Verify it worked:
To remove the global link later, run npm unlink xspec from the repository directory.

​
Option 2 — Direct path invocation

If you prefer not to modify your global npm bin directory, invoke the compiled entry point directly using node:
Replace /path/to/xspec with the absolute path to the directory where you cloned the repository. You can add a shell alias to your .bashrc or .zshrc to avoid typing the full path every time:
Both invocation methods are functionally identical. The npm link approach is more convenient for day-to-day use; the direct path approach is useful in restricted environments where global npm operations are not permitted.

​
Project-level setup

xspec does not need to be listed as a dependency in your project’s package.json. The defineConfig helper you import in xspec.config.ts is resolved through the globally linked binary, not through your project’s node_modules. Create xspec.config.ts at the root of the workspace you want to instrument:
You can have multiple projects on the same machine all sharing a single globally linked xspec binary. Each project supplies its own xspec.config.ts to point xspec at the right spec files and source directories.

​
Keeping xspec up to date

Because you installed from a Git checkout, updating is a standard git pull followed by a rebuild:
If you used npm link, the existing symlink continues to point at the rebuilt output automatically — no need to re-run npm link.