NgRx state schema compatibility during re-hydration rollbacks

Implementing Version-Aware Re-hydration

The most effective strategy for handling schema evolution in NgRx is a version-aware meta-reducer that intercepts the re-hydrated state before it reaches the store. To prevent runtime errors during version rollbacks (where the persisted state is newer than the application code), the meta-reducer must implement a strict version check and a purge mechanism.

The Meta-Reducer Strategy

The meta-reducer should act as a gatekeeper during the INIT action or the re-hydration phase. The logic follows these priorities:

1. Version Comparison: Compare the version key in the persisted state against the current application's SCHEMA_VERSION constant.
2. Rollback Handling: If persistedVersion > currentVersion, the state is incompatible. The only safe operation is to purge the persisted state and return the initial state to avoid unpredictable crashes.
3. Forward Migration: If persistedVersion < currentVersion, pass the state through a chain of migration functions (e.g., v1ToV2(), v2ToV3()) until it matches the current schema.
4. Performance: Perform these transformations synchronously during the bootstrap phase. This ensures that the rest of the application interacts with a consistent schema, avoiding the overhead of checking versions inside every selector.

Defensive Selector Design

Since TypeScript interfaces are erased at runtime, they cannot protect against missing fields in localStorage. Selectors must be designed to handle undefined or null values gracefully to prevent UI breakage.

• Optional Chaining: Use optional chaining (?.) when accessing deeply nested properties in the state.
• Nullish Coalescing: Provide sensible defaults using the ?? operator to ensure the component receives a valid type (e.g., an empty array instead of undefined).
• Memoized Defaults: Create a base selector that ensures a minimum viable state shape before passing it to derived selectors.

Practical Implementation Example

// Example of a defensive selector pattern
export const selectUserPreferences = createSelector(
  selectAuthState,
  (state) => ({
    theme: state?.preferences?.theme ?? 'light',
    notificationsEnabled: state?.preferences?.notificationsEnabled ?? true
  })
);

Assumptions and Constraints

This approach assumes that the state is persisted as a JSON object containing a top-level version property. It also assumes that a total state purge is an acceptable trade-off during a version rollback to maintain application stability. If your application uses the @ngrx/entity adapter, migrations must explicitly re-map the ids and entities collections if the idField has changed.

Diagnostic Detail Needed: Are you using a third-party persistence library (like ngrx-store-localstorage) or a custom implementation? This determines whether the version check happens inside a meta-reducer or within the persistence library's configuration.