fix(Provider): throw actionable error when rendered in a React Server Component (reduxjs#2082)

Author: veksa

src/components/Provider.tsx

@@ -57,6 +57,25 @@ export interface ProviderProps<
 function Provider<A extends Action<string> = UnknownAction, S = unknown>(
   providerProps: ProviderProps<A, S>,
 ) {
+  if (process.env.NODE_ENV !== 'production') {
+    // React Server Components do not provide the effect hooks that `<Provider>`
+    // relies on, so `useIsomorphicLayoutEffect` (which resolves to
+    // `useLayoutEffect`/`useEffect`) is `undefined` in that environment. Detect
+    // this before any hook runs and throw an actionable error, instead of the
+    // cryptic "X is not a function" that would otherwise surface.
+    if (typeof useIsomorphicLayoutEffect !== 'function') {
+      throw new Error(
+        'The React Redux `<Provider>` component requires React hooks that are ' +
+          'not available in a React Server Component. This usually means you are ' +
+          'rendering `<Provider>` in a Server Component. Add the `"use client"` ' +
+          'directive to the top of the file that renders `<Provider>` (or a ' +
+          'parent that ends up rendering it) so it is treated as a Client ' +
+          'Component. See https://react.dev/reference/rsc/use-client for more ' +
+          'information.',
+      )
+    }
+  }
+
   const { children, context, serverState, store } = providerProps
 
   const contextValue = React.useMemo(() => {

test/components/Provider-rsc.spec.tsx

@@ -0,0 +1,42 @@
+/*eslint-disable react/prop-types*/
+
+import * as rtl from '@testing-library/react'
+import { Provider } from 'react-redux'
+import { createStore } from 'redux'
+
+// In a React Server Components environment, React does not expose the effect
+// hooks that `<Provider>` relies on, so `useIsomorphicLayoutEffect` (which
+// resolves to `useLayoutEffect`/`useEffect`) ends up `undefined`. Simulate that
+// here to assert `<Provider>` surfaces a clear, actionable error rather than a
+// cryptic "X is not a function".
+vi.mock('../../src/utils/useIsomorphicLayoutEffect', () => ({
+  useIsomorphicLayoutEffect: undefined,
+}))
+
+// This mock replaces an internal source module, which only exists as a separate
+// module in the `src` build. When the suite runs against the bundled build
+// artifact (`TEST_DIST`), `useIsomorphicLayoutEffect` is inlined into a single
+// file with no module boundary left to mock, so the RSC condition cannot be
+// simulated there. The guard itself is unchanged between builds, so exercising
+// it against `src` is sufficient.
+const describeSource = process.env.TEST_DIST ? describe.skip : describe
+
+describeSource('React', () => {
+  describe('Provider in a React Server Component environment', () => {
+    it('throws an actionable error when React effect hooks are unavailable', () => {
+      const store = createStore(() => ({}))
+
+      const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+      expect(() =>
+        rtl.render(
+          <Provider store={store}>
+            <div />
+          </Provider>,
+        ),
+      ).toThrow(/React Server Component/)
+
+      spy.mockRestore()
+    })
+  })
+})