PyReact Forge — React for Python

Build browser user interfaces with Python components and React hooks. Python runs in the browser through Pyodide/WebAssembly, while the real React renderer handles state, reconciliation and DOM updates. Static export does not require a Python application server for event handling.

Alpha 0.1.0a1 · MIT framework · Python 3.11+ CLI

Documentation · Installation · API reference · Compatibility

from pyreact_forge import component, html, use_state

@component
def App():
    count, set_count = use_state(0)
    return html.button(
        f"Clicked {count} times",
        on_click=lambda: set_count(lambda previous: previous + 1),
    )

Install and start

After this version is published on PyPI:

python -m pip install "pyreact-forge==0.1.0a1"
pyreact-forge init my-app
cd my-app
pyreact-forge dev

Before the first upload, install from this source folder with python -m pip install ., or install the supplied wheel. Open the local URL printed by the CLI. Node is not needed for ordinary app development with the packaged browser runtime; Node 22+ is required for SSR and framework runtime rebuilds.

What is included

• Function/class components, Python object state and keyed lists.
• State, reducer, effect, context, ref, memo, callback, external-store and ID hooks.
• Deferred/transition, optimistic, action-state, form-status and effect-event adapters.
• HTML/SVG/custom elements, controlled forms, CSS and native RTL attributes.
• Suspense resources, lazy components, portals, error boundaries and Activity.
• Optional History API routing and registered JavaScript React components.
• Static builds plus Node/Pyodide server rendering and browser hydration.
• Searchable tutorials, task-app walkthrough, API/CLI/config references and troubleshooting with an explicit tested-capability matrix.

How the Python frontend works

Decorated Python components become React component types. Elements are real React elements, hooks call React's dispatcher, and Python callbacks run locally in the browser. The project is a Python API and bridge on React, not an independent implementation of its reconciler.

Python browser code is public client code. Keep private credentials, trusted operations and authorization on an appropriate backend. The alpha has no Python RSC/Flight protocol, React Compiler equivalent or state-preserving Fast Refresh. The application exporter currently expects origin-root hosting. See the matrix for adapters with limited scenario coverage.

Build for static hosting

pyreact-forge vendor
pyreact-forge build --offline
pyreact-forge serve

Serve the complete dist/ over HTTP/HTTPS with a route fallback. Extra Python packages must be compatible with Pyodide and can introduce their own downloads. See deployment and SSR.

Develop the framework and docs

python -m pip install -e .
python -m pip install -r requirements-docs.txt -r requirements-release.txt
python -m unittest discover -s tests -v
python scripts/generate_api.py --check
python -m zensical build --strict
python scripts/check_docs.py

For full SSR/browser checks, install the locked Node dependencies and follow testing. For runtime changes, run npm run build:runtime and commit the generated bundles with the source change.

Contribute and license

Read CONTRIBUTING.md, SECURITY.md and the capability matrix. Provide small reproductions and full tracebacks when reporting a bug.

Framework source is MIT. Bundled React is MIT; optional Pyodide is MPL 2.0 with additional upstream component licenses. See third-party notices.