Contributing

Contributions to react-querybuilder and associated packages are more than welcome!

First contribution? Learn how to contribute to an open source project on GitHub (free course).

Project setup

This project requires Bun.

1. Fork and clone this repository.
2. Run bun install to install dependencies.
3. Build the packages with bun run build.
4. Create a branch for your PR with git checkout -b your-branch-name.

Testing changes

To serve a demo page locally, run bun start. This demo is HMR-enabled and can load the compatibility packages.

Your IDE should check for TypeScript and lint problems as you code, but to check manually run bun typecheck/bun lint.

Testing individual packages

Each package has its own start:*, build:*, and typecheck:* scripts, as well as test:* scripts with coverage checking bounded to the subject package (for granular coverage checks).

Package	Start script	Build script	Typecheck script	Test script
All packages	bun start	bun run build	bun typecheck	bun run test
react-querybuilder	bun start:rqb	bun build:rqb	bun typecheck:rqb	bun test:rqb
@react-querybuilder/antd	bun start:antd	bun build:antd	bun typecheck:antd	bun test:antd
@react-querybuilder/bootstrap	bun start:bootstrap	bun build:bootstrap	bun typecheck:bootstrap	bun test:bootstrap
@react-querybuilder/bulma	bun start:bulma	bun build:bulma	bun typecheck:bulma	bun test:bulma
@react-querybuilder/chakra	bun start:chakra	bun build:chakra	bun typecheck:chakra	bun test:chakra
@react-querybuilder/datetime	bun start:datetime	bun build:datetime	bun typecheck:datetime	bun test:datetime
@react-querybuilder/dnd	bun start:dnd	bun build:dnd	bun typecheck:dnd	bun test:dnd
@react-querybuilder/expr	bun start:expr	bun build:expr	bun typecheck:expr	bun test:expr
@react-querybuilder/fluent	bun start:fluent	bun build:fluent	bun typecheck:fluent	bun test:fluent
@react-querybuilder/mantine	bun start:mantine	bun build:mantine	bun typecheck:mantine	bun test:mantine
@react-querybuilder/material	bun start:material	bun build:material	bun typecheck:material	bun test:material
@react-querybuilder/native	bun start:native	bun build:native	bun typecheck:native	bun test:native
@react-querybuilder/prime	bun start:prime	bun build:prime	bun typecheck:prime	bun test:prime
@react-querybuilder/rules-engine	bun start:re	bun build:re	bun typecheck:re	bun test:re
@react-querybuilder/tremor	bun start:tremor	bun build:tremor	bun typecheck:tremor	bun test:tremor

To locally serve the documentation website, run bun web. (To skip regeneration of the TypeDoc API docs, run bun web:skiptypedoc.)

The website demo uses the static build of each package and therefore does not support HMR except for the website code itself. To update the website after making changes to one of the packages, run the package's build:* script. The change will be detected and the website will be reloaded automatically.

Proposing changes

Before submitting a pull request, please do the following:

• Discuss the change you wish to make by creating a new issue, creating a discussion topic, or chatting with us on Discord.
• Run bun check:all to make sure CI will run successfully.
• If adding a new feature, add corresponding tests (we maintain 100% coverage).
• If changing behavior or adding a feature, update the documentation. You may need to update both the current (aka "next") docs and the latest versioned docs.
• If your editor doesn't automatically format code with oxfmt when saving changes, run bun fmt.
• When addressing a bug, refer to an existing GitHub issue or provide a reproducible example. Any interactive demo or minimal repository is fine, including CodeSandbox or StackBlitz. You can use the CI base, the basic example (JS version), or any of the other examples as a starter template.

Generated files

Some files committed to this repository are generated by scripts and should not be modified by hand. If you modify any of the following source files, regenerate the dependent files before committing your changes.

CEL and SQL parsers

Run bun generate-parsers.

Source file	Generated file
cel.jison	celParser.js
sql.jison	sqlParser.js

Examples

Run bun generate-examples.

Sources:

• examples/_template - template example folder
• examples/exampleConfigs.ts - configurations for each example
• examples/generateExamples.ts - script to generate examples from template

Generated folders:

• examples/antd
• examples/basic-ts
• examples/basic
• examples/bootstrap
• examples/bulma
• examples/chakra
• examples/datetime
• examples/dnd
• examples/fluent
• examples/mantine
• examples/material

(The dependencies and Prettier configs of other examples will be updated, but they will not be completely regenerated like the ones listed above.)

Publishing

Preparation

1. Update CHANGELOG.md with changes per Keep a Changelog format.
2. Update documentation in website/docs (and the latest version in website/versioned_docs if not releasing a new major version).

Publish to npm

Publish from GitHub if possible to add provenance statements.

From GitHub

Note: The "Version" and "Publish" workflows are separate so that the "Publish" workflow runs against the commit created by the "Version" workflow. This ensures that the provenance statements point to the commit with the latest version tag and not its parent commit.

1. Manually run the Version workflow, choosing a version bump strategy and setting Run type to Live. It bumps the package versions with Lerna, pushes the tag, and creates a GitHub Release. (Use Dry run to preview without changing anything.)

2. Creating the release automatically triggers the Publish workflow — there is no need to run it by hand. It builds the packages and publishes them to npm, choosing the dist-tag from the release:

   • Prereleases (e.g. 8.0.0-next.1) publish under the next tag.
   • Stable releases marked "latest" publish under the latest tag.
   • Stable releases not marked "latest" are skipped.

   The Publish workflow can still be run manually if you need to re-publish or push a specific dist-tag.

Manual

1. Run npx lerna version [major|minor|patch|prerelease] (this automatically runs the version script in ./package.json before committing and tagging).
2. Run npx lerna publish from-git (add --dist-tag next if version was prerelease in previous step).
3. Publish a new release on GitHub. (When publishing from GitHub, the "Version" workflow does this automatically.)