feat(redux-storage-middleware)!: require rootReducer and return hydrated reducer

BREAKING CHANGE: API signature changed for createStorageMiddleware()

Before:
  const { middleware } = createStorageMiddleware({ name, slices })
  const store = configureStore({
    reducer: withHydration(rootReducer),  // Easy to forget!
    middleware: (get) => get().concat(middleware),
  })

After:
  const { middleware, reducer } = createStorageMiddleware({
    rootReducer,  // Required
    name,
    slices,
  })
  const store = configureStore({
    reducer,  // Already hydration-wrapped
    middleware: (get) => get().concat(middleware),
  })

Changes:
- rootReducer is now required parameter
- Returns { middleware, reducer, api } - reducer is pre-wrapped
- Removed skipHydration option (auto-hydration always enabled)
- withHydration() marked as @deprecated
- Updated all tests (16 tests migrated)
- Updated README with Migration Guide
- Updated GitBox app and gmail-clone example

Author: ryota-murakami

lib/redux/store.ts

@@ -16,10 +16,7 @@ import { combineReducers, configureStore } from '@reduxjs/toolkit'
 import type { TypedUseSelectorHook } from 'react-redux'
 import { useDispatch, useSelector } from 'react-redux'
 
-import {
-  createStorageMiddleware,
-  withHydration,
-} from '@gitbox/redux-storage-middleware'
+import { createStorageMiddleware } from '@gitbox/redux-storage-middleware'
 import authReducer from './slices/authSlice'
 import boardReducer from './slices/boardSlice'
 import draftReducer from './slices/draftSlice'
@@ -33,16 +30,18 @@ const rootReducer = combineReducers({
   settings: settingsReducer,
 })
 
-// Storage middleware configuration
-const { middleware: storageMiddleware } = createStorageMiddleware({
-  // Synchronize settings, board, and draft slices to LocalStorage
-  name: 'gitbox-state',
-  slices: ['settings', 'board', 'draft'],
-})
+// Storage middleware configuration with new API
+// Returns hydration-wrapped reducer automatically
+const { middleware: storageMiddleware, reducer: hydratedReducer } =
+  createStorageMiddleware({
+    rootReducer, // Required: pass root reducer
+    name: 'gitbox-state',
+    slices: ['settings', 'board', 'draft'], // Persist these slices to localStorage
+  })
 
 export const store = configureStore({
-  // Wrap reducer with withHydration to handle localStorage state restoration
-  reducer: withHydration(rootReducer),
+  // Use returned reducer (already hydration-wrapped)
+  reducer: hydratedReducer,
   middleware: (getDefaultMiddleware) =>
     getDefaultMiddleware({
       serializableCheck: {

packages/redux-storage-middleware/README.md

@@ -38,6 +38,7 @@ SSR-safe Redux Toolkit middleware for localStorage persistence with selective sl
 - [Testing](#testing)
 - [Examples](#examples)
 - [TypeScript Support](#typescript-support)
+- [Migration Guide](#migration-guide)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -67,31 +68,36 @@ pnpm add lz-string     # For compression
 ## Quick Start
 
 ```typescript
-import { configureStore } from '@reduxjs/toolkit'
+import { combineReducers, configureStore } from '@reduxjs/toolkit'
 import { createStorageMiddleware } from '@gitbox/redux-storage-middleware'
 
 interface AppState {
   emails: EmailsState
   settings: SettingsState
 }
 
-// Create middleware and API
-const { middleware, api } = createStorageMiddleware<AppState>({
+// Create root reducer
+const rootReducer = combineReducers({
+  emails: emailReducer,
+  settings: settingsReducer,
+})
+
+// Create middleware, reducer, and API
+const { middleware, reducer, api } = createStorageMiddleware<AppState>({
+  rootReducer, // Required: pass your root reducer
   name: 'my-app-state',
   slices: ['emails', 'settings'],
   version: 1,
 })
 
-// Configure store
+// Configure store with returned reducer (already hydration-wrapped)
 export const store = configureStore({
-  reducer: {
-    emails: emailReducer,
-    settings: settingsReducer,
-  },
+  reducer, // Use the returned reducer
   middleware: (getDefaultMiddleware) =>
     getDefaultMiddleware().concat(middleware),
 })
 
+// Hydration happens automatically on client
 // Export API for manual control
 export { api as storageApi }
 ```
@@ -106,18 +112,18 @@ Creates the storage middleware and returns both the middleware and a control API
 
 #### Configuration Options
 
-| Option          | Type                        | Default        | Description                                            |
-| --------------- | --------------------------- | -------------- | ------------------------------------------------------ |
-| `name`          | `string`                    | **required**   | localStorage key name                                  |
-| `slices`        | `(keyof S)[]`               | `undefined`    | State slices to persist (all if undefined)             |
-| `partialize`    | `(state: S) => Partial<S>`  | `undefined`    | Custom state selector function                         |
-| `exclude`       | `string[]`                  | `[]`           | Dot-notation paths to exclude (e.g., `['auth.token']`) |
-| `version`       | `number`                    | `0`            | Storage version for migrations                         |
-| `skipHydration` | `boolean`                   | `false`        | Skip automatic hydration on init                       |
-| `storage`       | `StateStorage`              | `localStorage` | Custom storage backend                                 |
-| `serializer`    | `Serializer<T>`             | JSON           | Custom serialization logic                             |
-| `merge`         | `(persisted, current) => S` | shallow        | Merge strategy for hydration                           |
-| `migrate`       | `(state, version) => S`     | identity       | Version migration function                             |
+| Option        | Type                        | Default        | Description                                            |
+| ------------- | --------------------------- | -------------- | ------------------------------------------------------ |
+| `rootReducer` | `Reducer<S, AnyAction>`     | **required**   | Root reducer to wrap with hydration handling           |
+| `name`        | `string`                    | **required**   | localStorage key name                                  |
+| `slices`      | `(keyof S)[]`               | `undefined`    | State slices to persist (all if undefined)             |
+| `partialize`  | `(state: S) => Partial<S>`  | `undefined`    | Custom state selector function                         |
+| `exclude`     | `string[]`                  | `[]`           | Dot-notation paths to exclude (e.g., `['auth.token']`) |
+| `version`     | `number`                    | `0`            | Storage version for migrations                         |
+| `storage`     | `StateStorage`              | `localStorage` | Custom storage backend                                 |
+| `serializer`  | `Serializer<T>`             | JSON           | Custom serialization logic                             |
+| `merge`       | `(persisted, current) => S` | shallow        | Merge strategy for hydration                           |
+| `migrate`     | `(state, version) => S`     | identity       | Version migration function                             |
 
 #### Performance Options
 
@@ -141,8 +147,9 @@ Creates the storage middleware and returns both the middleware and a control API
 
 ```typescript
 interface StorageMiddlewareResult<S> {
-  middleware: Middleware<object, S>
-  api: HydrationApi<S>
+  middleware: Middleware<object, S> // Redux middleware
+  reducer: Reducer<S, AnyAction> // Hydration-wrapped reducer (use this in configureStore)
+  api: HydrationApi<S> // Control API
 }
 ```
 
@@ -265,7 +272,8 @@ const serializer = createCompressedSerializer<AppState>({
 ### Version Migrations
 
 ```typescript
-const { middleware } = createStorageMiddleware<AppState>({
+const { middleware, reducer } = createStorageMiddleware<AppState>({
+  rootReducer,
   name: 'my-app',
   slices: ['settings'],
   version: 2,
@@ -290,7 +298,8 @@ const { middleware } = createStorageMiddleware<AppState>({
 ```typescript
 import { shallowMerge, deepMerge } from '@gitbox/redux-storage-middleware'
 
-const { middleware } = createStorageMiddleware<AppState>({
+const { middleware, reducer } = createStorageMiddleware<AppState>({
+  rootReducer,
   name: 'my-app',
   slices: ['emails'],
   merge: deepMerge, // or shallowMerge (default)
@@ -340,7 +349,8 @@ export function StoreProvider({ children }) {
 ### Exclude Paths
 
 ```typescript
-const { middleware } = createStorageMiddleware<AppState>({
+const { middleware, reducer } = createStorageMiddleware<AppState>({
+  rootReducer,
   name: 'my-app',
   exclude: [
     'auth.token', // Skip sensitive data
@@ -353,7 +363,8 @@ const { middleware } = createStorageMiddleware<AppState>({
 ### Partialize Function
 
 ```typescript
-const { middleware } = createStorageMiddleware<AppState>({
+const { middleware, reducer } = createStorageMiddleware<AppState>({
+  rootReducer,
   name: 'my-app',
   partialize: (state) => ({
     // Only persist specific nested data
@@ -488,7 +499,8 @@ A production-grade demo showing 5000+ email persistence:
 **Configuration:**
 
 ```typescript
-const { middleware, api } = createStorageMiddleware<AppState>({
+const { middleware, reducer, api } = createStorageMiddleware<AppState>({
+  rootReducer, // Pass your root reducer
   name: 'gmail-clone-state',
   slices: ['emails'],
   version: 1,
@@ -517,7 +529,8 @@ Full TypeScript support with generic state typing:
 
 ```typescript
 // State type inference
-const { middleware, api } = createStorageMiddleware<RootState>({
+const { middleware, reducer, api } = createStorageMiddleware<RootState>({
+  rootReducer,  // Required: pass your root reducer
   name: 'app',
   slices: ['user', 'settings'],  // Type-checked against RootState keys
 })
@@ -538,13 +551,75 @@ import {
   ACTION_HYDRATE_ERROR,
   type StorageMiddlewareAction,
 } from '@gitbox/redux-storage-middleware'
+```
+
+> **Note:** `withHydration()` is deprecated. The returned `reducer` from `createStorageMiddleware()` is already hydration-wrapped.
+
+---
+
+## Migration Guide
+
+### Upgrading from v0.1.x to v0.2.x
+
+**Breaking Changes:**
 
-// Use in reducers for hydration handling
-import { withHydration } from '@gitbox/redux-storage-middleware'
+1. `rootReducer` is now a required parameter
+2. `skipHydration` option has been removed (hydration is always enabled)
+3. Return type now includes `reducer` which must be used in `configureStore`
 
-const enhancedReducer = withHydration(rootReducer)
+**Before (v0.1.x):**
+
+```typescript
+import {
+  createStorageMiddleware,
+  withHydration,
+} from '@gitbox/redux-storage-middleware'
+
+const rootReducer = combineReducers({
+  settings: settingsReducer,
+  board: boardReducer,
+})
+
+const { middleware } = createStorageMiddleware({
+  name: 'my-app-state',
+  slices: ['settings'],
+  skipHydration: false, // This option no longer exists
+})
+
+const store = configureStore({
+  reducer: withHydration(rootReducer), // Manual wrapper required
+  middleware: (getDefault) => getDefault().concat(middleware),
+})
+```
+
+**After (v0.2.x):**
+
+```typescript
+import { createStorageMiddleware } from '@gitbox/redux-storage-middleware'
+
+const rootReducer = combineReducers({
+  settings: settingsReducer,
+  board: boardReducer,
+})
+
+const { middleware, reducer } = createStorageMiddleware({
+  rootReducer, // Required: pass your root reducer
+  name: 'my-app-state',
+  slices: ['settings'],
+})
+
+const store = configureStore({
+  reducer, // Use returned reducer (already hydration-wrapped)
+  middleware: (getDefault) => getDefault().concat(middleware),
+})
 ```
 
+**Key Benefits of the New API:**
+
+- No more "silent failures" from forgetting to use `withHydration()`
+- Simpler, more intuitive API
+- Automatic hydration on client (no need to configure `skipHydration`)
+
 ---
 
 ## Contributing

packages/redux-storage-middleware/examples/gmail-clone/src/lib/store.ts

@@ -4,7 +4,7 @@
  * Gmail Clone demonstration of localStorage persistence
  */
 
-import { configureStore } from '@reduxjs/toolkit'
+import { combineReducers, configureStore } from '@reduxjs/toolkit'
 import { createStorageMiddleware } from '@gitbox/redux-storage-middleware'
 
 import emailReducer, { type EmailsState } from './features/emails/emailSlice'
@@ -16,36 +16,42 @@ interface AppState {
   emails: EmailsState
 }
 
-// Create storage middleware with performance settings
-const { middleware: storageMiddleware, api: storageApi } =
-  createStorageMiddleware<AppState>({
-    name: 'gmail-clone-state',
-    slices: ['emails'],
-    version: 1,
-    performance: {
-      debounceMs: 300, // Debounce writes for performance
-      useIdleCallback: false, // Disabled for E2E test predictability
-    },
-    skipHydration: false,
-    onHydrationComplete: (state: AppState) => {
-      console.log('[Gmail Clone] Hydrated from localStorage:', {
-        emailCount: state.emails?.emails?.length ?? 0,
-      })
-    },
-    onSaveComplete: (state: AppState) => {
-      console.log('[Gmail Clone] Saved to localStorage:', {
-        emailCount: state.emails?.emails?.length ?? 0,
-      })
-    },
-    onError: (error: Error, operation: string) => {
-      console.error(`[Gmail Clone] Storage ${operation} error:`, error)
-    },
-  })
+// Create root reducer
+const rootReducer = combineReducers({
+  emails: emailReducer,
+})
 
-export const store = configureStore({
-  reducer: {
-    emails: emailReducer,
+// Create storage middleware with new API (rootReducer is now required)
+const {
+  middleware: storageMiddleware,
+  reducer: hydratedReducer,
+  api: storageApi,
+} = createStorageMiddleware<AppState>({
+  rootReducer, // Required: pass root reducer
+  name: 'gmail-clone-state',
+  slices: ['emails'],
+  version: 1,
+  performance: {
+    debounceMs: 300, // Debounce writes for performance
+    useIdleCallback: false, // Disabled for E2E test predictability
+  },
+  onHydrationComplete: (state: AppState) => {
+    console.log('[Gmail Clone] Hydrated from localStorage:', {
+      emailCount: state.emails?.emails?.length ?? 0,
+    })
+  },
+  onSaveComplete: (state: AppState) => {
+    console.log('[Gmail Clone] Saved to localStorage:', {
+      emailCount: state.emails?.emails?.length ?? 0,
+    })
   },
+  onError: (error: Error, operation: string) => {
+    console.error(`[Gmail Clone] Storage ${operation} error:`, error)
+  },
+})
+
+export const store = configureStore({
+  reducer: hydratedReducer, // Use returned reducer (already hydration-wrapped)
   middleware: (getDefaultMiddleware) =>
     getDefaultMiddleware({
       serializableCheck: {

packages/redux-storage-middleware/src/index.ts

@@ -1,29 +1,34 @@
 /**
  * @gitbox/redux-storage-middleware
  *
- * Custom middleware to synchronize Redux state with LocalStorage
- * SSR-safe with version migration and hydration control support
+ * SSR-safe Redux Toolkit middleware for localStorage persistence
+ * Automatic hydration, version migration, and selective slice persistence
  *
  * @example
  * ```ts
- * import { createStorageMiddleware, withHydration } from '@gitbox/redux-storage-middleware'
+ * import { createStorageMiddleware } from '@gitbox/redux-storage-middleware'
+ * import { combineReducers, configureStore } from '@reduxjs/toolkit'
  *
- * const { middleware, api } = createStorageMiddleware({
+ * const rootReducer = combineReducers({
+ *   settings: settingsReducer,
+ *   board: boardReducer,
+ * })
+ *
+ * const { middleware, reducer, api } = createStorageMiddleware({
+ *   rootReducer,  // Required: pass your root reducer
  *   name: 'my-app-state',
- *   slices: ['settings', 'preferences'],
+ *   slices: ['settings'],
  *   version: 1,
  * })
  *
  * const store = configureStore({
- *   reducer: withHydration(rootReducer),
+ *   reducer,  // Use the returned reducer (already hydration-wrapped)
  *   middleware: (getDefaultMiddleware) =>
  *     getDefaultMiddleware().concat(middleware),
  * })
  *
- * // Check hydration status
- * if (api.hasHydrated()) {
- *   console.log('State restored from localStorage')
- * }
+ * // Hydration happens automatically on client
+ * // Check status with api.hasHydrated()
  * ```
  */