feat: @W-22204286 add maintenance mode page for 503/sfdc_maintenance responses - #3827
Conversation
Enable throwOnMaintenanceHeader in commerce-sdk-react, propagate MaintenanceError as 503 through the SSR and client error pipelines, and render a new _maintenance-error component that displays either a shared CDN-hosted page (proxied via /api/maintenance-page) or a built-in fallback, configurable via app.pages.maintenancePage.
|
Git2Gus App is installed but the |
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
Signed-off-by: Philippe Riand <36373169+priandsf@users.noreply.github.com>
There was a problem hiding this comment.
_{component} is a PWA Kit SDK file system convention for SDK level special components.
It indicates that this component is being processed by the SDK, and the SDK will look at the user land /app/components/ folder for these special components, if not found it will fallback to the SDK default implementation.
The current file system convention we have are:
_app_config - wraps the top level application with providers
_app - root application
_document - the HTML shell (equivalent to next.js layout.js)
_error - error page (equivalent to next.js error.js)
Did you want to introduce the maintainence page as a new member of the SDK component family? or is this just a template level component, if so, we should remove the _ prefix
There was a problem hiding this comment.
@kevinxh So I copied that from _error, as I think it should behave the same. Is there any issue with it?
There was a problem hiding this comment.
Does it make sense to move the component to SDK?
There was a problem hiding this comment.
If the intent is to register _maintenance-error as a new framework-level file convention (alongside _app, _document, _error, etc.), there are two additional changes needed to make it a true SDK-level component:
- Add a default
_maintenance-errorimplementation under https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/pwa-kit-react-sdk/src/ssr/universal/components so the SDK has a fallback. - Register it in the webpack override list at https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/pwa-kit-dev/src/configs/webpack/plugins.js#L67-L87 so userland overrides are resolved correctly.
That said, my recommendation is to drop the _ prefix here. As used in this PR, _maintenance-error is consumed internally by the error component and doesn’t need a dedicated SSR code path or override hook — it’s a template-level component, not a framework-level one. Reserving the _ convention for components that genuinely participate in the SDK’s resolution mechanism keeps the convention meaningful and avoids implying behavior that isn’t wired up.
There was a problem hiding this comment.
Thanks, I dropped it - done. Is that documented somewhere?
There was a problem hiding this comment.
Enable throwOnMaintenanceHeader in commerce-sdk-react, propagate MaintenanceError as 503 through the SSR and client error pipelines, and render a new _maintenance-error component that displays either a shared CDN-hosted page (proxied via /api/maintenance-page) or a built-in fallback, configurable via app.pages.maintenancePage.
Description
Maintenance Mode Page
Summary
Adds a dedicated maintenance mode page that is automatically displayed when the Commerce API signals that the site is under maintenance via the
sfdc_maintenanceresponse header.How it works
Detection —
commerce-sdk-isomorphicalready throws aMaintenanceErrorwhen it detects thesfdc_maintenanceheader andthrowOnMaintenanceHeaderis enabled. This PR enables that flag by hardcodingthrowOnMaintenanceHeader: trueincommerce-sdk-react's provider config (alongside the existingthrowOnBadResponse: true).Error propagation —
MaintenanceErroris not anHTTPError, so it was previously swallowed as a generic 500. Three places are fixed to correctly propagate it as a 503:with-react-query/doInitAppState— rethrowsMaintenanceErrorinstead of swallowing it during SSR query prefetchingreact-rendering/logAndFormatError— formats it withstatus: 503instead of 500app-error-boundary— detects it byerr.name === 'MaintenanceError'in bothonGetPropsError(server/getPropspath) andgetDerivedStateFromError(client render path)Client-side —
useErrorBoundary: (err) => err?.name === 'MaintenanceError'is added to the React Query default options so thatMaintenanceErrorthrown by client-side queries is rethrown into the React error boundary rather than silently held in query state.Rendering —
_error/index.jsxdispatches to a new_maintenance-errorcomponent whenstatus === 503.Maintenance page content — The
_maintenance-errorcomponent supports two modes, configured viaconfig.app.pages.maintenancePage:sharedMaintenancePage: true(default) — fetches a shared HTML maintenance page from a configurable CDN URL, proxied through a new/api/maintenance-pageExpress endpoint to avoid CORS restrictionssharedMaintenancePage: false— displays a built-in branded fallback messageTypes of Changes
Changes
How to Test-Drive This PR
sfdc_maintenance: systemorsfdc_maintenance: siteheader is returned by the APIsharedMaintenancePage: trueandcdnUrlis configuredsharedMaintenancePage: false_maintenance-errorunit tests:jest app/components/_maintenance-errorChecklists
General
Accessibility Compliance
You must check off all items in one of the follow two lists:
or...
Localization