Contributing Guide

Learn how to contribute to Reatom - from reporting issues to creating packages and submitting pull requests.

We welcome contributions to Reatom! This guide will help you get started whether you’re fixing a bug, adding a feature, or creating a new package.

We prefer English language for all communication in issues, pull requests, and discussions.

Creating an Issue

Before creating an issue, please:

1. Search existing issues - Check if the problem is already reported
2. Provide context - Include relevant details about your environment and use case

Bug Reports

For bug reports, please include:

• Reproduction - Create a minimal reproduction using StackBlitz or CodeSandbox
• Expected behavior - What should happen
• Actual behavior - What actually happens
• Environment - Reatom version, framework, Node version, etc.

A good reproduction is half the solution! The easier it is to reproduce, the faster we can fix it.

Feature Requests

For feature requests, please include:

• Motivation - Why is this feature needed?
• Use cases - How would you use this feature?
• Examples - Show what the API might look like
• Alternatives - What alternatives have you considered?

Development Setup

1. Fork and clone the repository

   git clone https://github.com/YOUR_USERNAME/reatom.git
   cd reatom
   
2. Create a development branch from v1000

   git checkout -b my-feature v1000
   
3. Install dependencies

   We recommend Node 24.2.0 and pnpm 10.25.0:

   pnpm install
   

   This command installs dependencies for all packages but only builds @reatom/core.

4. Build the package you're editing

   pnpm --filter <PACKAGE_NAME> run build
   

   Replace <PACKAGE_NAME> with the relevant package like @reatom/react.

   Example:

   pnpm --filter @reatom/react run build
   

Making Changes

Coding Guidelines

• Bug fixes should include tests that reproduce the bug
• New features must be tested and documented
• Type annotations - Use // @ts-ignore for temporary suppressions, // @ts-expect-error for known false positives

Use // @ts-ignore if you’re uncertain about an error. Use // @ts-expect-error when you’re certain it’s a false positive and want TypeScript to verify it.

Testing

Run tests for your package:

pnpm --filter @reatom/react test

Run tests for all packages:

pnpm test

Code Style

• Follow the existing code style in the package
• Use meaningful variable and function names
• Add comments for complex logic
• Keep functions focused and small

Commit Messages

Reatom uses Conventional Commits specification:

<type>[optional scope]: <description>

Commit Types

• chore - Repository maintenance changes
• feat - New feature
• fix - Bug fix
• perf - Performance improvement
• refactor - Code change that neither fixes a bug nor adds a feature
• docs - Documentation only changes
• ci - CI configuration and script changes
• style - Cosmetic code changes
• test - Adding or correcting tests
• revert - Reverting previous commits

Scope

The scope is the package directory name. For example, /packages/react is scoped as react.

Description Rules

• Write in English
• Use imperative mood (like change instead of changed or changes)
• Don’t capitalize the first letter
• Don’t add period (.) at the end

Examples

# Good commits
git commit -m "docs: fix typo in react"
git commit -m "fix(core): add check for atoms with equal ids"
git commit -m "feat(react): add reatomComponent hook"
git commit -m "perf(core): optimize dependency tracking"

# Bad commits
git commit -m "Fixed bug"  # No type, capitalized, vague
git commit -m "feat: Added new feature."  # Capitalized, has period
git commit -m "docs(react): Changes the documentation"  # Not imperative

Submitting a Pull Request

1. Make your changes and commit them

   Follow the commit message guidelines.

2. Push your branch

   git push origin my-feature
   
3. Create a Pull Request

   Go to the Reatom repository and create a Pull Request to merge into v1000.

4. Link to the issue

   Use a closing keyword or provide a description:

   fix #74
   

   Or explain your changes with motivation if there’s no related issue.

5. Wait for review

   A team member will review your PR. Be responsive to feedback and make requested changes.

PR Guidelines

• Keep it focused - One PR should address one issue or feature
• Update documentation - Include docs for new features
• Add tests - Ensure new code is tested
• Follow code style - Match the existing patterns
• Be responsive - Address review feedback promptly

Small, focused PRs are easier to review and more likely to be merged quickly.

Creating a New Package

Reatom’s ecosystem includes adapters for Web APIs and popular npm modules. Creating a new package is similar to editing an existing one.

1. Run the package generator

   From the repository root:

   pnpm run package-generator
   

   Follow the interactive prompts to create your package structure.

2. Add dependencies

   Add dependencies to your package:

   pnpm --filter <PACKAGE_NAME> add <LIBRARY>
   

   Or update package.json manually and run:

   pnpm install
   
3. For adapter packages, add peer dependencies

   If creating an adapter (like @reatom/react for React):

   pnpm --filter <PACKAGE_NAME> add --save-peer <LIBRARY>
   

   Example:

   pnpm --filter @reatom/vue add --save-peer vue
   
4. Implement your package

   Follow the coding guidelines and add tests.

5. Document your package

   Create or update the README.md in your package directory with:

   • Installation instructions
   • Usage examples
   • API documentation

Package Structure

packages/my-package/
├── src/
│   ├── index.ts       # Main entry point
│   └── index.test.ts  # Tests
├── package.json
├── tsconfig.json
├── README.md
└── CHANGELOG.md

Development Workflow

Watch Mode

During development, run your package in watch mode:

pnpm --filter @reatom/react dev

This rebuilds automatically when you make changes.

Testing Changes

Test your changes in an example app:

1. Build your package
2. Link it to an example app using pnpm link
3. Or use the examples in the repo: examples/react-search

Running Examples

cd examples/react-search
pnpm install
pnpm dev

Documentation

Code Comments

Add JSDoc comments for public APIs:

/**
 * Extension that adds abort handling to actions and computed atoms.
 *
 * @example
 *   const fetchUser = action(async (id: number) => {
 *     const response = await wrap(fetch(`/api/user/${id}`))
 *     return response.json()
 *   }).extend(withAbort())
 *
 * @param strategy - The abort strategy to use:
 *   - `'last-in-win'` (default): Aborts previous concurrent calls
 *   - `'first-in-win'`: Ignores new calls while one is running
 *   - `'manual'`: No automatic abort, manual control only
 */
export let withAbort = (
  strategy: 'last-in-win' | 'first-in-win' | 'manual' = 'last-in-win',
): AssignerExt<AbortExt> => {
  // Implementation
}

README Files

Each package should have a README with:

• Installation - How to install the package
• Quick Start - Basic usage example
• API Reference - All exported functions/types
• Examples - Common use cases
• TypeScript - Type information if relevant

Community

Join the Reatom community:

• Twitter - Updates and announcements
• Discord - Real-time chat
• GitHub Discussions - Questions and ideas
• Telegram (RU) - Russian community
• YouTube (RU) - Video tutorials

Code of Conduct

• Be respectful - Treat everyone with respect
• Be constructive - Provide helpful feedback
• Be patient - Maintainers are volunteers
• Be collaborative - Work together towards solutions

Getting Help

If you need help contributing:

• Check existing issues and PRs
• Ask in Discord
• Start a GitHub Discussion

Recognition

All contributors are recognized in:

• Contributors graph
• Package release notes
• Project README

Thank you for contributing to Reatom! Your efforts help make state management better for everyone.

Additional Resources

• Architecture Overview - Understanding Reatom’s design
• API Reference - Complete API documentation
• Examples - Reference implementations
• Changelog - Recent changes