diff --git a/packages/reflex-base/src/reflex_base/.templates/web/app/entry.client.embed.js b/packages/reflex-base/src/reflex_base/.templates/web/app/entry.client.embed.js
new file mode 100644
index 00000000000..57ef621468e
--- /dev/null
+++ b/packages/reflex-base/src/reflex_base/.templates/web/app/entry.client.embed.js
@@ -0,0 +1,63 @@
+import { startTransition, createElement } from "react";
+import { createRoot, hydrateRoot } from "react-dom/client";
+import { HydratedRouter } from "react-router/dom";
+import env from "$/env.json";
+
+const selector = env.MOUNT_TARGET;
+
+if (selector) {
+  const target = document.querySelector(selector);
+  if (!target) {
+    console.error(
+      `[Reflex embed] No element matching MOUNT_TARGET selector ${JSON.stringify(selector)}; widget will not mount.`,
+    );
+  } else {
+    // @react-router/dev injects a preamble check at the top of every
+    // transformed JSX module that throws when this flag is unset. Framework-
+    // mode prerendered HTML installs it via <Scripts>; embed mode does not,
+    // so we install it before any user JSX module loads (the imports below
+    // are dynamic).
+    window.__vite_plugin_react_preamble_installed__ = true;
+    window.$RefreshReg$ = () => {};
+    window.$RefreshSig$ = () => (type) => type;
+
+    // No __reactRouterContext on the host page; mount through a memory data
+    // router so the widget owns its URL space (host's window.location is
+    // unrelated) and react-router hooks like useLoaderData resolve. The route
+    // table is generated at compile time into __reflex_embed_manifest.js.
+    Promise.all([
+      import("$/styles/__reflex_global_styles.css"),
+      import("react-router"),
+      import("$/app/root"),
+      import("$/app/__reflex_embed_manifest"),
+    ])
+      .then(([, reactRouter, root, manifest]) => {
+        const { createMemoryRouter, RouterProvider, Outlet } = reactRouter;
+        const children = manifest.default.map(({ path, load }) => {
+          const lazy = async () => ({ Component: (await load()).default });
+          if (path === "") return { index: true, lazy };
+          return { path, lazy };
+        });
+        const router = createMemoryRouter(
+          [
+            {
+              Component: () =>
+                createElement(root.EmbedLayout, null, createElement(Outlet)),
+              children,
+            },
+          ],
+          { initialEntries: ["/"] },
+        );
+        startTransition(() => {
+          createRoot(target).render(createElement(RouterProvider, { router }));
+        });
+      })
+      .catch((err) => {
+        console.error("[Reflex embed] Failed to load:", err);
+      });
+  }
+} else {
+  startTransition(() => {
+    hydrateRoot(document, createElement(HydratedRouter));
+  });
+}
diff --git a/packages/reflex-base/src/reflex_base/.templates/web/utils/state.js b/packages/reflex-base/src/reflex_base/.templates/web/utils/state.js
index d931a19299d..ddaa466aba8 100644
--- a/packages/reflex-base/src/reflex_base/.templates/web/utils/state.js
+++ b/packages/reflex-base/src/reflex_base/.templates/web/utils/state.js
@@ -42,6 +42,17 @@ export const refs = {};
 // Array holding pending events to be processed.
 const event_queue = [];
 
+// Mirrors the data router's location so applyEvent can populate router_data
+// with the in-widget URL. In embed mode the host page's window.location is
+// unrelated to the Reflex route, so the backend's on_load and dynamic-route
+// matching rely on this ref instead. Updated by useEventLoop once mounted;
+// pre-seeded in embed mode with the memory router's initial path (see
+// initialEntries in entry.client.embed.js) so events dispatched before the
+// first effect commit don't briefly fall back to the host page's URL.
+const locationRef = {
+  current: env.MOUNT_TARGET ? { pathname: "/", search: "", hash: "" } : null,
+};
+
 /**
  * Generate a UUID (Used for session tokens).
  * Taken from: https://stackoverflow.com/questions/105034/how-do-i-create-a-guid-uuid
@@ -378,16 +389,15 @@ export const applyEvent = async (event, socket, navigate, params) => {
     event.router_data === undefined ||
     Object.keys(event.router_data).length === 0
   ) {
-    // Since we don't have router directly, we need to get info from our hooks
+    const loc = locationRef.current ?? window.location;
+    const search = loc.search ?? "";
+    const hash = loc.hash ?? "";
     event.router_data = {
-      pathname: window.location.pathname,
-      asPath:
-        window.location.pathname +
-        window.location.search +
-        window.location.hash,
+      pathname: loc.pathname,
+      asPath: loc.pathname + search + hash,
     };
     const query = {
-      ...Object.fromEntries(new URLSearchParams(window.location.search)),
+      ...Object.fromEntries(new URLSearchParams(search)),
       ...params.current,
     };
     if (query && Object.keys(query).length > 0) {
@@ -903,6 +913,10 @@ export const useEventLoop = (
     }
   }, [paramsR]);
 
+  useEffect(() => {
+    locationRef.current = location;
+  }, [location]);
+
   const ensureSocketConnected = useCallback(async () => {
     if (!mounted.current) {
       // During hot reload, some components may still have a reference to
diff --git a/packages/reflex-base/src/reflex_base/compiler/templates.py b/packages/reflex-base/src/reflex_base/compiler/templates.py
index 3c525e99f4e..08bb95a71d9 100644
--- a/packages/reflex-base/src/reflex_base/compiler/templates.py
+++ b/packages/reflex-base/src/reflex_base/compiler/templates.py
@@ -208,13 +208,7 @@ def app_root_template(
 
 {custom_code_str}
 
-function AppWrap({{children}}) {{
-{_render_hooks(hooks)}
-return ({_RenderUtils.render(render)})
-}}
-
-
-export function Layout({{children}}) {{
+function ReflexProviders({{children}}) {{
   useEffect(() => {{
     // Make contexts and state objects available globally for dynamic eval'd components
     let windowImports = {{
@@ -223,17 +217,32 @@ def app_root_template(
     window["__reflex"] = windowImports;
   }}, []);
 
-  return jsx(AppLayout, {{}},
-    jsx(ThemeProvider, {{defaultTheme: defaultColorMode, attribute: "class"}},
-      jsx(StateProvider, {{}},
-        jsx(EventLoopProvider, {{}},
-          jsx(AppWrap, {{}}, children)
-        )
+  return jsx(ThemeProvider, {{defaultTheme: defaultColorMode, attribute: "class"}},
+    jsx(StateProvider, {{}},
+      jsx(EventLoopProvider, {{}},
+        jsx(AppWrap, {{}}, children)
       )
     )
   );
 }}
 
+
+function AppWrap({{children}}) {{
+{_render_hooks(hooks)}
+return ({_RenderUtils.render(render)})
+}}
+
+export function Layout({{children}}) {{
+  return jsx(AppLayout, {{}}, jsx(ReflexProviders, {{}}, children));
+}}
+
+// Used by entry.client.js when mount_target is configured: skips the document
+// shell (which renders react-router's <Meta>/<Scripts>/<Links> and requires a
+// framework router context) but keeps the runtime providers.
+export function EmbedLayout({{children}}) {{
+  return jsx(ReflexProviders, {{}}, children);
+}}
+
 export default function App() {{
   return jsx(Outlet, {{}});
 }}
diff --git a/packages/reflex-base/src/reflex_base/constants/__init__.py b/packages/reflex-base/src/reflex_base/constants/__init__.py
index e790572a13a..b308500593a 100644
--- a/packages/reflex-base/src/reflex_base/constants/__init__.py
+++ b/packages/reflex-base/src/reflex_base/constants/__init__.py
@@ -29,6 +29,7 @@
     CompileContext,
     CompileVars,
     ComponentName,
+    Embed,
     Ext,
     Hooks,
     Imports,
@@ -90,6 +91,7 @@
     "DefaultPage",
     "DefaultPorts",
     "Dirs",
+    "Embed",
     "Endpoint",
     "Env",
     "EventTriggers",
diff --git a/packages/reflex-base/src/reflex_base/constants/compiler.py b/packages/reflex-base/src/reflex_base/constants/compiler.py
index 8113f522484..a5dd51b3925 100644
--- a/packages/reflex-base/src/reflex_base/constants/compiler.py
+++ b/packages/reflex-base/src/reflex_base/constants/compiler.py
@@ -100,6 +100,27 @@ class PageNames(SimpleNamespace):
     STATEFUL_COMPONENTS = "stateful_components"
 
 
+class Embed(SimpleNamespace):
+    """Public artifacts for ``mount_target`` (embed) builds.
+
+    These paths form the host-page contract: a host script tag points at
+    ``ENTRY_PATH`` (relative to the frontend origin), which loads the route
+    manifest at ``MANIFEST_FILE`` and dispatches into the embedded app. They
+    are intentionally stable across dev and prod so the same host HTML works
+    in both modes.
+    """
+
+    # Host pages reference this path (e.g. ``<script src="/app/entry.client.js">``).
+    # In dev, Vite serves the source file at this URL; in prod, a shim emitted
+    # by ``_emit_stable_entry_bootloader`` re-exports the hashed Vite entry.
+    ENTRY_PATH = "app/entry.client.js"
+    # Embed-aware variant of the entry, swapped in only when ``mount_target``
+    # is set so non-embed builds remain byte-identical to the framework default.
+    ENTRY_EMBED_TEMPLATE = "app/entry.client.embed.js"
+    # Compile-time-emitted route manifest the embed entry imports at runtime.
+    MANIFEST_FILE = "__reflex_embed_manifest.js"
+
+
 class ComponentName(Enum):
     """Component names."""
 
diff --git a/packages/reflex-base/src/reflex_base/plugins/__init__.py b/packages/reflex-base/src/reflex_base/plugins/__init__.py
index f3ef5aa971c..bec44565662 100644
--- a/packages/reflex-base/src/reflex_base/plugins/__init__.py
+++ b/packages/reflex-base/src/reflex_base/plugins/__init__.py
@@ -1,6 +1,6 @@
 """Reflex Plugin System."""
 
-from . import sitemap, tailwind_v3, tailwind_v4
+from . import embed, sitemap, tailwind_v3, tailwind_v4
 from ._screenshot import ScreenshotPlugin as _ScreenshotPlugin
 from .base import CommonContext, Plugin, PreCompileContext
 from .compiler import (
@@ -11,6 +11,7 @@
     PageContext,
     PageDefinition,
 )
+from .embed import EmbedPlugin
 from .sitemap import SitemapPlugin
 from .tailwind_v3 import TailwindV3Plugin
 from .tailwind_v4 import TailwindV4Plugin
@@ -21,6 +22,7 @@
     "CompileContext",
     "CompilerHooks",
     "ComponentAndChildren",
+    "EmbedPlugin",
     "PageContext",
     "PageDefinition",
     "Plugin",
@@ -29,6 +31,7 @@
     "TailwindV3Plugin",
     "TailwindV4Plugin",
     "_ScreenshotPlugin",
+    "embed",
     "sitemap",
     "tailwind_v3",
     "tailwind_v4",
diff --git a/packages/reflex-base/src/reflex_base/plugins/base.py b/packages/reflex-base/src/reflex_base/plugins/base.py
index 082258ddb9c..6673309840b 100644
--- a/packages/reflex-base/src/reflex_base/plugins/base.py
+++ b/packages/reflex-base/src/reflex_base/plugins/base.py
@@ -63,6 +63,12 @@ class PostCompileContext(CommonContext):
     app: "App"
 
 
+class PostBuildContext(CommonContext):
+    """Context for post-build hooks."""
+
+    static_dir: Path
+
+
 class Plugin:
     """Base class for all plugins."""
 
@@ -137,6 +143,47 @@ def post_compile(self, **context: Unpack[PostCompileContext]) -> None:
             context: The context for the plugin.
         """
 
+    def post_build(self, **context: Unpack[PostBuildContext]) -> None:
+        """Called after the production frontend build finishes.
+
+        Fires after ``npm run export`` so plugins can inspect or post-process
+        the Vite output (``context["static_dir"]``).
+
+        Args:
+            context: The context for the plugin.
+        """
+
+    def provides_entry_client(self) -> bool:
+        """Return whether this plugin emits its own ``entry.client.js``.
+
+        The framework calls this during ``setup_frontend`` to decide whether
+        to skip its default ``entry.client.js`` write. Plugins that register
+        a save task for the same path should return ``True`` so the framework
+        write doesn't race with (or overwrite) theirs.
+
+        Returns:
+            ``True`` if the plugin owns ``entry.client.js`` for this build.
+        """
+        return False
+
+    def update_env_json(
+        self, **context: Unpack[CommonContext]
+    ) -> dict[str, Any] | None:
+        """Return entries to merge into ``.web/env.json``.
+
+        The framework merges each plugin's contribution on top of the base
+        ``env.json`` it writes during ``setup_frontend``. Later plugins
+        override earlier ones. Return ``None`` (the default) to contribute
+        nothing.
+
+        Args:
+            context: The context for the plugin.
+
+        Returns:
+            A mapping of env entries to add or override, or ``None``.
+        """
+        return None
+
     def eval_page(
         self,
         page_fn: Any,
diff --git a/packages/reflex-base/src/reflex_base/plugins/embed.py b/packages/reflex-base/src/reflex_base/plugins/embed.py
new file mode 100644
index 00000000000..a9cdbf2aebe
--- /dev/null
+++ b/packages/reflex-base/src/reflex_base/plugins/embed.py
@@ -0,0 +1,363 @@
+"""Plugin that compiles a Reflex app for embedding into a host page.
+
+When this plugin is registered in ``rx.Config.plugins``, the compiler swaps the
+framework-mode entry for an embed-aware variant that mounts the app into a
+host-page DOM element (selected by ``mount_target``) instead of taking over the
+document. A route manifest is emitted alongside so the embed entry can lazy-
+load page modules through a memory router.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+import os
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from reflex_base import constants
+
+from .base import Plugin
+
+if TYPE_CHECKING:
+    from reflex.app import UnevaluatedPage
+
+
+_DEV_HOST_FALLBACK_ID = "reflex-dev-root"
+_SELECTOR_TOKEN = re.compile(
+    r"(?P<kind>[#.])(?P<value>[A-Za-z_][\w-]*)"
+    r"|\[(?P<attr>[A-Za-z_][\w-]*)(?:=(?P<quote>[\"']?)(?P<attr_value>[^\"'\]]*)(?P=quote))?\]"
+)
+
+
+def _embed_entry_task() -> tuple[str, str]:
+    template = (
+        constants.Templates.Dirs.WEB_TEMPLATE / constants.Embed.ENTRY_EMBED_TEMPLATE
+    )
+    return constants.Embed.ENTRY_PATH, template.read_text()
+
+
+def _embed_manifest_path_for(route: str) -> str:
+    """Translate a Reflex route into a React Router 7 path string.
+
+    Args:
+        route: The registered Reflex route (e.g. ``"index"``, ``"users/[id]"``).
+
+    Returns:
+        The React Router 7 path: ``""`` for the index (consumer treats empty
+        as the index route), ``"*"`` for the 404 slug or splat-catchall,
+        ``":name"`` for ``[name]``, ``":name?"`` for ``[[name]]``; static
+        parts pass through.
+    """
+    if route == constants.Page404.SLUG:
+        return "*"
+    if route == "index":
+        return ""
+    parts: list[str] = []
+    for part in route.split("/"):
+        if part == constants.RouteRegex.SPLAT_CATCHALL:
+            parts.append("*")
+            continue
+        optional = constants.RouteRegex.OPTIONAL_ARG.fullmatch(part)
+        if optional:
+            parts.append(":" + optional.group(1) + "?")
+            continue
+        arg = constants.RouteRegex.ARG.fullmatch(part)
+        if arg:
+            parts.append(":" + arg.group(1))
+            continue
+        parts.append(part)
+    return "/".join(parts)
+
+
+def _embed_manifest_entry(route: str) -> str:
+    from reflex.compiler.utils import get_page_import_specifier
+
+    path = _embed_manifest_path_for(route)
+    specifier = get_page_import_specifier(route)
+    return (
+        f"{{ path: {json.dumps(path)}, load: () => import({json.dumps(specifier)}) }}"
+    )
+
+
+def compile_embed_manifest(routes: Iterable[str]) -> tuple[str, str]:
+    """Emit the route manifest consumed by entry.client.js in embed mode.
+
+    Args:
+        routes: Registered Reflex routes (e.g. ``"index"``, ``"about"``,
+            ``"users/[id]"``, ``"404"``).
+
+    Returns:
+        The path and code of the manifest module.
+    """
+    from reflex.utils.prerequisites import get_web_dir
+
+    output_path = str(
+        get_web_dir() / constants.Dirs.PAGES / constants.Embed.MANIFEST_FILE
+    )
+    entries = [_embed_manifest_entry(route) for route in routes]
+    code = (
+        "// Generated by reflex; do not edit.\n"
+        "export default [\n" + "".join(f"  {entry},\n" for entry in entries) + "];\n"
+    )
+    return output_path, code
+
+
+def _embed_manifest_task(
+    unevaluated_pages: Sequence[UnevaluatedPage],
+) -> tuple[str, str]:
+    return compile_embed_manifest(page.route for page in unevaluated_pages)
+
+
+def _mount_attrs_for_selector(selector: str) -> tuple[dict[str, str], bool]:
+    """Translate a CSS selector into HTML attributes for the host wrapper.
+
+    Args:
+        selector: The ``mount_target`` selector configured on the plugin.
+
+    Returns:
+        ``(attrs, ok)`` where ``attrs`` is a mapping of attribute names to
+        values for the wrapper element and ``ok`` indicates whether the parsed
+        attributes are guaranteed to satisfy the selector.
+    """
+    attrs: dict[str, str] = {}
+    classes: list[str] = []
+    consumed = 0
+    for match in _SELECTOR_TOKEN.finditer(selector):
+        if match.start() != consumed:
+            break
+        consumed = match.end()
+        kind = match.group("kind")
+        if kind == "#":
+            attrs["id"] = match.group("value")
+        elif kind == ".":
+            classes.append(match.group("value"))
+        else:
+            attrs[match.group("attr")] = match.group("attr_value") or ""
+    if classes:
+        attrs["class"] = " ".join(classes)
+    ok = consumed == len(selector) and bool(attrs)
+    if not ok:
+        attrs = {"id": _DEV_HOST_FALLBACK_ID}
+    return attrs, ok
+
+
+def _format_attrs(attrs: dict[str, str]) -> str:
+    parts: list[str] = []
+    for name, value in attrs.items():
+        if value == "":
+            parts.append(name)
+        else:
+            parts.append(f'{name}="{html.escape(value, quote=True)}"')
+    return (" " + " ".join(parts)) if parts else ""
+
+
+def _render_dev_host_html(mount_target: str) -> str:
+    from reflex_base.utils import console
+
+    attrs, ok = _mount_attrs_for_selector(mount_target)
+    if not ok:
+        console.warn(
+            f"EmbedPlugin: dev_preview cannot synthesize an element for "
+            f"selector {mount_target!r}; using id={_DEV_HOST_FALLBACK_ID!r} "
+            "instead. Open a hand-written host page if your selector matches "
+            "something more complex."
+        )
+    return (
+        "<!doctype html>\n"
+        '<html lang="en">\n'
+        "<head>\n"
+        '<meta charset="utf-8" />\n'
+        '<meta name="viewport" content="width=device-width, initial-scale=1" />\n'
+        "<title>Reflex embed dev preview</title>\n"
+        "</head>\n"
+        "<body>\n"
+        f"<div{_format_attrs(attrs)}></div>\n"
+        f'<script type="module" src="/{constants.Embed.ENTRY_PATH}"></script>\n'
+        "</body>\n"
+        "</html>\n"
+    )
+
+
+_VITE_DEV_PREVIEW_PLUGIN_DEF = """
+function reflexEmbedDevPreview(html) {
+  return {
+    name: "reflex-embed-dev-preview",
+    enforce: "pre",
+    apply: "serve",
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const url = (req.url || "").split("?")[0];
+        if (url === "/" || url === "/index.html") {
+          res.setHeader("Content-Type", "text/html; charset=utf-8");
+          res.end(html);
+          return;
+        }
+        next();
+      });
+    }
+  };
+}
+"""
+
+
+def _inject_vite_dev_preview(mount_target: str):
+    """Build a modify task that registers the dev-preview Vite middleware.
+
+    Args:
+        mount_target: The selector used to synthesize the host wrapper element.
+
+    Returns:
+        A function suitable for ``add_modify_task`` that injects the plugin
+        definition into ``vite.config.js`` and prepends it to the plugins array.
+    """
+    html_literal = json.dumps(_render_dev_host_html(mount_target))
+    define_anchor = "export default defineConfig"
+    plugins_anchor = "alwaysUseReactDomServerNode(),"
+
+    def modify(content: str) -> str:
+        if "reflexEmbedDevPreview" in content:
+            return content
+        if define_anchor not in content or plugins_anchor not in content:
+            msg = (
+                "EmbedPlugin dev_preview cannot patch vite.config.js: expected "
+                f"anchors {define_anchor!r} and {plugins_anchor!r} were not "
+                "found. The Vite config template may have changed upstream."
+            )
+            raise RuntimeError(msg)
+        return content.replace(
+            define_anchor,
+            _VITE_DEV_PREVIEW_PLUGIN_DEF + "\nexport default defineConfig",
+            1,
+        ).replace(
+            plugins_anchor,
+            f"reflexEmbedDevPreview({html_literal}),\n    {plugins_anchor}",
+            1,
+        )
+
+    return modify
+
+
+@dataclass
+class EmbedPlugin(Plugin):
+    """Compile the app to mount into a host-page element instead of the document.
+
+    When ``mount_target`` is omitted, the value is read from the
+    ``REFLEX_MOUNT_TARGET`` environment variable so the plugin remains usable
+    when registered through ``REFLEX_PLUGINS`` (which instantiates plugins
+    with no constructor args). Same fallback for ``embed_origin`` /
+    ``REFLEX_EMBED_ORIGIN``.
+
+    When ``dev_preview`` is ``True``, a dev-only Vite middleware serves a
+    minimal host wrapper at ``http://localhost:3000/`` so the embedded app
+    can be previewed without a separately served host page. Off by default so
+    the bundle root stays predictable for production embeds.
+    """
+
+    mount_target: str | None = field(
+        default_factory=lambda: os.getenv("REFLEX_MOUNT_TARGET")
+    )
+    embed_origin: str | None = field(
+        default_factory=lambda: os.getenv("REFLEX_EMBED_ORIGIN")
+    )
+    dev_preview: bool = False
+
+    def __post_init__(self):
+        """Validate that a mount target is configured.
+
+        Raises:
+            ValueError: If neither the constructor arg nor
+                ``REFLEX_MOUNT_TARGET`` provides a value.
+        """
+        if not self.mount_target:
+            msg = (
+                "EmbedPlugin requires a mount_target (constructor arg or "
+                "REFLEX_MOUNT_TARGET environment variable)."
+            )
+            raise ValueError(msg)
+
+    def pre_compile(self, **context):
+        """Register save tasks for the embed entry and the route manifest.
+
+        Args:
+            context: The pre-compile plugin context.
+        """
+        context["add_save_task"](_embed_entry_task)
+        context["add_save_task"](_embed_manifest_task, context["unevaluated_pages"])
+        if self.dev_preview:
+            assert self.mount_target is not None
+            context["add_modify_task"](
+                constants.ReactRouter.VITE_CONFIG_FILE,
+                _inject_vite_dev_preview(self.mount_target),
+            )
+
+    def provides_entry_client(self) -> bool:
+        """Declare that EmbedPlugin emits its own ``entry.client.js``.
+
+        ``pre_compile`` registers ``_embed_entry_task`` which writes the
+        embed-aware entry template at ``constants.Embed.ENTRY_PATH``; the
+        framework's default ``update_entry_client`` must skip this path to
+        avoid stomping the embed entry on every compile.
+
+        Returns:
+            Always ``True``.
+        """
+        return True
+
+    def update_env_json(self, **context):
+        """Contribute the mount target so the embed entry can read it.
+
+        Args:
+            context: The context for the plugin.
+
+        Returns:
+            A mapping containing ``MOUNT_TARGET`` for ``.web/env.json``.
+        """
+        return {"MOUNT_TARGET": self.mount_target}
+
+    def post_build(self, **context):
+        """Re-emit the hashed Vite entry chunk at a stable host-page URL.
+
+        Vite hashes the entry chunk (``assets/entry.client-<hash>.js``), so a
+        host page can't ``<script src>`` it directly. Write a one-line
+        re-export shim at ``Embed.ENTRY_PATH`` so the same script tag works
+        against both dev (Vite serves the source file at the same URL) and
+        prod (this shim points at the hashed asset).
+
+        Args:
+            context: The post-build plugin context (carries ``static_dir``).
+
+        Raises:
+            RuntimeError: If the entry chunk can't be located or is ambiguous.
+        """
+        static_dir = context["static_dir"]
+        matches = list((static_dir / "assets").glob("entry.client-*.js"))
+        if len(matches) != 1:
+            msg = (
+                f"Expected exactly one Vite entry chunk under {static_dir / 'assets'}, "
+                f"found {len(matches)}: {[m.name for m in matches]}. "
+                "The embed bootloader cannot be emitted; the host page's "
+                f"<script src='/{constants.Embed.ENTRY_PATH}'> will 404."
+            )
+            raise RuntimeError(msg)
+        base = (self.embed_origin or "").rstrip("/")
+        hashed_url = f"{base}/assets/{matches[0].name}"
+        shim_path = static_dir / constants.Embed.ENTRY_PATH
+        shim_path.parent.mkdir(parents=True, exist_ok=True)
+        shim_path.write_text(f"import {json.dumps(hashed_url)};\n")
+
+
+def get_embed_plugin() -> EmbedPlugin | None:
+    """Return the EmbedPlugin instance from the active config, if any.
+
+    Returns:
+        The first ``EmbedPlugin`` registered in ``config.plugins``, or ``None``.
+    """
+    from reflex_base.config import get_config
+
+    return next(
+        (p for p in get_config().plugins if isinstance(p, EmbedPlugin)),
+        None,
+    )
diff --git a/reflex/compiler/compiler.py b/reflex/compiler/compiler.py
index 39ff4931a9e..5c5bad66eb0 100644
--- a/reflex/compiler/compiler.py
+++ b/reflex/compiler/compiler.py
@@ -1241,6 +1241,8 @@ def add_save_task(
             if page_file.is_file() and page_file not in keep_files:
                 page_file.unlink()
 
+    frontend_skeleton.update_entry_client()
+
     output_mapping: dict[Path, str] = {}
     for output_path, code in compile_results:
         path = utils.resolve_path_of_web_dir(output_path)
diff --git a/reflex/compiler/utils.py b/reflex/compiler/utils.py
index c2bdf618650..7f8fe249bf3 100644
--- a/reflex/compiler/utils.py
+++ b/reflex/compiler/utils.py
@@ -738,6 +738,20 @@ def get_page_path(path: str) -> str:
     )
 
 
+def get_page_import_specifier(path: str) -> str:
+    """Get the ``$``-aliased module specifier for the given page.
+
+    Args:
+        path: The path of the page.
+
+    Returns:
+        The import specifier (e.g. ``"$/pages/routes/users.$id._index"``).
+    """
+    return (
+        f"$/{constants.Dirs.PAGES}/{constants.Dirs.ROUTES}/{_path_to_file_stem(path)}"
+    )
+
+
 def get_theme_path() -> str:
     """Get the path of the base theme style.
 
diff --git a/reflex/plugins/__init__.py b/reflex/plugins/__init__.py
index 9bd4335ab02..e28a0c3cdde 100644
--- a/reflex/plugins/__init__.py
+++ b/reflex/plugins/__init__.py
@@ -6,6 +6,7 @@
     CompileContext,
     CompilerHooks,
     ComponentAndChildren,
+    EmbedPlugin,
     PageContext,
     Plugin,
     PreCompileContext,
@@ -13,6 +14,7 @@
     TailwindV3Plugin,
     TailwindV4Plugin,
     _ScreenshotPlugin,
+    embed,
     sitemap,
     tailwind_v3,
     tailwind_v4,
@@ -25,6 +27,7 @@
     "CompileContext",
     "CompilerHooks",
     "ComponentAndChildren",
+    "EmbedPlugin",
     "PageContext",
     "Plugin",
     "PreCompileContext",
@@ -33,6 +36,7 @@
     "TailwindV3Plugin",
     "TailwindV4Plugin",
     "_ScreenshotPlugin",
+    "embed",
     "sitemap",
     "tailwind_v3",
     "tailwind_v4",
diff --git a/reflex/utils/build.py b/reflex/utils/build.py
index c25bb5660c1..af42111687a 100644
--- a/reflex/utils/build.py
+++ b/reflex/utils/build.py
@@ -16,13 +16,19 @@
 
 def set_env_json():
     """Write the upload url to a REFLEX_JSON."""
+    config = get_config()
+    env: dict[str, object] = {
+        **{endpoint.name: endpoint.get_url() for endpoint in constants.Endpoint},
+        "TRANSPORT": config.transport,
+        "TEST_MODE": is_in_app_harness(),
+    }
+    for plugin in config.plugins:
+        contribution = plugin.update_env_json()
+        if contribution:
+            env.update(contribution)
     path_ops.update_json_file(
         str(prerequisites.get_web_dir() / constants.Dirs.ENV_JSON),
-        {
-            **{endpoint.name: endpoint.get_url() for endpoint in constants.Endpoint},
-            "TRANSPORT": get_config().transport,
-            "TEST_MODE": is_in_app_harness(),
-        },
+        env,
     )
 
 
@@ -228,28 +234,31 @@ def build():
         raise SystemExit(1)
     _duplicate_index_html_to_parent_directory(wdir / constants.Dirs.STATIC)
 
-    spa_fallback = wdir / constants.Dirs.STATIC / constants.ReactRouter.SPA_FALLBACK
+    config = get_config()
+    static_dir = wdir / constants.Dirs.STATIC
+    for plugin in config.plugins:
+        plugin.post_build(static_dir=static_dir)
+
+    spa_fallback = static_dir / constants.ReactRouter.SPA_FALLBACK
     if not spa_fallback.exists():
-        spa_fallback = wdir / constants.Dirs.STATIC / "index.html"
+        spa_fallback = static_dir / "index.html"
 
     if spa_fallback.exists():
         path_ops.cp(
             spa_fallback,
-            wdir / constants.Dirs.STATIC / "404.html",
+            static_dir / "404.html",
         )
 
-    config = get_config()
-
     if frontend_path := config.frontend_path.strip("/"):
         # Create a subdirectory that matches the configured frontend_path.
         frontend_path = PosixPath(frontend_path)
         first_part = frontend_path.parts[0]
-        for child in list((wdir / constants.Dirs.STATIC).iterdir()):
+        for child in list(static_dir.iterdir()):
             if child.is_dir() and child.name == first_part:
                 continue
             path_ops.mv(
                 child,
-                wdir / constants.Dirs.STATIC / frontend_path / child.name,
+                static_dir / frontend_path / child.name,
             )
 
 
diff --git a/reflex/utils/frontend_skeleton.py b/reflex/utils/frontend_skeleton.py
index dc60f5ae85b..e28903b3949 100644
--- a/reflex/utils/frontend_skeleton.py
+++ b/reflex/utils/frontend_skeleton.py
@@ -7,8 +7,10 @@
 from reflex_base import constants
 from reflex_base.config import Config, get_config
 from reflex_base.environment import environment
+from reflex_base.plugins.embed import get_embed_plugin
 
 from reflex.compiler import templates
+from reflex.compiler.utils import write_file
 from reflex.utils import console, path_ops
 from reflex.utils.prerequisites import get_project_hash, get_web_dir
 from reflex.utils.registry import get_npm_registry
@@ -181,27 +183,33 @@ def initialize_web_directory():
     init_reflex_json(project_hash=project_hash)
 
 
+def update_entry_client():
+    """Write ``.web/app/entry.client.js`` from the framework-mode template.
+
+    Skipped when any registered plugin reports ``provides_entry_client()`` —
+    that plugin emits its own variant via a save task and overwriting it
+    here would just be redone on the same compile.
+    """
+    if any(p.provides_entry_client() for p in get_config().plugins):
+        return
+    write_file(
+        get_web_dir() / constants.Embed.ENTRY_PATH,
+        (
+            constants.Templates.Dirs.WEB_TEMPLATE / constants.Embed.ENTRY_PATH
+        ).read_text(),
+    )
+
+
 def update_react_router_config(prerender_routes: bool = False):
     """Update react-router.config.js config from Reflex config.
 
     Args:
         prerender_routes: Whether to enable prerendering of routes.
     """
-    react_router_config_file_path = get_web_dir() / constants.ReactRouter.CONFIG_FILE
-
-    new_react_router_config = _update_react_router_config(
-        get_config(), prerender_routes=prerender_routes
-    )
-
-    # Overwriting the config file triggers a full server reload, so make sure
-    # there is actually a diff.
-    old_react_router_config = (
-        react_router_config_file_path.read_text()
-        if react_router_config_file_path.exists()
-        else ""
+    write_file(
+        get_web_dir() / constants.ReactRouter.CONFIG_FILE,
+        _update_react_router_config(get_config(), prerender_routes=prerender_routes),
     )
-    if old_react_router_config != new_react_router_config:
-        react_router_config_file_path.write_text(new_react_router_config)
 
 
 def _update_react_router_config(config: Config, prerender_routes: bool = False):
@@ -239,9 +247,14 @@ def initialize_package_json():
 
 
 def _compile_vite_config(config: Config):
-    # base must have exactly one trailing slash
+    base = config.prepend_frontend_path("/")
+    embed_plugin = get_embed_plugin()
+    if embed_plugin and embed_plugin.embed_origin:
+        # Cross-origin hosts must resolve assets against the bundle's server
+        # rather than their own document.baseURI.
+        base = embed_plugin.embed_origin.rstrip("/") + base
     return templates.vite_config_template(
-        base=config.prepend_frontend_path("/"),
+        base=base,
         hmr=environment.VITE_HMR.get(),
         force_full_reload=environment.VITE_FORCE_FULL_RELOAD.get(),
         experimental_hmr=environment.VITE_EXPERIMENTAL_HMR.get(),
diff --git a/reflex/utils/path_ops.py b/reflex/utils/path_ops.py
index 5ed2f8104aa..6e4da438e7d 100644
--- a/reflex/utils/path_ops.py
+++ b/reflex/utils/path_ops.py
@@ -224,7 +224,7 @@ def get_bun_path() -> Path | None:
     return bun_path.absolute() if bun_path else None
 
 
-def update_json_file(file_path: str | Path, update_dict: dict[str, int | str]):
+def update_json_file(file_path: str | Path, update_dict: dict[str, object]):
     """Update the contents of a json file.
 
     Args:
diff --git a/tests/integration/tests_playwright/test_mount_target.py b/tests/integration/tests_playwright/test_mount_target.py
new file mode 100644
index 00000000000..baf5d2c4531
--- /dev/null
+++ b/tests/integration/tests_playwright/test_mount_target.py
@@ -0,0 +1,169 @@
+"""Integration tests for the ``mount_target`` config option.
+
+Builds the app in prod mode with ``mount_target`` set, then serves a
+hand-written host HTML page that loads the bundle's entry script and contains
+``<div id="reflex-root">`` so we can verify the app mounts inside it instead of
+taking over ``<html>``/``<body>``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from pathlib import Path
+
+import pytest
+from playwright.sync_api import Page, expect
+from reflex_base import constants as base_constants
+
+import reflex.constants
+from reflex.testing import AppHarnessProd
+from reflex.utils.prerequisites import get_web_dir
+
+
+def MountTargetApp():
+    import reflex as rx
+
+    class S(rx.State):
+        n: int = 0
+        last_loaded_path: str = ""
+
+        @rx.event
+        def inc(self):
+            self.n += 1
+
+        @rx.event
+        def on_load_about(self):
+            self.last_loaded_path = self.router.url.path
+
+        @rx.event
+        def on_load_counter(self):
+            self.n += 1
+            self.last_loaded_path = self.router.url.path
+
+    def index():
+        return rx.box(
+            rx.text("count: ", S.n, id="count"),
+            rx.button("inc", on_click=S.inc, id="inc"),
+            rx.link("about", href="/about", id="link-about"),
+            rx.link("counter", href="/counter", id="link-counter"),
+            id="index-marker",
+        )
+
+    @rx.page(route="/about", on_load=S.on_load_about)
+    def about():
+        return rx.box(
+            rx.text("about page"),
+            rx.text("loaded: ", S.last_loaded_path, id="loaded-path"),
+            rx.link("home", href="/", id="link-home"),
+            id="about-marker",
+        )
+
+    @rx.page(route="/counter", on_load=S.on_load_counter)
+    def counter():
+        return rx.box(
+            rx.text("count: ", S.n, id="count"),
+            rx.text("loaded: ", S.last_loaded_path, id="loaded-path"),
+            id="counter-marker",
+        )
+
+    app = rx.App()
+    app.add_page(index)
+
+    # Set plugins after rx.App() because App.__post_init__ reloads the config
+    # from rxconfig.py and would wipe any earlier mutation.
+    config = rx.config.get_config()
+    config.plugins = [rx.plugins.EmbedPlugin(mount_target="#reflex-root")]
+
+
+@pytest.fixture(scope="module")
+def mount_target_app(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> Generator[AppHarnessProd, None, None]:
+    """Start MountTargetApp in prod mode with mount_target set.
+
+    Args:
+        tmp_path_factory: Pytest fixture.
+
+    Yields:
+        Running harness.
+    """
+    with AppHarnessProd.create(
+        root=tmp_path_factory.mktemp("mount_target_app"),
+        app_source=MountTargetApp,
+    ) as harness:
+        assert harness.app_instance is not None, "app is not running"
+        yield harness
+
+
+def _static_dir(harness: AppHarnessProd) -> Path:
+    return harness.app_path / get_web_dir() / reflex.constants.Dirs.STATIC
+
+
+def _write_host(static_dir: Path, name: str = "host.html") -> None:
+    entry_src = "/" + base_constants.Embed.ENTRY_PATH
+    host_html = f"""<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>host</title></head>
+<body>
+  <div data-host-marker="yes">host content above</div>
+  <div id="reflex-root"></div>
+  <div data-host-marker="yes">host content below</div>
+  <script type="module" src="{entry_src}"></script>
+</body>
+</html>
+"""
+    (static_dir / name).write_text(host_html)
+
+
+def test_app_mounts_into_host_container(mount_target_app: AppHarnessProd, page: Page):
+    """A host HTML page with #reflex-root receives the mounted app."""
+    static = _static_dir(mount_target_app)
+    _write_host(static)
+
+    base = mount_target_app.frontend_url
+    assert base is not None
+    page.goto(f"{base.rstrip('/')}/host.html")
+
+    expect(page.locator("#reflex-root #count")).to_contain_text("count:")
+    expect(page.locator('[data-host-marker="yes"]')).to_have_count(2)
+
+
+def test_in_widget_navigation_keeps_host_url(
+    mount_target_app: AppHarnessProd, page: Page
+):
+    """Clicking a Reflex link routes inside the widget; host URL stays put."""
+    static = _static_dir(mount_target_app)
+    _write_host(static)
+
+    base = mount_target_app.frontend_url
+    assert base is not None
+    host_url = f"{base.rstrip('/')}/host.html"
+    page.goto(host_url)
+
+    expect(page.locator("#reflex-root #index-marker")).to_be_visible()
+
+    page.locator("#reflex-root #link-about").click()
+
+    expect(page.locator("#reflex-root #about-marker")).to_be_visible()
+    # Host URL must not have changed despite the in-widget navigation.
+    assert page.url == host_url
+    # The about page's on_load handler writes the path it observed; the
+    # backend's route matcher only resolves the on_load if router_data.pathname
+    # is the in-widget URL "/about" (not the host's "/host.html").
+    expect(page.locator("#reflex-root #loaded-path")).to_have_text("loaded: /about")
+
+
+def test_on_load_fires_for_embedded_route(mount_target_app: AppHarnessProd, page: Page):
+    """An on_load handler tied to a non-index route fires after navigation."""
+    static = _static_dir(mount_target_app)
+    _write_host(static)
+
+    base = mount_target_app.frontend_url
+    assert base is not None
+    page.goto(f"{base.rstrip('/')}/host.html")
+
+    expect(page.locator("#reflex-root #count")).to_have_text("count: 0")
+    page.locator("#reflex-root #link-counter").click()
+    expect(page.locator("#reflex-root #counter-marker")).to_be_visible()
+    expect(page.locator("#reflex-root #count")).to_have_text("count: 1")
+    expect(page.locator("#reflex-root #loaded-path")).to_have_text("loaded: /counter")
diff --git a/tests/units/plugins/test_embed.py b/tests/units/plugins/test_embed.py
new file mode 100644
index 00000000000..d8efd11f536
--- /dev/null
+++ b/tests/units/plugins/test_embed.py
@@ -0,0 +1,272 @@
+"""Unit tests for the embed plugin."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+from pytest_mock import MockerFixture
+from reflex_base import constants
+from reflex_base.plugins.embed import (
+    EmbedPlugin,
+    _inject_vite_dev_preview,
+    _mount_attrs_for_selector,
+    _render_dev_host_html,
+    compile_embed_manifest,
+    get_embed_plugin,
+)
+
+from reflex.compiler import utils
+
+
+def test_explicit_args_set_fields():
+    plugin = EmbedPlugin(mount_target="#root", embed_origin="https://cdn.example")
+    assert plugin.mount_target == "#root"
+    assert plugin.embed_origin == "https://cdn.example"
+
+
+def test_env_fallback_populates_fields(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("REFLEX_MOUNT_TARGET", "#widget")
+    monkeypatch.setenv("REFLEX_EMBED_ORIGIN", "https://cdn.example")
+    plugin = EmbedPlugin()
+    assert plugin.mount_target == "#widget"
+    assert plugin.embed_origin == "https://cdn.example"
+
+
+def test_explicit_args_override_env(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("REFLEX_MOUNT_TARGET", "#env-target")
+    plugin = EmbedPlugin(mount_target="#explicit")
+    assert plugin.mount_target == "#explicit"
+
+
+def test_missing_mount_target_raises(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv("REFLEX_MOUNT_TARGET", raising=False)
+    monkeypatch.delenv("REFLEX_EMBED_ORIGIN", raising=False)
+    with pytest.raises(ValueError, match="mount_target"):
+        EmbedPlugin()
+
+
+def test_update_env_json_returns_mount_target():
+    plugin = EmbedPlugin(mount_target="#widget")
+    assert plugin.update_env_json() == {"MOUNT_TARGET": "#widget"}
+
+
+def test_provides_entry_client_is_true():
+    plugin = EmbedPlugin(mount_target="#widget")
+    assert plugin.provides_entry_client() is True
+
+
+def test_pre_compile_registers_save_tasks():
+    plugin = EmbedPlugin(mount_target="#root")
+    saved: list[tuple] = []
+
+    def add_save_task(task, *args, **kwargs):
+        saved.append((task, args, kwargs))
+
+    plugin.pre_compile(
+        add_save_task=add_save_task,
+        add_modify_task=lambda *_args, **_kwargs: None,
+        radix_themes_plugin=None,
+        unevaluated_pages=[],
+    )
+
+    assert len(saved) == 2
+    task_names = {task.__name__ for task, _, _ in saved}
+    assert task_names == {"_embed_entry_task", "_embed_manifest_task"}
+
+
+def test_get_embed_plugin_returns_instance(mocker: MockerFixture):
+    plugin = EmbedPlugin(mount_target="#root")
+    config = mocker.Mock()
+    config.plugins = [plugin]
+    mocker.patch("reflex_base.config.get_config", return_value=config)
+    assert get_embed_plugin() is plugin
+
+
+def test_get_embed_plugin_returns_none_when_absent(mocker: MockerFixture):
+    config = mocker.Mock()
+    config.plugins = []
+    mocker.patch("reflex_base.config.get_config", return_value=config)
+    assert get_embed_plugin() is None
+
+
+@pytest.mark.parametrize(
+    ("selector", "expected_attrs"),
+    [
+        ("#reflex-root", {"id": "reflex-root"}),
+        (".widget", {"class": "widget"}),
+        ("[data-mount]", {"data-mount": ""}),
+        ('[data-mount="x"]', {"data-mount": "x"}),
+        ("#reflex-root.widget", {"id": "reflex-root", "class": "widget"}),
+    ],
+)
+def test_mount_attrs_for_selector_parses_simple_selectors(
+    selector: str, expected_attrs: dict[str, str]
+):
+    attrs, ok = _mount_attrs_for_selector(selector)
+    assert ok is True
+    assert attrs == expected_attrs
+
+
+def test_mount_attrs_for_selector_falls_back_for_complex():
+    attrs, ok = _mount_attrs_for_selector("div > .child")
+    assert ok is False
+    assert attrs == {"id": "reflex-dev-root"}
+
+
+def test_render_dev_host_html_is_minimal():
+    html = _render_dev_host_html("#reflex-root")
+    assert 'id="reflex-root"' in html
+    assert 'src="/app/entry.client.js"' in html
+    assert "<style" not in html
+    assert "banner" not in html.lower()
+
+
+def _noop_save_task(task, *args, **kwargs) -> None:
+    return None
+
+
+def test_dev_preview_off_by_default_skips_modify_task():
+    plugin = EmbedPlugin(mount_target="#root")
+    modified: list = []
+    plugin.pre_compile(
+        add_save_task=_noop_save_task,
+        add_modify_task=lambda path, fn: modified.append((path, fn)),
+        radix_themes_plugin=None,
+        unevaluated_pages=[],
+    )
+    assert modified == []
+
+
+def test_dev_preview_enabled_registers_modify_task():
+    plugin = EmbedPlugin(mount_target="#root", dev_preview=True)
+    modified: list = []
+    plugin.pre_compile(
+        add_save_task=_noop_save_task,
+        add_modify_task=lambda path, fn: modified.append((path, fn)),
+        radix_themes_plugin=None,
+        unevaluated_pages=[],
+    )
+    assert any(path == "vite.config.js" for path, _ in modified)
+
+
+def test_inject_vite_dev_preview_adds_plugin_to_array():
+    original = (
+        'import { reactRouter } from "@react-router/dev/vite";\n'
+        "function alwaysUseReactDomServerNode() { return {}; }\n"
+        "export default defineConfig((config) => ({\n"
+        '  base: "/",\n'
+        "  plugins: [\n"
+        "    alwaysUseReactDomServerNode(),\n"
+        "    reactRouter(),\n"
+        "  ],\n"
+        "}));\n"
+    )
+    modify = _inject_vite_dev_preview("#reflex-root")
+    out = modify(original)
+    assert "function reflexEmbedDevPreview" in out
+    assert out.index("reflexEmbedDevPreview(") < out.index(
+        "alwaysUseReactDomServerNode(),"
+    )
+
+
+def test_inject_vite_dev_preview_is_idempotent():
+    original = (
+        "function reflexEmbedDevPreview() {}\n"
+        "export default defineConfig((config) => ({}));"
+    )
+    modify = _inject_vite_dev_preview("#reflex-root")
+    assert modify(original) == original
+
+
+_ENTRY_RE = re.compile(
+    r'\{\s*path:\s*"([^"]*)",\s*load:\s*\(\)\s*=>\s*import\("([^"]*)"\)\s*\}'
+)
+
+
+def test_compile_embed_manifest_pairs_translated_paths_with_specifiers(
+    mocker: MockerFixture, tmp_path: Path
+):
+    """Each route produces one entry pairing its React-Router path with its import specifier."""
+    mocker.patch("reflex.utils.prerequisites.get_web_dir", return_value=tmp_path)
+
+    routes = [
+        "index",
+        "users/[id]",
+        "posts/[[slug]]",
+        "docs/[[...splat]]",
+        constants.Page404.SLUG,
+    ]
+    expected_pairs = [
+        ("", utils.get_page_import_specifier("index")),
+        ("users/:id", utils.get_page_import_specifier("users/[id]")),
+        ("posts/:slug?", utils.get_page_import_specifier("posts/[[slug]]")),
+        ("docs/*", utils.get_page_import_specifier("docs/[[...splat]]")),
+        ("*", utils.get_page_import_specifier(constants.Page404.SLUG)),
+    ]
+
+    output_path, code = compile_embed_manifest(routes)
+
+    assert output_path == str(
+        tmp_path / constants.Dirs.PAGES / constants.Embed.MANIFEST_FILE
+    )
+    assert _ENTRY_RE.findall(code) == expected_pairs
+
+
+def _make_static_dir(tmp_path: Path, entry_names: list[str]) -> Path:
+    """Create a fake Vite static dir with ``assets/<name>`` for each entry.
+
+    Returns:
+        The created static-dir path.
+    """
+    static_dir = tmp_path / "client"
+    assets = static_dir / "assets"
+    assets.mkdir(parents=True)
+    for name in entry_names:
+        (assets / name).write_text("// chunk\n")
+    return static_dir
+
+
+def test_post_build_emits_shim_pointing_at_hashed_asset(tmp_path: Path):
+    static_dir = _make_static_dir(tmp_path, ["entry.client-abc123.js"])
+    plugin = EmbedPlugin(mount_target="#root")
+
+    plugin.post_build(static_dir=static_dir)
+
+    shim = static_dir / constants.Embed.ENTRY_PATH
+    assert shim.exists()
+    assert shim.read_text() == 'import "/assets/entry.client-abc123.js";\n'
+
+
+def test_post_build_prefixes_embed_origin(tmp_path: Path):
+    static_dir = _make_static_dir(tmp_path, ["entry.client-deadbeef.js"])
+    plugin = EmbedPlugin(mount_target="#root", embed_origin="https://cdn.example.com/")
+
+    plugin.post_build(static_dir=static_dir)
+
+    shim = static_dir / constants.Embed.ENTRY_PATH
+    assert (
+        shim.read_text()
+        == 'import "https://cdn.example.com/assets/entry.client-deadbeef.js";\n'
+    )
+
+
+def test_post_build_raises_when_no_entry_chunk(tmp_path: Path):
+    static_dir = _make_static_dir(tmp_path, [])
+    plugin = EmbedPlugin(mount_target="#root")
+
+    with pytest.raises(RuntimeError, match="Expected exactly one Vite entry chunk"):
+        plugin.post_build(static_dir=static_dir)
+
+
+def test_post_build_raises_when_multiple_entry_chunks(tmp_path: Path):
+    static_dir = _make_static_dir(
+        tmp_path, ["entry.client-aaa.js", "entry.client-bbb.js"]
+    )
+    plugin = EmbedPlugin(mount_target="#root")
+
+    with pytest.raises(
+        RuntimeError, match=r"Expected exactly one Vite entry chunk.*found 2: \["
+    ):
+        plugin.post_build(static_dir=static_dir)
diff --git a/tests/units/utils/test_build.py b/tests/units/utils/test_build.py
new file mode 100644
index 00000000000..86f6aa8637e
--- /dev/null
+++ b/tests/units/utils/test_build.py
@@ -0,0 +1,74 @@
+"""Tests for reflex.utils.build."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pytest_mock import MockerFixture
+
+from reflex.plugins import EmbedPlugin, Plugin
+from reflex.utils import build
+
+
+def _patch_env_json(
+    mocker: MockerFixture, tmp_path: Path, plugins: list[Plugin] | None = None
+):
+    web_dir = tmp_path / ".web"
+    web_dir.mkdir()
+    mocker.patch("reflex.utils.build.prerequisites.get_web_dir", return_value=web_dir)
+    config = mocker.Mock()
+    config.transport = "websocket"
+    config.plugins = plugins or []
+    mocker.patch("reflex.utils.build.get_config", return_value=config)
+    mocker.patch("reflex.utils.build.is_in_app_harness", return_value=False)
+    return web_dir
+
+
+def test_set_env_json_merges_plugin_contributions(
+    tmp_path: Path, mocker: MockerFixture
+):
+    """``update_env_json`` returns merge on top of the base env dict."""
+    web_dir = _patch_env_json(
+        mocker, tmp_path, plugins=[EmbedPlugin(mount_target="#reflex-root")]
+    )
+
+    build.set_env_json()
+
+    env = json.loads((web_dir / "env.json").read_text())
+    assert env["MOUNT_TARGET"] == "#reflex-root"
+    assert env["TRANSPORT"] == "websocket"
+
+
+def test_set_env_json_omits_plugin_keys_when_plugin_absent(
+    tmp_path: Path, mocker: MockerFixture
+):
+    """Plugin-contributed keys are absent from env.json when no plugin contributes."""
+    web_dir = _patch_env_json(mocker, tmp_path, plugins=[])
+
+    build.set_env_json()
+
+    env = json.loads((web_dir / "env.json").read_text())
+    assert "MOUNT_TARGET" not in env
+    assert env["TRANSPORT"] == "websocket"
+
+
+def test_set_env_json_later_plugin_wins(tmp_path: Path, mocker: MockerFixture):
+    """Later plugins override earlier ones on conflicting keys."""
+
+    class FirstPlugin(Plugin):
+        def update_env_json(self, **context):
+            return {"SHARED": "first", "ONLY_FIRST": 1}
+
+    class SecondPlugin(Plugin):
+        def update_env_json(self, **context):
+            return {"SHARED": "second", "ONLY_SECOND": 2}
+
+    web_dir = _patch_env_json(mocker, tmp_path, plugins=[FirstPlugin(), SecondPlugin()])
+
+    build.set_env_json()
+
+    env = json.loads((web_dir / "env.json").read_text())
+    assert env["SHARED"] == "second"
+    assert env["ONLY_FIRST"] == 1
+    assert env["ONLY_SECOND"] == 2