@solidexpert/ngx-rehydrate

NgRx state rehydration library for Angular Universal SSR applications.

When an Angular app renders on the server, it initializes NgRx state with the latest data. Without rehydration, the browser would bootstrap with an empty store, replaying the same HTTP calls and briefly showing inconsistent UI. Rehydrating transfers the server state into the browser so the client starts fully populated—no duplicate API requests, no flicker, just a seamless transition.

Features

• 🚀 Seamless state transfer between server and browser
• 🔄 Configurable merge strategies for state rehydration
• 📦 Selective state slice rehydration
• 🛠️ Easy to integrate with existing NgRx applications
• 🎯 Full TypeScript support
• ⚡ Modern standalone API (no modules required)
• 🔧 Backward compatible with NgModule-based apps

Angular Compatibility

| Library version | Angular version | | --------------- | ---------------- | | 20.x.x | 20 | | 19.x.x | 19 |

Installation

npm install @solidexpert/ngx-rehydrate

Usage (Modern Standalone API)

Browser Configuration

In your app.config.ts:

import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideStore } from '@ngrx/store';
import { 
  provideRehydrateBrowser, 
  MergeStrategy 
} from '@solidexpert/ngx-rehydrate';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideStore(/* your reducers */),
    // Add rehydration
    provideRehydrateBrowser({
      stores: ['auth', 'user', 'settings'],
      mergeStrategy: MergeStrategy.OVERWRITE,
      disableWarnings: false,
    }),
  ],
};

Server Configuration

In your app.config.server.ts:

import { ApplicationConfig } from '@angular/core';
import { provideServerRendering } from '@angular/platform-server';
import { provideRehydrateServer } from '@solidexpert/ngx-rehydrate';
import { appConfig } from './app.config';

export const serverConfig: ApplicationConfig = {
  providers: [
    ...appConfig.providers,
    provideServerRendering(),
    provideRehydrateServer(),
  ],
};

Feature-Level Rehydration

For lazy-loaded routes or features:

import { Routes } from '@angular/router';
import { provideRehydrateFeature } from '@solidexpert/ngx-rehydrate';

export const routes: Routes = [
  {
    path: 'admin',
    providers: [
      provideRehydrateFeature(['adminUsers', 'adminSettings'])
    ],
    loadChildren: () => import('./admin/routes'),
  },
];

Preventing Duplicate HTTP Requests

Use the withTransferState operator to prevent duplicate HTTP requests during SSR hydration:

import { inject, Injectable, PLATFORM_ID } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { TransferState } from '@angular/core';
import { withTransferState } from '@solidexpert/ngx-rehydrate';

@Injectable({ providedIn: 'root' })
export class UserService {
  private http = inject(HttpClient);
  private platformId = inject(PLATFORM_ID);
  private transferState = inject(TransferState);

  getUsers() {
    return this.http.get('/api/users').pipe(
      withTransferState('api-users', this.platformId, this.transferState)
    );
  }

  getUserById(id: string) {
    return this.http.get(`/api/users/${id}`).pipe(
      withTransferState(`api-user-${id}`, this.platformId, this.transferState)
    );
  }
}

How it works:

• Server: HTTP request is made and marked in TransferState
• Browser (initial load): Request is skipped if already made on server
• Browser (subsequent): Request proceeds normally

Benefits:

• ⚡ Reduces unnecessary API calls
• 🚀 Improves initial page load performance
• 💾 Saves bandwidth and server resources
• 🎯 Works seamlessly with NgRx Effects

Advanced Usage with Helper Function

Create a base service with a helper method for cleaner code:

@Injectable({ providedIn: 'root' })
export class BaseApiService {
  protected http = inject(HttpClient);
  private platformId = inject(PLATFORM_ID);
  private transferState = inject(TransferState);

  // Helper method for transfer state
  protected withTransfer<T>(key: string) {
    return withTransferState<T>(key, this.platformId, this.transferState);
  }
}

@Injectable({ providedIn: 'root' })
export class UserService extends BaseApiService {
  getUsers() {
    return this.http.get<User[]>('/api/users').pipe(
      this.withTransfer('api-users')
    );
  }

  getPosts() {
    return this.http.get<Post[]>('/api/posts').pipe(
      this.withTransfer('api-posts')
    );
  }
}

Usage with NgRx Effects

import { inject, Injectable, PLATFORM_ID } from '@angular/core';
import { Actions, createEffect, ofType } from '@ngrx/effects';
import { TransferState } from '@angular/core';
import { withTransferState } from '@solidexpert/ngx-rehydrate';
import { switchMap, map, catchError } from 'rxjs/operators';
import { of } from 'rxjs';

@Injectable()
export class UserEffects {
  private actions$ = inject(Actions);
  private userService = inject(UserService);
  private platformId = inject(PLATFORM_ID);
  private transferState = inject(TransferState);

  loadUsers$ = createEffect(() =>
    this.actions$.pipe(
      ofType(UserActions.loadUsers),
      switchMap(() =>
        this.userService.getUsers().pipe(
          withTransferState('users-list', this.platformId, this.transferState),
          map(users => UserActions.loadUsersSuccess({ users })),
          catchError(error => of(UserActions.loadUsersFailure({ error })))
        )
      )
    )
  );

  loadUserById$ = createEffect(() =>
    this.actions$.pipe(
      ofType(UserActions.loadUser),
      switchMap(({ id }) =>
        this.userService.getUserById(id).pipe(
          withTransferState(`user-${id}`, this.platformId, this.transferState),
          map(user => UserActions.loadUserSuccess({ user })),
          catchError(error => of(UserActions.loadUserFailure({ error })))
        )
      )
    )
  );
}

Configuration Options

interface RehydrationRootConfig {
  // Array of store slice names to rehydrate
  stores: string[] | undefined;
  
  // Disable console warnings
  disableWarnings: boolean;
  
  // Strategy for merging server and client state
  mergeStrategy: MergeStrategy;
}

Merge Strategies

• MergeStrategy.OVERWRITE: Replace browser state with server state (recommended for most cases)
• MergeStrategy.MERGE_OVER: Merge server state over browser state (server wins on conflicts)
• MergeStrategy.MERGE_UNDER: Merge browser state over server state (browser wins on conflicts)

Legacy NgModule-based API (Deprecated)

Browser Module (Deprecated)

import { NgrxUniversalRehydrateBrowserModule } from '@solidexpert/ngx-rehydrate';

@NgModule({
  imports: [
    NgrxUniversalRehydrateBrowserModule.forRoot({
      stores: ['auth', 'user'],
      mergeStrategy: MergeStrategy.OVERWRITE,
    }),
  ],
})
export class AppModule {}

Server Module (Deprecated)

import { NgrxUniversalRehydrateServerModule } from '@solidexpert/ngx-rehydrate';

@NgModule({
  imports: [
    NgrxUniversalRehydrateServerModule.forServer(),
  ],
})
export class AppServerModule {}

Note: The NgModule-based API is deprecated. Please migrate to the standalone provider functions for better tree-shaking and simpler configuration.

API Reference

provideRehydrateBrowser(config?)

Provides rehydration for browser/client-side rendering.

Parameters:

• config (optional): Partial configuration object

Returns: EnvironmentProviders

provideRehydrateServer()

Provides rehydration for server-side rendering.

Returns: EnvironmentProviders

provideRehydrateFeature(stores)

Provides additional store slices for feature modules or lazy-loaded routes.

Parameters:

• stores: Array of store slice names

Returns: EnvironmentProviders

withTransferState<T>(key, platformId, transferState)

RxJS operator that prevents duplicate HTTP requests during SSR hydration.

Parameters:

• key: Unique identifier for the request
• platformId: Angular PLATFORM_ID injection token
• transferState: Angular TransferState service

Returns: OperatorFunction<T, T>

Development

See CONTRIBUTING.md for development guidelines.

To build the library locally:

# Install dependencies
npm install

# Build the library
npm run build

# Create package for testing
npm run pack

Publishing

This library is automatically published to npm via GitHub Actions. See Publishing Guide for details.

Changelog

See GitHub Releases for version history.

Support

• 📝 Documentation
• 🐛 Report Issues
• 💬 Discussions

License

MIT

Copyright (c) 2025 Solidexpert LTD