You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Proposal: mount Framework Mode (SPA / API-only) apps into an arbitrary DOM element with a custom history
#15768
API-only Mode (ssr: "unstable_api-only" + unstable_apiServerOrigin + unstable_fetch) almost lets a Framework Mode app be embedded in a page it doesn't own, for example as a Web Component (<my-app></my-app>) inside a CMS page served from another origin. The server side already works as-is. The client entry is what blocks it:
HydratedRouter hardcodes createBrowserHistory().
The bootstrap state (__reactRouterContext, __reactRouterManifest, __reactRouterRouteModules) is only emitted as inline scripts inside index.html.
That state lives in un-namespaced window globals, so only one Framework Mode app can exist per page.
I'd like to propose small, opt-in APIs so this use case doesn't need to fork HydratedRouter.
Motivation
My organization have a CMS-managed site that embed small "system" screens. Today these are usually <iframe>s, which bring fixed heights, postMessage resizing hacks, modals trapped inside the frame, and broken focus and scroll.
As alternative, we are using in some new pages a custom element that renders a React SPA (Data Mode with createHashRouter), loaded with a single script tag:
This works well, but it gives up everything Framework Mode offers: server loader/action, typegen, automatic revalidation, and route-level code splitting. API-only Mode is the missing server half. The client half needs to:
render into an element (createRoot(el)) instead of hydrating document;
use hash (or memory) history, so the embedded app doesn't take over the host page's pathname;
be bootstrapped from a JS module instead of an HTML document.
Current workaround (working POC)
Fork of HydratedRouter (~150 lines). It reuses the same UNSAFE_* exports (createClientRoutes, getTurboStreamSingleFetchDataStrategy, getPatchRoutesOnNavigationFunction, useFogOFWarDiscovery, FrameworkContext, RemixErrorBoundary, createRouter). The only meaningful change is:
It also skips decoding the shell's turbo-stream, because in SPA mode that data was captured at build time and only root loader data is used anyway.
entry.client.tsx exports mount(el), which calls createRoot(el).render(<HashHydratedRouter unstable_fetch={…} />).
A buildEnd hook parses build/client/index.html with regexes. It extracts the context JSON, the manifest URL, the root route module URL and the entry URL, and writes screen-xpto.js. That file sets the globals, imports the modules and calls customElements.define(...).
Vite base is an absolute URL, so all chunk and manifest URLs work cross-origin.
The root Layout renders <html>…<Scripts/> only during the shell prerender, and only children in the browser.
Everything else works unchanged: lazy route discovery against unstable_apiServerOrigin, .data GET/POST, revalidation after actions, allowedActionOrigins, custom fetch with credentials: "include", and deep links via #/route.
The fragile parts are the fork (it depends on UNSAFE_* internals) and the HTML scraping (it depends on the shape of the generated index.html).
Proposal
These are independent and incremental. Any one of them helps.
1. Allow a custom history in HydratedRouter (smallest change)
<HydratedRouterunstable_history={createHashHistory()}/>// or a factory, so it's created once with the router singleton:<HydratedRouterunstable_createHistory={()=>createHashHistory()}/>
In SPA / API-only mode, nothing in hydration depends on window.location.pathname other than the initial location, which the history provides. Together with rendering via createRoot(el) instead of hydrateRoot(document), this would remove the need for the fork. Today it already works if the root Layout doesn't render <html>.
2. Emit a JS bootstrap module alongside index.html
For example, build/client/__reactRouterBootstrap.js (or a buildManifest entry exposed to buildEnd). It would contain what the inline scripts of index.html contain today: the context, the manifest import, and the root route module import. It would export a promise or function instead of auto-importing entry.client:
import{bootstrap}from"https://my.app/__reactRouterBootstrap.js";awaitbootstrap();// sets up context/manifest/route modulesconst{ mount }=awaitimport(/* entry */);
This lets integrators wrap the app in a custom element, a micro-frontend shell, or a browser extension without scraping HTML.
3. Namespaced bootstrap state (to allow multiple apps per page)
Instead of fixed window.__reactRouter* globals, read the state from an object passed explicitly:
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Summary
API-only Mode (
ssr: "unstable_api-only"+unstable_apiServerOrigin+unstable_fetch) almost lets a Framework Mode app be embedded in a page it doesn't own, for example as a Web Component (<my-app></my-app>) inside a CMS page served from another origin. The server side already works as-is. The client entry is what blocks it:HydratedRouterhardcodescreateBrowserHistory().__reactRouterContext,__reactRouterManifest,__reactRouterRouteModules) is only emitted as inline scripts insideindex.html.windowglobals, so only one Framework Mode app can exist per page.I'd like to propose small, opt-in APIs so this use case doesn't need to fork
HydratedRouter.Motivation
My organization have a CMS-managed site that embed small "system" screens. Today these are usually
<iframe>s, which bring fixed heights,postMessageresizing hacks, modals trapped inside the frame, and broken focus and scroll.As alternative, we are using in some new pages a custom element that renders a React SPA (Data Mode with
createHashRouter), loaded with a single script tag:This works well, but it gives up everything Framework Mode offers: server
loader/action, typegen, automatic revalidation, and route-level code splitting. API-only Mode is the missing server half. The client half needs to:createRoot(el)) instead of hydratingdocument;Current workaround (working POC)
HydratedRouter(~150 lines). It reuses the sameUNSAFE_*exports (createClientRoutes,getTurboStreamSingleFetchDataStrategy,getPatchRoutesOnNavigationFunction,useFogOFWarDiscovery,FrameworkContext,RemixErrorBoundary,createRouter). The only meaningful change is:entry.client.tsxexportsmount(el), which callscreateRoot(el).render(<HashHydratedRouter unstable_fetch={…} />).buildEndhook parsesbuild/client/index.htmlwith regexes. It extracts the context JSON, the manifest URL, the root route module URL and the entry URL, and writesscreen-xpto.js. That file sets the globals, imports the modules and callscustomElements.define(...).baseis an absolute URL, so all chunk and manifest URLs work cross-origin.Layoutrenders<html>…<Scripts/>only during the shell prerender, and onlychildrenin the browser.Everything else works unchanged: lazy route discovery against
unstable_apiServerOrigin,.dataGET/POST, revalidation after actions,allowedActionOrigins, custom fetch withcredentials: "include", and deep links via#/route.The fragile parts are the fork (it depends on
UNSAFE_*internals) and the HTML scraping (it depends on the shape of the generatedindex.html).Proposal
These are independent and incremental. Any one of them helps.
1. Allow a custom history in
HydratedRouter(smallest change)In SPA / API-only mode, nothing in hydration depends on
window.location.pathnameother than the initial location, which the history provides. Together with rendering viacreateRoot(el)instead ofhydrateRoot(document), this would remove the need for the fork. Today it already works if the rootLayoutdoesn't render<html>.2. Emit a JS bootstrap module alongside
index.htmlFor example,
build/client/__reactRouterBootstrap.js(or abuildManifestentry exposed tobuildEnd). It would contain what the inline scripts ofindex.htmlcontain today: the context, the manifest import, and the root route module import. It would export a promise or function instead of auto-importingentry.client:This lets integrators wrap the app in a custom element, a micro-frontend shell, or a browser extension without scraping HTML.
3. Namespaced bootstrap state (to allow multiple apps per page)
Instead of fixed
window.__reactRouter*globals, read the state from an object passed explicitly:Or key it by an app id. Today two independent Framework Mode apps on the same page overwrite each other's globals.
Environment
ssr: "unstable_api-only",unstable_apiServerOriginset,allowedActionOriginssetHappy to to contribute a PR for option 1 if the team is open to it.
All reactions