[Chakra v3] Fix data fetching regression with the SSR rendering (@W-18822712@)

packages/extension-chakra-storefront/CHANGELOG.md

@@ -4,5 +4,6 @@
 - Send PWA Kit events to Data Cloud [#318] (https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2229)
 - Fix dependencies vulnerabilities [#2338](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2338)
 - Fix accessibility issues [#2375](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2375)
+- Create a safe version of `<Portal>` that won't break the SSR rendering [#2785](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2785)
 
 For historical changelog, look for the original `retail-react-app` in the [release notes](https://github.com/SalesforceCommerceCloud/pwa-kit/releases).

packages/extension-chakra-storefront/src/components/product-view-modal/bundle.jsx

@@ -7,10 +7,11 @@
 
 import React, {useState, useRef} from 'react'
 import PropTypes from 'prop-types'
-import {Dialog, Portal, Flex, Box, VStack, useBreakpointValue} from '@chakra-ui/react'
+import {Dialog, Flex, Box, VStack, useBreakpointValue} from '@chakra-ui/react'
 import {keepPreviousData} from '@tanstack/react-query'
 import ProductView from '../../components/product-view'
 import {useProductViewModal} from '../../hooks/use-product-view-modal'
+import SafePortal from '../safe-portal'
 import {useProducts} from '@salesforce/commerce-sdk-react'
 import ImageGallery, {Skeleton as ImageGallerySkeleton} from '../../components/image-gallery'
 import {useDerivedProduct} from '../../hooks'
@@ -62,7 +63,7 @@ const BundleProductViewModal = ({product: bundle, isOpen, onClose, updateCart, .
             size="4xl"
             closeOnInteractOutside={false}
         >
-            <Portal>
+            <SafePortal>
                 <Dialog.Backdrop />
                 <Dialog.Positioner>
                     <Dialog.Content data-testid="product-view-modal" aria-label={label}>
@@ -170,7 +171,7 @@ const BundleProductViewModal = ({product: bundle, isOpen, onClose, updateCart, .
                         </Dialog.Body>
                     </Dialog.Content>
                 </Dialog.Positioner>
-            </Portal>
+            </SafePortal>
         </Dialog.Root>
     )
 }

packages/extension-chakra-storefront/src/components/product-view-modal/index.jsx

@@ -7,9 +7,10 @@
 
 import React from 'react'
 import PropTypes from 'prop-types'
-import {Dialog, Portal, CloseButton} from '@chakra-ui/react'
+import {Dialog, CloseButton} from '@chakra-ui/react'
 import ProductView from '../../components/product-view'
 import {useProductViewModal} from '../../hooks/use-product-view-modal'
+import SafePortal from '../safe-portal'
 import {useIntl} from 'react-intl'
 
 /**
@@ -34,7 +35,7 @@ const ProductViewModal = ({product, isOpen, onClose, ...props}) => {
             size="xl"
             closeOnInteractOutside={false}
         >
-            <Portal>
+            <SafePortal>
                 <Dialog.Backdrop />
                 <Dialog.Positioner>
                     <Dialog.Content data-testid="product-view-modal" aria-label={label}>
@@ -53,7 +54,7 @@ const ProductViewModal = ({product, isOpen, onClose, ...props}) => {
                         </Dialog.CloseTrigger>
                     </Dialog.Content>
                 </Dialog.Positioner>
-            </Portal>
+            </SafePortal>
         </Dialog.Root>
     )
 }

packages/extension-chakra-storefront/src/components/safe-portal/index.jsx

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2021, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import React, {useEffect, useState} from 'react'
+import {Portal} from '@chakra-ui/react'
+
+/**
+ * A safe version of Portal that only renders on the client side.
+ * This prevents SSR issues where Portal tries to access the DOM during server rendering.
+ * (Portal would call Ark UI's useEnvironmentContext hook, which tries to access `document` that doesn't exist on the server)
+ *
+ * @param {Object} props - Props to pass to the Portal component
+ * @returns {React.Element|null} Portal component or null if on server
+ */
+export const SafePortal = (props) => {
+    const [isClient, setIsClient] = useState(false)
+
+    useEffect(() => {
+        // This effect only runs on the client side
+        // And with it, we avoid any hydration mismatch error
+        setIsClient(true)
+    }, [])
+
+    // Don't render anything on the server or before hydration
+    if (!isClient) {
+        return null
+    }
+
+    return <Portal {...props} />
+}
+
+export default SafePortal

packages/extension-chakra-storefront/src/components/toaster/index.jsx

@@ -6,7 +6,8 @@
  */
 import React from 'react'
 import PropTypes from 'prop-types'
-import {Toaster as ChakraToaster, Portal, Stack, Toast, createToaster} from '@chakra-ui/react'
+import {Toaster as ChakraToaster, Stack, Toast, createToaster} from '@chakra-ui/react'
+import SafePortal from '../safe-portal'
 
 // A toaster is a shared global instance that can be used to create and manage toasts.
 export const toaster = createToaster({
@@ -15,7 +16,7 @@ export const toaster = createToaster({
 
 export default function Toaster({toaster}) {
     return (
-        <Portal>
+        <SafePortal>
             <ChakraToaster toaster={toaster} insetInline={{mdDown: '4'}}>
                 {(toast) => (
                     <Toast.Root width={{md: 'sm'}}>
@@ -33,7 +34,7 @@ export default function Toaster({toaster}) {
                     </Toast.Root>
                 )}
             </ChakraToaster>
-        </Portal>
+        </SafePortal>
     )
 }
 

packages/extension-chakra-storefront/src/hooks/use-add-to-cart-modal.js

@@ -16,7 +16,6 @@ import {
     Dialog,
     Flex,
     Heading,
-    Portal,
     Text,
     Stack,
     useBreakpointValue
@@ -29,6 +28,7 @@ import {findImageGroupBy} from '../utils/image-groups-utils'
 import {getPriceData, getDisplayVariationValues} from '../utils/product-utils'
 import {EINSTEIN_RECOMMENDERS} from '../constants'
 import DisplayPrice from '../components/display-price'
+import SafePortal from '../components/safe-portal'
 
 /**
  * This is the context for managing the AddToCartModal.
@@ -84,7 +84,7 @@ export const AddToCartModal = () => {
             scrollBehavior="inside"
             placement="center"
         >
-            <Portal>
+            <SafePortal>
                 <Dialog.Backdrop />
                 <Dialog.Positioner>
                     <Dialog.Content
@@ -422,7 +422,7 @@ export const AddToCartModal = () => {
                         </Dialog.CloseTrigger>
                     </Dialog.Content>
                 </Dialog.Positioner>
-            </Portal>
+            </SafePortal>
         </Dialog.Root>
     )
 }

packages/extension-chakra-storefront/src/hooks/use-auth-modal.js

@@ -8,7 +8,7 @@ import React, {useEffect, useState} from 'react'
 import PropTypes from 'prop-types'
 import {defineMessage, useIntl} from 'react-intl'
 import {useForm} from 'react-hook-form'
-import {Dialog, Portal, CloseButton, useDisclosure} from '@chakra-ui/react'
+import {Dialog, CloseButton, useDisclosure} from '@chakra-ui/react'
 import {keepPreviousData} from '@tanstack/react-query'
 import {
     AuthHelpers,
@@ -40,6 +40,7 @@ import {isServer} from '../utils/utils'
 import {isAbsoluteURL} from '../page-designer/utils'
 import {useAppOrigin} from './use-app-origin'
 import {useExtensionConfig} from './use-extension-config'
+import SafePortal from '../components/safe-portal'
 
 export const LOGIN_VIEW = 'login'
 export const REGISTER_VIEW = 'register'
@@ -286,7 +287,7 @@ export const AuthModal = ({
             data-testid="sf-auth-modal"
             {...props}
         >
-            <Portal>
+            <SafePortal>
                 <Dialog.Backdrop />
                 <Dialog.Positioner>
                     <Dialog.Content>
@@ -342,7 +343,7 @@ export const AuthModal = ({
                         </Dialog.Body>
                     </Dialog.Content>
                 </Dialog.Positioner>
-            </Portal>
+            </SafePortal>
         </Dialog.Root>
     )
 }

packages/extension-chakra-storefront/src/pages/checkout/partials/contact-info.jsx

@@ -6,13 +6,14 @@
  */
 import React, {useEffect, useRef, useState} from 'react'
 import PropTypes from 'prop-types'
-import {Alert, Box, Button, Container, Dialog, Portal, Stack, Text} from '@chakra-ui/react'
+import {Alert, Box, Button, Container, Dialog, Stack, Text} from '@chakra-ui/react'
 import {useForm} from 'react-hook-form'
 import {FormattedMessage, useIntl} from 'react-intl'
 import {useCheckout} from '../../../pages/checkout/util/checkout-context'
 import useLoginFields from '../../../components/forms/useLoginFields'
 import {ToggleCard, ToggleCardEdit, ToggleCardSummary} from '../../../components/toggle-card'
 import Field from '../../../components/field'
+import SafePortal from '../../../components/safe-portal'
 import {AlertIcon} from '../../../components/icons'
 import LoginState from '../../../pages/checkout/partials/login-state'
 import {AuthModal, EMAIL_VIEW, PASSWORD_VIEW, useAuthModal} from '../../../hooks/use-auth-modal'
@@ -274,7 +275,7 @@ const SignOutConfirmationDialog = ({isOpen, onConfirm, onClose}) => {
             open={isOpen}
             onOpenChange={(details) => !details.open && onClose()}
         >
-            <Portal>
+            <SafePortal>
                 <Dialog.Backdrop />
                 <Dialog.Positioner>
                     <Dialog.Content>
@@ -313,7 +314,7 @@ const SignOutConfirmationDialog = ({isOpen, onConfirm, onClose}) => {
                         </Dialog.Footer>
                     </Dialog.Content>
                 </Dialog.Positioner>
-            </Portal>
+            </SafePortal>
         </Dialog.Root>
     )
 }

packages/extension-chakra-storefront/src/pages/product-list/index.jsx

@@ -30,7 +30,6 @@ import {
     Button,
     Field,
     Dialog,
-    Portal,
     Drawer,
     NativeSelect
 } from '@chakra-ui/react'
@@ -60,6 +59,7 @@ import {
     useExtensionConfig
 } from '../../hooks'
 import useToast from '../../hooks/use-toast'
+import SafePortal from '../../components/safe-portal'
 import useEinstein from '../../hooks/use-einstein'
 import useActiveData from '../../hooks/use-active-data'
 import useDataCloud from '../../hooks/use-datacloud'
@@ -483,7 +483,7 @@ const ProductList = (props) => {
                                                 />
                                             </Button>
                                         </Dialog.Trigger>
-                                        <Portal>
+                                        <SafePortal>
                                             <Dialog.Backdrop />
                                             <Dialog.Positioner>
                                                 <Dialog.Content
@@ -590,7 +590,7 @@ const ProductList = (props) => {
                                                     </Dialog.Footer>
                                                 </Dialog.Content>
                                             </Dialog.Positioner>
-                                        </Portal>
+                                        </SafePortal>
                                     </Dialog.Root>
                                 </Flex>
                                 <Flex align="center">
@@ -727,7 +727,7 @@ const ProductList = (props) => {
                 placement="bottom"
                 size="sm"
             >
-                <Portal>
+                <SafePortal>
                     <Drawer.Backdrop />
                     <Drawer.Positioner>
                         <Drawer.Content>
@@ -775,7 +775,7 @@ const ProductList = (props) => {
                             </Drawer.Body>
                         </Drawer.Content>
                     </Drawer.Positioner>
-                </Portal>
+                </SafePortal>
             </Drawer.Root>
         </Box>
     )

packages/pwa-kit-react-sdk/CHANGELOG.md

@@ -1,4 +1,6 @@
 ## v4.0.0-extensibility-preview.5 (May 06, 2025)
+- SSR rendering: implement workaround for react-ssr-prepass to ignore React's useInsertionEffect [#2785](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2785)
+
 ## v4.0.0-extensibility-preview.4 (Feb 12, 2025)
 - Replace `event-emitter` in favor of the native `EventTarget` [#2289](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2289)
 - Call app extension's new methods `getRoutes` and `getRoutesAsync` [#2308](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2308)

packages/pwa-kit-react-sdk/src/ssr/server/react-rendering.js

@@ -39,6 +39,16 @@ import * as errors from '../universal/errors'
 import logger from '../../utils/logger-instance'
 import PerformanceTimer, {PERFORMANCE_MARKS} from '../../utils/performance'
 
+// Workaround for react-ssr-prepass lack of no-op for the React hook `useInsertionEffect`.
+// (see https://github.com/FormidableLabs/react-ssr-prepass/issues/84)
+// - Why useInsertionEffect? Chakra v3 hooks (like useDisclosure, useBreakpointValue, useMediaQuery, useCallbackRef) rely on it for rendering optimization.
+//   * see https://github.com/chakra-ui/chakra-ui/blob/c83e7f5acff2751ee3722bf22d89a5fe581fd72c/packages/react/src/hooks/use-callback-ref.ts#L17-L19
+// - Why no-op? useInsertionEffect is meant for client side only. So on the server, we wanted prepass to ignore it.
+// - Is it safe? Yes, we're not breaking the original behaviour. As React doc explains, the hook is for client side only: https://react.dev/reference/react/useInsertionEffect
+if (React.useInsertionEffect) {
+    React.useInsertionEffect = () => {} // no-op
+}
+
 const CWD = process.cwd()
 const BUNDLES_PATH = path.resolve(CWD, 'build/loadable-stats.json')
 

packages/pwa-kit-react-sdk/src/ssr/universal/components/with-react-query/index.js

@@ -70,8 +70,11 @@ export const withReactQuery = (Wrapped, options = {}) => {
 
             res.__performanceTimer.mark(PERFORMANCE_MARKS.reactQueryPrerender, 'start')
             // Use `ssrPrepass` to collect all uses of `useQuery`.
+            // NOTE: See a workaround in 'ssr/server/react-rendering.js' file that we had to implement,
+            // so that prepass would ignore React's useInsertionEffect hook.
             await ssrPrepass(appJSX)
             res.__performanceTimer.mark(PERFORMANCE_MARKS.reactQueryPrerender, 'end')
+
             const queryCache = queryClient.getQueryCache()
             const queries = queryCache.getAll().filter((q) => q.options.enabled !== false)
             await Promise.all(