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.

[masenf]

i see some of what you were saying before about how the changes are still somewhat spread out even with the plugin.

at least the changes in reflex/compiler/compiler.py seem like they could be moved into the embed plugin module, since they are constructing the embed manifest and only used when embedding is enabled.

the problematic areas are where we're calling get_embed_plugin(); this seems like a role reversal. ideally the rest of the code doesn't need to know anything about the internals of the EmbedPlugin for it to work. what it tells me is that maybe we need more hooks into the compilation process to allow plugins like this to be expressed succinctly.

• update_env_json - this could return dictionaries that get merged together and become env.json.
• maybe _emit_stable_entry_bootloader could be moved to a post_compile step, which should run before the production build step.
• the compile_vite_config is slightly more annoying, so we can leave that for now. but I'm wanting to bring in something like @riebecj's https://github.com/riebecj/reflex-vite-config-plugin at some point. So it would be cool if we could bring in something like that which exposed its own hooks, like modify_vite_config which would allow plugins to make structural modifications to the vite config before it gets written out.

[riebecj]

This is a useless assignment. Nowhere in any of your code are you importing plugins.embed.Plugin. Which makes this import statement unnecessary. Just from .base import Plugin and subclass as class EmbedPlugin(Plugin): so we're not creating needlessly confusing module attributes.