Luma Bridge

This section provides guidance on how to implement the Luma Bridge for your Adobe Commerce on Edge Delivery Services project.

PaaS

Supported Configuration

Luma Bridge is intended for Adobe Commerce Platform as a Service (PaaS) instances with complex cart, checkout, and account page implementations that need to be migrated progressively to Edge Delivery Services. It is only supported for the following configuration: Edge Delivery Services (EDS) + Adobe Commerce Optimizer (ACO) + PaaS.

If you need access to the Luma Bridge package, please reach out to us at commerce-storefront-luma-bridge@adobe.com.

What is Luma Bridge?

Luma Bridge is a session management mechanism between two storefronts:

• The main storefront (headless storefront) that is built using the Commerce boilerplate template on Edge Delivery Services
• The default, theme-based PHP storefront that is built using Adobe Commerce (Luma theme or another base theme)

It allows you to reuse complex parts of your storefront (for example, cart, checkout, and account pages). This approach provides a path for Adobe customers currently using default, theme-based storefronts to migrate to a highly performant shopping experience in a phased manner. Using Luma Bridge, you can progressively migrate your theme-based storefront to Edge Delivery Services.

Note

If you already have a headless storefront implementation (for example, PWA Studio or Vue Storefront), Luma Bridge is not a suitable solution to share session and other context between Edge Delivery Services and your storefront.

Demo site

The following demo site was built with Luma Bridge. You can access the full demo site at https://mcprod.eds.ecg.magento.com/.

Requirements for implementation

You must meet the following requirements to implement Luma Bridge:

• Both the Edge Delivery Services storefront and the theme-based Adobe Commerce storefront must operate on the same top-level domain.
• You must use the user authentication and cart drop-in components to manage your storefront authentication and cart context. This ensures that Luma Bridge works with the correct set of cookies.

How does session management work?

Luma Bridge relies on cookies generated by the user authentication and cart drop-in components. These components are part of your Commerce boilerplate template-based storefront on Edge Delivery Services.

Luma Bridge is a PHP module installed in Adobe Commerce, as noted above. When you enable the Luma Bridge module, Adobe Commerce can recognize and create the same cookies that your storefront drop-in components generate. This enables both applications to share the same session cookies, whether the user has a guest session or a logged-in session.

The cookies include:

• A JWT token that represents the customer session when the user is logged in, generated as a response to the generateCustomerToken GraphQL mutation.
• A cart ID that represents a masked quote ID, generated as a response to the createGuestCart GraphQL mutation.

No changes are required on your Edge Delivery Services storefront when you use the user authentication and cart drop-in components.

Implementation considerations

Before starting an implementation, clarify the following information:

• Architecture of cart, checkout, and account pages
• Complexity of implementation
• Customization requirements

This information will help you decide whether to use Luma Bridge or a headless implementation for the cart, checkout, and account pages.

Tip

When implementing Luma Bridge, ensure that you have engineers on the project with backend PHP knowledge on Adobe Commerce.

Installation

To install the Luma Bridge, use the following steps:

1. Fetch the package via Composer:

   composer require adobe-commerce/luma-bridge

2. Enable the module and complete the standard CLI procedure:

   bin/magento module:enable Magento_LumaBridge
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush

After completing the installation, Luma Bridge will automatically recognize and share session cookies between your Edge Delivery Services storefront and Adobe Commerce. Test that user authentication and cart state persist correctly as customers navigate between both storefronts.