Expand React on Django rendering and docs

Author: justin808

.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  unit:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13"]
+        django-version: ["4.2.*", "5.1.*"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "Django==${{ matrix.django-version }}" -e .[dev]
+
+      - name: Ruff
+        run: ruff check .
+
+      - name: Pytest
+        run: pytest
+
+  example-e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: example/package-lock.json
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Install example dependencies
+        working-directory: example
+        run: npm ci
+
+      - name: Install Playwright browser
+        working-directory: example
+        run: npx playwright install --with-deps chromium
+
+      - name: Make example scripts executable
+        run: chmod +x example/bin/dev example/bin/prod example/bin/test-ci
+
+      - name: Run example smoke and Playwright suite
+        working-directory: example
+        run: ./bin/test-ci

.gitignore

@@ -11,4 +11,12 @@ __pycache__/
 build/
 dist/
 htmlcov/
-
+.playwright-cli/
+example/db.sqlite3
+example/node_modules/
+example/public/packs/
+example/public/packs-test/
+example/playwright-report/
+example/test-results/
+example/tmp/
+output/

README.md

@@ -9,10 +9,111 @@ This initial scaffold covers:
 - package metadata and tooling
 - Django settings-backed configuration
 - safe JSON and HTML output helpers
+- `django-rspack` integration helpers for bundle tags and asset lookup
 - client-only component rendering
+- server-side rendering over the shared node renderer protocol
+- streaming SSR and RSC response adapters
 - Django template tags for `react_component` and `react_component_hash`
+- store hydration helpers via `redux_store` and `redux_store_hydration_data`
+- a `server_render_js` helper for raw node-side evaluation
 - pytest coverage for the initial API surface
 
-`django-rspack` is intentionally kept at the boundary for now. The rendering
-core does not assume a specific asset loader yet, so we can plug in the bundler
-without rewriting the component API.
+## Example app
+
+The repository now includes a runnable Django example at `example/`. It ports
+the supported client-rendering slice of `react_on_rails_pro/spec/dummy` and
+now also exercises the live SSR, streaming, and RSC adapters.
+
+- the client-side HelloWorld page
+- the `server_render_js` page for non-React server evaluation
+- the `react_component_hash` metadata page
+- a multi-component index page
+- the shared-store pages for deferred and server-rendered hydration
+- the HTML options example, including JSON-string props and nested `data-*` attributes
+
+The example uses `django-rspack` for manifest-backed asset lookup and the shared
+`react-on-rails` npm runtime for browser mounting and hydration.
+
+Run the main validation paths with:
+
+```bash
+cd example && npm install
+./bin/test-ci
+./bin/dev dev
+./bin/dev static
+./bin/prod
+```
+
+Useful routes in the example app:
+
+- `/`
+- `/client_side_hello_world/`
+- `/server_side_hello_world/`
+- `/server_side_hello_world_shared_store/`
+- `/server_render_js_example/`
+- `/metadata_example/`
+- `/streaming_hello_world/`
+- `/rsc_hello_world/`
+- `/client_side_hello_world_with_options/`
+
+The Python package also exposes the helper APIs directly:
+
+```python
+from react_on_django import (
+    redux_store,
+    redux_store_hydration_data,
+    render_react_component,
+    render_react_component_hash,
+    server_render_js,
+)
+```
+
+The Django app now also ships management commands for starter scaffolding:
+
+```bash
+python manage.py react_install
+python manage.py react_generate dashboard-card
+python manage.py react_generate posts-feed --rsc
+```
+
+## Using with django-rspack
+
+`react-on-django` uses `django-rspack` for compiled asset lookup. The component
+renderer stays separate from the bundler, but React on Django exposes helpers so
+the two packages fit together cleanly.
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...,
+    "django_rspack",
+    "react_on_django",
+]
+
+REACT_ON_DJANGO = {
+    "bundle_name": "application",
+}
+```
+
+```django
+{% load react %}
+<!DOCTYPE html>
+<html>
+<head>
+  {% react_component_assets %}
+</head>
+<body>
+  {% react_component "HelloWorld" props=hello_props %}
+</body>
+</html>
+```
+
+The integration helpers are also available from Python:
+
+```python
+from react_on_django.assets import (
+    get_react_bundle_urls,
+    get_server_bundle_path,
+    render_react_component_assets,
+)
+```

docs/README.md

@@ -0,0 +1,15 @@
+# React on Django Docs
+
+This directory is the canonical documentation source for `react-on-django`.
+
+The public site will live in the separate `shakacode/react-on-django.com` repo.
+That site should sync content from this directory, prepare it for Docusaurus,
+and handle deployment, branding, and marketing pages.
+
+Current docs are organized into:
+
+- `introduction.md`
+- `getting-started/`
+- `guides/`
+- `pro/`
+- `sidebars.ts`

docs/getting-started/create-react-on-django-app.md

@@ -0,0 +1,36 @@
+# Create a React on Django App
+
+The package ships with both a reference example in `example/` and starter
+management commands.
+
+Recommended starting points:
+
+- run `manage.py react_install` for the starter JavaScript layout
+- run `manage.py react_generate` for new component scaffolds
+- copy the example bundle layout under `app/javascript/`
+- copy the Django settings seam for `django-rspack`
+- copy the example process scripts:
+  - `example/bin/dev`
+  - `example/bin/prod`
+  - `example/bin/test-ci`
+
+Minimum directories:
+
+```text
+your-project/
+  app/javascript/components/
+  app/javascript/packs/
+  public/packs/manifest.json
+  templates/
+```
+
+Starter command examples:
+
+```bash
+python manage.py react_install
+python manage.py react_generate dashboard-card
+python manage.py react_generate posts-feed --rsc
+```
+
+The example app is still the reference for richer flows such as shared stores,
+streaming shells, and the current RSC demos.

docs/getting-started/installation.md

@@ -0,0 +1,49 @@
+# Installation
+
+Install the package and its Django integration dependencies:
+
+```bash
+python -m pip install react-on-django django-rspack
+```
+
+Add the apps to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    "django.contrib.staticfiles",
+    "django_rspack",
+    "react_on_django",
+]
+```
+
+Add the request middleware so the current request is available to the render
+helpers:
+
+```python
+MIDDLEWARE = [
+    "django.middleware.common.CommonMiddleware",
+    "react_on_django.middleware.ReactOnDjangoRequestMiddleware",
+]
+```
+
+Configure the bundler manifest and React on Django settings:
+
+```python
+RSPACK = {
+    "manifest_path": BASE_DIR / "public" / "packs" / "manifest.json",
+}
+
+REACT_ON_DJANGO = {
+    "bundle_name": "application",
+    "server_bundle_js_file": "server-bundle.js",
+    "rsc_bundle_js_file": "rsc-bundle.js",
+    "rendering_server_url": "http://localhost:3500",
+}
+```
+
+Finally, load the assets in your base template:
+
+```django
+{% load react %}
+{% react_component_assets %}
+```

docs/getting-started/quick-start.md

@@ -0,0 +1,59 @@
+# Quick Start
+
+This is the shortest path from a Django template to a mounted React component.
+
+## 1. Register a browser bundle
+
+Build a client bundle that registers your components with the shared runtime:
+
+```jsx
+import RuntimeBridge from "react-on-rails/client";
+import HelloWorld from "../components/HelloWorld";
+
+RuntimeBridge.register({ HelloWorld });
+```
+
+## 2. Render assets in the layout
+
+```django
+{% load react %}
+<!doctype html>
+<html>
+  <head>
+    {% react_component_assets %}
+  </head>
+  <body>
+    {% block content %}{% endblock %}
+  </body>
+</html>
+```
+
+## 3. Render a component from a template
+
+```django
+{% extends "base.html" %}
+{% load react %}
+
+{% block content %}
+  {% react_component "HelloWorld" props=hello_props id="hello-world-root" %}
+{% endblock %}
+```
+
+## 4. Pass props from the Django view
+
+```python
+def homepage(request):
+    return render(
+        request,
+        "homepage.html",
+        {"hello_props": {"helloWorldData": {"name": "Ada"}}},
+    )
+```
+
+## 5. Enable SSR when ready
+
+```django
+{% react_component "HelloWorld" props=hello_props prerender=True %}
+```
+
+That only requires a renderer server once you actually enable prerendering.