Embed an External Web App (Developer Preview)

Embed an externally hosted web app inside a Salesforce page with the <lwc-shell> host component. Salesforce loads your app in a sandboxed iframe and manages the connection between the page and your app.

This topic describes the Developer Preview API (<lwc-shell>, package @salesforce/experimental-mfe-lwc-shell). The generally available release replaces this with the <lightning-ui-embedding> component and a different SDK. Treat every API name in this topic as Developer Preview only. To move an app to the generally available version, see Migrate from the Developer Preview API.

Note

How It Works

Salesforce embeds your externally hosted app in an iframe managed by the <lwc-shell> custom element. You generate a deployable Lightning web component from the shell package, wrap it in your own component, point it at your app’s URL, and add it to the page. The shell applies a sandbox policy to the iframe and opens a message channel to your app.

Prerequisites

An externally hosted web app served over HTTPS.
The @salesforce/experimental-mfe-lwc-shell package (Developer Preview).
Permission to create Lightning web components and edit Lightning pages in your org.

Generate the Deployable Component

Run the vendor build to generate a deployable Lightning web component from the shell package.

1npx lwc-shell-vendor-build

This creates a component at force-app/main/default/lwc/vendorLwcShell/ that you can deploy and reference from your wrapper component.

Create the Shell in a Wrapper Component

Create the shell imperatively, and set its attributes before you add it to the DOM.

1const shell = document.createElement("lwc-shell");
2shell.title = "Loan application";
3shell.src = appUrl;
4shell.sandbox = "allow-forms allow-modals";
5container.appendChild(shell);

Create the shell with document.createElement('lwc-shell') and set src, title, and any sandbox tokens before you call appendChild. A declarative <lwc-shell> tag placed directly in an LWC template doesn’t upgrade to the custom element, so the imperative pattern is required.

Important

Sandbox Policy

The shell applies a tiered iframe sandbox policy:

Base tokens, always applied: allow-scripts, allow-pointer-lock, allow-same-origin.
Optional tokens, which you opt into through the sandbox attribute: allow-forms, allow-modals, allow-downloads.
Blocked tokens, which the host removes even if you request them: allow-top-navigation, allow-popups.

The host blocks allow-top-navigation and allow-popups so an embedded app can’t navigate the top-level window or escape the sandbox through a popup.

allow-same-origin for a third-party embedded app works only on Experience Cloud sites that have Locker or Lightning Web Security disabled. It doesn’t work on Lightning Experience pages in Developer Preview. Cookies and localStorage in the embedded app depend on allow-same-origin, so they’re subject to the same limitation. This limitation is resolved in the generally available release, where the shell becomes a first-party component.

Warning

Allowlist Your App's Domain

Before Salesforce can load your app, add your app’s domain to the org’s allowlist in Setup.