Add React to an Existing Project

Overview¶

If you want to add some interactivity to your existing project, you don't have to rewrite it in React. Add React to your existing stack, and render interactive React components anywhere.

Using React for an entire subroute of your existing website¶

Let's say you have an existing web app at example.com built with another server technology (like Rails), and you want to implement all routes starting with example.com/some-app/ fully with React.

Using an ASGI subroute¶

Here's how we recommend to set it up:

Build the React part of your app using one of the ReactPy executors.
Specify /some-app as the base path in your executors kwargs (path_prefix="/some-app").
Configure your server or a proxy so that all requests under /some-app/ are handled by your React app.

This ensures the React part of your app can benefit from the best practices baked into those frameworks.

Using static site generation (SSG)¶

Support for SSG is coming in a future version.

Using React for a part of your existing page¶

Let's say you have an existing page built with another Python web technology (ASGI or WSGI), and you want to render interactive React components somewhere on that page.

The exact approach depends on your existing page setup, so let's walk through some details.

Using ASGI Middleware¶

ReactPy supports running as middleware for any existing ASGI application. ReactPy components are embedded into your existing HTML templates using Jinja2. You can use any ASGI framework, however for demonstration purposes we have selected Starlette for the example below.

First, install ReactPy, Starlette, and your preferred ASGI webserver.

Terminal

pip install reactpy[asgi,jinja] starlette uvicorn[standard]

Next, configure your ASGI framework to use ReactPy's Jinja2 template tag. The method for doing this will vary depending on the ASGI framework you are using. Below is an example that follow's Starlette's documentation:

from jinja2 import Environment, FileSystemLoader
from starlette.applications import Starlette
from starlette.routing import Route
from starlette.templating import Jinja2Templates

from reactpy.templatetags import ReactPyJinja

jinja_templates = Jinja2Templates(
    env=Environment(
        loader=FileSystemLoader("path/to/my_templates"),
        extensions=[ReactPyJinja],
    )
)


async def example_webpage(request):
    return jinja_templates.TemplateResponse(request, "my_template.html")


starlette_app = Starlette(routes=[Route("/", example_webpage)])

Now you will need to wrap your existing ASGI application with ReactPy's middleware, define the dotted path to your root components, and render your components in your existing HTML templates.

Note

The ReactPyJinja extension enables a handful of template tags that allow you to render ReactPy components in your templates. The component tag is used to render a ReactPy SSR component, while the pyscript_setup and pyscript_component tags can be used together to render CSR components.

main.pymy_components.pymy_template.html

from jinja2 import Environment, FileSystemLoader
from starlette.applications import Starlette
from starlette.routing import Route
from starlette.templating import Jinja2Templates

from reactpy.executors.asgi import ReactPyMiddleware
from reactpy.templatetags import ReactPyJinja

jinja_templates = Jinja2Templates(
    env=Environment(
        loader=FileSystemLoader("path/to/my_templates"),
        extensions=[ReactPyJinja],
    )
)


async def example_webpage(request):
    return jinja_templates.TemplateResponse(request, "my_template.html")


starlette_app = Starlette(routes=[Route("/", example_webpage)])
reactpy_app = ReactPyMiddleware(starlette_app, ["my_components.hello_world"])

from reactpy import component, html


@component
def hello_world():
    return html.div("Hello World")

<!doctype html>
<html lang="en">

<head>
  <title>ReactPy in Django</title>
</head>

<body>
  {% component "my_components.hello_world" %}
</body>

</html>

Finally, use your webserver of choice to start ReactPy:

Terminal

uvicorn main:reactpy_app

Using WSGI Middleware¶

Support for WSGI executors is coming in a future version.

External Executors¶

Note

External executors exist outside ReactPy's core library and have significantly different installation and configuration instructions.

Make sure to follow the documentation for setting up your chosen external executor.

Django¶

Django is a full-featured web framework that provides a batteries-included approach to web development.

Due to it's batteries-included approach, ReactPy has unique features only available to this executor.

To learn how to configure Django for ReactPy, see the ReactPy-Django documentation.

Last update: March 15, 2025

Authors: Archmonger