Contributing to Schema Benchmarks

Firstly, thank you for wanting to contribute! Ideas for improvements are always welcome, and pull requests are even better.

Getting set up

1. Fork the repository
2. Clone your fork
3. Use Node.js from .node-version and install the global Vite+ CLI, or use the project-local CLI after dependencies are installed.
4. Install dependencies with vp install. If you do not have global vp yet, bootstrap with pnpm install and then run Vite+ locally with pnpm exec vp.
5. Install Playwright with vp exec playwright install --with-deps chromium (needed for browser tests)
6. Build the schemas with vpr schemas:build
7. Run the website with vpr website:dev

Git Etiquette

Please avoid creating merge commits, instead rebase your changes on top of main and force push. This allows the history to remain linear, and changes to be traceable to a single commit (with git bisect, for example).

Keeping commit history simple is appreciated, but not necessarily required. For example, you can include many small commits during your workflow, and interactively rebase them into a few logical chunks before submitting for review.

Adding a new library

1. Add the library to the dependencies of the schemas package (vp add --filter schemas <library>; without global Vite+, use pnpm exec vp add --filter schemas <library>).
2. Create a new folder in schemas/libraries named after the library.
3. Add a index.ts file with the schema definition. Usually this should be a single function that creates and returns the schema - any other values and types can be exported as well. The schema should match as much of the validation specified as possible. Use existing library schema factories as a reference.
4. Add a benchmarks.ts file with the benchmark definitions. Use other benchmarks as a reference.
5. Create download benchmarks (usually just a single download/index.ts file, but can be a download/ folder with multiple files). This should match how the library would typically be used, matching the specified data type.
6. Add a types/index.ts file if the library infers TypeScript types from its schemas - export the schema plus Input/Output type aliases read from it, or a noInference string explaining why it can't. Add a types/fromType.ts file if the library can build a schema from an existing type - export a style ("annotation" or "builder") plus a schema built against the shared Product type. Use existing types/ folders as a reference.
7. Build the schema package with vpr schemas:build
8. Run the benchmarks with vpr bench:all to check all is working. You can commit the results during development, as they'll be overwritten when the PR is merged. Additionally, the GitHub action will run the benchmarks and upload its results as an artifact.
9. Open a PR with your changes.

Bug reports/feature requests

Please open an issue for any bugs you find, or features you would like to see. Opening a PR without confirmation it's desired means it may not be merged.

Make sure any changes meet our coding standards. We lint and format with Vite+, type check using TypeScript and test using Vitest for unit/integration tests and Playwright for end-to-end testing.

Prefer browser tests (*.browser.test.ts(x)) for anything needing DOM specific features (e.g. React components), and Node tests (*.node.test.ts) for everything else. Include type tests (*.test-d.ts) for anything with complex typing.

The following commands will help you check your changes before opening a PR. With only the project-local CLI, prefix built-in vp commands with pnpm exec.

• vp check - runs formatting, lint, and type checks
• vpr typecheck - runs TypeScript project checks
• vpr test - runs unit and integration tests
• vpr e2e - runs end-to-end tests
• vpr bench:all - runs all benchmark suites

PRs written by AI

Please do not submit PRs solely written by AI. There's nothing wrong with using an assistant to speed up the process, but you should (at the very least) always review and test the changes yourself before submitting. Opening "slop" PRs is inconsiderate and only adds to the workload of the maintainers.