Skip to main content
Start with the active roadmap, then use 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 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.

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 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 for the public actions.

Building and running packages

See Building and running packages.

Build outputs

See Build outputs.

Plugin source layout

See Plugin source layout.

Trying the local CLI

See Trying the local CLI.

Release this repository

See Release this repository.

npm trusted publishing setup

See 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:
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 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 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.