> ## Documentation Index
> Fetch the complete documentation index at: https://xspec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing xspec: Build and Link from Source

> Install xspec on Node.js 22+: clone the repository, build from source, and put the CLI on your PATH using npm link or a direct path invocation.

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:

```sh theme={null}
node --version
```

If the output is below `v22.0.0`, install a newer release from [nodejs.org](https://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:

```sh theme={null}
git clone https://github.com/modularcloud/xspec.git
cd xspec
npm ci
npm run build
```

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

### Option 1 — `npm link` (recommended)

`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:

```sh theme={null}
npm link
```

Verify it worked:

```sh theme={null}
xspec --version
```

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`:

```sh theme={null}
node /path/to/xspec/dist/cli.js --version
```

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:

```sh theme={null}
alias xspec="node /path/to/xspec/dist/cli.js"
```

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

## 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:

```ts theme={null}
import { defineConfig } from "xspec"

export default defineConfig({
  specs: { product: ["specs/**/*.mdx"] },
  code: { app: ["src/**/*.ts"], tests: ["test/**/*.ts"] },
  markdown: { emit: true },
  coverage: [
    {
      name: "tested",
      target: "product",
      boundary: "tests",
      mode: "direct",
    },
  ],
})
```

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

## Keeping xspec up to date

Because you installed from a Git checkout, updating is a standard `git pull` followed by a rebuild:

```sh theme={null}
cd /path/to/xspec
git pull
npm ci
npm run build
```

If you used `npm link`, the existing symlink continues to point at the rebuilt output automatically — no need to re-run `npm link`.