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.

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

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.

lightning-out-application requires two attributes.

  • frontdoor-url: The frontdoor URL used to establish the Salesforce session. This attribute is set dynamically at run time. See Set Up Authentication for Lightning Out 2.0 in Salesforce Help.
  • components: A common-separated list of Lightning web components that are embedded in the external page. These components must be added 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 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.

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.

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.

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.

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

  1. An end user opens the host page.
  2. 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.
  3. After receiving the frontdoor URL, the host page sets the frontdoor-url attribute on lightning-out-application.
  4. 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.
  5. If the session is established successfully, the Lightning Out 2.0 app fires the lo.application.ready custom event.
  6. The other Lightning Out 2.0 web components are initialized. Each component contains an iframe that becomes the root element of a shadow DOM.
  7. Inside the iframes, the corresponding custom LWC components are initialized. The LWC components run in the Salesforce context.
  8. 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.
  9. If the components render successfully, the Lightning Out 2.0 app fires the lo.component.ready custom event.

See Also