@W-19869537 Added Hybrid Proxy support for local and ODS hybrid development when no eCDN available by yhsieh1 · Pull Request #3409 · SalesforceCommerceCloud/pwa-kit

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
NOTE: We need to change this to app.enableHybridProxy in the sample code and public doc
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 <126732792+aditek-sf@users.noreply.github.com>

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 ?

I will move them to utils.js. Thanks!

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 ?

This can be read from env var but the ask from one pager is to leave the decision to use env var to the customer that's why the string is used here.

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 ?

It can be read from env var but according to one pager we would like to leave the decision to customer and not introduce dotenv dependency in the project.

Customers can always implement using in env-vars on their own; our documenting using plain config will be simpler without introducing that extra dependency (and no need for the 3PP). Furthermore the rule set is unlikely to change within a customers implementation and they will likely only use env-vars for the ECOM upstream. We will leave this up to them.

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.)

Thank you for catching this. I will update it.

ssr.js.hbs is updated for both extensible and non-extensible and tested in generated project for:

my own instance
-- non extensible
-- extensible

demo instance

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 · 2025-10-21T14:01:44Z

enableHybrid
@shethj the default.js changes is required for customer to config proxy of dwrestatic and exclude the route from PWA storefront client side navigation(step 3 code) so that the request will be proxied from the server side.

shethj · 2025-10-21T14:42:14Z

enableHybrid
@shethj the default.js changes is required for customer to config proxy of dwrestatic and exclude the route from PWA storefront client side navigation(step 3 code) so that the request will be proxied from the server side.

Yeah I understood the changes. I was wondering if the config.js changes should be shipped with defaults OOTB.

yhsieh1 · 2025-10-21T16:35:04Z

enableHybrid
@shethj the default.js changes is required for customer to config proxy of dwrestatic and exclude the route from PWA storefront client side navigation(step 3 code) so that the request will be proxied from the server side.

Yeah I understood the changes. I was wondering if the config.js changes should be shipped with defaults OOTB.

@shethj You are right but the main problem is client might configure app.url site, locale, showDefaults differently and this will affect the routes.jsx changes needed accordingly to construct the newURL.pathname. We might need to provide routes.jsx examples to cover some use cases including default generated app in the doc. cc. @aditek-sf

yhsieh1 · 2025-10-21T19:11:09Z

packages/pwa-kit-create-app/assets/bootstrap/js/overrides/app/ssr.js.hbs

+        enabled: false,
+
+        // The origin of the SFCC instance (i.e. the instance that is being proxied to which hosts the storefront).
+        sfccOrigin: 'https://{{answers.project.commerce.instanceUrl}}',


use {{answers.project.commerce.instanceUrl}} so that user does not need to update this manually in ssr.js

yhsieh1 · 2025-10-21T19:11:43Z

packages/pwa-kit-create-app/assets/templates/@salesforce/retail-react-app/app/ssr.js.hbs

+        enabled: false,
+
+        // The origin of the SFCC instance (i.e. the instance that is being proxied to which hosts the storefront).
+        sfccOrigin: 'https://{{answers.project.commerce.instanceUrl}}',


use {{answers.project.commerce.instanceUrl}} so that user does not need to update this manually in ssr.js

shethj · 2025-10-21T20:15:16Z

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

@@ -0,0 +1,150 @@
+/*


@yhsieh1 Can we please rename this file to hybrid-proxy.js to make sure we follow the naming convention to match other files in the package. Also for the test file.
Thanks!

Thank you for catching this. I did not notice the file name is not right.

Signed-off-by: yhsieh1 <yhsieh@salesforce.com>

shethj · 2025-10-22T21:21:59Z

LGTM 👍

patricksullivansf · 2025-10-23T00:07:00Z

packages/pwa-kit-create-app/CHANGELOG.md

@@ -3,6 +3,7 @@
 - Prompt text for Site ID should match actual validation: Site ID may contain uppercase or lowercase letters, numbers, hyphens, or underscores. - Updated Site ID validator regex to allow both uppercase and lowercase letters for improved compatibility, clarity. [#3410] (https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3410)

 ## v3.14.0-dev (Sep 26, 2025)


maybe not this PR directly, but why are there two v3.14.0-dev sections?

Thanks @patricksullivansf. It must be the auto merge. I fixed it.

Signed-off-by: yhsieh1 <yhsieh@salesforce.com>

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 <126732792+aditek-sf@users.noreply.github.com>

@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

update ssr.js.hbs

baa6709

yhsieh1 added 2 commits October 21, 2025 10:06

update changelog

dd7e236

update ssr.js.hbs

b484e92

yhsieh1 added 3 commits October 21, 2025 13:26

update ssr.js.hbs for overrides app

f5698b1

update ssr.js.hbs for template

f12eb6a

use answers.project.commerce.instanceUrl for sfccOrigin

db27ead

yhsieh1 commented Oct 21, 2025

View reviewed changes

move util functions

bc54ed0

yhsieh1 requested a review from shethj October 21, 2025 19:50

shethj reviewed Oct 21, 2025

View reviewed changes

rename to hybrid-proxy

04bf75a

yhsieh1 requested a review from shethj October 21, 2025 20:59

yhsieh1 added 2 commits October 22, 2025 15:17

Merge branch 'develop' into feature/hybridcdn

46aefd8

Signed-off-by: yhsieh1 <yhsieh@salesforce.com>

fix unit test after merge

401792c

shethj previously approved these changes Oct 22, 2025

View reviewed changes

patricksullivansf previously approved these changes Oct 23, 2025

View reviewed changes

yhsieh1 added 2 commits October 22, 2025 22:14

Merge branch 'develop' into feature/hybridcdn

7d553fa

correct changelog

c0e0e18

yhsieh1 dismissed stale reviews from shethj and patricksullivansf via c0e0e18 October 23, 2025 02:21

patricksullivansf previously approved these changes Oct 23, 2025

View reviewed changes

yhsieh1 requested a review from shethj October 23, 2025 14:48

Merge branch 'develop' into feature/hybridcdn

ab622b0

Signed-off-by: yhsieh1 <yhsieh@salesforce.com>

yhsieh1 dismissed patricksullivansf’s stale review via ab622b0 October 23, 2025 15:57

patricksullivansf approved these changes Oct 23, 2025

View reviewed changes

shethj approved these changes Oct 23, 2025

View reviewed changes

yhsieh1 merged commit 9765651 into develop Oct 23, 2025
42 checks passed

yhsieh1 deleted the feature/hybridcdn branch October 23, 2025 16:31

		@@ -3,6 +3,7 @@
		- Prompt text for Site ID should match actual validation: Site ID may contain uppercase or lowercase letters, numbers, hyphens, or underscores. - Updated Site ID validator regex to allow both uppercase and lowercase letters for improved compatibility, clarity. [#3410] (https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3410)

		## v3.14.0-dev (Sep 26, 2025)

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!

Choose a reason for hiding this comment

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

yhsieh1 commented Oct 21, 2025

Uh oh!

shethj commented Oct 21, 2025

Uh oh!

yhsieh1 commented Oct 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shethj commented Oct 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 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