feat: support embedding Reflex apps into host pages via mount_target

[FarhanAliRaza]

Add and config options for embedding a Reflex
app into an arbitrary DOM node on a host page. When is set, the entry client mounts a memory data router into the target element via
instead of hydrating the document, the build emits a stable
shim re-exporting the hashed Vite chunk, and a route
manifest is generated at compile time so the embedded app owns its own URL space. now sources from the data router's
location so the backend sees the in-widget URL rather than the host page's.

Usage

rxconfig.py

import reflex as rx

config = rx.Config(
    app_name="my_app",
    mount_target="#reflex-root",
    # only needed when host page and bundle live on different origins
    embed_origin="http://localhost:3000",
    cors_allowed_origins=["*"],  # tighten for prod
)

usage in the HTML file.

<div id="reflex-root">loading reflex...</div>
<script type="module" src="http://localhost:3000/app/entry.client.js"></script>

All Submissions:

• Have you followed the guidelines stated in CONTRIBUTING.md file?
• Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

New Feature Submission:

• Does your submission pass the tests?
• Have you linted your code locally prior to submission?

Changes To Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you successfully ran tests with your changes locally?

[codspeed-hq]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing FarhanAliRaza:embedd-mode (29cb5f4) with main (1ffc3b5)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[greptile-apps]

Greptile Summary

This PR adds mount_target and embed_origin config options that allow a Reflex app to be embedded as a widget inside an arbitrary host page element instead of taking over the entire document. When mount_target is set, the entry client mounts a createMemoryRouter into the selected DOM node, a stable shim re-exports the hashed Vite entry chunk, a compile-time route manifest is generated, and locationRef in state.js mirrors the data-router's location so the backend sees the in-widget URL rather than the host page's.

• Entry client branching: entry.client.js reads MOUNT_TARGET from env.json and switches between hydrateRoot(document, ...) (normal) and createRoot(target).render(...) with a createMemoryRouter (embed); the EmbedLayout export skips the document shell while keeping all Reflex providers.
• Build pipeline changes: compile_embed_manifest generates a JS route manifest from registered routes, _emit_stable_entry_bootloader writes a shim at the stable app/entry.client.js path pointing to the hashed Vite asset, and _compile_vite_config prepends embed_origin to Vite's base for cross-origin asset resolution.
• State routing fix: locationRef replaces direct window.location reads in applyEvent, so router data sent to the backend reflects the memory router's in-widget path.

Confidence Score: 4/5

The core embedding mechanism is well-reasoned and the happy-path test coverage is solid, but there are error-handling gaps and a caching quirk that could obscure problems in production.

All four findings are non-blocking quality concerns: Promise.all lacks error handling so embed mount failures are invisible to users, a misconfigured selector silently triggers document hydration causing cryptic React Router errors on real host pages, @functools.cache contradicts the per-compile-refresh docstring and would serve stale content after a mid-session package upgrade, and the module-level locationRef is null until first render so early events still read the host window.location in embed mode.

entry.client.js (error handling and selector fallback behavior) and frontend_skeleton.py (@functools.cache on the template reader) deserve a second look before merge.

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/.templates/web/app/entry.client.js	Adds embed-mode branching via MOUNT_TARGET; missing error handling on Promise.all and a misleading silent fallback when the selector resolves to null.
packages/reflex-base/src/reflex_base/.templates/web/utils/state.js	Introduces locationRef to mirror the data router location for embed mode; module-level singleton may serve the host URL on very early events before component mount.
reflex/utils/frontend_skeleton.py	Adds update_entry_client with functools.cache that prevents the template from being re-read after the first compile despite the docstring claiming per-compile refresh.
reflex/compiler/compiler.py	Adds compile_embed_manifest and route-translation helpers; correctly gates manifest generation on config.mount_target.
reflex/utils/build.py	Adds _emit_stable_entry_bootloader to write a side-effect import shim for the hashed Vite entry; propagates mount_target to env.json correctly.
packages/reflex-base/src/reflex_base/constants/compiler.py	Introduces Embed SimpleNamespace with ENTRY_PATH and MANIFEST_FILE constants; well documented.

_{Reviews (1): Last reviewed commit: "feat: support embedding Reflex apps into..." | Re-trigger Greptile}

[masenf]

My main feedback here is to implement this primarily as a Plugin instead of wiring it through the whole framework. The plugin can take in the mount_target and embed_origin as parameters instead of adding more to the global config.

The only real downside of this approach is the current interpret_plugin_env parser for environment var specified plugins does not expose a way to provide arguments to a plugin class.

[FarhanAliRaza]

My thought was plugin too, but most of the will still remain outside of plugin i think.

So I implemented this way.. I ll update it.