Contributing

First off, thank you for considering contributing to zod-validation-error! Source code contributions, bug reports, and feature requests are most welcome.

To ensure the project remains stable, consistent, and easy to maintain, please follow the guidelines outlined below.

Development Environment

This project enforces specific Node versions and uses standard tooling for building, linting, and testing.

  • Node.js: The project relies on an .nvmrc file which specifies Node v24. Please ensure you are using this version (e.g., by running nvm use).
  • Package Manager: We exclusively use npm. Do not use yarn or pnpm to generate lockfiles, as package-lock.json is the source of truth.

Initial Setup

  1. Clone the repository.

  2. Use the correct Node version: 

    nvm use

  3. Install dependencies: 

    npm ci

Note: When you install dependencies, a prepare script will automatically run, setting up husky git hooks for pre-commit linting and commit message validation.

Architecture & Scripts

Because this library supports both Zod v3 and v4, the source code inside lib/ is explicitly split into v3/ and v4/ subdirectories. Ensure you are applying changes to the correct directory, or both if the bug/feature applies universally.

The package.json provides several utility scripts:

  • npm run build: Bundles the code using tsup. It generates both CommonJS and ESM artifacts and outputs them to the root /v3 and /v4 directories.
  • npm run test: Runs the test suite using vitest. We rely heavily on snapshot testing for exact string matching.
  • npm run typecheck: Runs tsc --noEmit to verify type integrity without outputting files.
  • npm run lint: Lints the lib/ directory using ESLint.
  • npm run format: Formats code globally using Prettier.

Submitting Changes

  1. Branching: Create a descriptive feature branch from main (e.g., feat/add-new-option or fix/handle-null-issue).
  2. Implementation: Implement your feature or bug fix.
  3. Testing: Write tests for your changes. If altering string outputs, update the vitest inline snapshots carefully. Ensure tests pass (npm run test) and typechecks succeed (npm run typecheck).
  4. Committing: Commit your changes using Conventional Commits. Husky and @commitlint will verify the format of your commit message automatically.
  5. Pull Request: Open a Pull Request against the main branch. Provide a clear description of the problem and your solution.

Release Process (Changesets)

This project uses Changesets for versioning, changelog generation, and NPM publishing.

If your Pull Request introduces user-facing changes, bug fixes, or new features:

  1. Run the changeset CLI: 

    npm run changeset

  2. Follow the prompts to select the bump type (major, minor, patch) and provide a summary of the changes.

  3. Commit the generated markdown file found in the .changeset/ folder alongside your code changes.

When your PR is merged, GitHub Actions will automatically aggregate the changesets and prepare a new Release PR.

We are hiring

Causaly is building the world's largest biomedical knowledge platform, using technologies such as TypeScript, React and Node.js. Find out more about our openings at https://jobs.ashbyhq.com/causaly.