@W-19869537 Added Hybrid Proxy support for local and ODS hybrid development when no eCDN available #3409

yhsieh1 · 2025-10-20T14:11:21Z

Description

Overview
This PR introduces Hybrid Proxy support for PWA Kit, enabling seamless integration between PWA Kit applications and Salesforce Commerce Cloud (SFCC) instances during local development and ODS hybrid scenarios when no eCDN is available.

🎯 Key Changes

Added Hybrid Proxy in pwa-kit-runtime
Added Hybrid Proxy Configuration in template-retail-react-app app/ssr.js
Extra unit test is added to improve and pass test coverage requirement

A pwa-kit storefront with hybrid proxy enabled is deployed on MRT and connected to ODS for testing.

https://scaffold-pwa-yhsieh-dev.mobify-storefront.com/
cart and checkout page will be proxied to SFRA https://zzrf-039.dx.commercecloud.salesforce.com/s/RefArchGlobal/en-GB/home store cart/checkout page
plugin_redirect is not configured in SFRA store

Types of Changes

Bug fix (non-breaking change that fixes an issue)
New feature (non-breaking change that adds functionality)
Documentation update
Breaking change (could cause existing functionality to not work as expected)
Other changes (non-breaking changes that does not fit any of the above)

Breaking changes include:

Removing a public function or component or prop

Adding a required argument to a function

Changing the data type of a function parameter or return value

Adding a new peer dependency to package.json

Changes

Added Hybrid Proxy support for local and ODS hybrid development when no eCDN available

How to Test-Drive This PR

Steps to test:

Update ssr.js to enable Hybrid Proxy

localAllowCookies: true
hybridProxy.enabled: true
hybridProxy.sfccOrigin: [your SFCC store]

Uncomment hybridAuthEnabled in _app-config.js
Update routes.jsx to exclude routes on the PWA-Kit. Reference this code
Update default.js

app.commerceAPI.parameters
app.enableHybrid: true to toggle routes exclusion on routes.jsx
ssrParameters.proxyConfigs: add
{
host: [your SFCC store],
path: 'dwrestatic'
}

Start up app

Add item to cart
Go to cart
It should show SFCC store cart page

Checklists

General

Changes are covered by test cases
CHANGELOG.md updated with a short description of changes (not required for documentation updates)

Accessibility Compliance

You must check off all items in one of the follow two lists:

There are no changes to UI

or...

Changes were tested with a Screen Reader (iOS VoiceOver or Android Talkback) and had no issues
Changes comply with WCAG 2.0 guidelines levels A and AA
Changes to common UI patterns and interactions comply with WAI-ARIA best practices

Localization

Changes include a UI text update in the Retail React App (which requires translation)

- Resolved merge conflicts in pwa-kit-mcp package - Added new tools: hooks-recommendation and explore-scapi-shop-api - Updated CHANGELOG.md and README.md with new features - Merged changes from develop branch including new MCP tools and utilities

* Hybrid CDN 1st pass --------- Signed-off-by: Aditya Tekur <[email protected]>

cc-prodsec · 2025-10-20T14:11:33Z

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Licenses	0	0	0	0	0 issues
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

shethj · 2025-10-21T04:16:20Z

packages/pwa-kit-runtime/src/utils/ssr-server/hybridProxy.js

+const isString = (element) => typeof element === 'string'
+const isArray = (element) => Array.isArray(element)
+const isObject = (element) => element && typeof element === 'object'
+const isIterable = (element) => isArray(element) || isObject(element)
+
+const forEachIn = (iterable, functionRef) => {
+    Object.keys(iterable).forEach((key) => {
+        functionRef(key, iterable[key])
+    })
+}


These appear to be generic util functions. Do they need to be a part of hybridProxy.js ?

shethj · 2025-10-21T04:21:52Z

packages/template-retail-react-app/app/ssr.js

+        enabled: false,
+
+        // The origin of the SFCC instance (i.e. the instance that is being proxied to which hosts the storefront).
+        sfccOrigin: 'https://zzrf-001.dx.commercecloud.salesforce.com',


Did we consider reading this from config/env instead of hard-coding the hostname ?

shethj · 2025-10-21T04:22:36Z

packages/template-retail-react-app/app/ssr.js

+        // * https://developer.salesforce.com/docs/commerce/commerce-api/references/cdn-api-process-apis?meta=MrtRules
+        // * https://developer.salesforce.com/docs/commerce/commerce-api/guide/ecdn-rules-for-phased-headless-rollout.html
+        routingRules: [
+            'http.request.uri.path eq "/" or http.request.uri.path matches "^/callback" or http.request.uri.path matches "^/mobify" or http.request.uri.path matches "^/worker.js" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/$" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/login" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/reset-password" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/registration" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/account" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/account/orders" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/account/orders/(\\\\w+)" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/account/wishlist" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/product/(\\\\w+)" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/search" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/category/(\\\\w+)" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/order-status" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/page/(\\\\w+)" or http.request.uri.path matches "^/(\\\\w+)/([-\\\\w]+)/page-viewer/(\\\\w+)"'


Same here. Can we avoid hard-coding the routing rules and make them configurable via env var ?

shethj · 2025-10-21T04:46:53Z

packages/template-retail-react-app/app/ssr.js

+    // HYBRID PROXY REQUIREMENT:
+    // - Hybrid Proxy requires this to be 'true' for SFCC session management to work properly
+    // - Only enable Hybrid Proxy in development environments, never in production
+    localAllowCookies: false,


I don't see these options in the generated app. You might need to update the handlebar files. Please make sure you test the code with generated apps as well (with and without extensibility.)

shethj · 2025-10-21T04:58:56Z

I see the steps to test require updates to config/default.js:

app.commerceAPI.parameters
app.enableHybrid: true to toggle routes exclusion on routes.jsx
ssrParameters.proxyConfigs: add
{
host: [your SFCC store],
path: 'dwrestatic'
}

I don't see corresponding code changes to config/default.js in the PR.
Is this expected ?

Also for the config consider naming: app.enableHybridProxy: true because app.enableHybrid: true comes across as something I should enable for hybrid in general.

yhsieh1 and others added 6 commits October 8, 2025 12:08

@W-19626512 SPIKE hybrid proxy (#3120) (#3382)

162f1d5

@W-19477950 - hybrid cdn development (#3393)

ad65562

* Hybrid CDN 1st pass --------- Signed-off-by: Aditya Tekur <[email protected]>

@W-19478716 Hybrid Proxy Improvement (#3400)

499066a

@W-19869537 revert extra chagnes

953719d

@W-19869537 revert extra chagnes

6d0a761

yhsieh1 requested a review from a team as a code owner October 20, 2025 14:11

yhsieh1 added 3 commits October 20, 2025 10:18

update changelog

3cf8e55

Merge branch 'develop' into feature/hybridcdn

5b4455a

Merge branch 'develop' into feature/hybridcdn

b4db448

shethj reviewed Oct 21, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

@W-19869537 Added Hybrid Proxy support for local and ODS hybrid development when no eCDN available #3409

@W-19869537 Added Hybrid Proxy support for local and ODS hybrid development when no eCDN available #3409

yhsieh1 commented Oct 20, 2025 •

edited

Loading

Uh oh!

cc-prodsec commented Oct 20, 2025 •

edited

Loading

Uh oh!

shethj Oct 21, 2025

Uh oh!

shethj Oct 21, 2025 •

edited

Loading

Uh oh!

shethj Oct 21, 2025 •

edited

Loading

Uh oh!

shethj Oct 21, 2025

Uh oh!

shethj commented Oct 21, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

@W-19869537 Added Hybrid Proxy support for local and ODS hybrid development when no eCDN available #3409

Are you sure you want to change the base?

@W-19869537 Added Hybrid Proxy support for local and ODS hybrid development when no eCDN available #3409

Conversation

yhsieh1 commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Types of Changes

Changes

How to Test-Drive This PR

Checklists

General

Accessibility Compliance

Localization

Uh oh!

cc-prodsec commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Snyk checks have passed. No issues have been found so far.

Uh oh!

shethj Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

shethj Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shethj Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shethj Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

shethj commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yhsieh1 commented Oct 20, 2025 •

edited

Loading

cc-prodsec commented Oct 20, 2025 •

edited

Loading

shethj Oct 21, 2025 •

edited

Loading

shethj Oct 21, 2025 •

edited

Loading

shethj commented Oct 21, 2025 •

edited

Loading