{"owner":"reflex-dev","repo":"reflex","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# Coding Agent Guidelines\n\nReflex: Python web **framework** compiling to React. Monorepo using uv workspace — main package in `reflex/`, sub-packages in `packages/`, docs site in `docs/`.\n\n## Workflow\n\n1. **Plan first.** Ensure the task is well-defined before writing code. If unclear, work with the user to flesh out details. No sloppy/spaghetti code — every feature/fix must be clearly understood first.\n2. **Bugfixes:** write a regression test that fails before writing the fix.\n3. **After implementation:** act as an adversarial reviewer. Scrutinize the diff against all rules in this file. Call out numbered issues, then wait for the user to request followup changes.\n\n## Commands\n\nUse `uv` for everything — never bare `python` or `python3`.\n\n```\nuv sync                                                          # install deps\nuv run pytest tests/units --cov --no-cov-on-fail --cov-report=   # unit tests (>=72% coverage)\nuv run pytest tests/integration                                  # integration tests (slow)\nuv run ruff check .                                              # lint\nuv run ruff format .                                             # format\nuv run pyright reflex tests                                      # type check\nuv run python scripts/check_min_deps.py                          # validate each package's declared minimum dep versions (pyright in isolated min-version envs; *.dev pins resolve from the local workspace, all other deps from PyPI)\nuv run python scripts/check_min_deps.py --check-dev-pins [pkg]    # publish gate: fail if pkg (default: all) declares an unpublishable *.dev dependency pin\nuv run python scripts/make_pyi.py                                # regenerate .pyi stubs\nuv run pre-commit run --all-files                                # all pre-commit hooks\n```\n\n## Layout\n\n```\nreflex/                 # main framework package (app, state, compiler, components, utils, istate)\npackages/               # workspace sub-packages (reflex-base, reflex-components-*, reflex-docgen, reflex-components-internal)\ntests/units/            # unit tests, mirrors source tree\ntests/integration/      # Selenium integration tests (run in dev+prod modes)\n  tests_playwright/     # Playwright integration tests (preferred for new tests)\ntests/benchmarks/       # performance benchmarks\ndocs/                   # documentation site (separate workspace member)\n```\n\n## Code style\n\n- Concise, robust code. Reflex is a framework used in many ways — handle edge cases without unnecessary complexity.\n- Performance matters. Avoid suboptimal patterns (e.g. iterating a dict to find a value by identity). Suggest restructuring data/APIs if an operation can't be done efficiently.\n- Don't add expensive workarounds (e.g. `isinstance` checks) to paper over type-level problems — fix the root cause instead.\n- Don't repeat validation or be over-defensive; trust data that was already validated upstream.\n- Think in CPU cycles: avoid unnecessary data copies, redundant allocations, and gratuitous indirection.\n- Extract duplicated code into parameterized helpers.\n- No block comments (`# --- Section ---`, `# ============`). Plain inline comments only.\n- Be cautious creating new public APIs — they must be documented and supported long-term.\n- Google-style docstrings on all functions: one-line summary, optional detail sentence(s), then Args/Returns (or Yields)/Raises.\n- Prefer imports at the top of the module in isort order. Only use inline imports when necessary to avoid circular dependencies.\n\n## Testing\n\n- Write comprehensive tests for new/changed features; extend existing test files where possible.\n- Test functions at module level, not wrapped in classes.\n- **Unit tests:** `tests/units/`, run with `uv run pytest tests/units`.\n  - unit tests should primarily cover a single module, and should be named accordingly, including subdirectories (e.g. `tests/units/istate/test_manager.py` for `reflex/istate/manager.py`). For subpackages, also include the corresponding path below `src/` (e.g. `tests/units/reflex_base/event/test_context.py` for `packages/reflex-base/src/reflex_base/event/context.py`).\n- **Integration tests:** prefer Playwright (`tests/integration/tests_playwright/`). Integration tests are slow — extend existing test apps rather than creating new ones for trivial functionality. Multiple test cases sharing one app is fine.\n\n### Integration test patterns\n\nApps as factory functions, run via `AppHarness`:\n\n```python\ndef SomeApp():\n    import reflex as rx\n\n    class State(rx.State):\n        value: str = \"\"\n\n    def index():\n        return rx.box(rx.text(State.value))\n\n    app = rx.App()\n    app.add_page(index)\n\n\n@pytest.fixture(scope=\"module\")\ndef some_app(tmp_path_factory) -> Generator[AppHarness, None, None]:\n    with AppHarness.create(\n        root=tmp_path_factory.mktemp(\"some_app\"), app_source=SomeApp\n    ) as harness:\n        yield harness\n```\n\nPlaywright tests use the `page` fixture and navigate to `harness.frontend_url`. Utilities in `tests/integration/utils.py` (polling, event ordering, storage).\n\n## .pyi stubs\n\nWhen adding/modifying components: `uv run python scripts/make_pyi.py`. Commit `pyi_hashes.json` (not `.pyi` files). If the diff removes many modules, run `uv sync`, delete `.pyi_generator_last_run`, and regenerate.\n\n## Breaking changes and deprecation\n\nReflex has downstream users — don't break them. Provide a fallback path during deprecation.\n\n**Runtime warning** via `console.deprecate()`:\n```python\nfrom reflex_base.utils import console\n\nconsole.deprecate(\n    feature_name=\"OldFeature\",\n    reason=\"Use NewFeature instead.\",\n    deprecation_version=\"<next dot version of latest git tag>\",\n    removal_version=\"1.0\",\n)\n```\nSet `deprecation_version` to the next dot version of the latest tag (`git fetch --tags` if needed, e.g. tag `v0.7.3` -> `\"0.7.4\"`). Set `removal_version` to next major unless directed otherwise.\n\n**Type-level deprecation** for deprecated methods/overloads using `typing_extensions.deprecated`, always inside a `TYPE_CHECKING` guard to avoid double warnings:\n```python\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n    from typing_extensions import deprecated\n\n    @deprecated(\"Use new_method() instead\")\n    def old_method(self) -> str: ...\n```\n\n## Checklist\n\nBefore submitting:\n1. Tests pass with adequate coverage\n2. `uv run ruff check .` and `uv run ruff format .` clean\n3. `uv run pyright reflex tests` passes\n4. `pyi_hashes.json` updated if components changed\n5. Documentation updated if user-facing behavior changed\n6. Deprecation warnings added if breaking changes introduced\n"}}