Understand Lightning Out 2.0 Architecture

Learn how Lightning Out 2.0 provides ‌access to Salesforce on external host pages while securely encapsulating embedded Lightning web components (LWCs). Examine the Lightning Out 2.0 app code and understand how the elements interact with each other and the host page.

Lightning Out 2.0 JavaScript Library

Include the Lightning Out 2.0 JavaScript library as a script on the external host page.

1<script
2  type="text/javascript"
3  async=""
4  src="https://MY_DOMAIN_NAME.my.salesforce.com/lightning/lightning.out.latest/index.iife.prod.js"
5></script>

The Lightning Out 2.0 code block that the Lightning Out 2.0 App Manager provides includes the script element and its attributes. See Build a Lightning Out 2.0 App in Salesforce Help.

Lightning Out 2.0 App Component

When a host page initializes the Lightning Out 2.0 script, custom web components are created in the context of the external host page. One of these components is lightning-out-application, which contains the base configuration for the Lightning Out 2.0 app. It doesn’t have a UI element.

1<lightning-out-application
2  frontdoor-url="https://MY_DOMAIN_NAME.salesforce.com/secur/frontdoor.jsp?..."
3  app-id="18_DIGIT_SALESFORCE_ID"
4  components="c-my-lwc,complex_ns-lwc-component"
5>
6</lightning-out-application>

lightning-out-application requires three attributes.

frontdoor-url: The frontdoor URL used to establish the Salesforce session. You must set this attribute dynamically at run time. See Set Up Authentication for Lightning Out 2.0 in Salesforce Help.
app-id: The 18-digit Lightning Out 2.0 app ID, for example 1Usfi200000006TCAQ. You can find this value in the Lightning Out 2.0 App Manager in Setup. If you created a Lightning Out 2.0 app before Spring ’26, this attribute isn’t required.
components: A comma-separated list of LWC components to embed in the external page. Use the format c-my-component, where hyphens (-) separate the namespace and the parts of the component name. If the namespace is mixed cased, separate the parts of the namespace with an underscore (_). For example, enter complex_ns-lwc-component for complexNs/lwcComponent. You must also add the components to the Lightning Out 2.0 app in the Lightning Out 2.0 App Manager. See Build a Lightning Out 2.0 App in Salesforce Help.

The Lightning Out 2.0 code block that the Lightning Out 2.0 App Manager provides includes lightning-out-application, as well as the app-id and components attributes.

Lightning Out 2.0 Web Components

The other Lightning Out 2.0 web components mirror the LWC components added to the Lightning Out 2.0 app. The names of these components are defined in the components attribute of lightning-out-application.

1<c-my-lwc style="--custom-color: brown;"></c-my-lwc>
2<complex_ns-lwc-component
3  ex-attr="ex-value"
4  other-ex-attr="other-ex-value"
5></complex_ns-lwc-component>

Each Lightning Out 2.0 web component contains an iframe that becomes the root of a closed shadow DOM. Because the iframe is in the shadow DOM, JavaScript on the host page can’t directly see or manipulate content inside the iframe. Inside the iframe, the actual LWC component runs in the Salesforce context instead of the context of the host page.

On each Lightning Out 2.0 web component, you can set values for any attribute that the corresponding LWC component supports. Passing an unsupported attribute doesn’t trigger compilation or run-time errors, but that attribute’s value isn’t set on the LWC component. You can set supported attributes declaratively with HTML, programmatically with JavaScript, or as JSON properties in the Lightning Out 2.0 App Manager.

For example, the Lightning Out 2.0 component c-my-lwc has a style attribute set to "--custom-color: brown;". style is a global attribute, and the LWC component c-my-lwc has the CSS custom property --custom-color defined in its stylesheet. Therefore, the Lightning Out 2.0 component c-my-lwc can pass this attribute to the LWC component c-my-lwc in the iframe and override its styling. To learn more about passing attributes, see Set Component Styles and Properties in a Lightning Out 2.0 App.

Lightning Out 2.0 Markup

To show how the elements of a Lightning Out 2.0 app work together, here’s the expanded markup for a Lightning Out 2.0 app as it’s embedded in a host page.

1<!-- Host page context-->
2<body>
3  <!--Lightning Out 2.0 JS library -->
4  <script
5    type="text/javascript"
6    async=""
7    src="https://MY_DOMAIN_NAME.my.salesforce.com/lightning/lightning.out.latest/index.iife.prod.js"
8  ></script>
9  <!-- Lightning Out 2.0 web component: base configuration -->
10  <lightning-out-application
11    app-id="18_DIGIT_SALESFORCE_ID"
12    frontdoor-url="https://MY_DOMAIN_NAME.salesforce.com/secur/frontdoor.jsp?..."
13    components="c-my-lwc"
14  >
15  </lightning-out-application>
16  <!-- Lightning Out 2.0 web component -->
17  <c-my-lwc style="--custom-color: brown;">
18    <!-- shadow DOM open -->
19    <iframe>
20      <html>
21        <!-- Salesforce context -->
22        <body>
23          <!-- Lightning web component -->
24          <c-my-lwc style="--custom-color: brown;"></c-my-lwc>
25        </body>
26      </html>
27    </iframe>
28    <!-- shadow DOM close -->
29  </c-my-lwc>
30</body>

Lightning Out 2.0 Lifecycle Events

To track the lifecycle of a Lightning Out 2.0 app, Lightning Out 2.0 fires these custom events.

lo.application.ready: Fires if a Salesforce session is successfully established.
lo.application.error: Fires if a Salesforce session can’t be established. The detail property of the event has two properties.
- message: The error message.
- originalError: The original error generated inside the Salesforce context.
lo.component.ready: Fires if a Lightning Out 2.0 component successfully renders with the embedded LWC component.
lo.component.error: Fires if a Lightning Out 2.0 component either fails to render or encounters an error from the embedded LWC component during run time. The detail property of this event has two properties.
- message: The error message.
- originalError: The original error generated inside the Salesforce context.

Lightning Out 2.0 Initialization Flow

With these events in mind, let’s summarize the Lightning Out 2.0 app initialization flow.

An end user opens the host page.
The host page uses the UI Bridge API to exchange a valid Salesforce access token or Session ID for a frontdoor url. If the end user isn’t already logged into Salesforce, the OAuth authorization flow is initiated.
After receiving the frontdoor URL, the host page sets the frontdoor-url attribute on lightning-out-application.
The Lightning Out 2.0 script uses the frontdoor URL to initialize the lightning-out-application app and establish a Lightning Out 2.0 session.
If the session is established successfully, the Lightning Out 2.0 app fires the lo.application.ready custom event.
The other Lightning Out 2.0 web components are initialized. Each component contains an iframe that becomes the root element of a shadow DOM.
Inside the iframes, the corresponding custom LWC components are initialized. The LWC components run in the Salesforce context.
The Lightning Out 2.0 web components, still running in the context of the host page, render the iframes that contain the embedded LWC components.
If the components render successfully, the Lightning Out 2.0 app fires the lo.component.ready custom event.

See Also