Skip to content
IC Reactor

Contributing

Thanks for your interest in contributing to IC Reactor! This guide covers the development workflow, coding standards, and how to submit your changes.

Quickstart

Section titled “Quickstart”

  1. Fork the repository and clone it:

    Terminal window
    git clone https://github.com/<your-username>/ic-reactor.git
    cd ic-reactor
    git remote add upstream https://github.com/B3Pay/ic-reactor.git

  2. Install dependencies:

    Terminal window
    pnpm install

  3. Build and test:

    Terminal window
    pnpm build
    pnpm test
    pnpm typecheck            # runs each packages/* typecheck script, tests included
    pnpm format:check
    pnpm check:ai-context
    pnpm check:snippets       # compiles the snippets of the AI guides and READMEs (after pnpm build)
    pnpm check:snippets:docs  # also the docs pages' snippets (needs the examples installed)

Formatting

Section titled “Formatting”

We use Prettier for formatting. Format locally with:

Terminal window
pnpm format

You can check formatting without modifying files:

Terminal window
pnpm format:check

Husky + lint-staged will format staged files automatically on commit.

Running Tests

Section titled “Running Tests”
Terminal window
# Unit tests
pnpm test


# End-to-end tests
pnpm test-e2e

If you are adding a feature, include tests and documentation where applicable. A test that needs a canister runs a real Reactor against the fake replica from @ic-reactor/core/testing (see Testing) rather than a hand-built object cast to Reactor, which has to re-implement query keys and error unwrapping and can drift from them.

Before Opening a PR

Section titled “Before Opening a PR”

CI also builds and type-checks every example app. Run pnpm typecheck:examples and pnpm build:examples locally if you touched anything under packages/ or examples/ — the examples are now built in CI, not merely type-checked, so a change that compiles against the workspace can still fail there.

A PR that touches docs/, packages/ or examples/ also runs the docs gate. CI lints the MDX, checks the example pages against examples/, builds this site and crawls it for broken links. The API reference is generated from package sources, so a source change can break the docs build too. Run the same checks locally:

Terminal window
pnpm --dir docs run lint:mdx
pnpm docs:check-examples   # sandbox links, file= targets and index cards
pnpm docs:build
pnpm docs:check-links   # crawls docs/dist, so run it after docs:build

If pnpm docs:build fails with Cannot find native binding, your install is stale from a dependency bump. Run pnpm install first, and if the error remains, pnpm install --force, because a plain install does not recreate the link that was lost. The troubleshooting note in CONTRIBUTING.md has the details.

Commits and Pull Requests

Section titled “Commits and Pull Requests”
  • Use clear, descriptive commit messages.
  • Prefer small, focused PRs.
  • Include tests where applicable.
  • Add or update documentation for public API changes.

AI-Assisted Contributions

Section titled “AI-Assisted Contributions”

AI-assisted contributions are welcome, but contributors are responsible for correctness before opening a PR.

  • Prefer existing IC Reactor patterns over introducing new abstractions.
  • For React integrations, prefer createActorHooks(...) or query/mutation factories (createQuery, createMutation, etc.).
  • Validate generated or AI-written code with tests and examples whenever possible.
  • Update docs and examples when public API usage changes.