--- schema_version: "1" id: 5be695f568ce50b4fafdc6289ce1362b3c4c0f29efadf5e09b96ef1acf13dc2a title: Set Up Hybrid Storefront with On-Demand Sandbox (ODS) Instances Using eCDN collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-hybrid-ods.md canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-ods.html source_site: developer.salesforce.com content_type: documentation content_hash: f86dedbe01724c988751db1c1427fafec04e5603fe184700441336cf56963dc4 products: - Composable Storefront - Salesforce APIs --- # Set Up Hybrid Storefront with On-Demand Sandbox (ODS) Instances Using eCDN **Applies to: Storefront Next** Use Cloudflare eCDN origin routing on ODS instances to run Storefront Next and SFRA/SiteGenesis side by side at one origin. This setup is for deployed ODS environments and uses eCDN origin routing instead of the local hybrid proxy. At the end of this setup, navigate between Storefront Next and SFRA/SiteGenesis pages in ODS with no visible redirects, using routing behavior that mirrors production. **warning:** ODS deployments use eCDN origin routing instead of the hybrid proxy plugin. Hybrid proxy is local-development only and runs only with `pnpm dev`. For ODS, Managed Runtime (MRT), and production-style testing, route traffic with Cloudflare eCDN origin rules between Storefront Next and SFRA/SiteGenesis. ## Hybrid ODS Features ### Production-Like Hybrid Routing on ODS Run Storefront Next and SFRA/SiteGenesis together on deployed ODS instances under one origin, with no visible redirects or session loss. Teams can validate hybrid behavior in an environment that is much closer to production than localhost. ### Parity with Production eCDN Rules Routing decisions on ODS use the same Cloudflare eCDN expression format (`http.request.uri.path matches`) used in production. Reuse your production routing patterns so ODS testing reflects real deployment behavior. ### Scalable Development Environment Strategy ODS lets customers spin up multiple development instances in parallel and test different migration or routing configurations safely. This strategy complements local hybrid proxy workflows on `localhost`, giving teams both fast local iteration and production-like validation on ODS. ### Configuration Flexibility No assumptions are made about which pages live on Storefront Next versus SFRA/SiteGenesis. You define the split entirely through your eCDN origin rules, so any mix of migrated and legacy routes is supported. ## Before You Begin Make sure that: - You have an active ODS instance with SFRA/SiteGenesis deployed. - You have Managed Runtime Admin console access for the target environment. - You complete storefront setup in Business Manager as described in [Choose Your Storefront Next Quick Start Path](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-choice.md). ## Configure Hybrid Storefront Settings ### Step 1: Enable Hybrid Auth in Business Manager Complete the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md) for the site on your ODS instance. The shared steps are the same across all environments: 1. Create or confirm a SLAS client that includes the `sfcc.session_bridge` scope. For an ODS instance, you can find your SLAS Client ID and Client Secret in SLAS Admin or in your `.env.default` file. See [Shared Hybrid Auth Setup, Steps 1–2](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-1-set-up-a-slas-client). 2. In **Merchant Tools > Select Site > Site Preferences > Hybrid Auth Settings**, enable the **Hybrid Auth** toggle, enter your SLAS Client ID (and secret, or select **Is Public Client** for a public client), optionally enable **Shopper Context** and **Do-Not-Track Synchronization**, and click **Apply**. See [Shared Hybrid Auth Setup, Step 4](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-4-configure-business-manager). **note:** The **HttpOnly True** toggle doesn't affect Storefront Next. Storefront Next always sets cookies with `HttpOnly=true`, regardless of this setting. ### Step 2: Configure the Application (MRT Environments) In the Managed Runtime Admin console, open your project, select the target environment, and go to the **Environment Variables** section. Set the following values for each deployed environment where you use hybrid routing. 1. Enable hybrid mode. ```bash PUBLIC__app__hybrid__enabled=true ``` 2. Set `PUBLIC__app__hybrid__legacyRoutes` to a JSON array of routes that belong to SFRA/SiteGenesis. When a user clicks a `` to one of these paths, the client-side navigation middleware forces a full-page load so eCDN routes the request to SFRA/SiteGenesis. ```bash PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout"]' ``` Or use exact paths and React Router-style parameterized patterns: ```bash PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout", "/product/:id"]' ``` **note:** This list is the inverse of your eCDN origin routing rules. If a route isn't in your routing rules (SFRA/SiteGenesis owns it) and a Storefront Next page links to it, add it here. If it's missing, React Router tries to render the route client-side and shows a 404. For example, if your eCDN rule routes `/product/*` to Storefront Next, do not include `/product/*` in `legacyRoutes`. If `/cart` and `/checkout` aren't in your eCDN rule, include them in `legacyRoutes` so Storefront Next forces a full-page navigation to SFRA/SiteGenesis. ### Step 3: Configure eCDN Routing Rules Use the hosted zone created during setup to configure eCDN origin routing rules. To compare route split patterns, see [Choose a Hybrid Routing Matrix](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-routing-matrix.md). #### Locate the eCDN Zone Hostname 1. In Business Manager, navigate to **Administration > Sites > Storefronts**. 2. Select the storefront that you just created. 3. Under **Environments**, select the environment that you are setting up. 4. In the **eCDN** section, find the default routing rule. 5. Expand that routing rule to locate your eCDN zone hostname. ![Default eCDN routing rule showing the hosted zone hostname](https://developer.salesforce.com/docs/media/sfnext/sfnext-hybrid-ods-ecdn-1.png '{"class": "image-xl"}') #### Update Aliases with the eCDN Hostname 1. In Business Manager, navigate to **Merchant Tools > Select Site > SEO & Discoverability > Aliases**. 2. Update `http-host` and `https-host` with the eCDN hostname that you noted in the previous section. ```json { "__version": "1", "settings": { "http-host": "your-demo-hostname.zzrf-000.my.commercecloud.salesforce.com", "https-host": "your-demo-hostname.zzrf-000.my.commercecloud.salesforce.com" } } ``` 3. Click **Save**. **note:** ODS hybrid storefronts use the Salesforce-provided eCDN default domain. Custom or vanity domains aren't supported for ODS setups. Updating site URL aliases doesn't create a custom hostname—it only makes generated storefront URLs use the ODS default domain. #### Update eCDN Routing Rules for Your Demo Site Configure the eCDN routing rule for your hostname in the Business Manager eCDN UI, then set the Storefront Next rule expression. For the full UI walkthrough and screenshots, see [Configure Routing Rules in the Business Manager UI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/ecdn-rules-for-phased-headless-rollout.html#configure-routing-rules-in-the-business-manager-ui). 1. Go to **Administration > Sites > Embedded CDN Settings**, open **Configure Routing Rules** for the zone that contains your hostname, and click **Edit** on the routing rule for your hostname. 2. Confirm that the **Hostnames** and **MRT Origin** fields are prefilled and match your setup. 3. In **Rule expression**, paste the following rule. This expression matches Storefront Next routes (home, category, product, search, and account flows), plus resource routes, action endpoints, React Router data prefetch requests, and static assets. ```text (http.request.uri.path matches "^(/[^/]+/[^/]+)?/(|home|category|product|search|account|login|signup|logout|reset-password|social-callback)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$") ``` ![Rule expression configured for hybrid routing](https://developer.salesforce.com/docs/media/sfnext/sfnext-hybrid-ods-ecdn-3.png '{"class": "image-xl"}') **note:** This guide uses a default hybrid split: top-of-funnel pages (home, category, product, search, and authentication flows) on Storefront Next, with cart and checkout on SFRA. Modify both eCDN origin rules and `PUBLIC__app__hybrid__legacyRoutes` to support any hybrid storefront combination. Make sure the two route definitions are complementary. 4. Click **Save**. ### Step 4 (Optional): Configure Locale Rules Storefront Next enables storefront context and automatically adds site ID and locale prefixes to routes. To correctly route between pages that include locale prefixes, configure URL rules in Business Manager so that SFRA/SiteGenesis URLs use matching prefixes. 1. In Business Manager, navigate to **Merchant Tools > Select Site > SEO & Discoverability > URL Rules**. 2. Select the **Settings** tab. 3. In the **Locale Mapping** section, set **Locale Mapping** to **Path**. 4. Add your Storefront Next prefixes for each supported locale. ![Locale mapping configuration for hybrid routing](https://developer.salesforce.com/docs/media/sfnext/sfnext-hybrid-ods-locale-1.png '{"class": "image-xl"}') 5. Click **Apply**. ### Step 5: Verify Your Setup Your setup is working when navigation between Storefront Next and SFRA/SiteGenesis occurs without visible redirects, all required cookies persist across transitions, and the `sfdc_dwsid` request header matches the `dwsid` cookie value. 1. Visit your eCDN hostname. 2. Confirm the home page loads on Storefront Next. 3. Navigate to a page served by SFRA/SiteGenesis. 4. Open browser Developer Tools and inspect cookies. Confirm that the following cookies are set: - `cc-nx-g_{Site_ID}`: Guest refresh token - `dwsid`: B2C Commerce session ID - `usid`: SLAS customer ID - `cc-at_{Site_ID}`: SLAS access token (this cookie appears when the user lands on an SFRA/SiteGenesis page; after handoff to Storefront Next, it is consumed) 5. Navigate to any Storefront Next page and verify: - `cc-nx-g_{SiteID}` remains the same. - `dwsid` remains the same. - `usid_{SiteID}` remains the same. - `cc-at_{SiteID}` is no longer present because Storefront Next consumes it and stores the access token in `localStorage` as `accesstoken{SiteID}`. 6. In Developer Tools, switch to the **Network** tab. 7. Add an item to cart on Storefront Next. 8. Inspect the SCAPI Add to Cart request. In **Request Headers**, confirm `sfdc_dwsid` matches the `dwsid` cookie value. **note:** The `sfdc_dwsid` request header is required to keep hybrid storefront behavior stable at production scale when traffic can be distributed across multiple app servers. If you are not using Storefront Next, set this header in your headless application whenever the `dwsid` cookie is available. ## Troubleshooting | Symptom | Likely cause | Resolution | | ----------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Routing sends users to the wrong storefront. | eCDN rule and `PUBLIC__app__hybrid__legacyRoutes` are out of sync. | Confirm that routes matched by the eCDN expression are not listed in `legacyRoutes`, and that any route owned by SFRA/SiteGenesis is included in `legacyRoutes`. | | Cookies don't persist across navigation. | Hybrid Auth is disabled or SLAS is missing the `sfcc.session_bridge` scope. | Re-enable **Hybrid Auth** in Business Manager and confirm the SLAS client has `sfcc.session_bridge`. | | 404 errors on Storefront Next pages. | MRT environment variables aren't set or weren't applied to the active environment. | In the MRT Admin console, verify `PUBLIC__app__hybrid__enabled` and `PUBLIC__app__hybrid__legacyRoutes` for the active environment, then redeploy if needed. | | `sfdc_dwsid` header doesn't match the `dwsid` cookie. | The header isn't being sent with SCAPI requests. | Confirm that you're on Storefront Next, or that your headless app sets `sfdc_dwsid` from the `dwsid` cookie before each SCAPI request. | ## Next Steps - Compare alternate route splits in [Hybrid Storefront Routing Matrix](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-routing-matrix.md). - Iterate on routing locally before redeploying to ODS by following [Set Up Hybrid Proxy for Local Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-proxy-local-dev.md).