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

Bun is required to set up this repository.

1. Fork and clone this repository.
2. Run yarn install to install dependencies.
3. Build the main package with bun run build:rqb to bootstrap type checking in the other packages.
4. Create a branch for your PR with git checkout -b your-branch-name

To serve a hot-reloading demo page locally, run bun start.

To run the documentation website, including a full demo with all options and compatibility components available, run bun run build && bun run web.

The website uses the static build of each package and therefore does not support hot reloading/HMR except for the website code itself. To update the website after making changes to one of the packages:

1. Stop the web server (Ctrl+C).
2. Run the corresponding build:* script for the package.
3. Start the web server again with bun run web. (To skip the TypeDoc API docs regeneration, run RQB_TYPEDOC_DONE=true bun run web instead.)

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 checkall 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 Prettier when saving changes, run bun pretty-print.
• 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.

Sources:

• packages/react-querybuilder/src/utils/parseCEL/cel.jison
• packages/react-querybuilder/src/utils/parseSQL/sql.jison

Generated files:

• packages/react-querybuilder/src/utils/parseCEL/celParser.js
• packages/react-querybuilder/src/utils/parseSQL/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/dnd
• examples/fluent
• examples/mantine
• examples/material

The dependency versions and Prettier configs of other examples will be updated, but they are not completely regenerated like the ones listed above.