Contributing to React Grab

June 24, 2026 · View on GitHub

Thanks for your interest in contributing to React Grab! This document provides guidelines and instructions for contributing.

Getting Started

Prerequisites

  • Node.js >= 18
  • pnpm >= 8

Setup

  1. Fork and clone the repository:
git clone https://github.com/YOUR_USERNAME/react-grab.git
cd react-grab
  1. Install dependencies using @antfu/ni:
ni
  1. Build all packages:
nr build
  1. Start development mode:
nr dev

Project Structure

apps/
├── e2e-app-vite/        # E2E test target app (Vite)
├── e2e-app-next/        # E2E test target app (Next, for Next-runtime paths)
├── openstory/           # Openstory gallery: UI states + ad-hoc targeting playground
├── web-extension/       # Browser extension
└── website/             # Documentation site (react-grab.com)

packages/
├── cli/                 # CLI implementation (@react-grab/cli)
├── grab/                # Bundled package (library + CLI, published as `grab`)
└── react-grab/          # Core library

Development Workflow

Running the Openstory Playground

Run openstory locally to exercise react-grab against realistic DOM fixtures (composite dashboard, freeze-demo, live-updates, and targeting edge cases):

pnpm --filter @react-grab/openstory dev

Opens at http://localhost:6006. The Playground/ section hosts ad-hoc scenarios (replaces the former apps/gym) with real init() running so you can hover/grab to verify behavior.

Running Tests

# Run CLI tests
pnpm --filter @react-grab/cli test

Linting & Formatting

nr lint        # Check for lint errors
nr lint:fix    # Fix lint errors
nr format      # Format code with oxfmt

Code Style

  • Use TypeScript interfaces over types
  • Use arrow functions over function declarations
  • Use kebab-case for file names
  • Use descriptive variable names - avoid shorthands or 1-2 character names
    • Example: innerElement instead of el
    • Example: didPositionChange instead of moved
  • Avoid type casting (as) unless absolutely necessary
  • Keep interfaces/types at the global scope
  • Remove unused code and follow DRY principles
  • Avoid comments unless absolutely necessary
    • If a hack is required, prefix with // HACK: reason for hack

Submitting Changes

Creating a Pull Request

  1. Create a new branch:
git checkout -b feat/your-feature-name
  1. Make your changes and commit with a descriptive message:
git commit -m "feat: add new feature"
  1. Push to your fork and open a pull request

Commit Convention

We use conventional commits:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • chore: - Maintenance tasks
  • refactor: - Code refactoring
  • test: - Test additions or changes

Adding a Changeset

For changes that affect published packages, add a changeset:

nr changeset

Follow the prompts to describe your changes. This helps maintain accurate changelogs.

Reporting Issues

Found a bug? Have a feature request? Open an issue with:

  • Clear description of the problem or request
  • Steps to reproduce (for bugs)
  • Expected vs actual behavior
  • Environment details (OS, browser, Node version)

Community

  • Join our Discord to discuss ideas and get help
  • Check existing issues before opening new ones

License

By contributing, you agree that your contributions will be licensed under the MIT License.