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

# Contributing

> Set up the Isox repository, build packages, run tests, and improve the documentation.

Start with the [active roadmap](https://github.com/isox-sh/isox/blob/main/ROADMAP.md),
then use [Issues](https://github.com/isox-sh/isox/issues)
for individual work items or submit a PR.

## Development setup

Use Node.js 24 or 26+ for repository development. Vitest 5 excludes Node.js 25;
the CLI, core, and JS executor support Node.js 24+.
The repository uses pnpm workspaces, with packages under `packages/`. Install
[pnpm](https://pnpm.io/installation) using the version pinned in `package.json`,
then run `pnpm install` from the repository root. Commit changes to
`pnpm-lock.yaml` alongside dependency updates; use `pnpm install --frozen-lockfile`
in CI.

Builds use TypeScript 7 (`tsc`), installed as `@typescript/native`. The
`typescript` dependency aliases Microsoft's TypeScript 6 compatibility package
for ESLint's compiler API requirements. This follows the
[TypeScript 7 migration guidance](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6-0).

```bash theme={null}
pnpm install
pnpm bootstrap # Builds core, the executors, and CLI from a clean checkout
pnpm isox run-many --target=lint # Runs every project's lint target
pnpm isox run-many --target=lint --fix # Automatically fixes supported lint issues
pnpm isox run-many --target=test # Runs every project's test target
pnpm isox test e2e # Tests the plugin workspace helper
pnpm isox test js-e2e # Runs the TypeScript init/build end-to-end suite
```

## Tests

Package tests live in their owning package's `tests/` directory. Repository-wide
action, bootstrap, packaging, and release-workflow tests live in the root
`tests/` directory and run with `pnpm isox test workspace`. After bootstrapping,
`pnpm isox run-many --target=test` runs every project's test target, including the
package suites, workspace tooling tests, end-to-end suite, and website validation. Use
`pnpm isox test <project>` to run one suite, such as `pnpm isox test cli`.
Rebuild changed packages before running their tests.

The Vitest end-to-end suite lives in `e2e/` and runs with `pnpm isox test js-e2e`
after bootstrap. It uses the public [`@isox-sh/e2e`](https://isox.sh/docs/plugin-testing)
helper. Each test creates a workspace under `<root>/tmp/isox-e2e-*`, links the locally built
CLI/core/JS packages, and runs the CLI as a child process. It creates `isox.json`
using `isox init`, initializes a JS project with `--importPath`, builds it, checks
JavaScript and declaration outputs, executes the compiled code, and verifies a
rebuild after editing source. Relative and absolute project paths are covered.
The root `tmp/` directory is excluded from Git, lint, and Isox project discovery.
Fixtures are removed after each test, including failures. These tests require no
registry access and exercise local builds; they do not test published tarballs.

## Continuous integration

Pull requests and merge groups run the `pull-requests` workflow using `.github/actions/setup-isox` to set up
Node.js and pnpm, install dependencies, and build core, the CLI, and the
plugins. Call this action once after checkout in each job that needs Isox; subsequent steps in that job can
use `pnpm isox`. It defaults to Node.js 24, configurable through `node-version`.
The planning job creates an affected matrix for `test`, `build`, and `lint` through
our `actions/plan` action. Each target gets up to three workers, which bootstrap
their prerequisites and use `actions/run-many` to execute the exact planned
projects. The website's `test` target validates Mintlify alongside the package
and end-to-end tests. Projects' `plan.weight` values balance expensive commands.
Changes propagate through inferred and declared dependencies; workspace-wide
inputs select all projects with the requested targets. Unowned paths are ignored
unless matched by `affected.globalFiles`; `affected.ignoreFiles` excludes matching
files before selection.
A final required check preserves failures and accepts an empty plan. Pull requests
use their base SHA; other events use the nearest reachable Git tag, or all
projects if none exists. This workflow runs only for pull requests and merge groups.
A separate foundation matrix is temporarily disabled. When enabled, it runs core and CLI tests on
Linux, macOS, and Windows with Node.js 24 and 26. It also installs packed CLI/core
tarballs locally and globally in temporary directories, then runs the installed
binary from an external workspace. The aggregate check includes this matrix.
POSIX signal exit-code tests run on Linux/macOS; AbortSignal process-tree
cancellation is exercised on all three operating systems.
See [affected projects and CI](https://isox.sh/docs/affected-and-ci.md) for the public actions.

```yaml theme={null}
steps:
  - uses: actions/checkout@v7
  - uses: ./.github/actions/setup-isox
  - run: pnpm isox lint core
```

## Building and running packages

See [Building and running packages](https://isox.sh/docs/repository-builds.md#building-and-running-packages).

## Build outputs

See [Build outputs](https://isox.sh/docs/repository-builds.md#build-outputs).

## Plugin source layout

See [Plugin source layout](https://isox.sh/docs/repository-builds.md#plugin-source-layout).

## Trying the local CLI

See [Trying the local CLI](https://isox.sh/docs/repository-builds.md#trying-the-local-cli).

## Release this repository

See [Release this repository](https://isox.sh/docs/repository-releases.md#release-this-repository).

### npm trusted publishing setup

See [npm trusted publishing setup](https://isox.sh/docs/repository-releases.md#npm-trusted-publishing-setup).

## Documentation

The Mintlify site lives in `website/`, with navigation and branding in
`website/docs.json`, the homepage in `website/index.mdx`, and guides in `website/docs/`.
Preview it from the repository root:

```sh theme={null}
pnpm isox serve website
```

The preview normally runs at `http://localhost:3000`. Before submitting docs
changes, run `pnpm isox test website` to validate the build and internal links,
including heading anchors. These commands live in `website/project.json` and use
Mintlify through `pnpm dlx`, downloading its tooling on first use. Validation uses
a pinned CLI version.
Run `pnpm bootstrap` once after installing repository dependencies to prepare the
local Isox CLI.

Add new pages to `navigation.groups` in `website/docs.json` using paths such as
`docs/getting-started`. Include a `title` and
`description` in each page's YAML frontmatter, use extensionless site paths such
as `/docs/configuration` for internal links, and keep code examples consistent with
the source and schemas. Existing Markdown guides and new MDX pages are both
supported. Use GitHub URLs for source files outside `website/`. The website's
`test` target is selected automatically by the existing affected CI plan and runs
in the shared worker. Mintlify handles hosting from this directory.

See the [documentation README](https://github.com/isox-sh/isox/blob/main/website/README.md)
for direct CLI commands and Mintlify hosting setup.

## Pull requests

Create a branch, make a focused change, and run the affected build, lint, and test
targets. For documentation changes, run `pnpm isox test website`.

Use a Conventional Commit message, such as `fix(core): Handle missing configurations`.
Use the owning project name as the scope. The
[release plugin](https://isox.sh/docs/semver.md#how-versions-are-calculated) uses commit types and
breaking-change markers to determine versions.

Open a pull request describing the behavior changed and the checks you ran.
Include screenshots when a change affects the website's layout.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.