Notable changes to ReactPy, newest first. Read the Unreleased section for what has landed since the last release, and the versioned sections for what shipped in each.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Note
Entries use the Keep a Changelog categories — Added, Changed, Deprecated, Removed, Fixed, Security — and versions follow Semantic Versioning. Pre-release versions carry a bN suffix, and behaviour can shift between betas without a major-version bump, so pin an exact version if you depend on one.
The authoritative list of shipped artefacts, with downloads and commit ranges, is GitHub Releases; the published packages are on PyPI. This page is the curated narrative of what changed, not the release log.
ReactPy takes pull requests from anyone, and most of what gets rejected is not wrong — it is unreviewable. A short branch, a focused diff, and the checks run before you open the pull request is what makes a change easy to say yes to. This page covers the mechanics: where the code lives, how to branch, and what CI will run against you.
You will learn
This documentation site and the library are separate bodies of work, and the commands that work in one do nothing in the other.
| Change | Repository / branch |
|---|---|
| Library code, hooks, layout, backends | reactive-python/reactpy → main |
JavaScript client (src/js/) | Same, main |
These documentation pages (docs/src/, docs/examples/) | reactive-python/reactpy → new-docs |
The new-docs branch holds only docs/ — the package and tests/ were removed from it. A test command run there reports success without running anything.
Pitfall
Confirm the branch before you start typing, not after. A library fix committed onto the docs branch looks fine locally and becomes a rebase chore later. git branch --show-current costs nothing and settles it.
Look for an open discussion or issue that matches what you intend to do. If one exists, comment there before writing code — a maintainer who has already thought about the problem will usually redirect you in one sentence, and that sentence is cheaper than a rejected pull request. If none exists, open a discussion first.
For anything larger than a bug fix, expect the answer to be "show me the design first". A draft pull request is the right medium for that: it runs CI, it is reviewable, and it says plainly that it is not ready to merge.
Fork the repository if you do not have write access, then branch from an up-to-date main:
1 | |
Name the branch for the change, not for you. fix-key-not-resetting-on-provider beats patch-1 and survives a month of review.
Match the convention of the branch you are landing on; they differ. Documentation commits on new-docs use Conventional Commits subjects — docs(learn): author X for ReactPy v2, docs(examples): fix include-marker cropping. Library history on main instead uses plain sentence subjects, because pull requests there are squash-merged and the summary is written at merge time — Fix PyScript root component not hiding after render error (#1347). In both cases the subject is the thing a reader scans to find the functional change in a long history, so write it for that reader.
One commit per logical change. If a commit only makes sense next to a later one, squash them before you push rather than asking the reviewer to mentally reassemble them.
The repository ships a pull request template; fill it in rather than deleting it.
By submitting, you agree that your contribution complies with the project's open source licenses.
Tests are not optional for a behaviour change. A bug fix should arrive with the test that reproduces the bug — write it first and watch it fail, then fix and watch it pass. A test that has never failed proves nothing about the thing it claims to protect.
The changelog rule is narrower than it looks: CHANGELOG.md gets an entry under Unreleased for user-facing changes only. Test-only, docs-only, and CI-only changes get none. Adding one for those is a small annoyance to the person doing the release, who then has to notice and delete it. See Changelog.
Understanding the gate is cheaper than discovering it in a failed run.
1 +2 +3 +4 +5 +6 | |
Run the equivalents locally before you push — the same commands, not approximations of them:
1 +2 +3 | |
CI retries flaky tests, which is a mercy and a trap: a genuinely racy test can go green on the third attempt and stay in the tree. If a test fails once and passes on retry, that is a bug in the test — usually a bare asyncio.sleep where poll(...) belongs.
A pull request into new-docs gets no CI at all, for two independent reasons. GitHub runs pull_request workflows from the base branch, and the only workflow that exists on new-docs is the docs deploy, which triggers on push — so nothing matches a PR. And the test-documentation job in check.yml on main is disabled outright with if: 0 (temporarily, while the Sphinx-to-MkDocs transition finishes), so even a PR targeting main runs lint and Python tests but never builds the docs. A docs change is verified by you or by nobody — run the mkdocs build --strict set from Running Tests and read its exit code. The one thing that does run: pushing to new-docs deploys with mkdocs gh-deploy --force, no --strict — expect a change to be live the moment it merges, whether or not it builds cleanly.
Respond to every comment, including the ones you are not acting on. "Not taking this because X" is a complete reply and saves a round trip; silence invites a re-review of something you already considered.
Push fixes as new commits rather than force-pushing over the reviewed range. Reviewers read the delta between your last push and this one; a force-push that rewrites history they already read makes them re-read the whole diff, and they will notice when they skip it.
If a review asks for something you believe is wrong, say so once, with evidence, and then defer if the maintainer still wants it. Review is a conversation with an asymmetry: they own the file after you leave.
Note
When a review is posted by an automated tool, the maintainers still own the decision. Do not treat "the bot did not complain" as approval, and do not treat a bot comment as a demand — respond on the merits, the same as any other comment.
Documentation changes on new-docs deploy to the live site on push, so a mistake there is visible immediately rather than at the next release. That is a reason to run the build check locally, not a reason to be nervous about contributing.
Library changes reach users only through a release, which the maintainers cut. Do not ask when your fix will ship, and do not close a closed-issue loop by demanding a release — the tag is a maintainer's call.
main; documentation work on new-docs. Check the branch first.ReactPy is built in the open. Questions, bug reports, and ideas all have a home, and the same places are where you get help when an example on this site stops behaving. This page is a map of those places and what belongs in each.
You will learn
The ReactPy repository on GitHub is the centre of gravity. Everything else points back to it.
| You want to | Go to |
|---|---|
| Ask how to do something | Discussions → Question |
| Report something broken | Discussions → Problem |
| Propose a feature | Discussions → Ideas |
| Show off what you built | Discussions → Share |
| Publish a package you made | Discussions → Downloadable Packages |
| Track a confirmed defect | Issues |
| Chat in real time | Discord |
Discussions is the front door, not Issues. The repository's issue-template configuration disables blank issues and points new visitors at Discussions instead, so a question opened as an issue gets redirected rather than answered. Open an issue once a defect is confirmed and someone has reproduced it — the discussion that came first usually becomes the link inside it.
There is a Discord server for ReactPy, announced in Discussion #997 and linked from the repository README. It is the fastest place to get an answer to a "why is this doing that" question, and quiet enough that nobody minds a beginner question.
Note
An invite URL is mutable third-party state. If discord.gg/uNb5P4hA9X ever stops resolving, read the current invite from the README badge or from Discussion #997 — those two are maintained together — rather than trusting a search result, which may point at a cloned server.
Discord is good for conversation and bad for searchability. A solution that exists only in chat is invisible to the next person with the same problem. If a chat thread solves something real, post it to Discussions afterwards; if it exposes an error on this site, that is a documentation contribution.
Participation is governed by the Contributor Covenant code of conduct, which lives at the repository root. It applies everywhere the project is discussed — Discussions, Issues, pull requests, Discord, and any other space where ReactPy maintainers show up.
The practical version: assume good faith, criticise code rather than people, and accept that "this is obvious" is rarely true of the person asking. The enforcement section of the document names the contact route for escalating a problem.
ReactPy's core deliberately stays small, so much of what you might expect to find here lives in sibling repositories. Each has its own issue tracker — do not file a Django problem against the core repo.
Community-built packages are announced in Discussions → Downloadable Packages. Those are third-party: they are not reviewed before being posted, they are not pinned against a ReactPy release, and an unanswered thread there says nothing about the library. See Tools, Libraries, and Packages for how to evaluate one.
ReactPy is maintained by volunteers on their own time. GitHub Sponsors is the route the project uses, matching the maintainers listed in the repository's funding configuration.
Sponsoring buys maintenance, not priority. It does not queue your issue and does not entitle anyone to a feature. If you need a specific behaviour on a deadline, the reliable path is to write it — or fund someone to write it — and open a pull request.
Most unanswered questions are unanswered because they cannot be reproduced. Four things turn a vague report into one someone can act on:
pip show reactpy and paste it. Behaviour shifts between pre-releases, so 2.0.0b13 and 2.0.0 are different answers.Pitfall
"It doesn't work" with no traceback is not a question anyone can answer, and the error you think is irrelevant often is not the relevant one. Include the full traceback and the server-side console output. ReactPy logs failing event handlers and effects on the server while the browser stays silent, so a UI that merely stops responding usually has a server line that explains it — see Creating VDOM Event Handlers.
Most of these pages were ported from the ReactJS documentation, and the port is the whole job: a page is done when every claim in it is true of ReactPy and every snippet in it runs. That is a lower bound on effort and an upper bound on trustworthiness, which is the trade this project made deliberately. This page is how to do the work and how to know it is finished.
You will learn
🚧 marker worksdocs/examples/ instead of inside the markdown1 +2 +3 +4 +5 +6 +7 +8 | |
Page files are kebab-case.md; example directories are the same name with underscores (learn/scaling-up-with-reducer-and-context.md → examples/scaling_up_with_reducer_and_context/). A new page must be added to nav: in mkdocs.yml, but the build will not tell you when you forget: a page missing from nav: is still built and served, and mkdocs build --strict exits 0. The only trace is an INFO line listing the unlisted pages. Read it: every page currently on that list carries a Planned / Undeveloped banner in its body and can be ignored, which is exactly how a page you did mean to publish would hide among them. Adding the entry is what puts the page in the site's navigation, which is the actual reason to do it.
A page is authored, not migrated. Concretely:
className= outside an attribute dict, no hook that does not exist.🚧 badge is gone from its nav: entry.Note
🚧 in the navigation means "this is still a ReactJS page with the React names swapped". It is a promise to the reader that the content is unreliable, so removing it is the meaningful act — the badge should never come off before the checks above are true. 🚫 means the page is blocked on something outside this project and is parked; commented-out nav: entries work the same way.
The pages derive from react.dev. Editing means deleting what is false as much as replacing what is named differently, and the failure mode is a page that reads fluently and is wrong.
Things that do not survive a rename:
use_id, use_transition, use_deferred_value, use_layout_effect, use_insertion_effect, use_imperative_handle, or use_sync_external_store. Some of the react.dev pages for them are parked as 🚫; use_id has no page at all, because the upstream issue was closed as not planned. Never port a page that depends on one as if it worked.my_button, not MyButton. React's capital-letter rule does not apply, because ReactPy distinguishes a component from a tag by the call, not the case. Attribute keys stay camelCase (className, onClick), because those pass through to the DOM untouched.memo. Neither exists. React's double-invoke warnings and its "skip re-rendering unchanged children" optimisation have no ReactPy equivalent, so port those sections as a warning that ReactPy will not catch the problem for you.&& rendering. {cond && <X/>} has no safe Python spelling — False and X leaks the word False into the page, since only None renders nothing. Rewrite such examples rather than transliterating them.use_effect, use_memo, and use_callback infer dependencies from the closure when you omit the argument. React's "omit the array to run after every render" is simply wrong here.Pitfall
A page can pass every automated check while teaching something false, because the checks are syntactic. The ReactJS FIXME that sat in thinking-in-react.md claiming checked was not delivered was wrong — a checkbox onChange handler reads it back as await event.target.checked. The only defence is running the example against a real layout and reading what the client actually answered.
Every authored page opens the same way: an ## Overview heading, an intro paragraph in a <p class="intro"> block, then a You will learn summary.
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 +10 +11 +12 | |
Then the body as ## and ### sections, closing with ## Recap (bulleted, factual) and ## Related (links with a dash and a phrase explaining each).
Admonitions come from the Material theme plus assets/css/admonition.css. The set in use:
| Admonition | For |
|---|---|
!!! summary "You will learn" | Objectives, once, after the intro |
!!! abstract "Note" | Clarification that is not a warning |
!!! warning "Pitfall" | A mistake the reader is likely to make |
!!! info "Deep Dive" | Deeper mechanics a reader can skip |
!!! example "Terminal" | A shell session |
ReactJS's <Pitfall>, <DeepDive>, <Recap>, <Challenges>, <Solution>, and <Hint> JSX tags have no MkDocs equivalent. Convert them to admonitions or headings; never copy them through, since an unrecognised tag renders as literal text.
Links are relative .md paths from the current file — ../reference/use-state.md, ./extracting-state-logic-into-a-reducer.md#the-rule-reactpy-adds — not site-absolute paths like /learn/..., which break under versioned builds and make --strict unable to verify them.
Code fences: ```python linenums="0" for fragments, bare ```python for full-file tabs, and hl_lines="3-4 7" to mark the lines under discussion. Inline code that is Python gets the #!python prefix (\#!python use_state``) so it highlights.
Snippets are not typed into the markdown. They are real files under docs/examples/<page_slug>/, pulled in by the include plugin:
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 +10 +11 +12 +13 +14 +15 | |
The rules that make this work:
# start marker on its own line is what the include begins after; # end stops it. Crop at the marker so the marker itself never renders on the page.task_state_props/, task_context/, task_wiring/), one tabbed group per example.:material-play: Run tab is a standing placeholder. Keep it.Because the file is included, a snippet cannot drift from a runnable example — but nothing in the build proves the example behaves. Mount it and check the DOM before you write "this renders a list". When a page compares several versions, drive all of them through the same click sequence and assert the same observable output; "it looks the same" is how two versions of an example quietly disagree.
Also list children of a component with key= when they come from a list — html.ul([row(item, key=item["id"]) for item in items]). Omitting it renders fine and emits a debug-mode warning, which is exactly the lesson the page about keys is trying to teach.
From the repository root:
1 +2 +3 | |
Then run the examples themselves and open the built page in a browser. mkdocs build --strict catches broken internal links and unresolvable includes — both abort the build with a nonzero exit. Two things it does not catch: a page missing from nav: (an INFO line, exit 0), and a link whose #anchor does not exist in an otherwise valid target file (also exit 0), so check both by eye. And it cannot catch a snippet that renders nothing.
You are the only gate. The single workflow on new-docs runs mkdocs gh-deploy --force on push, and gh-deploy does not pass --strict — a build with broken links exits 0 and publishes. A miss does not fail a pipeline; it goes live.
Pitfall
Do not trust a component that renders without error. Set REACTPY_DEBUG=1 when probing: with debug off, a component that raised produces {"tagName": "", "error": ""} — a blank region and a 200 response. See Running Tests for the harness traps that make a broken example look green.
Branch from new-docs, one page per branch, and use the same Conventional Commit subjects as the history there — docs(learn): author X for ReactPy v2. A commit that removes a 🚧 badge from nav: should be the same commit that authored the page, never a separate "mark done" commit that could be cherry-picked alone.
No CHANGELOG.md entry: documentation work is not user-facing in the sense the changelog means. See Changelog.
Note
docs/src/dictionary.txt exists for the spellcheck plugin, which is currently commented out in mkdocs.yml. New domain words belong there if the plugin is ever re-enabled; nothing fails while it stays off.
🚧 badge.memo, && rendering, and React's dependency-array semantics.You will learn, sections, Recap, Related..md links; admonitions instead of ReactJS's JSX tags.docs/examples/, cropped at # start, formatted at 88 columns.--strict checks links and nothing about behaviour. Run the example.ReactPy's source is MIT-licensed. Much of the prose you are reading is derived from the ReactJS documentation, which carries a separate Creative Commons licence, and the two do not cover the same things. This page states which licence applies to what, and what you owe when you reuse either.
You will learn
The ReactPy package is released under the MIT licence, copyright Reactive Python and affiliates. The full text lives in the license file at the repository root and is reproduced below.
MIT is permissive: use, copy, modify, merge, publish, distribute, sublicense, and sell, subject to keeping the copyright notice and licence text in copies of the software. It comes with no warranty, and liability is excluded.
1 +2 +3 +4 +5 +6 +7 +8 +9 | |
These pages are a different body of work from the code, and they are separately encumbered.
Much of this documentation — including its layout and much of its content — was created with heavy influence from react.dev, which is licensed under the Creative Commons Attribution 4.0 International licence. ReactPy's behaviour often mirrors React's closely enough that the documents paraphrase, and in places copy, React's language and examples.
Note
CC BY 4.0 is also permissive, but its condition is attribution rather than keeping a licence block. If you copy substantial prose from these pages into your own documentation, credit ReactPy and, where the text is close to React's original, acknowledge the ReactJS documentation as the further source. Attributing to ReactPy alone is not sufficient for the passages that came from React.
The practical boundary: code you write against ReactPy is yours, unencumbered by either licence. These pages are text under a credit-bearing licence. A snippet in docs/examples/ is code that happens to be inside a document — treat it as MIT, since its purpose is to be pasted into a project.
A working ReactPy install bundles more than this repository's source: the browser-side client, the vendored JavaScript dependencies, and, for client-side rendering, PyScript. Each keeps its own upstream licence, shipped with the distribution.
Check what a release actually contains rather than trusting a summary — the package metadata and the static/ directory of the release are authoritative, and the licence files travel inside the wheel.
The pull request template ends with an agreement that contributions comply with the project's open source licences. It is a checkbox, but it is the whole of the provenance control this project has, so it is worth taking literally:
LICENSE.md at the repository root.docs/examples/ exist to be pasted; treat them as MIT code. There are two test suites in this project, and they live in different places. The Python and JavaScript suites exercise ReactPy itself and run through hatch; the documentation checks exercise the pages you are reading and run through mkdocs. Knowing which one a failing command belongs to is most of debugging it.
You will learn
Note
The ReactPy package and its tests/ directory live on the main branch. This documentation site is authored on the new-docs branch, which contains only docs/ — running a test command there collects zero tests rather than failing, which reads like a pass and is not one. If hatch test reports no tests ran, you are on the wrong branch, not on a clean tree.
The development environment is managed by Hatch, which creates and maintains its own virtual environments. Install Hatch, then clone:
1 +2 | |
You also need Bun for the JavaScript packages. Python must be 3.11 or newer — requires-python in pyproject.toml is >=3.11, and the test matrix runs 3.11 through 3.14.
Pitfall
Do not install the project's dependencies with pip install -r into your own environment. Hatch owns those environments, and a hand-built one drifts from CI in ways that look like your fault. The one exception is the documentation requirements, which are installed separately below.
The suite is pytest-based and runs under Hatch:
1 +2 +3 | |
CI runs hatch test --parallel --retries 10 across three operating systems and four Python versions, and a separate coverage job runs hatch test --parallel --cover --retries 10.
The suite needs a browser. Each test run installs Playwright's Chromium, builds the JavaScript client, and builds a wheel before it invokes pytest — that is what the hatch-test environment's run script does. A first run is therefore slow, and a failure inside Chromium installation looks identical to a failure in the test itself. Read the top of the output, not the bottom.
1 +2 | |
Tests are session-scoped around one browser and one backend server, defined in tests/conftest.py, and that file also turns on REACTPY_DEBUG and REACTPY_ASYNC_RENDERING for the whole session. Two consequences:
-k before you chase it.REACTPY_CHECK_VDOM_SPEC are exactly this.Configuration lives under [tool.pytest.ini_options] in pyproject.toml: --strict-config, --strict-markers, xfail_strict, asyncio_mode = "auto", testpaths = "tests", and a 120-second per-test timeout. xfail_strict means an expected failure that unexpectedly passes is itself a failure, so an xfail you fixed must be deleted rather than left alone.
reactpy.testing exists because a UI is only correct once it renders in a browser. The acceptance bar is that the real artefact behaves, not that a function returned the expected shape.
DisplayFixture — serves a component and gives you a Playwright page to drive it: await display.show(my_component), then display.page.BackendFixture — the server side, usually paired with DisplayFixture as in conftest.py.poll(...) — retries a condition until it holds or the timeout expires. Use it instead of asyncio.sleep, which passes vacuously on a slow machine and flakes on a fast one.HookCatcher and StaticEventHandler — capture a component's life-cycle hook and an event handler's target, for delivering events without a click.capture_reactpy_logs, assert_reactpy_did_log, assert_reactpy_did_not_log — assert on server-side log output, which is where ReactPy puts swallowed handler and effect errors.conftest.py also installs an autouse fixture that fails a test if any ReactPy log record carries an exception. That is deliberate: an error logged server-side while the browser stays quiet is the most common way a ReactPy bug hides. If a new test trips it, the exception is real even when the assertion you wrote passes.
The client packages are tested with Bun:
1 +2 +3 +4 | |
Changes under src/js/ need a rebuild before Python tests can see them. The test script does this itself, but a manual run against a stale bundle will not reflect your edit.
1 +2 +3 | |
CI runs hatch fmt src/reactpy --check followed by hatch run python:type_check.
Pitfall
Run hatch fmt --check before you commit, not hatch fmt. Bare hatch fmt rewrites files, so a run that "passes" has already edited your working tree — including files you did not intend to touch. Scope it (hatch fmt docs/) if you only want part of the tree.
Formatting is Ruff at a line length of 88. The rules that bite most in this repository are set in pyproject.toml; docs/**/*.py already ignores E402, S102, T201, TID252, RUF059, and INP001, because example files are teaching snippets rather than importable modules.
Run these from the repository root before you commit.
Pitfall
Nothing checks the documentation for you. The only workflow on new-docs installs the requirements and runs mkdocs gh-deploy --force on push — which does not pass --strict, so a broken internal link exits 0 and deploys anyway. The commands below are the gate only because you run them; there is no CI to catch a miss, and the live site is where an uncaught one appears.
1 +2 | |
Plus the type check over the example files, which are real Python:
1 | |
mkdocs build --strict is the important one: it turns broken internal links and unresolvable includes into build failures, both of which abort with a nonzero exit. It does not fail on two things you would expect it to: a page missing from nav: (only an INFO line, and the build still exits 0 while serving the orphaned page), and a link whose #anchor does not exist inside an otherwise valid target file (also exit 0). Read that nav: list yourself and check anchors by eye. Nor can it tell you whether a snippet works: the examples in docs/examples/ are the source of truth for every snippet on the site, and a snippet that does not run is a docs bug the build will not catch on its own. That part is on you.
Pitfall
Do not judge a build by its log output alone. A grep-style check on the output hides a nonzero exit:
1 | |
In a bash pipeline, use echo "${PIPESTATUS[0]}" instead — a trailing | grep that finds a match makes the pipeline's exit code meaningless.
1 +2 | |
Then follow the printed URL. Editing any file under docs/src/ or docs/examples/ reloads the page.
The requirements file pins mkdocs-material==9.7.7. Earlier revisions pinned 9.4.0, which pulled in regex~=2022.4 and resolved to a release shipping wheels only through CPython 3.11 — on newer Pythons that meant a source build and a hard failure without a C compiler. The current pin dropped the regex dependency altogether, so the install works on 3.12 and up. If you are on an older branch and the docs install dies inside regex, that is the reason: use Python 3.11 or raise the pin.
Before calling anything done, run the gates in this order and read every failure:
hatch fmt --check docs/ — formatting and lintpyright docs/ — types in the examplescd docs && mkdocs build --strict — links, includes, navSteps 1–4 can all pass while the thing you built does not work. A status is not an acceptance test: run the artefact. For a docs example that means mounting it in a browser and confirming the DOM changed, because a ReactPy component can render, error server-side, and show a blank region while the HTTP response still reads 200.
Deep Dive
Two harness traps have made broken examples look green more than once. First, the decorated function is a constructor: counter itself has no .render() and Layout(counter) raises TypeError: Expected a ReactPy component, so you must pass an instance. The instance does have .render(), but calling it outside a Layout raises RuntimeError: No life cycle hook is active. Are you rendering in a layout? for any component that uses a hook — which silently skips the behaviour you meant to test. Render through async with Layout(counter()) as layout: await layout.render(). Second, ReactPy formats exception text into the model only when REACTPY_DEBUG is on; with it off, a component that raised renders as {"tagName": "", "error": ""} — an empty region and no message. Set the variable when you are probing failures, and unset it when you are checking what a user would actually see.
hatch test for ReactPy (on main), mkdocs build --strict for the docs.hatch test reporting no tests ran means the suite is not there, not that it passed.pytest starts.conftest.py forces debug mode and fails any test that logs an exception.hatch fmt --check, never bare hatch fmt, before committing.