---
schema_version: "1"
id: 5b0a2c0c6339f688ce8b1a2372bf7ea11c4c0ad49ab98e1fede2250ff49554f0
title: Hybrid Storefront Routing Matrix (PWA Kit)
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/hybrid-routing-matrix.md
canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-routing-matrix.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 06766f9d81b27282c2d5ffbdc004c7a66da408bdf94cf016d47afc79da4f80a4
products:
  - Composable Storefront
  - Salesforce APIs
---
# Hybrid Storefront Routing Matrix (PWA Kit)

Use this routing matrix to choose a hybrid storefront split between PWA Kit (Composable Storefront) and SFRA/SiteGenesis.

PWA Kit hybrid routing has two complementary parts:

1. **eCDN routing rules** — a Cloudflare rule expression that routes matching paths to your Managed Runtime (MRT) environment. Everything else stays on SFRA/SiteGenesis.
2. **`app/routes.jsx` filtering** — remove the SFRA/SiteGenesis-owned routes from your PWA Kit route table so that React Router forces a full-page navigation (instead of a soft, client-side navigation) to those paths.

Keep the two definitions complementary: any path routed to MRT by eCDN should remain in `app/routes.jsx`, and any path owned by SFRA/SiteGenesis should be removed from `app/routes.jsx`.

**note:** This matrix is for PWA Kit. For Storefront Next, see [Hybrid Storefront Routing Matrix](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-routing-matrix.md).

## Use the Right Rule Syntax by Setup Type

Use the same Cloudflare expression pattern in every environment, but apply it differently:

- **PIG and ODS (eCDN)**: Paste the rule expression into **Rule expression** in the Business Manager eCDN UI, or pass it to the [`createMrtRules`](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createMrtRules) API. When you use the API, also scope the expression to your hostname with `http.host`. For the setup steps, see [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md).
- **Local development (hybrid proxy)**: eCDN isn't available on `localhost`. Use the PWA Kit hybrid proxy instead. See [Set Up Hybrid Locally for Local Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md#set-up-hybrid-locally-for-local-development).

## Architectural Foundations

- **eCDN MRT rule expression**: A single Cloudflare expression evaluated at the edge. Requests whose path matches the expression are routed to Managed Runtime (PWA Kit); all other requests go to SFRA/SiteGenesis. The matrix expressions support paths without a prefix and paths with a two-segment `/:site/:locale` prefix, such as `/category/mens` and `/us/en-US/category/mens`.
- **`app/routes.jsx`**: The PWA Kit client-side route table. Remove SFRA/SiteGenesis-owned routes so PWA Kit hard-navigates to them. For projects that use template extensibility, override `overrides/app/routes.jsx`.

The route patterns below use the default Retail React App routes (`/`, `/category/:categoryId`, `/product/:productId`, `/search`, `/account`, `/login`, `/registration`, `/reset-password`, `/cart`, `/checkout`). Adjust them to match your project's routes.

The examples use the optional prefix pattern `^(/[^/]+/[^/]+)?`. The first segment matches any site value, and the second segment matches any locale value. Each value can be an alias or a raw ID, so the eCDN rule doesn't need an allowlist of every site-locale combination. If your application uses a different prefix shape, replace the entire sample prefix with a pattern for that shape.

For configurations where PWA Kit handles the Home route, the dedicated Home expression `^(/|/[^/]+/[^/]+/)$` matches `/` and a prefixed Home path such as `/us/en-US/`. When an exactly two-segment path represents prefixed Home, end it with a trailing slash; an unprefixed two-segment route must use its canonical form without a trailing slash, such as `/product/123`. This convention lets eCDN distinguish the two shapes without maintaining site and locale allowlists. The expression intentionally doesn't match `/us/en-US` or `/us/en-US/home`. Configure generated Home links and SFRA/SiteGenesis redirects to use the canonical trailing-slash PWA Kit root.

**important:** A prefixed Home URL must end with a trailing slash, for example, `/us/en-US/`. Reserve the exactly-two-segment trailing-slash shape for prefixed Home; don't use that shape for an unprefixed two-segment route such as `/product/123`.

## Matrix Configurations

Each configuration lists the eCDN rule expression (paths routed to PWA Kit on MRT) and the routes to remove from `app/routes.jsx` (paths owned by SFRA/SiteGenesis).

### Matrix-01: Modern Core (Home, PDP, PLP on PWA Kit)

- **Strategy:** The discovery funnel, search, account, and authentication routes run on PWA Kit. Only checkout (`/cart` and `/checkout`) stays on SFRA/SiteGenesis.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/|/[^/]+/[^/]+/)$" or http.request.uri.path matches "^(/[^/]+/[^/]+)?/(category|product|search|account|login|registration|reset-password)(/.*)?$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/cart`, `/checkout`

### Matrix-02: Modern Checkout (Cart and Checkout on PWA Kit)

- **Strategy:** Test or roll out a PWA Kit checkout while keeping browse and discovery routes on SFRA/SiteGenesis.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(cart|checkout)(/.*)?$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/`, `/category/:categoryId`, `/product/:productId`, `/search`, `/account`, `/login`, `/registration`, `/reset-password`

### Matrix-03: Modern Entry Only (Home on PWA Kit)

- **Strategy:** An early pilot where only the home page is modernized and deeper flows remain on SFRA/SiteGenesis.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/|/[^/]+/[^/]+/)$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/category/:categoryId`, `/product/:productId`, `/search`, `/account`, `/login`, `/registration`, `/reset-password`, `/cart`, `/checkout`

### Matrix-04: Legacy Entry Only (Home on SFRA)

- **Strategy:** The home page stays on SFRA/SiteGenesis, while deeper browse and transactional routes move to PWA Kit.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(category|product|search|account|login|registration|reset-password|cart|checkout)(/.*)?$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/`

### Matrix-05: Catalog-Only Migration (PLP/PDP on PWA Kit)

- **Strategy:** Move high-volume catalog routes (category, product, search) to PWA Kit while preserving legacy account and checkout routes.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(category|product|search)(/.*)?$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/`, `/account`, `/login`, `/registration`, `/reset-password`, `/cart`, `/checkout`

### Matrix-06: Account and Auth Only (Identity Flows on PWA Kit)

- **Strategy:** Move account and authentication experiences to PWA Kit while leaving catalog and checkout on SFRA/SiteGenesis.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(account|login|registration|reset-password)(/.*)?$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/`, `/category/:categoryId`, `/product/:productId`, `/search`, `/cart`, `/checkout`

## Global Framework Requirements

Keep these route clauses routed to Managed Runtime in every matrix configuration. PWA Kit's server-side rendering system relies on them:

- `^/mobify.*` for PWA Kit internal proxies and static assets.
- `^/callback.*` for the SLAS authentication callback.
- `^/worker\.js.*` for the PWA Kit service worker.

For the catch-all route, update the PWA `/*` route in `app/routes.jsx` to redirect to the default origin instead of rendering `<PageNotFound />`. For the full procedure, see [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md#step-3-update-pwa-kit-routes).