Experience Editor hydration prop mismatch warning

coreyasmith commented 1 year ago

Describe the Bug

The following warning is shown in the browser console in the Experience Editor:

Warning: Prop phkey did not match. Server: "null" Client: "jss-main" code PlaceholderComponent@webpack-internal:///./node_modules/@sitecore-jss/sitecore-jss-react/dist/esm/components/Placeholder.js:24:9 WithComponentFactory@webpack-internal:///./node_modules/@sitecore-jss/sitecore-jss-react/dist/esm/enhancers/withComponentFactory.js:20:74 Placeholder@webpack-internal:///./node_modules/@sitecore-jss/sitecore-jss-nextjs/dist/esm/components/Placeholder.js:13:84 div Layout@webpack-internal:///./src/Layout.tsx:26:20 SitecoreContext@webpack-internal:///./node_modules/@sitecore-jss/sitecore-jss-react/dist/esm/components/SitecoreContext.js:21:9 ComponentPropsContext@webpack-internal:///./node_modules/@sitecore-jss/sitecore-jss-nextjs/dist/esm/components/ComponentPropsContext.js:27:31 SitecorePage@webpack-internal:///./src/pages/[[...path]].tsx:28:18 I18nProvider@webpack-internal:///./node_modules/next-localization/dist/index.modern.js:96:18 App@webpack-internal:///./src/pages/_app.tsx:52:19 _PathnameContextProviderAdapter@webpack-internal:///./node_modules/next/dist/shared/lib/router/adapters.js:118:18 ErrorBoundary@webpack-internal:///./node_modules/next/dist/compiled/@next/react-dev-overlay/dist/client.js:305:63 ReactDevOverlay@webpack-internal:///./node_modules/next/dist/compiled/@next/react-dev-overlay/dist/client.js:854:908 Container@webpack-internal:///./node_modules/next/dist/client/index.js:149:20 AppContainer@webpack-internal:///./node_modules/next/dist/client/index.js:342:18 Root@webpack-internal:///./node_modules/next/dist/client/index.js:561:19

See more info here: https://nextjs.org/docs/messages/react-hydration-error

To Reproduce

Install a new instance of Sitecore 10.3 (XP) in IIS.
Create a new JSS Next.js application.
Import JSS Styleguide into Sitecore 10.3 instance.
Open Experience Editor.
Open console and observe error.

Expected Behavior

No hydration warnings are thrown in the Experience Editor with a fresh install.

Possible Fix

No response

Provide environment information

Sitecore Version: 10.3 with Sitecore Headless Services Server XP 21.0.587
JSS Version: 21.1.5
Browser Name and version: Firefox, 113.0.1
Operating System and version (desktop or mobile): Windows 11
Link to your project (if available):

ambrauer commented 1 year ago

Hi @coreyasmith -

This is a known issue since Sitecore JSS Next.js SDK was introduced (v16). We have it in our backlog to revisit in the near-term; however, it has been a low priority as it does not impact content editing (and it only occurs for next:dev, not production).

Please feel free to re-open if this is impacting the actual content editing.

coreyasmith commented 1 year ago

@ambrauer Next.js only displays one hydration error mismatch at a time, so although this phkey warning does not cause issues, it hides other issues in our own app that are causing issues in the Experience Editor.

I believe that this is the source of the error: https://github.com/Sitecore/jss/blob/b006d3d34a59606d59fdde67f73f2867c75f5397/packages/sitecore-jss-nextjs/src/editing/editing-render-middleware.ts#L155

During SSR, EditingRenderMiddleware is rewriting the phkey attribute that is added to placeholder raw components by PlaceholderCommon to key. This upsets Next.js because it expects those raw components to be rendered as <code phkey="some-key" /> during SSR, but instead they're rendered as <code key="some-key" /> due to the EditingRenderMiddleware rewrite.

I fixed this warning by changing the EditingRenderMiddleware rewrite to preserve the phkey attribute when it adds the key attribute:

html = html.replace(new RegExp(/(phKey="[^"]+")/, 'g'), '$1 key=$1');

So during SSR <code phkey="some-key" /> becomes <code phkey="some-key" key="some-key" /> and Next.js doesn't seem to mind.

With this issue fixed, we get some new hydration warnings from the <Placeholder /> component we didn't see before:

One happens with empty placeholders and seems to be related to #1161 and Placeholder.tsx.
The other happens when no empty placeholders are present and again has something to do with the way raw elements are rendered.

I've not tested the fix above much, but I think it's a good starting point to look into this issue.

I'm not able to re-open this issue but I'm happy to open another one if you'd like.

ambrauer commented 1 year ago

@coreyasmith I'm re-opening for visibility (my bad) until we come up with a proper fix.

I've bumped this one in our backlog since, based on your findings, it appears this issue may be masking others.

Thanks once again for the detailed response, we appreciate it :)

stale[bot] commented 1 week ago

This has been automatically marked as stale because it has not had recent activity. It will be closed if there is no further activity within 30 days. You may add comments or the 'keep' label to prevent it from closing. Thank you for your contributions.

Sitecore / jss