Make it straightforward to mount a Reflex app on a sub-path of an existing ASGI application (Starlette, Litestar, Django, FastAPI, etc.). rx.App() already is an ASGI app — the problem isn't the interface, it's that mounting it anywhere other than / breaks in practice.
Current Limitations
1. Frontend can't find the backend when mounted on a sub-path
REFLEX_API_URL is baked into the compiled frontend at build time, but when the backend is mounted at a different path (e.g. /admin), the compiled frontend doesn't know where to find it. The websocket connection URL, state upload endpoint, and all /_reflex/ calls point to the wrong place.
Core problem: the frontend needs a more straightforward mechanism for discovering the backend location at runtime, rather than having it hardcoded at compile time.
2. REFLEX_FRONTEND_PATH doesn't work with static file serving
REFLEX_FRONTEND_PATH is baked into the compiled app, but should NOT be used when the host application mounts the static files from .web/build/client directly. The paths the app requests (CSS, JS, assets) don't agree with where they're actually being served from.
3. No build/export step when bringing up the ASGI app
Nothing triggers the export/bundle step when the rx.App() ASGI is mounted by a host application. There's no frontend build, so there are no static files to serve. This is less of an issue for larger deployments where frontends run separately, but for the common "mount Reflex alongside my existing API" case, bringing up the backend should trigger a build if needed.
4. Lifespan tasks may be lost
Lifespan tasks registered by the Reflex app may not propagate correctly when mounted as a sub-application, depending on how the host framework handles lifespan scoping.
What Needs to Happen
Primary: frontend ↔ backend path agreement
The main blocker is getting the static frontend and the backend to agree on paths regardless of where the app is mounted. If the frontend had a runtime mechanism to discover the backend (e.g. a relative path, a well-known discovery endpoint, or a <meta> tag injected at serve time), the mount path wouldn't need to be known at compile time.
Secondary: build-on-startup
Bringing up the backend ASGI app should trigger a production build/export of the frontend if the .web/build/client directory doesn't exist or is stale. This makes the "just mount it" experience work without a separate build step.
Directly Enables
- #46 — Embedding Reflex in other apps (see comment for current pain points)
Dependencies
- ENG-9165 — Consolidate internal endpoints under
/_reflex/ prefix
Tracking
Parent: ENG-9189 (Interoperability & Standardization)
Roadmap: #2727
Make it straightforward to mount a Reflex app on a sub-path of an existing ASGI application (Starlette, Litestar, Django, FastAPI, etc.).
rx.App()already is an ASGI app — the problem isn't the interface, it's that mounting it anywhere other than/breaks in practice.Current Limitations
1. Frontend can't find the backend when mounted on a sub-path
REFLEX_API_URLis baked into the compiled frontend at build time, but when the backend is mounted at a different path (e.g./admin), the compiled frontend doesn't know where to find it. The websocket connection URL, state upload endpoint, and all/_reflex/calls point to the wrong place.Core problem: the frontend needs a more straightforward mechanism for discovering the backend location at runtime, rather than having it hardcoded at compile time.
2.
REFLEX_FRONTEND_PATHdoesn't work with static file servingREFLEX_FRONTEND_PATHis baked into the compiled app, but should NOT be used when the host application mounts the static files from.web/build/clientdirectly. The paths the app requests (CSS, JS, assets) don't agree with where they're actually being served from.3. No build/export step when bringing up the ASGI app
Nothing triggers the
export/bundle step when therx.App()ASGI is mounted by a host application. There's no frontend build, so there are no static files to serve. This is less of an issue for larger deployments where frontends run separately, but for the common "mount Reflex alongside my existing API" case, bringing up the backend should trigger a build if needed.4. Lifespan tasks may be lost
Lifespan tasks registered by the Reflex app may not propagate correctly when mounted as a sub-application, depending on how the host framework handles lifespan scoping.
What Needs to Happen
Primary: frontend ↔ backend path agreement
The main blocker is getting the static frontend and the backend to agree on paths regardless of where the app is mounted. If the frontend had a runtime mechanism to discover the backend (e.g. a relative path, a well-known discovery endpoint, or a
<meta>tag injected at serve time), the mount path wouldn't need to be known at compile time.Secondary: build-on-startup
Bringing up the backend ASGI app should trigger a production build/export of the frontend if the
.web/build/clientdirectory doesn't exist or is stale. This makes the "just mount it" experience work without a separate build step.Directly Enables
Dependencies
/_reflex/prefixTracking
Parent: ENG-9189 (Interoperability & Standardization)
Roadmap: #2727