+
- React Recipes
+ Multi-Framework Recipes — {FRAMEWORK_LABEL[framework]}
- Sample patterns for building React web apps on Salesforce
+ Sample patterns for Salesforce-Hosted and Externally Hosted apps.
+ React today; Vue and Angular planned.
+ {/* Hosting filter */}
+
+
Hosting:
+
+ {HOSTING_FILTER_OPTIONS.map((option, i) => {
+ const active = filter === option.value;
+ return (
+ activate(option.value)}
+ onKeyDown={(e) => onFilterKeyDown(e, i)}
+ className={cn(
+ 'rounded-md px-3 py-1 text-xs font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+ active
+ ? 'bg-primary text-primary-foreground shadow-sm'
+ : 'text-muted-foreground hover:text-foreground'
+ )}
+ >
+ {option.label}
+
+ );
+ })}
+
+
+
{/* Category tiles */}
- {categories.map(cat => (
-
navigate(cat.to)}
- className="text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-xl"
- >
-
-
-
-
- {cat.name}
-
-
- {getRecipeCount(cat.to)} recipes
-
-
-
- {cat.description}
-
-
-
-
- ))}
+ {visibleCategories.map((cat) => {
+ const hosting = getCategoryHosting(cat.to);
+ const fw = getCategoryFramework(cat.to);
+ const flavors =
+ hosting && fw ? [{ hosting, framework: fw }] : [];
+ return (
+
navigate(cat.to)}
+ className="text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-xl"
+ >
+
+
+
+
+ {cat.name}
+
+
+ {getRecipeCount(cat.to)} recipes
+
+
+ {flavors.length > 0 && (
+
+ {cat.description}
+
+
+
+
+ );
+ })}
+ {visibleCategories.length === 0 && (
+
+ No categories match this hosting filter yet.
+
+ )}
+
+ {/* Hosting Models block */}
+
+ Hosting Models
+
+ Two ways to ship a framework app on Salesforce. Pick the one that
+ matches where your app lives.
+
+
+
+
+ Want to run your own server locally with SSL?{' '}
+
+ {EXTERNAL_LINKS.serverRepo.label}
+ {EXTERNAL_LINKS.serverRepo.placeholder ? ' (coming soon)' : ''}
+
+ .
+
+
);
}
+
+interface HostingModelCardProps {
+ icon: React.ReactNode;
+ title: string;
+ blurb: string;
+ onClick: () => void;
+}
+
+function HostingModelCard({ icon, title, blurb, onClick }: HostingModelCardProps) {
+ return (
+
+
+
+
+ {icon}
+ {title}
+
+
+ {blurb}
+
+
+
+
+ );
+}
+
diff --git a/force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Mfe.tsx b/force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Mfe.tsx
new file mode 100644
index 0000000..e98b7c8
--- /dev/null
+++ b/force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Mfe.tsx
@@ -0,0 +1,466 @@
+/**
+ * Embedding recipes page.
+ *
+ * Each recipe has one or more flavors (hosting × framework). The MFE-style
+ * recipes here ship Externally-Hosted React only today; SF-Hosted and
+ * Vue/Angular flavors are wired as disabled "(soon)" tabs so users can see
+ * the IA without us hiding the future surface.
+ *
+ * Source files: Guest (in mfe-app/), LWC host JS, LWC host HTML — all imported
+ * via ?shiki so the code shown is always current.
+ */
+import { useState } from 'react';
+import { useSearchParams } from 'react-router';
+import { ExternalLink, Info } from 'lucide-react';
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs';
+import {
+ Card,
+ CardHeader,
+ CardTitle,
+ CardDescription,
+ CardContent,
+} from '@/components/ui/card';
+import { cn } from '@/lib/utils';
+import CodeBlock from '@/components/app/CodeBlock';
+import { EXTERNAL_LINKS } from '@/lib/links';
+import {
+ FRAMEWORKS,
+ FRAMEWORK_LABEL,
+ HOSTING_LABEL,
+ HOSTING_PARAM_TO_VALUE,
+ HOSTING_VALUE_TO_PARAM,
+ SOON_LABEL,
+ isFramework,
+ isFrameworkEnabled,
+} from '@/lib/framework';
+import type { Framework, Hosting } from '@/recipeRegistry';
+
+// MFE bridge sources (mfe-app/src/recipes/)
+import basicEmbedMfe from '../../../../../../../mfe-app/src/recipes/BasicEmbed.tsx?shiki';
+import receiveDataMfe from '../../../../../../../mfe-app/src/recipes/ReceiveData.tsx?shiki';
+import sendEventMfe from '../../../../../../../mfe-app/src/recipes/SendEvent.tsx?shiki';
+import autoResizeMfe from '../../../../../../../mfe-app/src/recipes/AutoResize.tsx?shiki';
+import themeTokensMfe from '../../../../../../../mfe-app/src/recipes/ThemeTokens.tsx?shiki';
+import dirtyStateMfe from '../../../../../../../mfe-app/src/recipes/DirtyState.tsx?shiki';
+import graphQLMfe from '../../../../../../../mfe-app/src/recipes/GraphQLBridge.tsx?shiki';
+
+// LWC host JS sources (force-app/main/default/lwc/)
+import basicEmbedJs from '../../../../../default/lwc/mfeBasicEmbed/mfeBasicEmbed.js?shiki=js';
+import receiveDataJs from '../../../../../default/lwc/mfeReceiveData/mfeReceiveData.js?shiki=js';
+import sendEventJs from '../../../../../default/lwc/mfeSendEvent/mfeSendEvent.js?shiki=js';
+import autoResizeJs from '../../../../../default/lwc/mfeAutoResize/mfeAutoResize.js?shiki=js';
+import themeTokensJs from '../../../../../default/lwc/mfeThemeTokens/mfeThemeTokens.js?shiki=js';
+import dirtyStateJs from '../../../../../default/lwc/mfeDirtyState/mfeDirtyState.js?shiki=js';
+import graphQLJs from '../../../../../default/lwc/mfeGraphQL/mfeGraphQL.js?shiki=js';
+
+// LWC host HTML sources (force-app/main/default/lwc/)
+import basicEmbedHtml from '../../../../../default/lwc/mfeBasicEmbed/mfeBasicEmbed.html?shiki=html';
+import receiveDataHtml from '../../../../../default/lwc/mfeReceiveData/mfeReceiveData.html?shiki=html';
+import sendEventHtml from '../../../../../default/lwc/mfeSendEvent/mfeSendEvent.html?shiki=html';
+import autoResizeHtml from '../../../../../default/lwc/mfeAutoResize/mfeAutoResize.html?shiki=html';
+import themeTokensHtml from '../../../../../default/lwc/mfeThemeTokens/mfeThemeTokens.html?shiki=html';
+import dirtyStateHtml from '../../../../../default/lwc/mfeDirtyState/mfeDirtyState.html?shiki=html';
+import graphQLHtml from '../../../../../default/lwc/mfeGraphQL/mfeGraphQL.html?shiki=html';
+
+interface FlavorSources {
+ mfeSource: string;
+ lwcJsSource: string;
+ lwcHtmlSource: string;
+}
+
+interface MfeRecipeFlavor extends FlavorSources {
+ hosting: Hosting;
+ framework: Framework;
+}
+
+interface MfeRecipe {
+ name: string;
+ description: string;
+ flavors: MfeRecipeFlavor[];
+}
+
+const recipes: MfeRecipe[] = [
+ {
+ name: 'Basic Embed',
+ description:
+ 'Minimum viable lwc-shell embed. The host creates the shell, sets src and sandbox, and listens for widget-ready. The MFE uses bridge.isConnected() to detect the embedding context.',
+ flavors: [
+ {
+ hosting: 'externally-hosted',
+ framework: 'react',
+ mfeSource: basicEmbedMfe,
+ lwcJsSource: basicEmbedJs,
+ lwcHtmlSource: basicEmbedHtml,
+ },
+ ],
+ },
+ {
+ name: 'Receive Data',
+ description:
+ "Host pushes data into the MFE via shell.updateData(). The MFE receives it with bridge.addEventListener('data', handler).",
+ flavors: [
+ {
+ hosting: 'externally-hosted',
+ framework: 'react',
+ mfeSource: receiveDataMfe,
+ lwcJsSource: receiveDataJs,
+ lwcHtmlSource: receiveDataHtml,
+ },
+ ],
+ },
+ {
+ name: 'Send Event',
+ description:
+ 'MFE dispatches custom events to the host via bridge.dispatchEvent(). The host catches them as DOM events on the shell element.',
+ flavors: [
+ {
+ hosting: 'externally-hosted',
+ framework: 'react',
+ mfeSource: sendEventMfe,
+ lwcJsSource: sendEventJs,
+ lwcHtmlSource: sendEventHtml,
+ },
+ ],
+ },
+ {
+ name: 'Auto-Resize',
+ description:
+ 'Iframe height follows MFE content via a ResizeObserver inside the iframe. No fixed height on the shell. Cancel the resize event to opt out.',
+ flavors: [
+ {
+ hosting: 'externally-hosted',
+ framework: 'react',
+ mfeSource: autoResizeMfe,
+ lwcJsSource: autoResizeJs,
+ lwcHtmlSource: autoResizeHtml,
+ },
+ ],
+ },
+ {
+ name: 'Theme Tokens',
+ description:
+ 'Salesforce CSS custom properties are sent to the MFE on connect. The MFE applies them to document.documentElement. Call shell.refreshTheme() to re-sync.',
+ flavors: [
+ {
+ hosting: 'externally-hosted',
+ framework: 'react',
+ mfeSource: themeTokensMfe,
+ lwcJsSource: themeTokensJs,
+ lwcHtmlSource: themeTokensHtml,
+ },
+ ],
+ },
+ {
+ name: 'Dirty State',
+ description:
+ 'MFE notifies the host of unsaved changes via trackdirtystate events. The host can show a warning and block navigation.',
+ flavors: [
+ {
+ hosting: 'externally-hosted',
+ framework: 'react',
+ mfeSource: dirtyStateMfe,
+ lwcJsSource: dirtyStateJs,
+ lwcHtmlSource: dirtyStateHtml,
+ },
+ ],
+ },
+ {
+ name: 'GraphQL Bridge',
+ description:
+ 'MFE executes Salesforce GraphQL via bridge.graphql(). The host proxies requests — no allow-same-origin needed. Up to 10 concurrent requests with automatic queuing.',
+ flavors: [
+ {
+ hosting: 'externally-hosted',
+ framework: 'react',
+ mfeSource: graphQLMfe,
+ lwcJsSource: graphQLJs,
+ lwcHtmlSource: graphQLHtml,
+ },
+ ],
+ },
+];
+
+const HOSTINGS: Hosting[] = ['externally-hosted', 'salesforce-hosted'];
+
+function findFlavor(
+ recipe: MfeRecipe,
+ hosting?: Hosting,
+ framework?: Framework
+): MfeRecipeFlavor {
+ if (hosting && framework) {
+ const exact = recipe.flavors.find(
+ (f) => f.hosting === hosting && f.framework === framework
+ );
+ if (exact) return exact;
+ }
+ if (hosting) {
+ const byHosting = recipe.flavors.find((f) => f.hosting === hosting);
+ if (byHosting) return byHosting;
+ }
+ if (framework) {
+ const byFramework = recipe.flavors.find((f) => f.framework === framework);
+ if (byFramework) return byFramework;
+ }
+ return recipe.flavors[0];
+}
+
+export default function Mfe() {
+ const [selectedIndex, setSelectedIndex] = useState(0);
+ const selected = recipes[selectedIndex];
+ const [searchParams, setSearchParams] = useSearchParams();
+
+ // Parse URL flavor params (host, fw) and resolve via fallback. The URL is
+ // corrected via replaceState so an unknown combination doesn't pollute back.
+ const hostParam = searchParams.get('host');
+ const fwParam = searchParams.get('fw');
+ const requestedHosting = hostParam ? HOSTING_PARAM_TO_VALUE[hostParam] : undefined;
+ const requestedFramework =
+ fwParam && isFramework(fwParam) ? fwParam : undefined;
+ const flavor = findFlavor(selected, requestedHosting, requestedFramework);
+
+ function selectFlavor(hosting: Hosting, framework: Framework) {
+ const next = new URLSearchParams(searchParams);
+ next.set('host', HOSTING_VALUE_TO_PARAM[hosting]);
+ next.set('fw', framework);
+ if (searchParams.get('recipe')) {
+ next.set('recipe', searchParams.get('recipe')!);
+ }
+ setSearchParams(next, { replace: true });
+ }
+
+ const isExternallyHosted = flavor.hosting === 'externally-hosted';
+
+ return (
+
+
+
+
Embedding
+
+ {HOSTING_LABEL[flavor.hosting]} · {FRAMEWORK_LABEL[flavor.framework]}
+
+
+
+ An external framework app embedded into Salesforce via{' '}
+ lwc-shell. The Platform SDK (bridge)
+ is the shared contract; a Salesforce-Hosted flavor is planned.
+
+
+
+
+
+ {/* Sidebar */}
+
+
+ {recipes.map((recipe, i) => (
+
+ setSelectedIndex(i)}
+ className={cn(
+ 'w-full text-left px-3 py-2 text-sm rounded-md transition-colors',
+ i === selectedIndex
+ ? 'bg-primary text-primary-foreground font-medium shadow-sm'
+ : 'text-muted-foreground hover:text-foreground hover:bg-accent'
+ )}
+ >
+ {recipe.name}
+
+
+ ))}
+
+
+
+ {/* Recipe card */}
+
+
+ {selected.name}
+ {selected.description}
+
+ {/* Flavor switcher: Hosting */}
+
+ {HOSTINGS.map((h) => {
+ const enabled = recipe_hasFlavor(selected, h, flavor.framework);
+ const active = flavor.hosting === h;
+ return (
+ selectFlavor(h, flavor.framework)}
+ title={
+ enabled
+ ? undefined
+ : `${HOSTING_LABEL[h]} flavor ${SOON_LABEL}`
+ }
+ >
+ {HOSTING_LABEL[h]}
+ {!enabled &&
+ );
+ })}
+
+
+ {/* Flavor switcher: Framework */}
+
+ {FRAMEWORKS.map((f) => {
+ const frameworkAvailable = isFrameworkEnabled(f);
+ const flavorAvailable =
+ frameworkAvailable && recipe_hasFlavor(selected, flavor.hosting, f);
+ const active = flavor.framework === f;
+ return (
+ selectFlavor(flavor.hosting, f)}
+ title={
+ flavorAvailable
+ ? undefined
+ : `${FRAMEWORK_LABEL[f]} flavor ${SOON_LABEL}`
+ }
+ >
+ {FRAMEWORK_LABEL[f]}
+ {!flavorAvailable &&
+ );
+ })}
+
+
+ {isExternallyHosted && (
+
+ )}
+
+
+
+
+
+ Guest ({FRAMEWORK_LABEL[flavor.framework]})
+
+ Host (LWC JS)
+ Host (LWC HTML)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ );
+}
+
+function recipe_hasFlavor(
+ recipe: MfeRecipe,
+ hosting: Hosting,
+ framework: Framework
+): boolean {
+ return recipe.flavors.some(
+ (f) => f.hosting === hosting && f.framework === framework
+ );
+}
+
+interface FlavorRowProps {
+ label: string;
+ role: 'tablist' | 'radiogroup';
+ ariaLabel: string;
+ children: React.ReactNode;
+}
+
+function FlavorRow({ label, role, ariaLabel, children }: FlavorRowProps) {
+ return (
+
+
{label}
+
+ {children}
+
+
+ );
+}
+
+interface FlavorButtonProps {
+ active: boolean;
+ enabled: boolean;
+ onClick: () => void;
+ title?: string;
+ children: React.ReactNode;
+}
+
+function FlavorButton({
+ active,
+ enabled,
+ onClick,
+ title,
+ children,
+}: FlavorButtonProps) {
+ return (
+
+ {children}
+
+ );
+}
+
+function SoonTag() {
+ return (
+
+ {SOON_LABEL}
+
+ );
+}
diff --git a/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipeRegistry.ts b/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipeRegistry.ts
index 3a3d7b2..f5d5dcc 100644
--- a/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipeRegistry.ts
+++ b/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipeRegistry.ts
@@ -1,19 +1,59 @@
/**
* Central registry of all recipes, keyed by category route.
- * Each entry stores the recipe name, description, and the category it belongs to.
- * Used by the Home page for counts and by the global search bar for filtering.
+ *
+ * Each recipe has one or more flavors — a (hosting, framework) pair plus
+ * optional flavor-specific source imports. The first flavor is the default
+ * shown to users; "(soon)" UI states reference flavors that are not yet built.
*/
+export type Hosting = 'salesforce-hosted' | 'externally-hosted';
+export type Framework = 'react' | 'vue' | 'angular';
+
+export interface RecipeFlavor {
+ hosting: Hosting;
+ framework: Framework;
+ /** Source-file imports for code tabs. Shape varies by category; empty when not yet wired. */
+ sources?: Record
;
+ /** Optional flavor-specific description override. */
+ notes?: string;
+}
+
export interface RecipeEntry {
+ /** Stable ID, kebab-case, unique within a category. e.g. "basic-embed" */
+ id: string;
name: string;
description: string;
category: string;
categoryRoute: string;
/** Zero-based index of this recipe within its category page. */
recipeIndex: number;
+ /** At least one. flavors[0] is the default. */
+ flavors: RecipeFlavor[];
+}
+
+const CATEGORY_DEFAULTS: Record = {
+ '/hello': { hosting: 'salesforce-hosted', framework: 'react' },
+ '/read-data': { hosting: 'salesforce-hosted', framework: 'react' },
+ '/modify-data': { hosting: 'salesforce-hosted', framework: 'react' },
+ '/salesforce-apis': { hosting: 'salesforce-hosted', framework: 'react' },
+ '/error-handling': { hosting: 'salesforce-hosted', framework: 'react' },
+ '/styling': { hosting: 'salesforce-hosted', framework: 'react' },
+ '/routing': { hosting: 'salesforce-hosted', framework: 'react' },
+ '/integration': { hosting: 'salesforce-hosted', framework: 'react' },
+ '/mfe': { hosting: 'externally-hosted', framework: 'react' },
+};
+
+interface RawRecipeEntry {
+ category: string;
+ categoryRoute: string;
+ recipeIndex: number;
+ name: string;
+ description: string;
+ id?: string;
+ flavors?: RecipeFlavor[];
}
-export const recipeRegistry: RecipeEntry[] = [
+const rawRecipes: RawRecipeEntry[] = [
// Hello
{
category: 'Hello',
@@ -373,9 +413,192 @@ export const recipeRegistry: RecipeEntry[] = [
description:
'Fetches Accounts, Contacts, and Opportunities in a single aliased GraphQL request.',
},
+
+ // MFE
+ {
+ category: 'Embedding',
+ categoryRoute: '/mfe',
+ recipeIndex: 0,
+ name: 'Basic Embed',
+ description:
+ 'Minimum viable lwc-shell embed. Creates the shell imperatively, sets src and sandbox, and handles widget-ready.',
+ },
+ {
+ category: 'Embedding',
+ categoryRoute: '/mfe',
+ recipeIndex: 1,
+ name: 'Receive Data',
+ description:
+ 'Pushes data from the LWC host into the MFE via shell.updateData(). The MFE receives it with bridge.addEventListener(\'data\', handler).',
+ },
+ {
+ category: 'Embedding',
+ categoryRoute: '/mfe',
+ recipeIndex: 2,
+ name: 'Send Event',
+ description:
+ 'The MFE dispatches custom events to the LWC host via bridge.dispatchEvent(). The host catches them on the shell element.',
+ },
+ {
+ category: 'Embedding',
+ categoryRoute: '/mfe',
+ recipeIndex: 3,
+ name: 'Auto-Resize',
+ description:
+ 'The iframe height adjusts automatically as MFE content grows or shrinks via a ResizeObserver inside the iframe.',
+ },
+ {
+ category: 'Embedding',
+ categoryRoute: '/mfe',
+ recipeIndex: 4,
+ name: 'Theme Tokens',
+ description:
+ 'Salesforce CSS custom properties are sent to the MFE on connect and re-synced on demand via shell.refreshTheme().',
+ },
+ {
+ category: 'Embedding',
+ categoryRoute: '/mfe',
+ recipeIndex: 5,
+ name: 'Dirty State',
+ description:
+ 'The MFE notifies the host of unsaved changes via trackdirtystate events so the host can block navigation.',
+ },
+ {
+ category: 'Embedding',
+ categoryRoute: '/mfe',
+ recipeIndex: 6,
+ name: 'GraphQL Bridge',
+ description:
+ 'The MFE executes Salesforce GraphQL queries proxied through the host via bridge.graphql(). No allow-same-origin needed.',
+ },
];
+function slugify(name: string): string {
+ return name
+ .toLowerCase()
+ .replace(/[()]/g, '')
+ .replace(/[^a-z0-9]+/g, '-')
+ .replace(/^-+|-+$/g, '');
+}
+
+function buildRegistry(): RecipeEntry[] {
+ return rawRecipes.map((entry) => {
+ const flavors: RecipeFlavor[] =
+ entry.flavors ??
+ (() => {
+ const defaults = CATEGORY_DEFAULTS[entry.categoryRoute];
+ if (!defaults) {
+ throw new Error(
+ `Recipe "${entry.name}" in "${entry.categoryRoute}" has no category default and no explicit flavors.`
+ );
+ }
+ return [{ hosting: defaults.hosting, framework: defaults.framework }];
+ })();
+
+ if (flavors.length === 0) {
+ throw new Error(
+ `Recipe "${entry.name}" in "${entry.categoryRoute}" must have at least one flavor.`
+ );
+ }
+
+ // Validate (hosting, framework) pairs are unique within a recipe.
+ const seen = new Set();
+ for (const f of flavors) {
+ const key = `${f.hosting}|${f.framework}`;
+ if (seen.has(key)) {
+ throw new Error(
+ `Recipe "${entry.name}" has duplicate flavor (${f.hosting}, ${f.framework}).`
+ );
+ }
+ seen.add(key);
+ }
+
+ return {
+ id: entry.id ?? slugify(entry.name),
+ name: entry.name,
+ description: entry.description,
+ category: entry.category,
+ categoryRoute: entry.categoryRoute,
+ recipeIndex: entry.recipeIndex,
+ flavors,
+ };
+ });
+}
+
+export const recipeRegistry: RecipeEntry[] = buildRegistry();
+
/** Returns the number of recipes for a given category route (e.g. "/hello"). */
export function getRecipeCount(categoryRoute: string): number {
return recipeRegistry.filter((r) => r.categoryRoute === categoryRoute).length;
}
+
+/** Returns the default hosting for a category, or undefined if the category is unknown. */
+export function getCategoryHosting(categoryRoute: string): Hosting | undefined {
+ return CATEGORY_DEFAULTS[categoryRoute]?.hosting;
+}
+
+/** Returns the default framework for a category, or undefined if the category is unknown. */
+export function getCategoryFramework(categoryRoute: string): Framework | undefined {
+ return CATEGORY_DEFAULTS[categoryRoute]?.framework;
+}
+
+/** Look up a recipe by category route + id. */
+export function getRecipe(categoryRoute: string, id: string): RecipeEntry | undefined {
+ return recipeRegistry.find(
+ (r) => r.categoryRoute === categoryRoute && r.id === id
+ );
+}
+
+/** List recipes, optionally narrowed to those that have at least one matching flavor. */
+export function listRecipes(filter?: {
+ hosting?: Hosting;
+ framework?: Framework;
+}): RecipeEntry[] {
+ if (!filter || (!filter.hosting && !filter.framework)) return recipeRegistry;
+ return recipeRegistry.filter((r) =>
+ r.flavors.some(
+ (f) =>
+ (!filter.hosting || f.hosting === filter.hosting) &&
+ (!filter.framework || f.framework === filter.framework)
+ )
+ );
+}
+
+/** True if the recipe declares a flavor exactly matching (hosting, framework). */
+export function hasFlavor(
+ recipe: RecipeEntry,
+ hosting: Hosting,
+ framework: Framework
+): boolean {
+ return recipe.flavors.some(
+ (f) => f.hosting === hosting && f.framework === framework
+ );
+}
+
+/**
+ * Resolve the best-matching flavor for the requested (hosting, framework).
+ * Fallback order: exact match → hosting only → framework only → flavors[0].
+ * Callers that care which axis matched should compare the returned flavor's
+ * fields to what they requested.
+ */
+export function resolveFlavor(
+ recipe: RecipeEntry,
+ hosting?: Hosting,
+ framework?: Framework
+): RecipeFlavor {
+ if (hosting && framework) {
+ const exact = recipe.flavors.find(
+ (f) => f.hosting === hosting && f.framework === framework
+ );
+ if (exact) return exact;
+ }
+ if (hosting) {
+ const byHosting = recipe.flavors.find((f) => f.hosting === hosting);
+ if (byHosting) return byHosting;
+ }
+ if (framework) {
+ const byFramework = recipe.flavors.find((f) => f.framework === framework);
+ if (byFramework) return byFramework;
+ }
+ return recipe.flavors[0];
+}
diff --git a/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipes/README.md b/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipes/README.md
index d01bdfa..1714a05 100644
--- a/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipes/README.md
+++ b/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipes/README.md
@@ -1,6 +1,8 @@
-# React Recipes Catalog
+# Multi-Framework Recipes Catalog (React)
-React Recipes are self-contained, single-file examples that teach one concept at a time. Every recipe inlines its GraphQL queries, mutations, types, and SDK calls so you can read the entire pattern without jumping between files. Open any `.tsx` file in `src/recipes/` and everything you need is right there.
+Self-contained, single-file examples that teach one concept at a time. Every recipe inlines its GraphQL queries, mutations, types, and SDK calls so you can read the entire pattern without jumping between files. Open any `.tsx` file in `src/recipes/` and everything you need is right there.
+
+Each recipe is tagged by **hosting mode** (Salesforce-Hosted or Externally Hosted) and **framework** (React today; Vue/Angular planned). Categories 1–8 are Salesforce-Hosted React recipes. Category 9 (MFE) is Externally Hosted React — the framework app runs on its own server and embeds into Salesforce via `lwc-shell`.
## Recommended Learning Path
@@ -14,6 +16,7 @@ Work through the categories in this order. Each builds on concepts from the prev
6. **Routing** -- React Router in UI Bundles: Link, NavLink, route parameters, nested routes, programmatic navigation
7. **Styling** -- CSS approaches: SLDS utility classes, shadcn/ui + Tailwind, Design System React components
8. **Integration** -- End-to-end patterns combining multiple APIs and React features
+9. **MFE (Externally Hosted)** -- Embed an external React app into Salesforce Lightning via `lwc-shell`. Covers the Platform SDK surface: connection detection, receiving host data, dispatching events, auto-resize, theme tokens, dirty state, and GraphQL proxying. Requires the `mfe-app/` dev server running at `localhost:4300` — see the repo README for setup steps.
## Full Recipe Table
@@ -63,3 +66,10 @@ Work through the categories in this order. Each builds on concepts from the prev
| Styling | IconsDSR | Same icons as IconsSLDS via the Icon component from design-system-react. |
| Integration | SearchableAccountList | A controlled search input drives a GraphQL variable that filters Accounts by name with debounce. |
| Integration | DashboardAliasedQueries | Fetches Accounts, Contacts, and Opportunities in a single GraphQL request using aliases. |
+| MFE | BasicEmbed | Minimum viable lwc-shell embed. The MFE uses `bridge.isConnected()` to detect the embedding context. |
+| MFE | ReceiveData | Host pushes data into the MFE via `shell.updateData()`. MFE receives it with `bridge.addEventListener('data', handler)`. |
+| MFE | SendEvent | MFE dispatches custom events to the host via `bridge.dispatchEvent()`. Host catches them on the shell element. |
+| MFE | AutoResize | iframe height adjusts automatically as MFE content grows or shrinks via a ResizeObserver inside the iframe. |
+| MFE | ThemeTokens | Salesforce CSS custom properties sent to the MFE on connect and re-synced on demand via `shell.refreshTheme()`. |
+| MFE | DirtyState | MFE notifies the host of unsaved changes via `trackdirtystate` events so the host can block navigation. |
+| MFE | GraphQLBridge | MFE executes Salesforce GraphQL queries proxied through the host via `bridge.graphql()`. No `allow-same-origin` needed. |
diff --git a/force-app/main/react-recipes/uiBundles/reactRecipes/src/routes.tsx b/force-app/main/react-recipes/uiBundles/reactRecipes/src/routes.tsx
index db5113b..24b17f0 100644
--- a/force-app/main/react-recipes/uiBundles/reactRecipes/src/routes.tsx
+++ b/force-app/main/react-recipes/uiBundles/reactRecipes/src/routes.tsx
@@ -11,6 +11,7 @@ import ErrorHandling from './pages/ErrorHandling';
import Styling from './pages/Styling';
import Routing, { RouteParametersPage, NestedRoutesPage } from './pages/Routing';
import Integration from './pages/Integration';
+import Mfe from './pages/Mfe';
import { RouteParametersDetail } from './recipes/routing/RouteParameters';
import NestedRoutes, {
NestedRoutesIndex,
@@ -91,6 +92,11 @@ export const routes: RouteObject[] = [
element: MFE App
+
+
+
+
+
+
diff --git a/mfe-app/package.json b/mfe-app/package.json
new file mode 100644
index 0000000..f5c01ce
--- /dev/null
+++ b/mfe-app/package.json
@@ -0,0 +1,32 @@
+{
+ "name": "mfe-app",
+ "private": true,
+ "version": "1.0.0",
+ "type": "module",
+ "scripts": {
+ "dev": "vite",
+ "build": "tsc -b && vite build",
+ "preview": "vite preview",
+ "lint": "eslint ."
+ },
+ "dependencies": {
+ "@salesforce/experimental-mfe-bridge": "2.2.1-rc.1",
+ "react": "^19.2.0",
+ "react-dom": "^19.2.0",
+ "react-router-dom": "^7.9.5"
+ },
+ "devDependencies": {
+ "@eslint/js": "^9.39.1",
+ "@types/node": "^25.0.9",
+ "@types/react": "^19.2.2",
+ "@types/react-dom": "^19.2.2",
+ "@vitejs/plugin-react": "^5.1.0",
+ "eslint": "^9.39.1",
+ "eslint-plugin-react-hooks": "^5.2.0",
+ "eslint-plugin-react-refresh": "^0.4.24",
+ "globals": "^16.5.0",
+ "typescript": "~5.9.3",
+ "typescript-eslint": "^8.46.3",
+ "vite": "^7.2.2"
+ }
+}
diff --git a/mfe-app/src/App.tsx b/mfe-app/src/App.tsx
new file mode 100644
index 0000000..e4bd465
--- /dev/null
+++ b/mfe-app/src/App.tsx
@@ -0,0 +1,52 @@
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import BasicEmbed from './recipes/BasicEmbed';
+import ReceiveData from './recipes/ReceiveData';
+import SendEvent from './recipes/SendEvent';
+import AutoResize from './recipes/AutoResize';
+import ThemeTokens from './recipes/ThemeTokens';
+import DirtyState from './recipes/DirtyState';
+import GraphQLBridge from './recipes/GraphQLBridge';
+
+function Home() {
+ return (
+
+
MFE App
+
+ External MFE application for multiframework-recipes. Each route demonstrates one
+ bridge pattern. Open this app embedded inside a Salesforce Lightning component.
+
+
+
Available routes
+
+ /basic-embed
+ /receive-data
+ /send-event
+ /auto-resize
+ /theme-tokens
+ /dirty-state
+ /graphql-bridge
+
+
+
+
+
+
+ );
+}
+
+export default App;
diff --git a/mfe-app/src/index.css b/mfe-app/src/index.css
new file mode 100644
index 0000000..ba350a5
--- /dev/null
+++ b/mfe-app/src/index.css
@@ -0,0 +1,126 @@
+:root {
+ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,
+ Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', Arial,
+ sans-serif;
+ line-height: 1.5;
+ font-weight: 400;
+ color: #213547;
+ background-color: #ffffff;
+ font-synthesis: none;
+ text-rendering: optimizeLegibility;
+ -webkit-font-smoothing: antialiased;
+}
+
+body {
+ margin: 0;
+ min-width: 320px;
+}
+
+* {
+ box-sizing: border-box;
+}
+
+.recipe-container {
+ padding: 16px;
+ font-size: 14px;
+}
+
+.recipe-title {
+ font-size: 16px;
+ font-weight: 600;
+ margin: 0 0 4px;
+ color: #0a7cae;
+}
+
+.recipe-description {
+ font-size: 12px;
+ color: #666;
+ margin: 0 0 16px;
+}
+
+.recipe-card {
+ border: 1px solid #e5e7eb;
+ border-radius: 8px;
+ padding: 16px;
+ background: #fff;
+}
+
+.recipe-label {
+ font-size: 11px;
+ font-weight: 600;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ color: #888;
+ margin: 0 0 4px;
+}
+
+.recipe-value {
+ font-size: 14px;
+ color: #213547;
+ margin: 0 0 12px;
+}
+
+.recipe-badge {
+ display: inline-block;
+ padding: 2px 10px;
+ border-radius: 12px;
+ font-size: 12px;
+ font-weight: 600;
+}
+
+.badge-green { background: #d1fae5; color: #065f46; }
+.badge-yellow { background: #fef3c7; color: #92400e; }
+.badge-red { background: #fee2e2; color: #991b1b; }
+.badge-blue { background: #dbeafe; color: #1e40af; }
+
+.recipe-btn {
+ display: inline-block;
+ padding: 6px 14px;
+ border-radius: 6px;
+ border: none;
+ font-size: 13px;
+ font-weight: 500;
+ cursor: pointer;
+ transition: opacity 0.15s;
+}
+
+.recipe-btn:hover { opacity: 0.85; }
+.recipe-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+
+.recipe-btn-primary { background: #0a7cae; color: #fff; }
+.recipe-btn-secondary { background: #e5e7eb; color: #213547; }
+.recipe-btn-danger { background: #dc2626; color: #fff; }
+
+.recipe-input {
+ width: 100%;
+ padding: 8px 10px;
+ border: 1px solid #d1d5db;
+ border-radius: 6px;
+ font-size: 13px;
+ outline: none;
+}
+
+.recipe-input:focus { border-color: #0a7cae; }
+
+.recipe-alert {
+ padding: 10px 14px;
+ border-radius: 6px;
+ font-size: 13px;
+ margin-bottom: 12px;
+}
+
+.alert-warning { background: #fef3c7; color: #92400e; border: 1px solid #fcd34d; }
+.alert-error { background: #fee2e2; color: #991b1b; border: 1px solid #fca5a5; }
+.alert-success { background: #d1fae5; color: #065f46; border: 1px solid #6ee7b7; }
+.alert-info { background: #dbeafe; color: #1e40af; border: 1px solid #93c5fd; }
+
+.status-dot {
+ display: inline-block;
+ width: 8px;
+ height: 8px;
+ border-radius: 50%;
+ margin-right: 6px;
+}
+
+.dot-green { background: #10b981; }
+.dot-gray { background: #9ca3af; }
diff --git a/mfe-app/src/main.tsx b/mfe-app/src/main.tsx
new file mode 100644
index 0000000..7825095
--- /dev/null
+++ b/mfe-app/src/main.tsx
@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import './index.css';
+import App from './App.tsx';
+
+createRoot(document.getElementById('root')!).render(
+
+ ,
+);
diff --git a/mfe-app/src/recipes/AutoResize.tsx b/mfe-app/src/recipes/AutoResize.tsx
new file mode 100644
index 0000000..369910b
--- /dev/null
+++ b/mfe-app/src/recipes/AutoResize.tsx
@@ -0,0 +1,87 @@
+/**
+ * Auto-Resize
+ *
+ * Demonstrates iframe height auto-adjustment. As content is added or removed
+ * the lwc-shell on the host side receives resize events and updates the iframe
+ * height automatically — no fixed height is set.
+ *
+ * Key concept: the bridge reports height changes via a ResizeObserver on
+ * document.body. This happens automatically when using
+ * @salesforce/experimental-mfe-bridge — no explicit setup needed in the app.
+ * Simply add or remove content and the iframe height follows.
+ *
+ * @see ThemeTokens — receiving Salesforce design tokens
+ */
+import { useState } from 'react';
+
+interface Item {
+ id: number;
+ text: string;
+}
+
+let nextId = 1;
+
+function makeItem(): Item {
+ return { id: nextId++, text: `Item ${nextId - 1} — added at ${new Date().toLocaleTimeString()}` };
+}
+
+export default function AutoResize() {
+ const [items, setItems] = useState([makeItem(), makeItem()]);
+
+ function addItem() {
+ setItems(prev => [...prev, makeItem()]);
+ }
+
+ function removeItem(id: number) {
+ setItems(prev => prev.filter(item => item.id !== id));
+ }
+
+ return (
+
+
Auto-Resize
+
+ Add or remove items — the Salesforce iframe height adjusts automatically.
+ No fixed height is set on the host. The bridge reports content height via
+ a ResizeObserver.
+
+
+
+
+ + Add item
+
+ setItems([])}
+ disabled={items.length === 0}
+ >
+ Clear all
+
+
+
+
+
{items.length} item{items.length !== 1 ? 's' : ''}
+ {items.length === 0 ? (
+
No items — iframe should be at minimum height.
+ ) : (
+
+ {items.map(item => (
+
+ {item.text}
+ removeItem(item.id)}
+ >
+ remove
+
+
+ ))}
+
+ )}
+
+
pointing at
+ * this route. The bridge auto-initialises when this page loads inside that
+ * iframe — no explicit setup is needed.
+ *
+ * Key concept: bridge.isConnected() returns true only when running inside a
+ * Salesforce lwc-shell iframe. Use it to detect the embedding context and
+ * render accordingly.
+ *
+ * @see ReceiveData — receiving host data via the bridge
+ */
+import { useEffect, useState } from 'react';
+import bridge from '@salesforce/experimental-mfe-bridge';
+
+export default function BasicEmbed() {
+ const [connected, setConnected] = useState(false);
+
+ useEffect(() => {
+ // bridge.isConnected() is true when running inside an lwc-shell iframe.
+ // Outside Salesforce (plain browser tab) it returns false — useful for
+ // local development without a Salesforce org.
+ setConnected(bridge.isConnected());
+ }, []);
+
+ return (
+
+
Basic Embed
+
+ Detects whether this React app is running inside a Salesforce lwc-shell iframe.
+
+
+
+
Bridge status
+
+
+
+
Instance ID
+
+ {connected ? bridge.instanceId : '—'}
+
+
+
(INITIAL);
+ const [saved, setSaved] = useState(INITIAL);
+ const [isDirty, setIsDirty] = useState(false);
+
+ useEffect(() => {
+ const dirty = isDirtyCheck(form, saved);
+ setIsDirty(dirty);
+
+ // Notify the Salesforce host whenever dirty state changes.
+ // The host uses this to show a warning before the user navigates away.
+ bridge.dispatchEvent(
+ new CustomEvent('trackdirtystate', {
+ detail: {
+ isDirty: dirty,
+ label: dirty ? 'Loan application has unsaved changes' : '',
+ },
+ }),
+ );
+ }, [form, saved]);
+
+ function handleChange(field: keyof FormState, value: string) {
+ setForm(prev => ({ ...prev, [field]: value }));
+ }
+
+ function handleSave() {
+ setSaved(form);
+ }
+
+ function handleDiscard() {
+ setForm(saved);
+ }
+
+ return (
+
+
Dirty State
+
+ Edit the form — the host is notified of unsaved changes via{' '}
+ bridge.dispatchEvent('trackdirtystate'). The host can block
+ navigation until the user saves or discards.
+
+
+ {isDirty && (
+
+ Unsaved changes — the Salesforce host has been notified.
+
+ )}
+
+ {!isDirty && saved.name && (
+
Changes saved.
+ )}
+
+
+
+
+
+ Save
+
+
+ Discard
+
+
+
([]);
+ const [loading, setLoading] = useState(false);
+ const [error, setError] = useState();
+
+ async function fetchContacts() {
+ if (!bridge.isConnected()) {
+ setError('Bridge not connected — embed this app inside the mfeGraphQL LWC to execute queries.');
+ return;
+ }
+
+ setLoading(true);
+ setError(undefined);
+
+ try {
+ // bridge.graphql() proxies the query through the host LWC.
+ // The MFE never directly calls Salesforce APIs — the host acts as the proxy.
+ const result = (await bridge.graphql({ query: QUERY })) as QueryResult;
+
+ if (result.errors?.length) {
+ throw new Error(result.errors.map(e => e.message).join('; '));
+ }
+
+ const edges = result.data?.uiapi?.query?.Contact?.edges ?? [];
+ setContacts(edges.map(e => e.node));
+ } catch (err) {
+ setError(err instanceof Error ? err.message : 'Query failed');
+ } finally {
+ setLoading(false);
+ }
+ }
+
+ return (
+
+
GraphQL Bridge
+
+ Executes a Salesforce GraphQL query via bridge.graphql(). The
+ host proxies the request — no allow-same-origin needed.
+
+
+
+ {loading ? 'Querying…' : 'Fetch contacts'}
+
+
+ {error &&
{error}
}
+
+ {!error && contacts.length > 0 && (
+
+
{contacts.length} contact{contacts.length !== 1 ? 's' : ''}
+
+ {contacts.map(c => (
+
+ {c.Name.value ?? 'Unknown'}
+ {c.Title.value && (
+ {c.Title.value}
+ )}
+
+ ))}
+
+
+ )}
+
({});
+ const [updateCount, setUpdateCount] = useState(0);
+
+ useEffect(() => {
+ const handleData = (e: Event) => {
+ const detail = (e as CustomEvent).detail ?? {};
+ setHostData(detail);
+ setUpdateCount(c => c + 1);
+ };
+
+ // 'data' fires whenever the host calls shell.updateData(payload)
+ bridge.addEventListener('data', handleData);
+ return () => bridge.removeEventListener('data', handleData);
+ }, []);
+
+ const hasData = Object.keys(hostData).length > 0;
+
+ return (
+
+
Receive Data
+
+ Displays data pushed from the Salesforce host via{' '}
+ shell.updateData(). Interact with the host component to
+ trigger an update.
+
+
+ {!bridge.isConnected() && (
+
+ Running standalone — no host data will arrive. Embed this app in the
+ mfeReceiveData LWC to see live data.
+
+ )}
+
+
+
Updates received
+
{updateCount}
+
+
Latest payload
+ {hasData ? (
+
+ {JSON.stringify(hostData, null, 2)}
+
+ ) : (
+
+ Waiting for host data…
+
+ )}
+
+
([]);
+
+ function handleAction(action: Action) {
+ // Dispatch a custom event that bubbles up to the LWC host.
+ // The host listens: shell.addEventListener('mfe-action', handler)
+ bridge.dispatchEvent(
+ new CustomEvent('mfe-action', {
+ detail: { action, timestamp: Date.now() },
+ }),
+ );
+
+ setLog(prev => [
+ { action, timestamp: new Date().toLocaleTimeString() },
+ ...prev.slice(0, 9),
+ ]);
+ }
+
+ return (
+
+
Send Event
+
+ Dispatches custom events to the Salesforce LWC host via{' '}
+ bridge.dispatchEvent(). The host receives them on the shell
+ element.
+
+
+ {!bridge.isConnected() && (
+
+ Running standalone — events are dispatched but no host is listening.
+
+ )}
+
+
+
Actions
+
+ {ACTIONS.map(action => (
+ handleAction(action)}
+ >
+ {action}
+
+ ))}
+
+
+
+ {log.length > 0 && (
+
+
Dispatched events
+
+ {log.map((entry, i) => (
+
+ {entry.action}
+
+ {entry.timestamp}
+
+
+ ))}
+
+
+ )}
+
({});
+ const [syncCount, setSyncCount] = useState(0);
+
+ useEffect(() => {
+ const handleTheme = (e: Event) => {
+ const detail = (e as CustomEvent).detail ?? {};
+
+ // Apply every CSS custom property to the document root so they
+ // cascade to all components in this MFE.
+ Object.entries(detail).forEach(([prop, value]) => {
+ document.documentElement.style.setProperty(prop, value);
+ });
+
+ setTokens(detail);
+ setSyncCount(c => c + 1);
+ };
+
+ // 'theme' fires on connect and whenever the host calls shell.refreshTheme()
+ bridge.addEventListener('theme', handleTheme);
+ return () => bridge.removeEventListener('theme', handleTheme);
+ }, []);
+
+ const tokenEntries = Object.entries(tokens).slice(0, 20);
+
+ return (
+
+
Theme Tokens
+
+ Displays Salesforce CSS custom properties received from the host.
+ The host sends them automatically; call{' '}
+ shell.refreshTheme() to re-sync after a theme change.
+
+
+ {!bridge.isConnected() && (
+
+ Running standalone — no theme data will arrive from a host.
+
+ )}
+
+
+
Syncs received: {syncCount}
+
Tokens (first 20 of {Object.keys(tokens).length})
+
+ {tokenEntries.length === 0 ? (
+
Waiting for theme data…
+ ) : (
+
+
+
+ Property
+ Value
+
+
+
+ {tokenEntries.map(([prop, value]) => (
+
+ {prop}
+ {value}
+
+ ))}
+
+
+ )}
+
+
;
- /** Optional flavor-specific description override. */
- notes?: string;
-}
-
-interface RecipeEntry {
- /** Stable ID, kebab-case, unique within a category. e.g. "basic-embed" */
- id: string;
- name: string;
- description: string;
- category: string;
- categoryRoute: string;
- recipeIndex: number;
- /** At least one. The first entry is the default flavor. */
- flavors: RecipeFlavor[];
-}
-```
-
-Rules:
-
-- A recipe **must** have at least one flavor.
-- Default flavor = `flavors[0]`.
-- `(hosting, framework)` is unique within a recipe's flavors.
-- Filtering "show me Salesforce-Hosted" matches a recipe if **any** of its flavors is `salesforce-hosted`.
-
-### Helper functions (registry API)
-
-```ts
-getRecipe(categoryRoute: string, id: string): RecipeEntry | undefined
-listRecipes(filter?: { hosting?: Hosting; framework?: Framework }): RecipeEntry[]
-hasFlavor(recipe: RecipeEntry, hosting: Hosting, framework: Framework): boolean
-resolveFlavor(recipe: RecipeEntry, hosting?: Hosting, framework?: Framework): RecipeFlavor
-```
-
-`resolveFlavor` fallback order: exact match → match on `hosting` only → match on `framework` only → `flavors[0]`. The UI uses the resolved flavor's actual `(hosting, framework)` to update visible state — never silently shows wrong content.
-
-### Migration
-
-Today's registry entries map cleanly: each becomes a recipe with a single-element `flavors` array. No content rewrite needed; the registry shape changes and call sites are updated.
-
----
-
-## 6. URL contract
-
-URLs are the source of truth for state. Reload must restore the exact same view.
-
-| Surface | URL | Notes |
-|---|---|---|
-| Catalog | `/` | Hosting filter persisted to `localStorage`; not in URL (filter is a browse aid, not shareable state). |
-| Category | `/{category}` | e.g. `/mfe` |
-| Recipe — default flavor | `/{category}?recipe={index}` | Backwards compatible with current behavior in [SearchBar.tsx:91-95](../force-app/main/react-recipes/uiBundles/reactRecipes/src/components/app/SearchBar.tsx#L91-L95). |
-| Recipe — explicit flavor | `/{category}?recipe={index}&host={hosting}&fw={framework}` | `host ∈ {sf, ext}`, `fw ∈ {react, vue, angular}`. Short forms keep URLs scannable. |
-| Framework switcher | Navbar control | Updates the in-page selection only; does not navigate. Persisted to `localStorage`. |
-
-Invalid combinations are silently resolved via `resolveFlavor`. The URL is corrected via `replaceState` (not `pushState`) so the user's back button is not littered.
-
----
-
-## 7. Target UI
-
-### 7.1 Global chrome
-
-```ini
-┌──────────────────────────────────────────────────────────────────────┐
-│ ⌬ Multi-Framework Recipes [React ▾] Hello Read Modify … 🔍 │
-└──────────────────────────────────────────────────────────────────────┘
-```
-
-- Title: **Multi-Framework Recipes**.
-- Framework switcher (`React ▾`); Vue/Angular shown disabled "(soon)".
-- Categories unchanged in nav. `Embedding` is a normal category — its hosting nature is conveyed via tags.
-- New footer link: *Advanced server recipes ↗* (separate repo).
-
-### 7.2 Home / catalog
-
-```ini
-┌──────────────────────────────────────────────────────────────────────┐
-│ Multi-Framework Recipes — React │
-│ Sample patterns for Salesforce-Hosted and Externally-Hosted apps. │
-│ [Get Started] [Developer Guide ↗] │
-│ │
-│ Hosting: ● All ○ Salesforce-Hosted ○ Externally Hosted │
-│ │
-│ ┌─ Hello ─────────┐ ┌─ Read Data ─────┐ ┌─ Embedding ────┐ │
-│ │ 8 recipes │ │ 8 recipes │ │ 7 recipes │ │
-│ │ [SF] [React] │ │ [SF] [React] │ │ [Ext] [React] │ │
-│ └─────────────────┘ └─────────────────┘ └────────────────┘ │
-│ … │
-│ │
-│ ─── Hosting Models ───────────────────────────────────────────────── │
-│ 📦 Salesforce-Hosted 🌐 Externally Hosted │
-│ Deploy your app to Host on AWS / Heroku / │
-│ Salesforce.app (UI bundles). your own infra; embed via lwc-shell. │
-│ Best for new apps. Best for existing apps & SaaS vendors. │
-│ │
-│ Want to run your own server locally with SSL? │
-│ → Advanced server recipes (separate repo) ↗ │
-└──────────────────────────────────────────────────────────────────────┘
-```
-
-### 7.3 Category page
-
-Two layouts based on category type:
-
-- **Standard categories** (`/hello`, `/read-data`, …): existing recipe-card list. Add small `[SF] [React]` chips on each card.
-- **Multi-source categories** (`/mfe` and future similar): sidebar + tabbed-code layout from `Mfe.tsx`. Add the flavor switcher (§7.4) above the code tabs.
-
-### 7.4 Recipe page — flavor switcher
-
-```ini
-┌─ Basic Embed ────────────────────────────────────────────────┐
-│ Minimum viable lwc-shell embed. │
-│ │
-│ Hosting: [● Externally Hosted] [ Salesforce-Hosted ⓘ ] │
-│ Framework: [● React] [ Vue (soon) ] [ Angular (soon) ] │
-│ │
-│ ⓘ Externally hosted: this recipe assumes the guest app runs │
-│ on a third-party domain. For local dev with SSL, see │
-│ → Advanced server recipes ↗ │
-│ │
-│ ┌ Code ─────────────────────────────────────────────────────┐│
-│ │ [Guest (React)] [Host (LWC JS)] [Host (LWC HTML)] ││
-│ │ … ││
-│ └───────────────────────────────────────────────────────────┘│
-└──────────────────────────────────────────────────────────────┘
-```
-
-- Both switchers always visible. Unavailable flavors disabled "(soon)" — not hidden.
-- Tooltip on disabled flavors explains *why* it's unavailable ("Vue recipe coming in 266", "SF-hosted variant in design").
-- Selection reflected in URL per §6.
-- Externally-Hosted recipes get the inline callout linking to the server repo.
-
----
-
-## 8. Accessibility
-
-| Surface | Requirement |
-|---|---|
-| Hosting filter | `role="radiogroup"` with arrow-key navigation; each option is a `role="radio"` button. Keyboard-equivalent of a click. |
-| Framework switcher | `role="combobox"` with proper `aria-expanded`, `aria-controls`, focus trapping in the menu, Escape to close. |
-| Flavor tabs | `role="tablist"` / `role="tab"`. Disabled tabs use `aria-disabled="true"` (not `disabled`) so SR users still discover the "(soon)" state. |
-| Color | Hosting/framework chips must not rely on color alone; always include a text label. |
-| Focus | Visible focus ring on all interactive elements (already enforced via `focus-visible:ring-ring` in current Tailwind setup). |
-
-The existing search bar already meets keyboard-nav expectations (arrow keys, Enter, Esc) — see [SearchBar.tsx:100-111](../force-app/main/react-recipes/uiBundles/reactRecipes/src/components/app/SearchBar.tsx#L100-L111). New components match that bar.
-
----
-
-## 9. Search
-
-The Cmd+K search ([SearchBar.tsx](../force-app/main/react-recipes/uiBundles/reactRecipes/src/components/app/SearchBar.tsx)) currently matches `name` and `description` only (lines 56–59). Extension:
-
-- Index `hosting` and `framework` keywords so "external", "vue", "angular", "salesforce-hosted" surface relevant recipes.
-- Show flavor chips on each result row so users can disambiguate before clicking.
-- Selecting a result navigates to the recipe with the matching flavor pre-selected via URL params.
-
----
-
-## 10. Use-case → UI coverage
-
-| Discussion point | UI surface |
-|---|---|
-| MFE included in multi-framework recipes | `Embedding` is a normal category tile |
-| Two hosting types: SF-hosted vs externally-hosted | Hosting filter on Home + flavor tabs on recipe page |
-| Multi-framework: React → Vue → Angular | Navbar framework switcher + per-recipe flavor chips with "(soon)" |
-| `salesforce.app` family vs 3P explanation | "Hosting Models" block on Home |
-| SDK/bridge communication | Existing Guest / Host code tabs in `Mfe.tsx` |
-| Local-server / SSL / `/etc/hosts` (advanced) | Separate repo; linked from footer + Externally-Hosted recipes |
-| GA scope = local server only | Copy says *"local Express + SSL"*; nothing promises hosted demos |
-| Pro-code SF devs new to Node | Default path stays "deploy & go"; complexity is opt-in via outlinks |
-
----
-
-## 11. Build plan
-
-Each step is a small, shippable PR. Ownership is implicit (single dev) but each step has clear acceptance criteria for review.
-
-| # | Step | Files | Acceptance |
-|---|---|---|---|
-| 1 | Registry shape change: introduce `flavors[]` | [recipeRegistry.ts](../force-app/main/react-recipes/uiBundles/reactRecipes/src/recipeRegistry.ts) | All current entries migrate to single-flavor form; existing pages render unchanged; types are strict. |
-| 2 | Rebrand to *Multi-Framework Recipes* + disabled framework switcher | [Navbar.tsx](../force-app/main/react-recipes/uiBundles/reactRecipes/src/components/app/Navbar.tsx), [Home.tsx](../force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Home.tsx), `index.html` | Page title, H1, and navbar reflect new brand; switcher renders with disabled Vue/Angular. |
-| 3 | Home Hosting filter | [Home.tsx](../force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Home.tsx) | Radio group filters tile grid; selection persists across reload; a11y per §8. |
-| 4 | Hosting Models explainer + footer link | [Home.tsx](../force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Home.tsx), new `Footer.tsx` | Two-column block + footer link; placeholder URL acceptable v1. |
-| 5 | Recipe-card chips on standard category pages | All non-MFE pages under [pages/](../force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/) | Each card shows hosting + framework chip; same component as Home. |
-| 6 | Flavor switcher on `Mfe.tsx` | [Mfe.tsx](../force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Mfe.tsx) | URL-driven per §6; disabled "(soon)" states; `resolveFlavor` fallback. |
-| 7 | Contextual server-repo callout on Externally-Hosted recipes | `Mfe.tsx` + future externally-hosted pages | Shown only when current flavor is externally-hosted. |
-| 8 | Search index hosting + framework keywords | [SearchBar.tsx](../force-app/main/react-recipes/uiBundles/reactRecipes/src/components/app/SearchBar.tsx) | "external", "vue" surface relevant recipes; result rows show flavor chips. |
-
-Steps 1 and 2 are sequential (everything else builds on them). 3–8 are largely independent.
-
-### Out of scope (deferred)
-
-- Side-by-side comparison view of flavors.
-- Heroku-hosted demo server.
-- Vue and Angular *content* — IA scaffolding only.
-- Mobile-specific layout work (the recipes site is desktop-first; nothing here regresses mobile but no enhancements either).
-
----
-
-## 12. Testing
-
-| Layer | Approach |
-|---|---|
-| Registry shape | Type-level: strict TS; runtime: assertion in registry init that every recipe has ≥1 flavor and `(hosting, framework)` pairs are unique within a recipe. Throws at module load if violated — fast failure beats a misleading UI. |
-| Filters | Component test: Hosting filter narrows the tile list to the correct count; "All" restores. |
-| Flavor switcher | Component test: clicking each flavor updates URL; reload restores selection; invalid URL params resolve to default without 500. |
-| Search | Test that hosting/framework keywords return expected recipes. |
-| Visual | Manual walkthrough of every category page after step 5; smoke test in the dev server before each PR is merged. |
-
-The repo uses Jest already ([jest.config.js](../jest.config.js)). New tests follow the same pattern; no new test infra.
-
----
-
-## 13. Rollout
-
-- All steps are merged to `main` behind no flag — the recipes site is a static React app; there's no runtime risk to existing Salesforce orgs.
-- Deployment is a normal SFDX push of the React UI bundle.
-- "(soon)" labels are content-controlled in the registry; flipping a flavor from disabled to enabled is one PR, no infra change.
-- Server repo URL is configurable in one place ([Footer.tsx](../force-app/main/react-recipes/uiBundles/reactRecipes/src/components/app/Footer.tsx) constant) so it can flip from placeholder to real without touching every callsite.
-
----
-
-## 14. Risks
-
-| Risk | Likelihood | Impact | Mitigation |
-|---|---|---|---|
-| 264 freeze (July) — tight window for repo creation + content authoring | Med | High | Ship UI scaffolding (steps 1–8) ahead of MFE recipe content; backfill content when ready. |
-| Server repo not yet created when we ship link | High | Low | Ship with placeholder URL + "Coming soon" tooltip. Single constant to flip. |
-| "(soon)" labels age badly if Vue/Angular slip | Med | Low | Generic copy ("Additional frameworks planned") if a target slips beyond a release. |
-| Registry refactor breaks existing pages | Low | Med | Migration is mechanical (single flavor wrapping); covered by step 1's acceptance criteria. |
-| SF-hosted Embedding flavor design not finalized when step 6 lands | Med | Low | Step 6 only requires the *mechanism*; SF-hosted flavor stays disabled until content exists. |
-
----
-
-## 15. Open questions
-
-These need answers from §4 reviewers before step 2 ships:
-
-1. **Server-repo name and URL** — confirmed name from the open-source team? Charles Watkins is the contact per the meeting notes.
-2. **Framework switcher persistence** — proposed: `localStorage` per-user, default = `react`. Accept?
-3. **Future SF-hosted Embedding flavors** — confirmed: same recipe with multiple `flavors[]` (per §5). Reviewer should confirm this matches the team's mental model before we commit to the registry refactor.
-4. **Disabled-flavor copy** — generic "(soon)" or release-specific ("266")? Recommend release-specific where known, generic otherwise.
-
----
-
-## 16. Appendix — alternatives considered and rejected
-
-| Alternative | Why rejected |
-|---|---|
-| Two top-level tracks (SF-Hosted / Externally Hosted) | Most recipes are framework-pure; track-splitting would duplicate the catalog and force users to switch tracks for unrelated content. |
-| Flat catalog with multi-axis filters as the primary surface | Strong for power users, weak as a first-time learning surface. Audience is learning-oriented. |
-| Inline the server / SSL / `/etc/hosts` content into the main repo | Directly contradicts the meeting's "separation of concerns" decision and the "simple deploy & go" audience principle. |
-| Side-by-side flavor comparison on recipe pages | Premature when only one flavor exists per recipe today; high build cost; poor mobile fit. |
-| Leave site title as "React Recipes" until Vue/Angular ship | Contradicts the strategic framing of the meeting; the UI should set expectations now. |
From b0dd644941dda7fbe6e352965d153cb22bcfa5c7 Mon Sep 17 00:00:00 2001
From: AMAN SINGH
Date: Thu, 18 Jun 2026 12:43:44 +0530
Subject: [PATCH 03/10] feat(embedding): migrate to Platform SDK +
Replaces the legacy @salesforce/experimental-mfe-bridge / vendored
stack with the GA-track @salesforce/platform-sdk and the
base component, matching the lo2demo-sfdx
react-sdk pattern.
Guest (mfe-app):
- Switch dependency from @salesforce/experimental-mfe-bridge to
@salesforce/platform-sdk@10.9.2; add side-effect import
@salesforce/platform-sdk/sf-embedding in main.tsx
- Add SdkProvider context + useSdk() hook; resolve chat/view SDKs
once at startup via top-level await Promise.all
- Rewrite all six recipes against the SDK surface:
- BasicEmbed: chat.getHostContext()
- ReceiveData: view.getUiProps() + URLSearchParams fallback
- SendEvent: view.dispatchEvent(name, data)
- AutoResize: view.resize() driven by ResizeObserver
- ThemeTokens: view.getTheme() + chat.getHostContext()
- DirtyState: view.markDirtyState() / clearDirtyState()
- Drop GraphQLBridge recipe (host-side bridge.graphql() retired)
Host (LWC):
- Replace each mfe* host with a declarative
wrapper; drop imperative document.createElement('lwc-shell') and
c/vendorLwcShell imports
- Delete vendored vendorLwcShell (no longer needed;
is provided by the platform)
- Delete mfeGraphQL host
Explorer / docs:
- Rename Embedding route /mfe -> /embedding
- Update Mfe.tsx, recipeRegistry, READMEs, CSP description, and Home
page copy to reflect the SDK-shaped recipes
---
README.md | 23 +-
.../MfeAppLocalhost.cspTrustedSite-meta.xml | 2 +-
.../lwc/mfeAutoResize/mfeAutoResize.html | 16 +-
.../lwc/mfeAutoResize/mfeAutoResize.js | 36 +-
.../lwc/mfeBasicEmbed/mfeBasicEmbed.html | 13 +-
.../lwc/mfeBasicEmbed/mfeBasicEmbed.js | 31 +-
.../lwc/mfeDirtyState/mfeDirtyState.html | 20 +-
.../lwc/mfeDirtyState/mfeDirtyState.js | 93 +-
.../default/lwc/mfeGraphQL/mfeGraphQL.html | 12 -
.../main/default/lwc/mfeGraphQL/mfeGraphQL.js | 50 -
.../lwc/mfeGraphQL/mfeGraphQL.js-meta.xml | 10 -
.../lwc/mfeReceiveData/mfeReceiveData.html | 16 +-
.../lwc/mfeReceiveData/mfeReceiveData.js | 52 +-
.../lwc/mfeSendEvent/mfeSendEvent.html | 21 +-
.../default/lwc/mfeSendEvent/mfeSendEvent.js | 42 +-
.../lwc/mfeThemeTokens/mfeThemeTokens.html | 20 +-
.../lwc/mfeThemeTokens/mfeThemeTokens.js | 41 +-
.../lwc/vendorLwcShell/vendorLwcShell.js | 766 -----
.../vendorLwcShell/vendorLwcShell.js-meta.xml | 5 -
.../src/components/app/Navbar.tsx | 2 +-
.../uiBundles/reactRecipes/src/pages/Home.tsx | 6 +-
.../uiBundles/reactRecipes/src/pages/Mfe.tsx | 36 +-
.../reactRecipes/src/recipeRegistry.ts | 34 +-
.../reactRecipes/src/recipes/README.md | 17 +-
.../uiBundles/reactRecipes/src/routes.tsx | 4 +-
mfe-app/package-lock.json | 2607 +++++++++++++++++
mfe-app/package.json | 2 +-
mfe-app/src/App.tsx | 3 -
mfe-app/src/main.tsx | 14 +-
mfe-app/src/recipes/AutoResize.tsx | 40 +-
mfe-app/src/recipes/BasicEmbed.tsx | 50 +-
mfe-app/src/recipes/DirtyState.tsx | 36 +-
mfe-app/src/recipes/GraphQLBridge.tsx | 124 -
mfe-app/src/recipes/ReceiveData.tsx | 71 +-
mfe-app/src/recipes/SendEvent.tsx | 30 +-
mfe-app/src/recipes/ThemeTokens.tsx | 91 +-
mfe-app/src/sdk-context.tsx | 19 +
37 files changed, 2942 insertions(+), 1513 deletions(-)
delete mode 100644 force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.html
delete mode 100644 force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.js
delete mode 100644 force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.js-meta.xml
delete mode 100644 force-app/main/default/lwc/vendorLwcShell/vendorLwcShell.js
delete mode 100644 force-app/main/default/lwc/vendorLwcShell/vendorLwcShell.js-meta.xml
create mode 100644 mfe-app/package-lock.json
delete mode 100644 mfe-app/src/recipes/GraphQLBridge.tsx
create mode 100644 mfe-app/src/sdk-context.tsx
diff --git a/README.md b/README.md
index 2c0f126..b5f98fd 100644
--- a/README.md
+++ b/README.md
@@ -40,16 +40,14 @@ Today this mode lives in [`force-app/main/react-recipes/uiBundles/reactRecipes/`
### Externally Hosted
-The framework app runs on your own infrastructure (Vercel, AWS, anywhere) and is embedded into a Salesforce Lightning page via `lwc-shell`. A postMessage bridge proxies data, events, and GraphQL between the two sides.
+The framework app runs on your own infrastructure (Vercel, AWS, anywhere) and is embedded into a Salesforce Lightning page via the standard `` base component. The Platform SDK is the contract on the guest side; the sf-embedding protocol is the wire format underneath.
```mermaid
graph LR
- A[External Framework App` base component. In development, "externally hosted" means `localhost:4300`; in production you would point the LWC host at your deployed URL. Today the only implementation is React; Vue and Angular are planned.
> **Note:** The CSP trusted site for `localhost:4300` is included in the shared metadata deployed in the org setup steps above. No additional metadata deploy is needed.
@@ -240,13 +238,12 @@ These recipes run an external framework app on your own server and embed it into
| LWC host component | External app route | What it demonstrates |
|---|---|---|
-| `mfeBasicEmbed` | `/basic-embed` | Minimum viable embed — bridge connection detection |
-| `mfeReceiveData` | `/receive-data` | Host pushes data into guest via `shell.updateData()` |
-| `mfeSendEvent` | `/send-event` | Guest dispatches events to host via `bridge.dispatchEvent()` |
-| `mfeAutoResize` | `/auto-resize` | iframe height follows guest content via ResizeObserver |
-| `mfeThemeTokens` | `/theme-tokens` | Salesforce CSS custom properties synced to guest |
-| `mfeDirtyState` | `/dirty-state` | Guest notifies host of unsaved changes |
-| `mfeGraphQL` | `/graphql-bridge` | Guest queries Salesforce GraphQL proxied through host |
+| `mfeBasicEmbed` | `/basic-embed` | Minimum viable embed using `` — `chatSDK.getHostContext()` for connection detection |
+| `mfeReceiveData` | `/receive-data` | Host re-mounts `` with new src carrying URL query params; guest reads via `URLSearchParams` and `viewSDK.getUiProps()` |
+| `mfeSendEvent` | `/send-event` | Guest calls `viewSDK.dispatchEvent(name, data)`; surface-level routing is host-runtime specific |
+| `mfeAutoResize` | `/auto-resize` | Guest tracks body height with ResizeObserver and calls `viewSDK.resize()` |
+| `mfeThemeTokens` | `/theme-tokens` | Guest reads host theme via `viewSDK.getTheme()` and the broader environment via `chatSDK.getHostContext()` |
+| `mfeDirtyState` | `/dirty-state` | Guest calls `viewSDK.markDirtyState()` / `clearDirtyState()` to signal unsaved changes |
### Pointing at a deployed external app
diff --git a/force-app/main/default/cspTrustedSites/MfeAppLocalhost.cspTrustedSite-meta.xml b/force-app/main/default/cspTrustedSites/MfeAppLocalhost.cspTrustedSite-meta.xml
index 0987ccd..1003d18 100644
--- a/force-app/main/default/cspTrustedSites/MfeAppLocalhost.cspTrustedSite-meta.xml
+++ b/force-app/main/default/cspTrustedSites/MfeAppLocalhost.cspTrustedSite-meta.xml
@@ -3,7 +3,7 @@
false
false
All
- Local MFE app dev server — allows the lwc-shell iframe to load from localhost:4300
+ Local MFE app dev server — allows the lightning-embedding iframe to load from localhost:4300
http://localhost:4300
true
false
diff --git a/force-app/main/default/lwc/mfeAutoResize/mfeAutoResize.html b/force-app/main/default/lwc/mfeAutoResize/mfeAutoResize.html
index b5e5c03..9a874a7 100644
--- a/force-app/main/default/lwc/mfeAutoResize/mfeAutoResize.html
+++ b/force-app/main/default/lwc/mfeAutoResize/mfeAutoResize.html
@@ -2,11 +2,19 @@
- Add or remove items in the MFE — the iframe height adjusts automatically.
- No fixed height is set. The bridge reports content height changes via a
- ResizeObserver.
+ Add or remove items in the MFE — the guest calls
+ viewSDK.resize() on every body-size change. The
+ host applies the requested dimensions to the embedding
+ container.
-
+
+
diff --git a/force-app/main/default/lwc/mfeAutoResize/mfeAutoResize.js b/force-app/main/default/lwc/mfeAutoResize/mfeAutoResize.js
index 58b1400..bd19d16 100644
--- a/force-app/main/default/lwc/mfeAutoResize/mfeAutoResize.js
+++ b/force-app/main/default/lwc/mfeAutoResize/mfeAutoResize.js
@@ -1,46 +1,12 @@
import { LightningElement, api } from 'lwc';
-import 'c/vendorLwcShell';
export default class MfeAutoResize extends LightningElement {
@api baseUrl = 'http://localhost:4300';
- _shellElement;
+ debug = false;
get computedSrc() {
const url = new URL(this.baseUrl);
url.pathname = '/auto-resize';
return url.toString();
}
-
- renderedCallback() {
- this._initializeShell();
- }
-
- disconnectedCallback() {
- this._shellElement = null;
- }
-
- _initializeShell() {
- if (this._shellElement) {
- return;
- }
- const container = this.template.querySelector('.shell-container');
- if (!container) {
- return;
- }
- const shell = document.createElement('lwc-shell');
- shell.sandbox = 'allow-forms allow-modals';
- shell.title = 'MFE Auto-Resize';
- shell.src = this.computedSrc;
-
- // No explicit resize handler needed — lwc-shell receives 'resize' events
- // from the bridge and updates iframe.style.height automatically.
- // Cancel the event here if you need a fixed height instead.
- shell.addEventListener('widget-ready', () => {
- // eslint-disable-next-line no-console
- console.log('[MfeAutoResize] widget-ready');
- });
-
- container.appendChild(shell);
- this._shellElement = shell;
- }
}
diff --git a/force-app/main/default/lwc/mfeBasicEmbed/mfeBasicEmbed.html b/force-app/main/default/lwc/mfeBasicEmbed/mfeBasicEmbed.html
index 89cc3b6..a67cb06 100644
--- a/force-app/main/default/lwc/mfeBasicEmbed/mfeBasicEmbed.html
+++ b/force-app/main/default/lwc/mfeBasicEmbed/mfeBasicEmbed.html
@@ -2,10 +2,17 @@
- Minimum viable embed. Creates an lwc-shell pointing at the
- external MFE app and handles the widget-ready event.
+ Minimum viable embed using the standard
+ <lightning-embedding> base component.
-
+
+
diff --git a/force-app/main/default/lwc/mfeBasicEmbed/mfeBasicEmbed.js b/force-app/main/default/lwc/mfeBasicEmbed/mfeBasicEmbed.js
index 62652a4..0202bf7 100644
--- a/force-app/main/default/lwc/mfeBasicEmbed/mfeBasicEmbed.js
+++ b/force-app/main/default/lwc/mfeBasicEmbed/mfeBasicEmbed.js
@@ -1,41 +1,12 @@
import { LightningElement, api } from 'lwc';
-import 'c/vendorLwcShell';
export default class MfeBasicEmbed extends LightningElement {
@api baseUrl = 'http://localhost:4300';
- _shellElement;
+ debug = false;
get computedSrc() {
const url = new URL(this.baseUrl);
url.pathname = '/basic-embed';
return url.toString();
}
-
- renderedCallback() {
- this._initializeShell();
- }
-
- disconnectedCallback() {
- this._shellElement = null;
- }
-
- _initializeShell() {
- if (this._shellElement) {
- return;
- }
- const container = this.template.querySelector('.shell-container');
- if (!container) {
- return;
- }
- const shell = document.createElement('lwc-shell');
- shell.sandbox = 'allow-forms allow-modals';
- shell.title = 'MFE Basic Embed';
- shell.src = this.computedSrc;
- shell.addEventListener('widget-ready', () => {
- // eslint-disable-next-line no-console
- console.log('[MfeBasicEmbed] widget-ready');
- });
- container.appendChild(shell);
- this._shellElement = shell;
- }
}
diff --git a/force-app/main/default/lwc/mfeDirtyState/mfeDirtyState.html b/force-app/main/default/lwc/mfeDirtyState/mfeDirtyState.html
index 8b3353c..87baae4 100644
--- a/force-app/main/default/lwc/mfeDirtyState/mfeDirtyState.html
+++ b/force-app/main/default/lwc/mfeDirtyState/mfeDirtyState.html
@@ -2,16 +2,20 @@
- Type into any field in the MFE form. This component receives a
- trackdirtystate event, re-dispatches it to Lightning
- Experience (which blocks tab navigation), and attaches a
- beforeunload handler so the browser also warns on
- close or reload.
+ Edit the MFE form — the guest calls
+ viewSDK.markDirtyState() on every change and
+ viewSDK.clearDirtyState() after save. The host
+ surface decides how to honour the dirty signal (e.g. block
+ navigation).
-
-
⚠ {dirtyLabel} — save or discard before leaving.
+
+
-
diff --git a/force-app/main/default/lwc/mfeDirtyState/mfeDirtyState.js b/force-app/main/default/lwc/mfeDirtyState/mfeDirtyState.js
index 1cdbb2e..0efd4c6 100644
--- a/force-app/main/default/lwc/mfeDirtyState/mfeDirtyState.js
+++ b/force-app/main/default/lwc/mfeDirtyState/mfeDirtyState.js
@@ -1,101 +1,12 @@
-import { LightningElement, api, track } from 'lwc';
-import 'c/vendorLwcShell';
+import { LightningElement, api } from 'lwc';
export default class MfeDirtyState extends LightningElement {
@api baseUrl = 'http://localhost:4300';
- @track isDirty = false;
- @track dirtyLabel = '';
- _shellElement;
- _beforeUnloadHandler;
+ debug = false;
get computedSrc() {
const url = new URL(this.baseUrl);
url.pathname = '/dirty-state';
return url.toString();
}
-
- get warningClass() {
- return this.isDirty
- ? 'slds-notify slds-notify_alert slds-theme_warning slds-m-bottom_small'
- : 'slds-hide';
- }
-
- renderedCallback() {
- this._initializeShell();
- }
-
- disconnectedCallback() {
- this._shellElement = null;
- this._detachBeforeUnload();
- }
-
- _initializeShell() {
- if (this._shellElement) {
- return;
- }
- const container = this.template.querySelector('.shell-container');
- if (!container) {
- return;
- }
- const shell = document.createElement('lwc-shell');
- shell.sandbox = 'allow-forms allow-modals';
- shell.title = 'MFE Dirty State';
- shell.src = this.computedSrc;
-
- // trackdirtystate fires when the MFE calls
- // bridge.dispatchEvent(new CustomEvent('trackdirtystate', { detail: { isDirty, label } }))
- shell.addEventListener('trackdirtystate', (evt) => {
- const isDirty = !!evt.detail.isDirty;
- const label = evt.detail.label ?? 'Unsaved changes';
- this.isDirty = isDirty;
- this.dirtyLabel = label;
-
- // Re-dispatch from the LWC itself so Lightning Experience picks it
- // up and blocks navigation with its standard unsaved-changes dialog.
- this.dispatchEvent(
- new CustomEvent('trackdirtystate', {
- detail: { isDirty, label },
- bubbles: true,
- composed: true,
- })
- );
-
- // Belt-and-suspenders: also warn on browser-level navigation
- // (tab close, reload, URL change). Works when the component is
- // hosted outside a Lightning context too.
- if (isDirty) {
- this._attachBeforeUnload();
- } else {
- this._detachBeforeUnload();
- }
- });
-
- shell.addEventListener('widget-ready', () => {
- // eslint-disable-next-line no-console
- console.log('[MfeDirtyState] widget-ready');
- });
-
- container.appendChild(shell);
- this._shellElement = shell;
- }
-
- _attachBeforeUnload() {
- if (this._beforeUnloadHandler) {
- return;
- }
- this._beforeUnloadHandler = (evt) => {
- evt.preventDefault();
- // Modern browsers ignore the custom string but require returnValue set.
- evt.returnValue = '';
- };
- window.addEventListener('beforeunload', this._beforeUnloadHandler);
- }
-
- _detachBeforeUnload() {
- if (!this._beforeUnloadHandler) {
- return;
- }
- window.removeEventListener('beforeunload', this._beforeUnloadHandler);
- this._beforeUnloadHandler = null;
- }
}
diff --git a/force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.html b/force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.html
deleted file mode 100644
index 68cfcaa..0000000
--- a/force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.html
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-
-
- The MFE executes Salesforce GraphQL queries via bridge.graphql().
- The host proxies requests — no allow-same-origin needed.
- Up to 10 concurrent requests are supported.
-
-
-
-
diff --git a/force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.js b/force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.js
deleted file mode 100644
index 1a26acb..0000000
--- a/force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.js
+++ /dev/null
@@ -1,50 +0,0 @@
-import { LightningElement, api } from 'lwc';
-import 'c/vendorLwcShell';
-
-export default class MfeGraphQL extends LightningElement {
- @api baseUrl = 'http://localhost:4300';
- _shellElement;
-
- get computedSrc() {
- const url = new URL(this.baseUrl);
- url.pathname = '/graphql-bridge';
- return url.toString();
- }
-
- renderedCallback() {
- this._initializeShell();
- }
-
- disconnectedCallback() {
- this._shellElement = null;
- }
-
- _initializeShell() {
- if (this._shellElement) {
- return;
- }
- const container = this.template.querySelector('.shell-container');
- if (!container) {
- return;
- }
- const shell = document.createElement('lwc-shell');
- // allow-same-origin intentionally omitted — the GraphQL bridge proxies
- // queries through the host so the MFE never needs direct same-origin access.
- shell.sandbox = 'allow-forms allow-modals';
- shell.title = 'MFE GraphQL Bridge';
- shell.src = this.computedSrc;
-
- shell.addEventListener('widget-bridge-error', (evt) => {
- // eslint-disable-next-line no-console
- console.error('[MfeGraphQL] bridge error', evt.detail);
- });
-
- shell.addEventListener('widget-ready', () => {
- // eslint-disable-next-line no-console
- console.log('[MfeGraphQL] widget-ready — GraphQL bridge active');
- });
-
- container.appendChild(shell);
- this._shellElement = shell;
- }
-}
diff --git a/force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.js-meta.xml b/force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.js-meta.xml
deleted file mode 100644
index 620831e..0000000
--- a/force-app/main/default/lwc/mfeGraphQL/mfeGraphQL.js-meta.xml
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
- 66.0
- true
-
- lightning__AppPage
- lightning__RecordPage
- lightning__HomePage
-
-
diff --git a/force-app/main/default/lwc/mfeReceiveData/mfeReceiveData.html b/force-app/main/default/lwc/mfeReceiveData/mfeReceiveData.html
index 602042f..d1ea53e 100644
--- a/force-app/main/default/lwc/mfeReceiveData/mfeReceiveData.html
+++ b/force-app/main/default/lwc/mfeReceiveData/mfeReceiveData.html
@@ -2,8 +2,9 @@
- Type a message and click Send — the MFE receives it via
- bridge.addEventListener('data', handler).
+ Type a message and click Send — the host re-mounts the embedding
+ with a new src carrying the value as a query
+ parameter. The MFE reads it via URLSearchParams.
diff --git a/force-app/main/default/lwc/mfeReceiveData/mfeReceiveData.js b/force-app/main/default/lwc/mfeReceiveData/mfeReceiveData.js
index 7b144b3..b20e074 100644
--- a/force-app/main/default/lwc/mfeReceiveData/mfeReceiveData.js
+++ b/force-app/main/default/lwc/mfeReceiveData/mfeReceiveData.js
@@ -1,54 +1,28 @@
import { LightningElement, api, track } from 'lwc';
-import 'c/vendorLwcShell';
export default class MfeReceiveData extends LightningElement {
@api baseUrl = 'http://localhost:4300';
@track inputValue = 'Hello from Salesforce';
- _shellElement;
-
- get computedSrc() {
- const url = new URL(this.baseUrl);
- url.pathname = '/receive-data';
- return url.toString();
- }
-
- renderedCallback() {
- this._initializeShell();
- }
-
- disconnectedCallback() {
- this._shellElement = null;
- }
+ @track committedSrc;
+ debug = false;
handleInputChange(evt) {
this.inputValue = evt.target.value;
}
handleSend() {
- if (!this._shellElement) {
- return;
- }
- // updateData() sends a postMessage into the MFE iframe.
- // The MFE receives it via bridge.addEventListener('data', handler).
- this._shellElement.updateData({ message: this.inputValue, timestamp: Date.now() });
- }
+ //
's `src` is session-binding (read at mount; cannot
+ // be mutated). Re-render the element with a new src that carries the
+ // value as a query parameter; the MFE reads it via URLSearchParams.
+ const url = new URL(this.baseUrl);
+ url.pathname = '/receive-data';
+ url.searchParams.set('message', this.inputValue);
+ url.searchParams.set('timestamp', String(Date.now()));
- _initializeShell() {
- if (this._shellElement) {
- return;
- }
- const container = this.template.querySelector('.shell-container');
- if (!container) {
- return;
- }
- const shell = document.createElement('lwc-shell');
- shell.sandbox = 'allow-forms allow-modals';
- shell.title = 'MFE Receive Data';
- shell.src = this.computedSrc;
- shell.addEventListener('widget-ready', () => {
- this._shellElement.updateData({ message: this.inputValue, timestamp: Date.now() });
+ // Force remount: clear, then set on the next microtask.
+ this.committedSrc = undefined;
+ Promise.resolve().then(() => {
+ this.committedSrc = url.toString();
});
- container.appendChild(shell);
- this._shellElement = shell;
}
}
diff --git a/force-app/main/default/lwc/mfeSendEvent/mfeSendEvent.html b/force-app/main/default/lwc/mfeSendEvent/mfeSendEvent.html
index 4bd4072..211802a 100644
--- a/force-app/main/default/lwc/mfeSendEvent/mfeSendEvent.html
+++ b/force-app/main/default/lwc/mfeSendEvent/mfeSendEvent.html
@@ -2,15 +2,20 @@
- Click an action button in the MFE — the event arrives here via
- shell.addEventListener('mfe-action', handler).
+ Click an action button in the MFE — the guest calls
+ viewSDK.dispatchEvent(name, data). Surface-level
+ routing of those events to LWC code is host-runtime specific;
+ check your surface (MCPApps, OpenAI, etc.) for the listener
+ contract.
-
-
- Last action from MFE: {lastAction}
-
-
-
+
+
diff --git a/force-app/main/default/lwc/mfeSendEvent/mfeSendEvent.js b/force-app/main/default/lwc/mfeSendEvent/mfeSendEvent.js
index f52fb8f..b5515e4 100644
--- a/force-app/main/default/lwc/mfeSendEvent/mfeSendEvent.js
+++ b/force-app/main/default/lwc/mfeSendEvent/mfeSendEvent.js
@@ -1,50 +1,12 @@
-import { LightningElement, api, track } from 'lwc';
-import 'c/vendorLwcShell';
+import { LightningElement, api } from 'lwc';
export default class MfeSendEvent extends LightningElement {
@api baseUrl = 'http://localhost:4300';
- @track lastAction = '';
- _shellElement;
+ debug = false;
get computedSrc() {
const url = new URL(this.baseUrl);
url.pathname = '/send-event';
return url.toString();
}
-
- renderedCallback() {
- this._initializeShell();
- }
-
- disconnectedCallback() {
- this._shellElement = null;
- }
-
- _initializeShell() {
- if (this._shellElement) {
- return;
- }
- const container = this.template.querySelector('.shell-container');
- if (!container) {
- return;
- }
- const shell = document.createElement('lwc-shell');
- shell.sandbox = 'allow-forms allow-modals';
- shell.title = 'MFE Send Event';
- shell.src = this.computedSrc;
-
- // MFE dispatches bridge.dispatchEvent(new CustomEvent('mfe-action', { detail }))
- // lwc-shell re-dispatches it here as a DOM event on the shell element.
- shell.addEventListener('mfe-action', (evt) => {
- this.lastAction = `${evt.detail.action} at ${new Date(evt.detail.timestamp).toLocaleTimeString()}`;
- });
-
- shell.addEventListener('widget-ready', () => {
- // eslint-disable-next-line no-console
- console.log('[MfeSendEvent] widget-ready');
- });
-
- container.appendChild(shell);
- this._shellElement = shell;
- }
}
diff --git a/force-app/main/default/lwc/mfeThemeTokens/mfeThemeTokens.html b/force-app/main/default/lwc/mfeThemeTokens/mfeThemeTokens.html
index 674fa4e..72a3801 100644
--- a/force-app/main/default/lwc/mfeThemeTokens/mfeThemeTokens.html
+++ b/force-app/main/default/lwc/mfeThemeTokens/mfeThemeTokens.html
@@ -2,15 +2,19 @@
- Salesforce CSS custom properties are sent to the MFE automatically on connect.
- Click Refresh to re-sync after a theme change.
+ The host's theme mode is delivered to the MFE through the
+ Platform SDK. The guest reads it via
+ viewSDK.getTheme() and the broader environment
+ via chatSDK.getHostContext().
-
-
+
+
diff --git a/force-app/main/default/lwc/mfeThemeTokens/mfeThemeTokens.js b/force-app/main/default/lwc/mfeThemeTokens/mfeThemeTokens.js
index 04fadfb..24568bb 100644
--- a/force-app/main/default/lwc/mfeThemeTokens/mfeThemeTokens.js
+++ b/force-app/main/default/lwc/mfeThemeTokens/mfeThemeTokens.js
@@ -1,51 +1,12 @@
import { LightningElement, api } from 'lwc';
-import 'c/vendorLwcShell';
export default class MfeThemeTokens extends LightningElement {
@api baseUrl = 'http://localhost:4300';
- _shellElement;
+ debug = false;
get computedSrc() {
const url = new URL(this.baseUrl);
url.pathname = '/theme-tokens';
return url.toString();
}
-
- renderedCallback() {
- this._initializeShell();
- }
-
- disconnectedCallback() {
- this._shellElement = null;
- }
-
- handleRefreshTheme() {
- if (!this._shellElement) {
- return;
- }
- // Re-collects all CSS custom properties from the lwc-shell element
- // and pushes them to the MFE. Call this after the host page theme changes.
- this._shellElement.refreshTheme();
- }
-
- _initializeShell() {
- if (this._shellElement) {
- return;
- }
- const container = this.template.querySelector('.shell-container');
- if (!container) {
- return;
- }
- const shell = document.createElement('lwc-shell');
- shell.sandbox = 'allow-forms allow-modals';
- shell.title = 'MFE Theme Tokens';
- shell.src = this.computedSrc;
- // Theme is sent automatically on connect. refreshTheme() re-syncs on demand.
- shell.addEventListener('widget-ready', () => {
- // eslint-disable-next-line no-console
- console.log('[MfeThemeTokens] widget-ready — theme sent automatically');
- });
- container.appendChild(shell);
- this._shellElement = shell;
- }
}
diff --git a/force-app/main/default/lwc/vendorLwcShell/vendorLwcShell.js b/force-app/main/default/lwc/vendorLwcShell/vendorLwcShell.js
deleted file mode 100644
index ad3fb3a..0000000
--- a/force-app/main/default/lwc/vendorLwcShell/vendorLwcShell.js
+++ /dev/null
@@ -1,766 +0,0 @@
-/* eslint-disable */
-// Vendored from @salesforce/experimental-mfe-lwc-shell npm package
-/*! @salesforce/experimental-mfe-lwc-shell v2.2.1-rc.1 (2026-04-09) */
-import { gql, unstable_graphql_imperative } from 'lightning/graphql';
-
-/**
- * EmbeddingResizer - Handles dynamic iframe/container resizing
- * Uses ResizeObserver to monitor element size changes and notify the host
- */
-/**
- * Generates a pseudo-random alphanumeric identifier string for unique
- * element IDs or temporary identifiers (not cryptographically secure).
- *
- * @returns Random alphanumeric string
- *
- * @example
- * getUUID(); // 'k2j8f5l9m'
- */
-function getUUID() {
- return Math.floor(Math.random() * Number.MAX_SAFE_INTEGER).toString(36);
-}
-
-async function executeGraphQL(query, variables) {
- if (typeof query !== "string" || query.trim() === "") {
- throw new Error("Invalid GraphQL query: query must be a non-empty string.");
- }
- const documentNode = gql `
- ${query}
- `;
- const result = await unstable_graphql_imperative({ query: documentNode, variables });
- return { data: result?.data, errors: result?.errors };
-}
-class GraphQLBridgeHandler {
- #sendResponse;
- #pendingCount = 0;
- #queue = [];
- #maxConcurrent;
- #maxQueueSize;
- #generation = 0;
- constructor(sendResponse, maxConcurrent = 10, maxQueueSize = 50) {
- this.#sendResponse = sendResponse;
- this.#maxConcurrent = maxConcurrent;
- this.#maxQueueSize = maxQueueSize;
- }
- static isValidRequest(data) {
- const req = data;
- return (typeof req?.requestId === "string" &&
- typeof req?.query === "string" &&
- (req.variables == null || (typeof req.variables === "object" && !Array.isArray(req.variables))));
- }
- rejectInvalidRequest(data) {
- const req = data;
- if (typeof req?.requestId !== "string") {
- this.#sendResponse({
- requestId: req?.requestId,
- ok: false,
- error: { message: "Invalid GraphQL request data" },
- });
- return;
- }
- const { requestId, query, variables } = req;
- if (typeof query !== "string") {
- this.#sendResponse({
- requestId: requestId,
- ok: false,
- error: { message: "Invalid GraphQL query: query must be a string" },
- });
- return;
- }
- if (variables != null && (typeof variables !== "object" || Array.isArray(variables))) {
- this.#sendResponse({
- requestId: requestId,
- ok: false,
- error: { message: "Invalid GraphQL variables: must be a plain object" },
- });
- }
- }
- handleRequest({ requestId, query, variables }) {
- if (this.#pendingCount >= this.#maxConcurrent) {
- return this.#enqueueRequest(requestId, query, variables);
- }
- return this.#execute(requestId, query, variables);
- }
- reset() {
- this.#generation++;
- this.#queue = [];
- this.#pendingCount = 0;
- }
- #execute = async (requestId, query, variables) => {
- const gen = this.#generation;
- this.#pendingCount++;
- try {
- const result = await executeGraphQL(query, variables);
- if (gen === this.#generation) {
- this.#sendResponse({ requestId, ok: true, result });
- }
- }
- catch (err) {
- if (gen === this.#generation) {
- this.#sendResponse({
- requestId,
- ok: false,
- error: { message: err?.message || "GraphQL request failed" },
- });
- }
- }
- finally {
- if (gen === this.#generation) {
- this.#pendingCount--;
- this.#processRequestQueue();
- }
- }
- };
- #enqueueRequest = (requestId, query, variables) => {
- if (this.#queue.length >= this.#maxQueueSize) {
- this.#sendResponse({
- requestId,
- ok: false,
- error: { message: "Too many queued GraphQL requests" },
- });
- return Promise.resolve();
- }
- return new Promise((resolve) => {
- this.#queue.push({ requestId, query, variables, done: resolve });
- });
- };
- #processRequestQueue = () => {
- if (this.#queue.length === 0 || this.#pendingCount >= this.#maxConcurrent) {
- return;
- }
- const next = this.#queue.shift();
- this.#execute(next.requestId, next.query, next.variables).then(next.done);
- };
-}
-
-/**
- * InternalHostLwcShell
- *
- * A standard Web Component (custom element) that embeds an iframe-based widget
- * with bridge communication, sandbox management, and fullscreen support.
- *
- * Registered as ``.
- *
- * Dirty-state tracking is handled via a simple `trackdirtystate`
- * custom-event flow: the embedded widget dispatches `trackdirtystate`
- * with `{ isDirty, instanceId, label }`, and this shell re-dispatches
- * the event for the host LWC to observe.
- *
- * **How customers use this:**
- * 1. The build produces `dist/index.esm.js` which bundles this class.
- * 2. Customers copy that file into their SFDX project as an LWC entity
- * (e.g. `c/lwcShell`) and deploy it to their Salesforce org.
- * 3. A wrapper LWC imports `'c/lwcShell'` and creates ``
- * imperatively via `document.createElement('lwc-shell')`.
- *
- * See the README and the `productRegistration` demo for a full recipe.
- */
-const MAX_CONCURRENT_GRAPHQL_REQUESTS = 10;
-const MAX_GRAPHQL_QUEUE_SIZE = 50;
-const BASE_TOKENS = ["allow-scripts", "allow-pointer-lock"];
-const OPTIONAL_TOKENS = ["allow-downloads", "allow-forms", "allow-modals"];
-const BLOCKED_TOKENS = ["allow-same-origin", "allow-top-navigation", "allow-popups"];
-const STATES = {
- LOADING: "state-loading",
- LOADED: "state-loaded",
-};
-const STYLES = /* css */ `
-:host {
- display: block;
- position: relative;
- height: 100%;
- overflow: auto;
- box-sizing: border-box;
-}
-
-.container {
- width: 100%;
- height: 100%;
- position: relative;
-}
-
-.frame {
- visibility: hidden;
- display: block;
- width: 100%;
- height: 100%;
- border: none;
-}
-
-.container[data-state='state-loaded'] .frame {
- visibility: visible;
-}
-
-/* Fullscreen overlay */
-.overlayBackdrop {
- position: fixed;
- inset: 0;
- width: 100vw;
- height: 100vh;
- z-index: 9998;
- background: rgba(0, 0, 0, 0.8);
- backdrop-filter: blur(4px);
-}
-
-.overlayClose {
- position: fixed;
- top: 24px;
- right: 24px;
- z-index: 9999;
- width: 32px;
- height: 32px;
- background: rgba(0, 0, 0, 0.7);
- color: #fff;
- border-radius: 50%;
- border: none;
- display: flex;
- align-items: center;
- justify-content: center;
- font-size: 16px;
- font-weight: bold;
- cursor: pointer;
-}
-
-.frameFull {
- position: fixed;
- inset: 0;
- width: 90vw;
- height: 90vh !important;
- margin: 5vh 5vw;
- z-index: 10000;
- background: #fff;
- border-radius: 8px;
- box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3);
-}
-`;
-class InternalHostLwcShell extends HTMLElement {
- _shadow;
- _iframe = null;
- _container = null;
- _currentState = STATES.LOADING;
- _readinessTimeout = null;
- _isFullscreen = false;
- _preFullscreenHeight = "";
- _lastThemeData = {};
- _lastPayloadData = {};
- _bridgeReady = false;
- _shellInstanceId = getUUID();
- _hasSentTheme = false;
- _hasSentData = false;
- _src = null;
- _srcdoc = null;
- _sandbox = null;
- _title = "Embedded widget";
- _view = "compact";
- _debugEnabled = true;
- _graphqlHandler;
- static get observedAttributes() {
- return ["src", "srcdoc", "sandbox", "title", "view", "debug"];
- }
- constructor() {
- super();
- this._shadow = this.attachShadow({ mode: "closed" });
- this._graphqlHandler = new GraphQLBridgeHandler((data) => {
- this._postToIframe("bridge-graphql-response", data);
- }, MAX_CONCURRENT_GRAPHQL_REQUESTS, MAX_GRAPHQL_QUEUE_SIZE);
- }
- connectedCallback() {
- this._renderInitial();
- this._setupMessageListener();
- this._log("connectedCallback");
- }
- disconnectedCallback() {
- window.removeEventListener("message", this._handleMessage);
- this._graphqlHandler.reset();
- if (this._readinessTimeout) {
- clearTimeout(this._readinessTimeout);
- this._readinessTimeout = null;
- }
- this._log("disconnectedCallback");
- }
- attributeChangedCallback(name, oldVal, newVal) {
- if (oldVal === newVal)
- return;
- switch (name) {
- case "src":
- this.src = newVal;
- break;
- case "srcdoc":
- this.srcdoc = newVal;
- break;
- case "sandbox":
- this.sandbox = newVal;
- break;
- case "title":
- this.title = newVal;
- break;
- case "view":
- this.view = newVal;
- break;
- case "debug":
- this.debug = newVal !== null;
- break;
- }
- }
- get src() {
- return this._src;
- }
- set src(v) {
- const val = v || null;
- if (this._src === val)
- return;
- this._src = val;
- if (val !== null) {
- this.setAttribute("src", val);
- }
- else {
- this.removeAttribute("src");
- }
- this._updateIframeSrc();
- }
- get srcdoc() {
- return this._srcdoc;
- }
- set srcdoc(v) {
- const val = v || null;
- if (this._srcdoc === val)
- return;
- this._srcdoc = val;
- if (val !== null) {
- this.setAttribute("srcdoc", val);
- }
- else {
- this.removeAttribute("srcdoc");
- }
- this._updateIframeSrc();
- }
- get sandbox() {
- return this._sandbox;
- }
- set sandbox(v) {
- const val = v || null;
- if (this._sandbox === val)
- return;
- this._sandbox = val;
- if (val !== null) {
- this.setAttribute("sandbox", val);
- }
- else {
- this.removeAttribute("sandbox");
- }
- this._applySandbox();
- }
- get title() {
- return this._title;
- }
- set title(v) {
- const val = v || "Embedded widget";
- if (this._title === val)
- return;
- this._title = val;
- this.setAttribute("title", val);
- this._updateTitle();
- }
- get view() {
- return this._view;
- }
- set view(v) {
- const val = v === "full" ? "full" : "compact";
- if (this._view === val)
- return;
- this._view = val;
- this.setAttribute("view", val);
- this._updateViewDOM();
- }
- /**
- * Controls debug logging. Toggle via:
- * - HTML attribute: ``
- * - Programmatically: `shell.debug = true`
- */
- get debug() {
- return this._debugEnabled;
- }
- set debug(v) {
- const val = !!v;
- if (this._debugEnabled === val)
- return;
- this._debugEnabled = val;
- if (val) {
- this.setAttribute("debug", "");
- }
- else {
- this.removeAttribute("debug");
- }
- }
- updateData(newData) {
- if (!newData || typeof newData !== "object")
- return;
- Object.entries(newData).forEach(([key, value]) => {
- const dataAttr = `data-${String(key).replace(/[A-Z]/g, "-$&").toLowerCase()}`;
- this.setAttribute(dataAttr, String(value));
- });
- const payload = this._collectDataAttributes();
- this._lastPayloadData = payload;
- if (this._bridgeReady) {
- this._postToIframe("data", payload);
- this._hasSentData = true;
- this._log("send data", payload);
- }
- else {
- this._log("queue data until bridge ready", payload);
- }
- }
- refreshTheme() {
- this._sendInitialTheme();
- }
- get _isFullView() {
- return this._view === "full";
- }
- get _frameClass() {
- return this._isFullView ? "frame frameFull" : "frame";
- }
- _log(...args) {
- if (this._debugEnabled) {
- // eslint-disable-next-line no-console
- console.log("[InternalHostLwcShell]", JSON.stringify(args, null, 2));
- }
- }
- _renderInitial() {
- const shadow = this._shadow;
- shadow.innerHTML = `
-
-
-
-
- `;
- this._container = shadow.querySelector(".container");
- this._iframe = shadow.querySelector("iframe");
- this._container.addEventListener("click", () => this._handleContainerClick());
- this._applySandbox();
- this._updateIframeSrc();
- this._sendInitialTheme();
- this._log("renderInitial: iframe ready");
- }
- _updateContainerState() {
- if (this._container) {
- this._container.setAttribute("data-state", this._currentState);
- }
- }
- _updateTitle() {
- if (this._iframe) {
- this._iframe.setAttribute("title", this._title);
- }
- if (this._container) {
- this._container.setAttribute("aria-label", this._title);
- }
- this._log("title", this._title);
- }
- _updateViewDOM() {
- if (this._iframe) {
- this._iframe.className = this._frameClass;
- }
- if (!this._container)
- return;
- const existingBackdrop = this._container.querySelector(".overlayBackdrop");
- const existingClose = this._container.querySelector(".overlayClose");
- if (existingBackdrop)
- existingBackdrop.remove();
- if (existingClose)
- existingClose.remove();
- if (this._isFullView) {
- const backdrop = document.createElement("div");
- backdrop.className = "overlayBackdrop";
- backdrop.setAttribute("aria-hidden", "true");
- const closeBtn = document.createElement("button");
- closeBtn.className = "overlayClose";
- closeBtn.type = "button";
- closeBtn.setAttribute("aria-label", "Close fullscreen");
- closeBtn.textContent = "\u2715";
- closeBtn.addEventListener("click", this._exitFullscreen);
- this._container.appendChild(backdrop);
- this._container.appendChild(closeBtn);
- }
- }
- _setState(newState) {
- this._currentState = newState;
- this._updateContainerState();
- if (newState === STATES.LOADED) {
- this._sendInitialData();
- }
- }
- _setupMessageListener() {
- window.addEventListener("message", this._handleMessage);
- }
- _handleMessage = (event) => {
- const sourceWin = this._iframe?.contentWindow;
- if (event.source !== sourceWin) {
- return;
- }
- const payload = event.data || {};
- const { type, data, id } = payload;
- if (id ? id !== this._shellInstanceId : type !== "bridge-ready")
- return;
- this._log("receive", type, data);
- if (type === "bridge-event") {
- const { eventType, detail } = data || {};
- this._log("bridge-event", eventType, detail);
- if (eventType === "resize") {
- this._handleResize(detail);
- }
- else if (eventType === "widget-ready") {
- this._handleWidgetReady();
- }
- else {
- throw new RangeError(`Invalid bridge event ${eventType}`);
- }
- }
- else if (type === "custom-event") {
- const { eventType, detail } = data || {};
- this._log("custom-event", eventType, detail);
- if (eventType === "fullscreen-request") {
- const shouldRunDefault = this.dispatchEvent(new CustomEvent(eventType, {
- detail,
- bubbles: true,
- cancelable: true,
- }));
- if (shouldRunDefault) {
- this._handleFullscreenRequest();
- }
- }
- else {
- this.dispatchEvent(new CustomEvent(eventType, { detail, bubbles: true, cancelable: true, composed: true }));
- }
- }
- else if (type === "bridge-graphql-request") {
- if (GraphQLBridgeHandler.isValidRequest(data)) {
- this._graphqlHandler.handleRequest(data);
- }
- else {
- this._graphqlHandler.rejectInvalidRequest(data);
- }
- }
- else if (type === "bridge-ready") {
- this._handleBridgeReady();
- }
- else if (type === "bridge-error") {
- this._handleBridgeError(data);
- }
- };
- _handleResize({ height }) {
- const evt = new CustomEvent("resize", {
- detail: { height },
- cancelable: true,
- });
- this.dispatchEvent(evt);
- if (!evt.defaultPrevented && !this._isFullscreen && typeof height === "number" && Number.isFinite(height)) {
- if (this._iframe)
- this._iframe.style.height = height + "px";
- this._log("applied resize", height);
- }
- }
- _handleWidgetReady() {
- if (this._readinessTimeout) {
- clearTimeout(this._readinessTimeout);
- this._readinessTimeout = null;
- }
- this.dispatchEvent(new CustomEvent("widget-ready", { bubbles: true }));
- this._log("widget-ready");
- }
- _handleFullscreenRequest() {
- if (!this._isFullscreen) {
- this._enterFullscreen();
- }
- }
- _enterFullscreen() {
- this._isFullscreen = true;
- this._preFullscreenHeight = this._iframe?.style.height ?? "";
- this._view = "full";
- this._updateViewDOM();
- if (this._iframe)
- this._iframe.style.height = "100%";
- this.updateData({ view: "full" });
- this.dispatchEvent(new CustomEvent("fullscreen-entered", {
- detail: { element: this },
- bubbles: true,
- }));
- this._log("enter fullscreen");
- }
- _exitFullscreen = () => {
- this._isFullscreen = false;
- this._view = "compact";
- this._updateViewDOM();
- if (this._iframe)
- this._iframe.style.height = this._preFullscreenHeight;
- this.updateData({ view: "compact" });
- this.dispatchEvent(new CustomEvent("fullscreen-exited", {
- detail: { element: this },
- bubbles: true,
- }));
- this._log("exit fullscreen");
- };
- _handleBridgeReady() {
- this._bridgeReady = true;
- this._postToIframe("shell-ready");
- this._setState(STATES.LOADED);
- }
- _handleBridgeError(errorData) {
- this.dispatchEvent(new CustomEvent("widget-bridge-error", { detail: errorData }));
- this._log("bridge-error", errorData);
- }
- _handleContainerClick() {
- // placeholder
- }
- _applySandbox() {
- const frame = this._iframe;
- if (!frame)
- return;
- const tokens = this._computeSandboxTokens();
- frame.setAttribute("sandbox", tokens);
- this._log("sandbox", tokens);
- }
- _computeSandboxTokens() {
- const tokens = [...BASE_TOKENS];
- if (this._sandbox) {
- const requested = String(this._sandbox).split(/\s+/).filter(Boolean);
- requested.forEach((t) => {
- if (OPTIONAL_TOKENS.includes(t) && !tokens.includes(t))
- tokens.push(t);
- if (BLOCKED_TOKENS.includes(t)) {
- this.dispatchEvent(new CustomEvent("security-violation", {
- detail: {
- type: "blocked-sandbox-token",
- token: t,
- element: this,
- },
- }));
- }
- });
- }
- return tokens.join(" ");
- }
- _updateIframeSrc() {
- const frame = this._iframe;
- if (!frame)
- return;
- // reset tracking
- this._bridgeReady = false;
- this._graphqlHandler.reset();
- this._currentState = STATES.LOADING;
- this._updateContainerState();
- // clear existing
- frame.removeAttribute("src");
- frame.removeAttribute("srcdoc");
- if (this._src) {
- frame.setAttribute("src", this._src);
- }
- else if (this._srcdoc) {
- try {
- frame.setAttribute("srcdoc", this._srcdoc);
- }
- catch {
- frame.setAttribute("src", "about:blank");
- }
- }
- // load events
- frame.onload = this._handleIframeLoad;
- frame.onerror = this._handleIframeError;
- this._log("updateIframeSrc", this._src ? "src" : this._srcdoc ? "srcdoc" : "blank");
- }
- _handleIframeLoad = () => {
- this.dispatchEvent(new CustomEvent("iframe-loaded", {
- detail: { element: this },
- bubbles: true,
- }));
- this._log("iframe-loaded");
- this._readinessTimeout = setTimeout(() => {
- if (this._currentState !== STATES.LOADED) {
- this.dispatchEvent(new CustomEvent("widget-readiness-warning", {
- detail: {
- element: this,
- message: "Widget may not be using Bridge for readiness signaling",
- },
- bubbles: true,
- }));
- this._log("widget-readiness-warning");
- }
- }, 3000);
- };
- _handleIframeError = (error) => {
- this.dispatchEvent(new CustomEvent("widget-error", {
- detail: { error, element: this },
- }));
- };
- _postToIframe(type, data) {
- const win = this._iframe?.contentWindow;
- if (!win)
- return;
- try {
- const msgType = `salesforce-${type}`;
- win.postMessage({ type: msgType, data, id: this._shellInstanceId }, "*");
- this._log("postMessage", msgType, data);
- }
- catch (e) {
- this._log("postMessage error", e instanceof Error ? e.message : String(e));
- }
- }
- _collectDataAttributes() {
- const out = {};
- for (let i = 0; i < this.attributes.length; i++) {
- const a = this.attributes[i];
- if (a.name.startsWith("data-")) {
- const raw = a.name.replace(/^data-/, "");
- // convert kebab-case to camelCase
- const camel = raw.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
- out[camel] = a.value;
- }
- }
- return out;
- }
- _sendInitialTheme() {
- const computed = getComputedStyle(this);
- const theme = {};
- for (let i = 0; i < computed.length; i++) {
- const name = computed[i];
- if (name.startsWith("--")) {
- const val = computed.getPropertyValue(name).trim();
- if (val)
- theme[name] = val;
- }
- }
- this._lastThemeData = theme;
- if (this._bridgeReady) {
- this._postToIframe("theme", theme);
- this._hasSentTheme = true;
- this._log("send theme", theme);
- }
- else {
- this._log("queue theme until bridge ready", theme);
- }
- }
- _sendInitialData() {
- if (this._lastThemeData && Object.keys(this._lastThemeData).length) {
- this._postToIframe("theme", this._lastThemeData);
- this._hasSentTheme = true;
- this._log("send theme (initial)", this._lastThemeData);
- }
- const payload = this._collectDataAttributes();
- this._lastPayloadData = { ...payload };
- this._postToIframe("data", this._lastPayloadData);
- this._hasSentData = true;
- this._log("send data (initial)", this._lastPayloadData);
- }
-}
-// ---------------------------------------------------------------------------
-// Register the custom element
-// ---------------------------------------------------------------------------
-if (!window.customElements.get("lwc-shell")) {
- window.customElements.define("lwc-shell", InternalHostLwcShell);
-}
-
-export { InternalHostLwcShell, InternalHostLwcShell as default };
-//# sourceMappingURL=index.esm.js.map
diff --git a/force-app/main/default/lwc/vendorLwcShell/vendorLwcShell.js-meta.xml b/force-app/main/default/lwc/vendorLwcShell/vendorLwcShell.js-meta.xml
deleted file mode 100644
index 9176009..0000000
--- a/force-app/main/default/lwc/vendorLwcShell/vendorLwcShell.js-meta.xml
+++ /dev/null
@@ -1,5 +0,0 @@
-
-
- 64.0
- false
-
diff --git a/force-app/main/react-recipes/uiBundles/reactRecipes/src/components/app/Navbar.tsx b/force-app/main/react-recipes/uiBundles/reactRecipes/src/components/app/Navbar.tsx
index c6daa51..88c6438 100644
--- a/force-app/main/react-recipes/uiBundles/reactRecipes/src/components/app/Navbar.tsx
+++ b/force-app/main/react-recipes/uiBundles/reactRecipes/src/components/app/Navbar.tsx
@@ -13,7 +13,7 @@ const navItems = [
{ to: '/error-handling', label: 'Error Handling' },
{ to: '/styling', label: 'Styling' },
{ to: '/routing', label: 'Routing' },
- { to: '/mfe', label: 'Embedding' },
+ { to: '/embedding', label: 'Embedding' },
];
export default function Navbar() {
diff --git a/force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Home.tsx b/force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Home.tsx
index 03da58d..944261a 100644
--- a/force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Home.tsx
+++ b/force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Home.tsx
@@ -73,10 +73,10 @@ const categories = [
'End-to-end patterns that combine multiple Salesforce APIs and React features into realistic, production-style application pages.',
},
{
- to: '/mfe',
+ to: '/embedding',
name: 'Embedding',
description:
- 'Embed an external framework app into Salesforce Lightning via lwc-shell. Covers the Platform SDK: basic embed, receiving host data, dispatching events, auto-resize, theme tokens, dirty state, and GraphQL proxying.',
+ 'Embed an external framework app into Salesforce Lightning via . Covers the Platform SDK: basic embed, receiving host props, dispatching events, auto-resize, theme tokens, and dirty state.',
},
];
@@ -237,7 +237,7 @@ export default function Home() {
icon={. Best for existing apps and SaaS vendors.'
}
onClick={() => activate('externally-hosted')}
/>
diff --git a/force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Mfe.tsx b/force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Mfe.tsx
index e98b7c8..6211e41 100644
--- a/force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Mfe.tsx
+++ b/force-app/main/react-recipes/uiBundles/reactRecipes/src/pages/Mfe.tsx
@@ -35,14 +35,13 @@ import {
} from '@/lib/framework';
import type { Framework, Hosting } from '@/recipeRegistry';
-// MFE bridge sources (mfe-app/src/recipes/)
+// MFE guest sources (mfe-app/src/recipes/)
import basicEmbedMfe from '../../../../../../../mfe-app/src/recipes/BasicEmbed.tsx?shiki';
import receiveDataMfe from '../../../../../../../mfe-app/src/recipes/ReceiveData.tsx?shiki';
import sendEventMfe from '../../../../../../../mfe-app/src/recipes/SendEvent.tsx?shiki';
import autoResizeMfe from '../../../../../../../mfe-app/src/recipes/AutoResize.tsx?shiki';
import themeTokensMfe from '../../../../../../../mfe-app/src/recipes/ThemeTokens.tsx?shiki';
import dirtyStateMfe from '../../../../../../../mfe-app/src/recipes/DirtyState.tsx?shiki';
-import graphQLMfe from '../../../../../../../mfe-app/src/recipes/GraphQLBridge.tsx?shiki';
// LWC host JS sources (force-app/main/default/lwc/)
import basicEmbedJs from '../../../../../default/lwc/mfeBasicEmbed/mfeBasicEmbed.js?shiki=js';
@@ -51,7 +50,6 @@ import sendEventJs from '../../../../../default/lwc/mfeSendEvent/mfeSendEvent.js
import autoResizeJs from '../../../../../default/lwc/mfeAutoResize/mfeAutoResize.js?shiki=js';
import themeTokensJs from '../../../../../default/lwc/mfeThemeTokens/mfeThemeTokens.js?shiki=js';
import dirtyStateJs from '../../../../../default/lwc/mfeDirtyState/mfeDirtyState.js?shiki=js';
-import graphQLJs from '../../../../../default/lwc/mfeGraphQL/mfeGraphQL.js?shiki=js';
// LWC host HTML sources (force-app/main/default/lwc/)
import basicEmbedHtml from '../../../../../default/lwc/mfeBasicEmbed/mfeBasicEmbed.html?shiki=html';
@@ -60,7 +58,6 @@ import sendEventHtml from '../../../../../default/lwc/mfeSendEvent/mfeSendEvent.
import autoResizeHtml from '../../../../../default/lwc/mfeAutoResize/mfeAutoResize.html?shiki=html';
import themeTokensHtml from '../../../../../default/lwc/mfeThemeTokens/mfeThemeTokens.html?shiki=html';
import dirtyStateHtml from '../../../../../default/lwc/mfeDirtyState/mfeDirtyState.html?shiki=html';
-import graphQLHtml from '../../../../../default/lwc/mfeGraphQL/mfeGraphQL.html?shiki=html';
interface FlavorSources {
mfeSource: string;
@@ -83,7 +80,7 @@ const recipes: MfeRecipe[] = [
{
name: 'Basic Embed',
description:
- 'Minimum viable lwc-shell embed. The host creates the shell, sets src and sandbox, and listens for widget-ready. The MFE uses bridge.isConnected() to detect the embedding context.',
+ 'Minimum viable embed using the standard base component. The MFE resolves the Platform SDK on startup and reads chatSDK.getHostContext() to detect the embedding context.',
flavors: [
{
hosting: 'externally-hosted',
@@ -97,7 +94,7 @@ const recipes: MfeRecipe[] = [
{
name: 'Receive Data',
description:
- "Host pushes data into the MFE via shell.updateData(). The MFE receives it with bridge.addEventListener('data', handler).",
+ 'Host re-mounts with new src carrying URL query params. The MFE reads them via URLSearchParams and viewSDK.getUiProps().',
flavors: [
{
hosting: 'externally-hosted',
@@ -111,7 +108,7 @@ const recipes: MfeRecipe[] = [
{
name: 'Send Event',
description:
- 'MFE dispatches custom events to the host via bridge.dispatchEvent(). The host catches them as DOM events on the shell element.',
+ 'MFE dispatches custom events via viewSDK.dispatchEvent(name, data). Surface-level routing of those events to LWC code is host-runtime specific.',
flavors: [
{
hosting: 'externally-hosted',
@@ -125,7 +122,7 @@ const recipes: MfeRecipe[] = [
{
name: 'Auto-Resize',
description:
- 'Iframe height follows MFE content via a ResizeObserver inside the iframe. No fixed height on the shell. Cancel the resize event to opt out.',
+ 'A ResizeObserver inside the MFE tracks body height; the guest calls viewSDK.resize() to ask the host to adjust the embedding container.',
flavors: [
{
hosting: 'externally-hosted',
@@ -139,7 +136,7 @@ const recipes: MfeRecipe[] = [
{
name: 'Theme Tokens',
description:
- 'Salesforce CSS custom properties are sent to the MFE on connect. The MFE applies them to document.documentElement. Call shell.refreshTheme() to re-sync.',
+ 'MFE reads the host theme via viewSDK.getTheme() and the broader environment via chatSDK.getHostContext() (locale, displayMode, host styles).',
flavors: [
{
hosting: 'externally-hosted',
@@ -153,7 +150,7 @@ const recipes: MfeRecipe[] = [
{
name: 'Dirty State',
description:
- 'MFE notifies the host of unsaved changes via trackdirtystate events. The host can show a warning and block navigation.',
+ 'MFE calls viewSDK.markDirtyState() / clearDirtyState() to signal unsaved changes. The host surface decides how to surface the dirty signal.',
flavors: [
{
hosting: 'externally-hosted',
@@ -164,20 +161,6 @@ const recipes: MfeRecipe[] = [
},
],
},
- {
- name: 'GraphQL Bridge',
- description:
- 'MFE executes Salesforce GraphQL via bridge.graphql(). The host proxies requests — no allow-same-origin needed. Up to 10 concurrent requests with automatic queuing.',
- flavors: [
- {
- hosting: 'externally-hosted',
- framework: 'react',
- mfeSource: graphQLMfe,
- lwcJsSource: graphQLJs,
- lwcHtmlSource: graphQLHtml,
- },
- ],
- },
];
const HOSTINGS: Hosting[] = ['externally-hosted', 'salesforce-hosted'];
@@ -241,8 +224,9 @@ export default function Mfe() {
An external framework app embedded into Salesforce via{' '}
- lwc-shell. The Platform SDK (bridge)
- is the shared contract; a Salesforce-Hosted flavor is planned.
+ <lightning-embedding>. The
+ Platform SDK is the shared contract; a Salesforce-Hosted flavor is
+ planned.
diff --git a/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipeRegistry.ts b/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipeRegistry.ts
index f5d5dcc..f3a3927 100644
--- a/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipeRegistry.ts
+++ b/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipeRegistry.ts
@@ -40,7 +40,7 @@ const CATEGORY_DEFAULTS: Record base component. The MFE detects the embedding context via chatSDK.getHostContext().',
},
{
category: 'Embedding',
- categoryRoute: '/mfe',
+ categoryRoute: '/embedding',
recipeIndex: 1,
name: 'Receive Data',
description:
- 'Pushes data from the LWC host into the MFE via shell.updateData(). The MFE receives it with bridge.addEventListener(\'data\', handler).',
+ 'Host re-mounts with new src carrying URL query params. The MFE reads them via URLSearchParams and viewSDK.getUiProps().',
},
{
category: 'Embedding',
- categoryRoute: '/mfe',
+ categoryRoute: '/embedding',
recipeIndex: 2,
name: 'Send Event',
description:
- 'The MFE dispatches custom events to the LWC host via bridge.dispatchEvent(). The host catches them on the shell element.',
+ 'The MFE dispatches custom events to the host via viewSDK.dispatchEvent(name, data). Surface-level routing is host-runtime specific.',
},
{
category: 'Embedding',
- categoryRoute: '/mfe',
+ categoryRoute: '/embedding',
recipeIndex: 3,
name: 'Auto-Resize',
description:
- 'The iframe height adjusts automatically as MFE content grows or shrinks via a ResizeObserver inside the iframe.',
+ 'A ResizeObserver inside the MFE tracks body height; the guest calls viewSDK.resize() to ask the host to adjust the embedding container.',
},
{
category: 'Embedding',
- categoryRoute: '/mfe',
+ categoryRoute: '/embedding',
recipeIndex: 4,
name: 'Theme Tokens',
description:
- 'Salesforce CSS custom properties are sent to the MFE on connect and re-synced on demand via shell.refreshTheme().',
+ 'The MFE reads the host theme via viewSDK.getTheme() and the broader environment via chatSDK.getHostContext().',
},
{
category: 'Embedding',
- categoryRoute: '/mfe',
+ categoryRoute: '/embedding',
recipeIndex: 5,
name: 'Dirty State',
description:
- 'The MFE notifies the host of unsaved changes via trackdirtystate events so the host can block navigation.',
- },
- {
- category: 'Embedding',
- categoryRoute: '/mfe',
- recipeIndex: 6,
- name: 'GraphQL Bridge',
- description:
- 'The MFE executes Salesforce GraphQL queries proxied through the host via bridge.graphql(). No allow-same-origin needed.',
+ 'The MFE calls viewSDK.markDirtyState() / clearDirtyState() to signal unsaved changes to the host surface.',
},
];
diff --git a/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipes/README.md b/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipes/README.md
index 1714a05..8b515c2 100644
--- a/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipes/README.md
+++ b/force-app/main/react-recipes/uiBundles/reactRecipes/src/recipes/README.md
@@ -2,7 +2,7 @@
Self-contained, single-file examples that teach one concept at a time. Every recipe inlines its GraphQL queries, mutations, types, and SDK calls so you can read the entire pattern without jumping between files. Open any `.tsx` file in `src/recipes/` and everything you need is right there.
-Each recipe is tagged by **hosting mode** (Salesforce-Hosted or Externally Hosted) and **framework** (React today; Vue/Angular planned). Categories 1–8 are Salesforce-Hosted React recipes. Category 9 (MFE) is Externally Hosted React — the framework app runs on its own server and embeds into Salesforce via `lwc-shell`.
+Each recipe is tagged by **hosting mode** (Salesforce-Hosted or Externally Hosted) and **framework** (React today; Vue/Angular planned). Categories 1–8 are Salesforce-Hosted React recipes. Category 9 (MFE) is Externally Hosted React — the framework app runs on its own server and embeds into Salesforce via the standard `` base component.
## Recommended Learning Path
@@ -16,7 +16,7 @@ Work through the categories in this order. Each builds on concepts from the prev
6. **Routing** -- React Router in UI Bundles: Link, NavLink, route parameters, nested routes, programmatic navigation
7. **Styling** -- CSS approaches: SLDS utility classes, shadcn/ui + Tailwind, Design System React components
8. **Integration** -- End-to-end patterns combining multiple APIs and React features
-9. **MFE (Externally Hosted)** -- Embed an external React app into Salesforce Lightning via `lwc-shell`. Covers the Platform SDK surface: connection detection, receiving host data, dispatching events, auto-resize, theme tokens, dirty state, and GraphQL proxying. Requires the `mfe-app/` dev server running at `localhost:4300` — see the repo README for setup steps.
+9. **MFE (Externally Hosted)** -- Embed an external React app into Salesforce Lightning via ``. Covers the Platform SDK surface: connection detection (`chatSDK.getHostContext()`), reading host props (`viewSDK.getUiProps()`), dispatching events (`viewSDK.dispatchEvent()`), resize (`viewSDK.resize()`), theme (`viewSDK.getTheme()`), and dirty state (`viewSDK.markDirtyState()` / `clearDirtyState()`). Requires the `mfe-app/` dev server running at `localhost:4300` — see the repo README for setup steps.
## Full Recipe Table
@@ -66,10 +66,9 @@ Work through the categories in this order. Each builds on concepts from the prev
| Styling | IconsDSR | Same icons as IconsSLDS via the Icon component from design-system-react. |
| Integration | SearchableAccountList | A controlled search input drives a GraphQL variable that filters Accounts by name with debounce. |
| Integration | DashboardAliasedQueries | Fetches Accounts, Contacts, and Opportunities in a single GraphQL request using aliases. |
-| MFE | BasicEmbed | Minimum viable lwc-shell embed. The MFE uses `bridge.isConnected()` to detect the embedding context. |
-| MFE | ReceiveData | Host pushes data into the MFE via `shell.updateData()`. MFE receives it with `bridge.addEventListener('data', handler)`. |
-| MFE | SendEvent | MFE dispatches custom events to the host via `bridge.dispatchEvent()`. Host catches them on the shell element. |
-| MFE | AutoResize | iframe height adjusts automatically as MFE content grows or shrinks via a ResizeObserver inside the iframe. |
-| MFE | ThemeTokens | Salesforce CSS custom properties sent to the MFE on connect and re-synced on demand via `shell.refreshTheme()`. |
-| MFE | DirtyState | MFE notifies the host of unsaved changes via `trackdirtystate` events so the host can block navigation. |
-| MFE | GraphQLBridge | MFE executes Salesforce GraphQL queries proxied through the host via `bridge.graphql()`. No `allow-same-origin` needed. |
+| MFE | BasicEmbed | Minimum viable embed using the standard `` base component. MFE uses `chatSDK.getHostContext()` to detect the embedding context. |
+| MFE | ReceiveData | Host re-mounts `` with new src carrying URL query params. MFE reads them via `URLSearchParams` and `viewSDK.getUiProps()`. |
+| MFE | SendEvent | MFE dispatches custom events via `viewSDK.dispatchEvent(name, data)`. Surface-level routing is host-runtime specific. |
+| MFE | AutoResize | A ResizeObserver inside the MFE tracks body height; the guest calls `viewSDK.resize()` to ask the host to adjust the embedding container. |
+| MFE | ThemeTokens | MFE reads the host theme via `viewSDK.getTheme()` and the broader environment via `chatSDK.getHostContext()`. |
+| MFE | DirtyState | MFE calls `viewSDK.markDirtyState()` / `clearDirtyState()` to signal unsaved changes to the host surface. |
diff --git a/force-app/main/react-recipes/uiBundles/reactRecipes/src/routes.tsx b/force-app/main/react-recipes/uiBundles/reactRecipes/src/routes.tsx
index 24b17f0..fb9f36c 100644
--- a/force-app/main/react-recipes/uiBundles/reactRecipes/src/routes.tsx
+++ b/force-app/main/react-recipes/uiBundles/reactRecipes/src/routes.tsx
@@ -93,9 +93,9 @@ export const routes: RouteObject[] = [
handle: { showInNavigation: true, label: 'Integration' },
},
{
- path: 'mfe',
+ path: 'embedding',
element: /auto-resize
/theme-tokens
/dirty-state
- /graphql-bridge