Contributing to Valtio

Thank you for your interest in contributing! We welcome all contributions, from bug reports to new features. Here’s how you can help.

General Guidelines

Reporting Issues

If you believe you have found a bug, please start a discussion in the Bug Report category. Provide as much detail as possible, including a minimal reproduction link (e.g., StackBlitz, CodeSandbox).

Asking Questions

For usage questions, please start a discussion in the Q&A category.

Suggesting New Features

If you have an idea for a new feature, please start a discussion in the Ideas category to discuss the use cases and potential implementation.

Development Workflow

If you'd like to contribute code, please follow this workflow:

Fork the repository on GitHub.
Create a new branch from the main branch for your feature or fix.
Set up the development environment as described below.
Make your changes and add tests to cover them.
Run pnpm run fix:format to format the code.
Commit your changes following the Conventional Commits specification.
Push your branch and submit a Pull Request.

Setting up the Core Development Environment

Install dependencies:
```
pnpm install
```
Create failing tests for your bug fix or feature in the tests/ folder.
Implement your changes in the src/ directory.

Build the library. You can use watch mode for convenience:

# Single build
pnpm run build

# Watch for changes and rebuild
pnpm run build-watch

Run the tests and ensure they pass:
```
pnpm run test
```

Setting up the Documentation Website

Navigate to the website directory:
```
cd website
```
Install dependencies:
```
pnpm install
```
Start the development server:
```
pnpm run dev
```
Open http://localhost:3000 in your browser.
Make changes to the documentation files in the docs/ directory at the root of the repository.

Commit Message Guidelines

We follow the Conventional Commits specification. Each commit message must start with a type, which can be one of the following:

feat: A new feature.
fix: A bug fix.
refactor: A code change that neither fixes a bug nor adds a feature.
chore: Changes to the build process, configuration, or other auxiliary tools.
docs: Documentation-only changes.
test: Adding or correcting tests.

Example:

feat: add support for proxying Set objects

Example with scope:

fix(react): correct dependency tracking in useSnapshot

Pull Requests

Please keep your pull requests focused on a single change. After submitting, we will review it as soon as possible. Ensure you have checked the "Allow edits from maintainers" box on your PR to allow us to make small adjustments if needed.

Thank you for contributing! ❤️