reflex/CONTRIBUTING.md

Reflex Contributing Guidelines

For an extensive guide on the different ways to contribute to Reflex see our Contributing Guide on Notion.

Running a Local Build of Reflex

Here is a quick guide on how to run Reflex repo locally so you can start contributing to the project.

Prerequisites:

• Python >= 3.9
• Poetry version >= 1.4.0 and add it to your path (see Poetry Docs for more info).

1. Fork this repository: Fork this repository by clicking on the Fork button on the top right.

2. Clone Reflex and navigate into the repo:

git clone https://github.com/<YOUR-USERNAME>/reflex.git
cd reflex

3. Install your local Reflex build:

poetry install

4. Create an examples directory within the repository:

The examples directory is used for testing your local changes. It's included in .gitignore so your test apps won't be committed.

mkdir examples
cd examples

5. Init and Run:

Initialize a new Reflex app and run it in development mode:

poetry run reflex init  # Select option 0 for blank template
poetry run reflex run  # Add --frontend-only for faster frontend-only development

The development server will start and your app will be available at http://localhost:3000. The server will automatically reload when you make changes to your code.

Note: In development mode, the server may occasionally need to be restarted when making significant changes. You can use Ctrl+C to stop the server and run it again.

To clean up your examples directory and start fresh, you can use the provided cleanup script:

poetry run python scripts/clean_examples.py

🧪 Testing and QA

Any feature or significant change added should be accompanied with unit tests.

Within the 'test' directory of Reflex you can add to a test file already there or create a new test python file if it doesn't fit into the existing layout.

What to unit test?

• Any feature or significant change that has been added.
• Any edge cases or potential problem areas.
• Any interactions between different parts of the code.

✅ Making a PR

Once you solve a current issue or improvement to Reflex, you can make a PR, and we will review the changes.

Before submitting a pull request, ensure the following steps are taken and tests are passing:

1. Run unit tests and coverage checks:

poetry run pytest tests/units --cov --no-cov-on-fail --cov-report=

This will fail if code coverage is below 70%.

2. Run code quality checks:

poetry run ruff check .
poetry run pyright reflex tests
find reflex tests -name "*.py" -not -path reflex/reflex.py | xargs poetry run darglint

3. Format your code:

poetry run ruff format .

4. Install and run pre-commit hooks: Consider installing git pre-commit hooks so Ruff, Pyright, Darglint and make_pyi will run automatically before each commit. Note that pre-commit will only be installed when you use a Python version >= 3.9.

pre-commit install

You can also run the pre-commit checks manually:

pre-commit run --all-files

Type Stub Generation

When adding new components or modifying existing ones, you need to regenerate the type stub files (.pyi). This ensures proper type checking and IDE support.

To generate type stubs:

poetry run python scripts/make_pyi.py

After running this command:

1. Check git status to see if any .pyi files were modified
2. If changes were made, include them in your commit
3. If no changes were made, your types are up to date

Editing Templates

To edit the templates in Reflex you can do so in two ways:

1. Change to the basic blank template can be done in the reflex/.templates/apps/blank directory.

2. Other templates can be edited in their own repository. For example the sidebar template can be found in the reflex-sidebar repository.

Troubleshooting

Common issues and their solutions:

1. Development Server Issues

   • If the development server becomes unresponsive, stop it with Ctrl+C and restart
   • For frontend-only changes, use --frontend-only flag for faster development
   • Clear the examples directory using scripts/clean_examples.py if you encounter unexplained issues

2. Pre-commit Hook Failures

   • Run pre-commit run --all-files to identify specific issues
   • Ensure you've formatted code with ruff format . before committing
   • Check that type stubs are up to date with make_pyi.py

3. Type Checking Errors

   • Verify your changes haven't broken type definitions
   • Regenerate type stubs if you modified components
   • Check the error messages from pyright for specific type issues

Other Notes

For some pull requests when adding new components you will have to generate a pyi file for the new component. This is done by running the following command in the reflex directory.

(Please check in with the team before adding a new component to Reflex we are cautious about adding new components to Reflex's core.)

poetry run python scripts/make_pyi.py