Merge pull request #2906 from Arktomson/fix/2856-localStorage-ssr-hydration

fix(useLocalStorageState): Add a new SSR secure initialization option.

Author: crazylxr

packages/hooks/src/createUseStorageState/__tests__/index.spec.ts

@@ -1,5 +1,7 @@
 import { act, renderHook } from '@testing-library/react';
-import { describe, expect, test } from 'vitest';
+import { createElement } from 'react';
+import { renderToString } from 'react-dom/server';
+import { describe, expect, test, vi } from 'vitest';
 import type { Options } from '../index';
 import { createUseStorageState } from '../index';
 
@@ -98,4 +100,45 @@ describe('useStorageState', () => {
     act(() => hook.result.current.setState(undefined));
     expect(hook.result.current.state).toBeUndefined();
   });
+
+  test('should not read storage in SSR when getInitialValueInEffect is true', () => {
+    const storage = new TestStorage();
+    storage.setItem('key', JSON.stringify('stored-value'));
+    const getItemSpy = vi.spyOn(storage, 'getItem');
+    const useStorageState = createUseStorageState(() => storage);
+
+    const Demo = () => {
+      const [state] = useStorageState('key', {
+        defaultValue: 'default-value',
+        getInitialValueInEffect: true,
+      });
+
+      return createElement('span', null, state);
+    };
+
+    const html = renderToString(createElement(Demo));
+
+    expect(html).toContain('default-value');
+    expect(getItemSpy).not.toHaveBeenCalled();
+  });
+
+  test('should read storage in SSR when getInitialValueInEffect is false', () => {
+    const storage = new TestStorage();
+    storage.setItem('key', JSON.stringify('stored-value'));
+    const getItemSpy = vi.spyOn(storage, 'getItem');
+    const useStorageState = createUseStorageState(() => storage);
+
+    const Demo = () => {
+      const [state] = useStorageState('key', {
+        defaultValue: 'default-value',
+      });
+
+      return createElement('span', null, state);
+    };
+
+    const html = renderToString(createElement(Demo));
+
+    expect(html).toContain('stored-value');
+    expect(getItemSpy).toHaveBeenCalledWith('key');
+  });
 });

packages/hooks/src/createUseStorageState/index.ts

@@ -1,6 +1,7 @@
 import { useRef, useState } from 'react';
 import useEventListener from '../useEventListener';
 import useMemoizedFn from '../useMemoizedFn';
+import useMount from '../useMount';
 import useUpdateEffect from '../useUpdateEffect';
 import { isFunction, isUndef } from '../utils';
 
@@ -10,6 +11,7 @@ export type SetState<S> = S | ((prevState?: S) => S);
 
 export interface Options<T> {
   defaultValue?: T | (() => T);
+  getInitialValueInEffect?: boolean;
   listenStorageChange?: boolean;
   serializer?: (value: T) => string;
   deserializer?: (value: string) => T;
@@ -19,8 +21,7 @@ export interface Options<T> {
 export const createUseStorageState = (getStorage: () => Storage | undefined) => {
   const useStorageState = <T>(key: string, options: Options<T> = {}) => {
     let storage: Storage | undefined;
-
-    const { listenStorageChange = false } = options;
+    const { listenStorageChange = false, getInitialValueInEffect = false } = options;
 
     const serializer = isFunction(options.serializer) ? options.serializer : JSON.stringify;
 
@@ -44,13 +45,32 @@ export const createUseStorageState = (getStorage: () => Storage | undefined) =>
       } catch (e) {
         onError(e);
       }
+      return getDefaultValue();
+    }
+
+    function getDefaultValue() {
       if (isFunction(options.defaultValue)) {
         return options.defaultValue();
       }
+
       return options.defaultValue;
     };
 
-    const [state, setState] = useState<T>(getStoredValue);
+    const [state, setState] = useState<T>(() => {
+      if (getInitialValueInEffect) {
+        return getDefaultValue();
+      }
+
+      return getStoredValue();
+    });
+
+    useMount(() => {
+      if (!getInitialValueInEffect) {
+        return;
+      }
+
+      setState(getStoredValue());
+    });
 
     const stateRef = useRef<T>(state);
     stateRef.current = state;

packages/hooks/src/useLocalStorageState/index.en-US.md

@@ -34,6 +34,7 @@ type SetState<S> = S | ((prevState?: S) => S);
 
 interface Options<T> {
   defaultValue?: T | (() => T);
+  getInitialValueInEffect?: boolean;
   listenStorageChange?: boolean;
   serializer?: (value: T) => string;
   deserializer?: (value: string) => T;
@@ -58,6 +59,7 @@ const [state, setState] = useLocalStorageState<T>(
 | Property            | Description                                                                                                                                                                                             | Type                       | Default                       |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----------------------------- |
 | defaultValue        | Default value                                                                                                                                                                                           | `any \| (() => any)`       | -                             |
+| getInitialValueInEffect | Whether to read localStorage in an effect after mount, useful to avoid SSR hydration mismatch                                                                                                      | `boolean`                  | `false`                       |
 | listenStorageChange | Whether to listen storage changes. If `true`, when the stored value changes, all `useLocalStorageState` with the same `key` will synchronize their states, including different tabs of the same browser | `boolean`                  | `false`                       |
 | serializer          | Custom serialization method                                                                                                                                                                             | `(value: any) => string`   | `JSON.stringify`              |
 | deserializer        | Custom deserialization method                                                                                                                                                                           | `(value: string) => any`   | `JSON.parse`                  |

packages/hooks/src/useLocalStorageState/index.zh-CN.md

@@ -34,6 +34,7 @@ type SetState<S> = S | ((prevState?: S) => S);
 
 interface Options<T> {
   defaultValue?: T | (() => T);
+  getInitialValueInEffect?: boolean;
   listenStorageChange?: boolean;
   serializer?: (value: T) => string;
   deserializer?: (value: string) => T;
@@ -58,6 +59,7 @@ const [state, setState] = useLocalStorageState<T>(
 | 参数                | 说明                                                                                                                              | 类型                       | 默认值                        |
 | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----------------------------- |
 | defaultValue        | 默认值                                                                                                                            | `any \| (() => any)`       | -                             |
+| getInitialValueInEffect | 是否在挂载后通过 effect 读取 localStorage，可用于避免 SSR hydration 不一致                                                                 | `boolean`                  | `false`                       |
 | listenStorageChange | 是否监听存储变化。如果是 `true`，当存储值变化时，所有 `key` 相同的 `useLocalStorageState` 会同步状态，包括同一浏览器不同 tab 之间 | `boolean`                  | `false`                       |
 | serializer          | 自定义序列化方法                                                                                                                  | `(value: any) => string`   | `JSON.stringify`              |
 | deserializer        | 自定义反序列化方法                                                                                                                | `(value: string) => any`   | `JSON.parse`                  |