SEO Compatible Rendering (#186)

- SEO compatible rendering
    - Prerenders the initial component via the template tag using `vdom_to_html`, then loads the actual component in the background within a `hidden` div. When loaded, the prerender is replaced with the actual render.
    - `settings.py:REACTPY_PRERENDER` can be set to `True` to enable this behavior by default
    - Enable it on individual components via the template tag: `{% component "..." prerender="True" %}`
- Docs styling, verbiage, and formatting tweaks
- Rename undocumented utility function `reactpy_django.utils.ComponentPreloader` to `reactpy_django.utils.RootComponentFinder`.
- Fix JavaScript being via `pip install -e .` on Windows.
- Update PyPi package metadata
- Update pull request template

Author: Archmonger

.github/pull_request_template.md

@@ -1,5 +1,3 @@
-*By submitting this pull request you agree that all contributions to this project are made under the MIT license.*
-
 ## Description
 
 A summary of the changes.
@@ -8,6 +6,9 @@ A summary of the changes.
 
 Please update this checklist as you complete each item:
 
--   [ ] Tests have been included for all bug fixes or added functionality.
--   [ ] The changelog has been updated with any significant changes, if necessary.
--   [ ] GitHub Issues which may be closed by this PR have been linked.
+-   [ ] Tests have been developed for bug fixes or new functionality.
+-   [ ] The changelog has been updated, if necessary.
+-   [ ] Documentation has been updated, if necessary.
+-   [ ] GitHub Issues closed by this PR have been linked.
+
+<sub>By submitting this pull request you agree that all contributions comply with this project's open source license(s).</sub>

CHANGELOG.md

@@ -32,6 +32,18 @@ Using the following categories, list your changes in this order:
 
 <!--changelog-start-->
 
+## [Unreleased]
+
+### Added
+
+-   ReactPy components can now use SEO compatible rendering!
+    -   `settings.py:REACTPY_PRERENDER` can be set to `True` to enable this behavior by default
+    -   Or, you can enable it on individual components via the template tag: `{% component "..." prerender="True" %}`
+
+### Changed
+
+-   Renamed undocumented utility function `reactpy_django.utils.ComponentPreloader` to `reactpy_django.utils.RootComponentFinder`.
+
 ## [3.5.1] - 2023-09-07
 
 ### Added

docs/python/template-tag-bad-view.py

@@ -2,5 +2,5 @@
 
 
 def example_view(request):
-    context_vars = {"dont_do_this": "example_project.my_app.components.hello_world"}
+    context_vars = {"my_variable": "example_project.my_app.components.hello_world"}
     return render(request, "my-template.html", context_vars)

docs/src/about/code.md

@@ -35,7 +35,7 @@ Then, by running the command below you can:
 -   Download, build, and install Javascript dependencies
 
 ```bash linenums="0"
-pip install -e . -r requirements.txt
+pip install -e . -r requirements.txt --verbose --upgrade
 ```
 
 !!! warning "Pitfall"

docs/src/about/docs.md

@@ -28,7 +28,7 @@ Then, by running the command below you can:
 -   Self-host a test server for the documentation
 
 ```bash linenums="0"
-pip install -e . -r requirements.txt --upgrade
+pip install -r requirements.txt --upgrade
 ```
 
 Finally, to verify that everything is working properly, you can manually run the docs preview web server.

docs/src/assets/css/admonition.css

@@ -1,20 +1,20 @@
 [data-md-color-scheme="slate"] {
 	--admonition-border-color: transparent;
 	--admonition-expanded-border-color: rgba(255, 255, 255, 0.1);
-	--note-bg-color: rgb(43 110 98/ 0.2);
+	--note-bg-color: rgba(43, 110, 98, 0.2);
 	--terminal-bg-color: #0c0c0c;
 	--terminal-title-bg-color: #000;
-	--deep-dive-bg-color: rgb(43 52 145 / 0.2);
+	--deep-dive-bg-color: rgba(43, 52, 145, 0.2);
 	--you-will-learn-bg-color: #353a45;
-	--pitfall-bg-color: rgb(182 87 0 / 0.2);
+	--pitfall-bg-color: rgba(182, 87, 0, 0.2);
 }
 [data-md-color-scheme="default"] {
 	--admonition-border-color: rgba(0, 0, 0, 0.08);
 	--admonition-expanded-border-color: var(--admonition-border-color);
-	--note-bg-color: rgb(244 251 249);
-	--terminal-bg-color: rgb(64 71 86);
-	--terminal-title-bg-color: rgb(35 39 47);
-	--deep-dive-bg-color: rgb(243 244 253);
+	--note-bg-color: rgb(244, 251, 249);
+	--terminal-bg-color: rgb(64, 71, 86);
+	--terminal-title-bg-color: rgb(35, 39, 47);
+	--deep-dive-bg-color: rgb(243, 244, 253);
 	--you-will-learn-bg-color: rgb(246, 247, 249);
 	--pitfall-bg-color: rgb(254, 245, 231);
 }
@@ -81,12 +81,12 @@ React Name: "Note"
 	font-size: 1rem;
 	background: transparent;
 	padding-bottom: 0;
-	color: rgb(68 172 153);
+	color: rgb(68, 172, 153);
 }
 
 .md-typeset .note .admonition-title:before {
 	font-size: 1.1rem;
-	background: rgb(68 172 153);
+	background: rgb(68, 172, 153);
 }
 
 .md-typeset .note > .admonition-title:before,
@@ -109,12 +109,12 @@ React Name: "Pitfall"
 	font-size: 1rem;
 	background: transparent;
 	padding-bottom: 0;
-	color: rgb(219 125 39);
+	color: rgb(219, 125, 39);
 }
 
 .md-typeset .warning .admonition-title:before {
 	font-size: 1.1rem;
-	background: rgb(219 125 39);
+	background: rgb(219, 125, 39);
 }
 
 /* 
@@ -131,12 +131,12 @@ React Name: "Deep Dive"
 	font-size: 1rem;
 	background: transparent;
 	padding-bottom: 0;
-	color: rgb(136 145 236);
+	color: rgb(136, 145, 236);
 }
 
 .md-typeset .info .admonition-title:before {
 	font-size: 1.1rem;
-	background: rgb(136 145 236);
+	background: rgb(136, 145, 236);
 }
 
 /* 
@@ -152,11 +152,11 @@ React Name: "Terminal"
 
 .md-typeset .example .admonition-title {
 	background: var(--terminal-title-bg-color);
-	color: rgb(246 247 249);
+	color: rgb(246, 247, 249);
 }
 
 .md-typeset .example .admonition-title:before {
-	background: rgb(246 247 249);
+	background: rgb(246, 247, 249);
 }
 
 .md-typeset .admonition.example code {

docs/src/assets/css/code.css

@@ -9,7 +9,7 @@
 	--md-code-hl-color: #ffffcf1c;
 	--md-code-bg-color: #16181d;
 	--md-code-hl-comment-color: hsla(var(--md-hue), 75%, 90%, 0.43);
-	--code-tab-color: rgb(52 58 70);
+	--code-tab-color: rgb(52, 58, 70);
 	--md-code-hl-name-color: #aadafc;
 	--md-code-hl-string-color: hsl(21 49% 63% / 1);
 	--md-code-hl-keyword-color: hsl(289.67deg 35% 60%);

docs/src/assets/css/main.css

@@ -3,7 +3,7 @@
 	--reactpy-color: #58b962;
 	--reactpy-color-dark: #42914a;
 	--reactpy-color-darker: #34743b;
-	--reactpy-color-opacity-10: rgb(88 185 98 / 10%);
+	--reactpy-color-opacity-10: rgba(88, 185, 98, 0.1);
 }
 
 [data-md-color-accent="red"] {
@@ -12,7 +12,7 @@
 }
 
 [data-md-color-scheme="slate"] {
-	--md-default-bg-color: rgb(35 39 47);
+	--md-default-bg-color: rgb(35, 39, 47);
 	--md-default-bg-color--light: hsla(var(--md-hue), 15%, 16%, 0.54);
 	--md-default-bg-color--lighter: hsla(var(--md-hue), 15%, 16%, 0.26);
 	--md-default-bg-color--lightest: hsla(var(--md-hue), 15%, 16%, 0.07);

docs/src/assets/css/navbar.css

@@ -1,9 +1,11 @@
 [data-md-color-scheme="slate"] {
 	--md-header-border-color: rgb(255 255 255 / 5%);
+	--md-version-bg-color: #ffffff0d;
 }
 
 [data-md-color-scheme="default"] {
 	--md-header-border-color: rgb(0 0 0 / 7%);
+	--md-version-bg-color: #ae58ee2e;
 }
 
 .md-header {
@@ -28,12 +30,20 @@
 }
 
 .md-version__list {
-	margin: 0.2rem -0.8rem;
+	margin: 0;
+	left: 0;
+	right: 0;
+	top: 2.5rem;
 }
 
-[dir="ltr"] .md-header__title.md-header__title--active {
-	margin: 0;
-	transition: margin 0.35s ease;
+.md-version {
+	background: var(--md-version-bg-color);
+	border-radius: 999px;
+	padding: 0 0.8rem;
+	margin: 0.3rem 0;
+	height: 1.8rem;
+	display: flex;
+	font-size: 0.7rem;
 }
 
 /* Mobile Styling */
@@ -97,6 +107,12 @@
 	.md-header__topic {
 		position: relative;
 	}
+	.md-header__title--active .md-header__topic {
+		transform: none;
+		opacity: 1;
+		pointer-events: auto;
+		z-index: 4;
+	}
 
 	/* Search */
 	.md-search {

docs/src/assets/css/sidebar.css

@@ -28,7 +28,7 @@
 	}
 
 	.md-nav--lifted > .md-nav__list > .md-nav__item--active > .md-nav__link {
-		color: rgb(133 142 159);
+		color: rgb(133, 142, 159);
 		margin: 0.5rem;
 	}
 

docs/src/learn/add-reactpy-to-a-django-project.md

@@ -53,6 +53,8 @@ Add `#!python "reactpy_django"` to [`INSTALLED_APPS`](https://docs.djangoproject
 
 ??? note "Configure ReactPy settings (Optional)"
 
+    {% include "../reference/settings.md" start="<!--intro-start-->" end="<!--intro-end-->"  %}
+
     {% include "../reference/settings.md" start="<!--config-table-start-->" end="<!--config-table-end-->"  %}
 
 ## Step 3: Configure `urls.py`

docs/src/reference/settings.md

@@ -2,7 +2,11 @@
 
 <p class="intro" markdown>
 
-Your **Django project's** `settings.py` can modify the behavior of ReactPy.
+<!--intro-start-->
+
+These are ReactPy-Django's default settings values. You can modify these values in your **Django project's** `settings.py` to change the behavior of ReactPy.
+
+<!--intro-end-->
 
 </p>
 
@@ -14,25 +18,34 @@ Your **Django project's** `settings.py` can modify the behavior of ReactPy.
 
 ---
 
-## Primary Configuration
-
 <!--config-table-start-->
 
-These are ReactPy-Django's default settings values. You can modify these values in your **Django project's** `settings.py` to change the behavior of ReactPy.
+## General Settings
 
 | Setting | Default Value | Example Value(s) | Description |
 | --- | --- | --- | --- |
-| `#!python REACTPY_CACHE` | `#!python "default"` | `#!python "my-reactpy-cache"` | Cache used to store ReactPy web modules. ReactPy benefits from a fast, well indexed cache. We recommend installing [`redis`](https://redis.io/) or [`python-diskcache`](https://grantjenks.com/docs/diskcache/tutorial.html#djangocache). |
-| `#!python REACTPY_DATABASE` | `#!python "default"` | `#!python "my-reactpy-database"` | Database used to store ReactPy session data. ReactPy requires a multiprocessing-safe and thread-safe database. If configuring `#!python REACTPY_DATABASE`, it is mandatory to enable our database router like such:<br/>`#!python DATABASE_ROUTERS = ["reactpy_django.database.Router", ...]` |
-| `#!python REACTPY_SESSION_MAX_AGE` | `#!python 259200` | `#!python 0`, `#!python 60`, `#!python 96000` | Maximum seconds to store ReactPy session data, such as `#!python args` and `#!python kwargs` passed into your component template tag. Use `#!python 0` to not store any session data. |
-| `#!python REACTPY_URL_PREFIX` | `#!python "reactpy/"` | `#!python "rp/"`, `#!python "render/reactpy/"` | The prefix to be used for all ReactPy WebSocket and HTTP URLs. |
-| `#!python REACTPY_DEFAULT_QUERY_POSTPROCESSOR` | `#!python "reactpy_django.utils.django_query_postprocessor"` | `#!python None`, `#!python "example_project.my_query_postprocessor"` | Dotted path to the default `#!python reactpy_django.hooks.use_query` postprocessor function. Postprocessor functions can be async or sync, and the parameters must contain the arg `#!python data`. Set `#!python REACTPY_DEFAULT_QUERY_POSTPROCESSOR` to `#!python None` to globally disable the default postprocessor. |
+| `#!python REACTPY_URL_PREFIX` | `#!python "reactpy/"` | `#!python "rp/"`, `#!python "render/reactpy/"` | The prefix used for all ReactPy WebSocket and HTTP URLs. |
+| `#!python REACTPY_DEFAULT_QUERY_POSTPROCESSOR` | `#!python "reactpy_django.utils.django_query_postprocessor"` | `#!python "example_project.postprocessor"`, `#!python None` | Dotted path to the default `#!python reactpy_django.hooks.use_query` postprocessor function. Postprocessor functions can be async or sync, and the function must contain a `#!python data` parameter. Set `#!python REACTPY_DEFAULT_QUERY_POSTPROCESSOR` to `#!python None` to globally disable the default postprocessor. |
 | `#!python REACTPY_AUTH_BACKEND` | `#!python "django.contrib.auth.backends.ModelBackend"` | `#!python "example_project.auth.MyModelBackend"` | Dotted path to the Django authentication backend to use for ReactPy components. This is only needed if:<br/> 1. You are using `#!python AuthMiddlewareStack` and...<br/> 2. You are using Django's `#!python AUTHENTICATION_BACKENDS` setting and...<br/> 3. Your Django user model does not define a `#!python backend` attribute. |
-| `#!python REACTPY_BACKHAUL_THREAD` | `#!python False` | `#!python True` | Whether to render ReactPy components in a dedicated thread. This allows the web server to process traffic during ReactPy rendering. Vastly improves throughput with web servers such as [`hypercorn`](https://pgjones.gitlab.io/hypercorn/) and [`uvicorn`](https://www.uvicorn.org/). |
-| `#!python REACTPY_DEFAULT_HOSTS` | `#!python None` | `#!python ["localhost:8000", "localhost:8001", "localhost:8002/subdir" ]` | The default host(s) that can render your ReactPy components. ReactPy will use these hosts in a round-robin fashion, allowing for easy distributed computing. You can use the `#!python host` argument in your [template tag](../reference/template-tag.md#component) as a manual override. |
-| `#!python REACTPY_RECONNECT_INTERVAL` | `#!python 750` | `#!python 100`, `#!python 2500`, `#!python 6000` | Milliseconds between client reconnection attempts. This value will gradually increase if `#!python REACTPY_RECONNECT_BACKOFF_MULTIPLIER` is greater than `#!python 1`. |
+
+## Performance Settings
+
+| Setting | Default Value | Example Value(s) | Description |
+| --- | --- | --- | --- |
+| `#!python REACTPY_DATABASE` | `#!python "default"` | `#!python "my-reactpy-database"` | Multiprocessing-safe database used to store ReactPy session data. If configuring `#!python REACTPY_DATABASE`, it is mandatory to enable our database router like such:<br/>`#!python DATABASE_ROUTERS = ["reactpy_django.database.Router", ...]` |
+| `#!python REACTPY_CACHE` | `#!python "default"` | `#!python "my-reactpy-cache"` | Cache used for ReactPy JavaScript modules. We recommend installing [`redis`](https://redis.io/) or [`python-diskcache`](https://grantjenks.com/docs/diskcache/tutorial.html#djangocache). |
+| `#!python REACTPY_BACKHAUL_THREAD` | `#!python False` | `#!python True` | Configures whether ReactPy components are rendered in a dedicated thread. This allows the web server to process traffic during ReactPy rendering. Vastly improves throughput with web servers such as [`hypercorn`](https://pgjones.gitlab.io/hypercorn/) and [`uvicorn`](https://www.uvicorn.org/). |
+| `#!python REACTPY_DEFAULT_HOSTS` | `#!python None` | `#!python ["localhost:8000", "localhost:8001", "localhost:8002/subdir"]` | The default host(s) that can render your ReactPy components. ReactPy will use these hosts in a round-robin fashion, allowing for easy distributed computing. You can use the `#!python host` argument in your [template tag](../reference/template-tag.md#component) as a manual override. |
+| `#!python REACTPY_PRERENDER` | `#!python False` | `#!python True` | Configures whether to pre-render your components, which enables SEO compatibility and increases perceived responsiveness. You can use the `#!python prerender` argument in your [template tag](../reference/template-tag.md#component) as a manual override. During pre-rendering, there are some key differences in behavior:<br/> 1. Only the component's first render is pre-rendered.<br/> 2. All `#!python connection` related hooks use HTTP.<br/> 3. `#!python html.script` is executed during both pre-render and render.<br/> 4. Component is non-interactive until a WebSocket connection is formed. |
+
+## Stability Settings
+
+| Setting | Default Value | Example Value(s) | Description |
+| --- | --- | --- | --- |
+| `#!python REACTPY_RECONNECT_INTERVAL` | `#!python 750` | `#!python 100`, `#!python 2500`, `#!python 6000` | Milliseconds between client reconnection attempts. |
+| `#!python REACTPY_RECONNECT_BACKOFF_MULTIPLIER` | `#!python 1.25` | `#!python 1`, `#!python 1.5`, `#!python 3` | On each reconnection attempt, the `#!python REACTPY_RECONNECT_INTERVAL` will be multiplied by this value to increase the time between attempts. You can keep time between each reconnection the same by setting this to `#!python 1`. |
 | `#!python REACTPY_RECONNECT_MAX_INTERVAL` | `#!python 60000` | `#!python 10000`, `#!python 25000`, `#!python 900000` | Maximum milliseconds between client reconnection attempts. This allows setting an upper bound on how high `#!python REACTPY_RECONNECT_BACKOFF_MULTIPLIER` can increase the time between reconnection attempts. |
 | `#!python REACTPY_RECONNECT_MAX_RETRIES` | `#!python 150` | `#!python 0`, `#!python 5`, `#!python 300` | Maximum number of reconnection attempts before the client gives up. |
-| `#!python REACTPY_RECONNECT_BACKOFF_MULTIPLIER` | `#!python 1.25` | `#!python 1`, `#!python 1.5`, `#!python 3` | Multiplier for the time between client reconnection attempts. On each reconnection attempt, the `#!python REACTPY_RECONNECT_INTERVAL` will be multiplied by this to increase the time between attempts. You can keep time between each reconnection the same by setting this to `#!python 1`. |
+| `#!python REACTPY_SESSION_MAX_AGE` | `#!python 259200` | `#!python 0`, `#!python 60`, `#!python 96000` | Maximum seconds to store ReactPy component sessions. This includes data such as `#!python *args` and `#!python **kwargs` passed into your component template tag. Use `#!python 0` to not store any session data. |
 
 <!--config-table-end-->

docs/src/reference/template-tag.md

@@ -25,8 +25,9 @@ This template tag can be used to insert any number of ReactPy components onto yo
     | `#!python dotted_path` | `#!python str` | The dotted path to the component to render. | N/A |
     | `#!python *args` | `#!python Any` | The positional arguments to provide to the component. | N/A |
     | `#!python class` | `#!python str | None` | The HTML class to apply to the top-level component div. | `#!python None` |
-    | `#!python key` | `#!python str | None` | Force the component's root node to use a [specific key value](https://reactpy.dev/docs/guides/creating-interfaces/rendering-data/index.html#organizing-items-with-keys). Using `#!python key` within a template tag is effectively useless. | `#!python None` |
-    | `#!python host` | `#!python str | None` | The host to use for the ReactPy connections. If set to `#!python None`, the host will be automatically configured.<br/>Example values include: `localhost:8000`, `example.com`, `example.com/subdir` | `#!python None` |
+    | `#!python key` | `#!python Any` | Force the component's root node to use a [specific key value](https://reactpy.dev/docs/guides/creating-interfaces/rendering-data/index.html#organizing-items-with-keys). Using `#!python key` within a template tag is effectively useless. | `#!python None` |
+    | `#!python host` | `#!python str | None` | The host to use for the ReactPy connections. If unset, the host will be automatically configured.<br/>Example values include: `localhost:8000`, `example.com`, `example.com/subdir` | `#!python None` |
+    | `#!python prerender` | `#!python str` | If `#!python "True"`, the component will pre-rendered, which enables SEO compatibility and increases perceived responsiveness. | `#!python "False"` |
     | `#!python **kwargs` | `#!python Any` | The keyword arguments to provide to the component. | N/A |
 
     <font size="4">**Returns**</font>
@@ -37,11 +38,11 @@ This template tag can be used to insert any number of ReactPy components onto yo
 
 <!--context-start-->
 
-??? warning "Do not use context variables for the ReactPy component name"
+??? warning "Do not use context variables for the component path"
 
-    Our preprocessor relies on the template tag containing a string.
+    The ReactPy component finder (`#!python reactpy_django.utils.RootComponentFinder`) requires that your component path is a string.
 
-    **Do not** use Django template/context variables for the component path. Failure to follow this warning can result in unexpected behavior.
+    **Do not** use Django template/context variables for the component path. Failure to follow this warning can result in unexpected behavior, such as components that will not render.
 
     For example, **do not** do the following:
 
@@ -52,7 +53,7 @@ This template tag can be used to insert any number of ReactPy components onto yo
         {% component "example_project.my_app.components.hello_world" recipient="World" %}
 
         <!-- This is bad -->
-        {% component dont_do_this recipient="World" %}
+        {% component my_variable recipient="World" %}
         ```
 
     === "views.py"
@@ -81,7 +82,7 @@ This template tag can be used to insert any number of ReactPy components onto yo
 
     1. If your host address are completely separate ( `origin1.com != origin2.com` ) you will need to [configure CORS headers](https://pypi.org/project/django-cors-headers/) on your main application during deployment.
     2. You will not need to register ReactPy HTTP or WebSocket paths on any applications that do not perform any component rendering.
-    3. Your component will only be able to access `#!python *args`/`#!python **kwargs` you provide to the template tag if your applications share a common database.
+    3. Your component will only be able to access your template tag's `#!python *args`/`#!python **kwargs` if your applications share a common database.
 
 <!--multiple-components-start-->
 

docs/src/reference/utils.md

@@ -52,9 +52,9 @@ This function is used manually register a root component with ReactPy.
     {% include "../../python/register-component.py" %}
     ```
 
-??? warning "Only use this within `#!python AppConfig.ready()`"
+??? warning "Only use this within `#!python MyAppConfig.ready()`"
 
-    You should always call `#!python register_component` within a Django [`#!python AppConfig.ready()` method](https://docs.djangoproject.com/en/4.2/ref/applications/#django.apps.AppConfig.ready). This ensures you will retain multiprocessing compatibility, such as with ASGI web server workers.
+    You should always call `#!python register_component` within a Django [`#!python MyAppConfig.ready()` method](https://docs.djangoproject.com/en/dev/ref/applications/#django.apps.AppConfig.ready). This ensures you will retain multiprocessing compatibility, such as with ASGI web server workers.
 
 ??? question "Do I need to use this?"
 

mkdocs.yml

@@ -112,7 +112,7 @@ watch:
 
 site_name: ReactPy-Django
 site_author: Archmonger
-site_description: It's React, but in Python. Now for Django developers.
+site_description: It's React, but in Python. Now with Django integration.
 copyright: Copyright &copy; 2023 Reactive Python.<div class="legal-footer-right">This project has no affiliation to ReactJS or Meta Platforms, Inc.</div>
 repo_url: https://github.com/reactive-python/reactpy-django
 site_url: https://reactive-python.github.io/reactpy-django

setup.py

@@ -9,7 +9,7 @@
 from logging import StreamHandler, getLogger
 from pathlib import Path
 
-from setuptools import find_packages, setup
+from setuptools import find_namespace_packages, setup
 from setuptools.command.develop import develop
 from setuptools.command.sdist import sdist
 
@@ -47,27 +47,35 @@ def list2cmdline(cmd_list):
 package = {
     "name": name,
     "python_requires": ">=3.9",
-    "packages": find_packages(str(src_dir)),
+    "packages": find_namespace_packages(str(src_dir)),
     "package_dir": {"": "src"},
-    "description": "Control the web with Python",
-    "author": "Ryan Morshead",
-    "author_email": "ryan.morshead@gmail.com",
+    "description": "It's React, but in Python. Now with Django integration.",
+    "author": "Mark Bakhit",
+    "author_email": "archiethemonger@gmail.com",
     "url": "https://github.com/reactive-python/reactpy-django",
     "license": "MIT",
     "platforms": "Linux, Mac OS X, Windows",
-    "keywords": ["interactive", "widgets", "DOM", "React"],
+    "keywords": [
+        "interactive",
+        "reactive",
+        "widgets",
+        "DOM",
+        "React",
+        "ReactJS",
+        "ReactPy",
+    ],
     "include_package_data": True,
     "zip_safe": False,
     "classifiers": [
         "Framework :: Django",
         "Framework :: Django :: 4.0",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
         "Operating System :: OS Independent",
         "Intended Audience :: Developers",
         "Intended Audience :: Science/Research",
         "Topic :: Multimedia :: Graphics",
-        "Programming Language :: Python :: 3.9",
-        "Programming Language :: Python :: 3.10",
-        "Programming Language :: Python :: 3.11",
         "Environment :: Web Environment",
     ],
 }
@@ -129,18 +137,17 @@ def run(self):
                 log.info(f"> {list2cmdline(args_list)}")
                 subprocess.run(args_list, cwd=js_dir, check=True)
             except Exception:
-                log.error("Failed to update NPM")
                 log.error(traceback.format_exc())
-                raise
+                log.error("Failed to update NPM, continuing anyway...")
 
             log.info("Installing Javascript...")
             try:
                 args_list = [npm, "install"]
                 log.info(f"> {list2cmdline(args_list)}")
                 subprocess.run(args_list, cwd=js_dir, check=True)
             except Exception:
-                log.error("Failed to install Javascript")
                 log.error(traceback.format_exc())
+                log.error("Failed to install Javascript")
                 raise
 
             log.info("Building Javascript...")
@@ -149,8 +156,8 @@ def run(self):
                 log.info(f"> {list2cmdline(args_list)}")
                 subprocess.run(args_list, cwd=js_dir, check=True)
             except Exception:
-                log.error("Failed to build Javascript")
                 log.error(traceback.format_exc())
+                log.error("Failed to build Javascript")
                 raise
 
             log.info("Successfully built Javascript")

src/js/package-lock.json

@@ -13,6 +13,9 @@
 		"@rollup/plugin-commonjs": "^24.0.1",
 		"@rollup/plugin-node-resolve": "^15.0.1",
 		"@rollup/plugin-replace": "^5.0.2",
+		"@types/react": "^17.0",
+		"@types/react-dom": "^17.0",
+		"typescript": "^4.9.5",
 		"prettier": "^3.0.2",
 		"rollup": "^3.28.1"
 	},

src/js/package.json

@@ -1,4 +1,4 @@
-import { mount } from "@reactpy/client";
+import { mount } from "./mount";
 import { ReactPyDjangoClient } from "./client";
 
 export function mountComponent(

src/js/src/index.ts

@@ -0,0 +1,18 @@
+import React from "react";
+import { render } from "react-dom";
+import { Layout } from "@reactpy/client/src/components";
+import { ReactPyDjangoClient } from "./client";
+
+export function mount(element: HTMLElement, client: ReactPyDjangoClient): void {
+  const prerenderElement = document.getElementById(element.id + "-prerender");
+  if (prerenderElement) {
+    element.hidden = true;
+    client.onMessage("layout-update", ({ path, model }) => {
+      if (prerenderElement) {
+        prerenderElement.replaceWith(element);
+        element.hidden = false;
+      }
+    });
+  }
+  render(<Layout client={client} />, element);
+}

src/js/src/mount.tsx

@@ -3,5 +3,14 @@
         "target": "ES2017",
         "module": "esnext",
         "moduleResolution": "node",
+        "jsx": "react",
     },
+    "paths": {
+        "react": [
+            "./node_modules/preact/compat/"
+        ],
+        "react-dom": [
+            "./node_modules/preact/compat/"
+        ]
+    }
 }

src/js/tsconfig.json

@@ -1,11 +1,11 @@
 from django.apps import AppConfig
 
-from reactpy_django.utils import ComponentPreloader
+from reactpy_django.utils import RootComponentFinder
 
 
 class ReactPyConfig(AppConfig):
     name = "reactpy_django"
 
     def ready(self):
         # Populate the ReactPy component registry when Django is ready
-        ComponentPreloader().run()
+        RootComponentFinder().run()

src/reactpy_django/apps.py

@@ -473,4 +473,13 @@ def reactpy_errors(app_configs, **kwargs):
             )
         )
 
+    if not isinstance(config.REACTPY_PRERENDER, bool):
+        errors.append(
+            Error(
+                "Invalid type for REACTPY_PRERENDER.",
+                hint="REACTPY_PRERENDER should be a boolean.",
+                id="reactpy_django.E021",
+            )
+        )
+
     return errors

src/reactpy_django/checks.py

@@ -107,3 +107,8 @@
     "REACTPY_RECONNECT_BACKOFF_MULTIPLIER",
     1.25,  # Default to 25% backoff per connection attempt
 )
+REACTPY_PRERENDER: bool = getattr(
+    settings,
+    "REACTPY_PRERENDER",
+    False,
+)

src/reactpy_django/config.py

@@ -8,3 +8,7 @@ class ComponentDoesNotExistError(AttributeError):
 
 class InvalidHostError(ValueError):
     ...
+
+
+class ComponentCarrierError(ValueError):
+    ...

src/reactpy_django/exceptions.py

@@ -48,16 +48,27 @@ def use_origin() -> str | None:
     this will be None."""
     scope = _use_scope()
     try:
-        return next(
-            (
-                header[1].decode("utf-8")
-                for header in scope["headers"]
-                if header[0] == b"origin"
-            ),
-            None,
-        )
+        if scope["type"] == "websocket":
+            return next(
+                (
+                    header[1].decode("utf-8")
+                    for header in scope["headers"]
+                    if header[0] == b"origin"
+                ),
+                None,
+            )
+        if scope["type"] == "http":
+            host = next(
+                (
+                    header[1].decode("utf-8")
+                    for header in scope["headers"]
+                    if header[0] == b"host"
+                )
+            )
+            return f"{scope['scheme']}://{host}" if host else None
     except Exception:
-        return None
+        _logger.info("Failed to get origin")
+    return None
 
 
 def use_scope() -> dict[str, Any]:

src/reactpy_django/hooks.py

@@ -1,9 +1,11 @@
 {% load static %}
-{% if reactpy_failure %}
-{% if reactpy_debug_mode %}
+
+{% if reactpy_failure and reactpy_debug_mode %}
 <b>{% firstof reactpy_error "UnknownError" %}:</b> "{% firstof reactpy_dotted_path "UnknownPath" %}"
 {% endif %}
-{% else %}
+
+{% if not reactpy_failure %}
+{% if reactpy_prerender_html %}<div id="{{ reactpy_uuid }}-prerender">{{ reactpy_prerender_html|safe }}</div>{% endif %}
 <div id="{{ reactpy_uuid }}" class="{{ reactpy_class }}"></div>
 <script type="module" crossorigin="anonymous">
   import { mountComponent } from "{% static 'reactpy_django/client.js' %}";

src/reactpy_django/templates/reactpy/component.html

@@ -1,22 +1,27 @@
 from __future__ import annotations
 
+from distutils.util import strtobool
 from logging import getLogger
 from uuid import uuid4
 
 import dill as pickle
 from django import template
 from django.http import HttpRequest
 from django.urls import NoReverseMatch, reverse
+from reactpy.backend.hooks import ConnectionContext
+from reactpy.backend.types import Connection, Location
 from reactpy.core.types import ComponentConstructor
+from reactpy.utils import vdom_to_html
 
 from reactpy_django import config, models
 from reactpy_django.exceptions import (
+    ComponentCarrierError,
     ComponentDoesNotExistError,
     ComponentParamError,
     InvalidHostError,
 )
 from reactpy_django.types import ComponentParams
-from reactpy_django.utils import validate_component_args
+from reactpy_django.utils import SyncLayout, validate_component_args
 
 try:
     RESOLVED_WEB_MODULES_PATH = reverse("reactpy:web_modules", args=["/"]).strip("/")
@@ -32,6 +37,7 @@ def component(
     dotted_path: str,
     *args,
     host: str | None = None,
+    prerender: str = str(config.REACTPY_PRERENDER),
     **kwargs,
 ):
     """This tag is used to embed an existing ReactPy component into your HTML template.
@@ -41,9 +47,14 @@ def component(
         *args: The positional arguments to provide to the component.
 
     Keyword Args:
+        class: The HTML class to apply to the top-level component div.
+        key: Force the component's root node to use a specific key value. Using \
+            key within a template tag is effectively useless.
         host: The host to use for the ReactPy connections. If set to `None`, \
             the host will be automatically configured. \
             Example values include: `localhost:8000`, `example.com`, `example.com/subdir`
+        prerender: Configures whether to pre-render this component, which \
+            enables SEO compatibility and increases perceived responsiveness.
         **kwargs: The keyword arguments to provide to the component.
 
     Example ::
@@ -67,6 +78,7 @@ def component(
     class_ = kwargs.pop("class", "")
     component_has_args = args or kwargs
     user_component: ComponentConstructor | None = None
+    _prerender_html = ""
 
     # Validate the host
     if host and config.REACTPY_DEBUG_MODE:
@@ -102,6 +114,25 @@ def component(
             )
             return failure_context(dotted_path, e)
 
+    # Pre-render the component, if requested
+    if strtobool(prerender):
+        if not is_local:
+            msg = "Cannot pre-render non-local components."
+            _logger.error(msg)
+            return failure_context(dotted_path, ComponentDoesNotExistError(msg))
+        if not user_component:
+            msg = "Cannot pre-render component that is not registered."
+            _logger.error(msg)
+            return failure_context(dotted_path, ComponentDoesNotExistError(msg))
+        if not request:
+            msg = (
+                "Cannot pre-render component without a HTTP request. Are you missing the "
+                "request context processor in settings.py:TEMPLATES['OPTIONS']['context_processors']?"
+            )
+            _logger.error(msg)
+            return failure_context(dotted_path, ComponentCarrierError(msg))
+        _prerender_html = prerender_component(user_component, args, kwargs, request)
+
     # Return the template rendering context
     return {
         "reactpy_class": class_,
@@ -116,6 +147,7 @@ def component(
         "reactpy_reconnect_max_interval": config.REACTPY_RECONNECT_MAX_INTERVAL,
         "reactpy_reconnect_backoff_multiplier": config.REACTPY_RECONNECT_BACKOFF_MULTIPLIER,
         "reactpy_reconnect_max_retries": config.REACTPY_RECONNECT_MAX_RETRIES,
+        "reactpy_prerender_html": _prerender_html,
     }
 
 
@@ -143,3 +175,24 @@ def validate_host(host: str):
         )
         _logger.error(msg)
         raise InvalidHostError(msg)
+
+
+def prerender_component(
+    user_component: ComponentConstructor, args, kwargs, request: HttpRequest
+):
+    search = request.GET.urlencode()
+    with SyncLayout(
+        ConnectionContext(
+            user_component(*args, **kwargs),
+            value=Connection(
+                scope=getattr(request, "scope", {}),
+                location=Location(
+                    pathname=request.path, search=f"?{search}" if search else ""
+                ),
+                carrier=request,
+            ),
+        )
+    ) as layout:
+        vdom_tree = layout.render()["model"]
+
+    return vdom_to_html(vdom_tree)

src/reactpy_django/templatetags/reactpy.py

@@ -16,6 +16,7 @@
 
 from django.db.models.base import Model
 from django.db.models.query import QuerySet
+from django.http import HttpRequest
 from django.views.generic import View
 from reactpy.types import Connection as _Connection
 from typing_extensions import ParamSpec
@@ -50,7 +51,7 @@ class ComponentWebsocket:
     dotted_path: str
 
 
-Connection = _Connection[ComponentWebsocket]
+Connection = _Connection[Union[ComponentWebsocket, HttpRequest]]
 
 
 @dataclass

src/reactpy_django/types.py

@@ -11,6 +11,7 @@
 from inspect import iscoroutinefunction
 from typing import Any, Callable, Sequence
 
+from asgiref.sync import async_to_sync
 from channels.db import database_sync_to_async
 from django.db.models import ManyToManyField, ManyToOneRel, prefetch_related_objects
 from django.db.models.base import Model
@@ -20,6 +21,7 @@
 from django.utils import timezone
 from django.utils.encoding import smart_str
 from django.views import View
+from reactpy.core.layout import Layout
 from reactpy.types import ComponentConstructor
 
 from reactpy_django.exceptions import ComponentDoesNotExistError, ComponentParamError
@@ -117,8 +119,8 @@ def import_dotted_path(dotted_path: str) -> Callable:
     return getattr(module, component_name)
 
 
-class ComponentPreloader:
-    """Preloads all ReactPy components found within Django templates.
+class RootComponentFinder:
+    """Searches Django templates to find and register all root components.
     This should only be `run` once on startup to maintain synchronization during mulitprocessing.
     """
 
@@ -352,3 +354,19 @@ def delete_expired_sessions(immediate: bool = False):
                 "This may indicate a performance issue with your system, cache, or database.",
                 clean_duration.total_seconds(),
             )
+
+
+class SyncLayout(Layout):
+    """Sync adapter for ReactPy's `Layout`. Allows it to be used in Django template tags.
+    This can be removed when Django supports async template tags.
+    """
+
+    def __enter__(self):
+        async_to_sync(self.__aenter__)()
+        return self
+
+    def __exit__(self, *_):
+        async_to_sync(self.__aexit__)(*_)
+
+    def render(self):
+        return async_to_sync(super().render)()

src/reactpy_django/utils.py

@@ -2,9 +2,6 @@
 ASGI config for test_app project.
 
 It exposes the ASGI callable as a module-level variable named ``application``.
-
-For more information on this file, see
-https://docs.djangoproject.com/en/3.2/howto/deployment/asgi/
 """
 
 import os

tests/test_app/asgi.py

@@ -0,0 +1,40 @@
+from time import sleep
+
+import reactpy_django
+from reactpy import component, html
+
+
+@component
+def prerender_string():
+    scope = reactpy_django.hooks.use_scope()
+
+    sleep(0.5)
+    return (
+        "prerender_string: Fully Rendered"
+        if scope.get("type") == "websocket"
+        else "prerender_string: Prerendered"
+    )
+
+
+@component
+def prerender_vdom():
+    scope = reactpy_django.hooks.use_scope()
+
+    if scope.get("type") == "http":
+        return html.div("prerender_vdom: Prerendered")
+
+    return html.div("prerender_vdom: Fully Rendered")
+
+
+@component
+def prerender_component():
+    scope = reactpy_django.hooks.use_scope()
+
+    @component
+    def inner(value):
+        return html.div(value)
+
+    if scope.get("type") == "http":
+        return inner("prerender_component: Prerendered")
+
+    return inner("prerender_component: Fully Rendered")

tests/test_app/prerender/__init__.py

@@ -0,0 +1,7 @@
+from django.urls import path
+
+from .views import prerender
+
+urlpatterns = [
+    path("prerender/", prerender),
+]

tests/test_app/prerender/components.py

@@ -0,0 +1,5 @@
+from django.shortcuts import render
+
+
+def prerender(request):
+    return render(request, "prerender.html", {})

tests/test_app/prerender/urls.py

@@ -1,15 +1,3 @@
-"""
-Django settings for test_app project.
-
-Generated by 'django-admin startproject' using Django 3.2.3.
-
-For more information on this file, see
-https://docs.djangoproject.com/en/3.2/topics/settings/
-
-For the full list of settings and their values, see
-https://docs.djangoproject.com/en/3.2/ref/settings/
-"""
-
 import os
 import sys
 from pathlib import Path
@@ -19,7 +7,6 @@
 SRC_DIR = BASE_DIR.parent / "src"
 
 # Quick-start development settings - unsuitable for production
-# See https://docs.djangoproject.com/en/3.2/howto/deployment/checklist/
 
 # SECURITY WARNING: keep the secret key used in production secret!
 SECRET_KEY = "django-insecure-n!bd1#+7ufw5#9ipayu9k(lyu@za$c2ajbro7es(v8_7w1$=&c"
@@ -73,7 +60,6 @@
 sys.path.append(str(SRC_DIR))
 
 # Database
-# https://docs.djangoproject.com/en/3.2/ref/settings/#databases
 # WARNING: There are overrides in `test_components.py` that require no in-memory
 # databases are used for testing. Make sure all SQLite databases are on disk.
 DATABASES = {
@@ -118,7 +104,6 @@
 }
 
 # Password validation
-# https://docs.djangoproject.com/en/3.2/ref/settings/#auth-password-validators
 AUTH_PASSWORD_VALIDATORS = [
     {
         "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",
@@ -135,7 +120,6 @@
 ]
 
 # Internationalization
-# https://docs.djangoproject.com/en/3.2/topics/i18n/
 LANGUAGE_CODE = "en-us"
 TIME_ZONE = "UTC"
 USE_I18N = True
@@ -144,12 +128,10 @@
 
 
 # Default primary key field type
-# https://docs.djangoproject.com/en/3.2/ref/settings/#default-auto-field
 DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
 STATIC_ROOT = os.path.join(BASE_DIR, "static-deploy")
 
 # Static Files (CSS, JavaScript, Images)
-# https://docs.djangoproject.com/en/3.2/howto/static-files/
 STATIC_URL = "/static/"
 STATICFILES_DIRS = [
     os.path.join(BASE_DIR, "test_app", "static"),
@@ -159,6 +141,7 @@
     "django.contrib.staticfiles.finders.AppDirectoriesFinder",
 ]
 
+
 # Logging
 LOG_LEVEL = "WARNING"
 if DEBUG and ("test" not in sys.argv):
@@ -177,6 +160,10 @@
             "handlers": ["console"],
             "level": LOG_LEVEL,
         },
+        "reactpy": {
+            "handlers": ["console"],
+            "level": LOG_LEVEL,
+        },
     },
 }
 

tests/test_app/prerender/views.py

@@ -0,0 +1,30 @@
+{% load static %} {% load reactpy %}
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="shortcut icon" type="image/png" href="{% static 'favicon.ico' %}" />
+    <title>ReactPy</title>
+</head>
+
+<body>
+    <h1>ReactPy Prerender Test Page</h1>
+    <hr>
+    <div id="prerender_string">
+        {% component "test_app.prerender.components.prerender_string" class="prerender-string" prerender="true" %}
+    </div>
+    <hr>
+    <div id="prerender_vdom">
+        {% component "test_app.prerender.components.prerender_vdom" class="prerender-vdom" prerender="true" %}
+    </div>
+    <hr>
+    <div id="prerender_component">
+        {% component "test_app.prerender.components.prerender_component" class="prerender-component" prerender="true" %}
+    </div>
+    <hr>
+</body>
+
+</html>

tests/test_app/settings.py

@@ -4,6 +4,7 @@
 import sys
 from distutils.util import strtobool
 from functools import partial
+from time import sleep
 
 from channels.testing import ChannelsLiveServerTestCase
 from channels.testing.live import make_application
@@ -375,3 +376,36 @@ def test_broken_postprocessor_query(self):
         broken_component = self.page.locator("#broken_postprocessor_query pre")
         broken_component.wait_for()
         self.assertIn("SynchronousOnlyOperation:", broken_component.text_content())
+
+    def test_prerender(self):
+        """Verify if round-robin host selection is working."""
+        new_page = self.browser.new_page()
+        try:
+            new_page.goto(f"{self.live_server_url}/prerender/")
+            string = new_page.locator("#prerender_string")
+            vdom = new_page.locator("#prerender_vdom")
+            component = new_page.locator("#prerender_component")
+
+            string.wait_for()
+            vdom.wait_for()
+            component.wait_for()
+
+            # Check if the prerender occurred
+            self.assertEqual(
+                string.all_inner_texts(), ["prerender_string: Prerendered"]
+            )
+            self.assertEqual(vdom.all_inner_texts(), ["prerender_vdom: Prerendered"])
+            self.assertEqual(
+                component.all_inner_texts(), ["prerender_component: Prerendered"]
+            )
+
+            sleep(1)
+            self.assertEqual(
+                string.all_inner_texts(), ["prerender_string: Fully Rendered"]
+            )
+            self.assertEqual(vdom.all_inner_texts(), ["prerender_vdom: Fully Rendered"])
+            self.assertEqual(
+                component.all_inner_texts(), ["prerender_component: Fully Rendered"]
+            )
+        finally:
+            new_page.close()

tests/test_app/templates/prerender.html

@@ -1,8 +1,5 @@
 """test_app URL Configuration
 
-The `urlpatterns` list routes URLs to views. For more information please see:
-    https://docs.djangoproject.com/en/3.2/topics/http/urls/
-
 Examples:
 
 Function views
@@ -20,7 +17,7 @@
 from django.contrib import admin
 from django.urls import include, path
 
-from .views import base_template, host_port_roundrobin_template, host_port_template
+from . import views
 
 
 class AccessUser:
@@ -30,11 +27,13 @@ class AccessUser:
 admin.site.has_permission = lambda r: setattr(r, "user", AccessUser()) or True  # type: ignore
 
 urlpatterns = [
-    path("", base_template),
-    path("port/<int:port>/", host_port_template),
+    path("", views.base_template),
+    path("port/<int:port>/", views.host_port_template),
     path(
-        "roundrobin/<int:port1>/<int:port2>/<int:count>/", host_port_roundrobin_template
+        "roundrobin/<int:port1>/<int:port2>/<int:count>/",
+        views.host_port_roundrobin_template,
     ),
+    path("", include("test_app.prerender.urls")),
     path("", include("test_app.performance.urls")),
     path("reactpy/", include("reactpy_django.http.urls")),
     path("admin/", admin.site.urls),