Contributing to Vest

Thank you for your interest in contributing to Vest! Whether you're fixing a bug, improving documentation, or proposing a new feature, your help is appreciated.

Vest is a monorepo managed by yarn and a custom tooling package called vx.

Prerequisites

• Node.js: Ensure you have a recent version of Node.js installed.
• Yarn: This project uses Yarn (v3+) for package management.

Getting Started

1. Fork and Clone the repository.
2. Install dependencies by running yarn in the root directory.
3. Build the workspace once to ensure internal package dependencies are linked correctly.

git clone [https://github.com/ealush/vest.git](https://github.com/ealush/vest.git)
cd vest
yarn
yarn build

ℹ️ yarn installs dependencies, but a first yarn build is required before working with packages that depend on built workspace artifacts.

Repository Structure

Vest is organized as a monorepo. Here is a high-level overview of the structure:

├── packages
│   ├── vest/                # Core Vest library
│   ├── n4s/                 # Enforce rules and assertions
│   ├── vest-utils/          # Shared internal utilities
│   ├── vestjs-runtime/      # The runtime engine powering Vest
│   ├── context/             # Context management package
│   └── anyone/              # Test matching utility
├── vx/                      # Internal tooling, scripts, and configuration
│   ├── commands/            # CLI commands (build, test, release)
│   └── config/              # Build tools configuration (Vitest, Rollup, etc.)
└── website/                 # Documentation website (Docusaurus)

Development Workflow

We use the vx CLI (located in the vx/ folder) to manage tasks across the monorepo. Most common tasks are aliased in the root package.json.

Building the Project

To build all packages in the monorepo:

yarn build

To build a specific package (e.g., only vest):

yarn vx build -p vest

Running Tests

We use Vitest for testing. You should run tests regularly to ensure your changes don't break existing functionality.

To run all tests:

yarn test

To run tests for a specific package:

yarn vx test vest

To run tests in watch mode:

yarn test --watch

Type Checking

Vest is written in TypeScript. Ensure your changes pass type checking before submitting a PR.

To typecheck the source code:

yarn vx typecheck

To typecheck the test files:

yarn vx typecheck-tests

Documentation

The documentation website is built with Docusaurus and located in the website/ directory.

To start the documentation server locally:

yarn website:start

To build the documentation for deployment:

yarn website:build

Note: This command also runs yarn build:llms to generate the LLM-friendly documentation files.

Making Changes

1. Create a Branch: Create a new branch for your feature or fix.
2. Make Changes: Modify the code in the relevant packages/ directory.
3. Add Tests:
   • Tests are located in __tests__ directories next to the source files.
   • Test files should be named *.test.ts.
   • If you are fixing a bug, please add a regression test.
4. Verify: Run yarn test and yarn vx typecheck to ensure everything is green.

Branching Strategy

We follow a standard flow for releases:

Branch Name	Role	Description
latest	Main	The active development branch. Submit all PRs here.
stable	Release	The current version published to npm.
release	CI	Used by CI to merge changes from latest to stable.