Hydration

/**
 * Sets up providers necessary to enable hydration functionality for the application.
 * By default, the function will set up the hydration functionality with no additional features.
 * You can enable additional features by passing them as function arguments.
 * @param features - Optional hydration features to enable
 * @returns Environment providers for hydration support
 */
function provideClientHydration(
  ...features: HydrationFeature<HydrationFeatureKind>[]
): EnvironmentProviders;

import { bootstrapApplication } from "@angular/platform-browser";
import { 
  provideClientHydration,
  withHttpTransferCacheOptions,
  withEventReplay,
  withI18nSupport
} from "@angular/platform-browser";

// Basic hydration
await bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration()
  ]
});

// Hydration with features
await bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        includePostRequests: true
      }),
      withEventReplay(),
      withI18nSupport()
    )
  ]
});

/**
 * Disables HTTP transfer cache for hydration.
 * Use when you need to disable the transfer cache completely.
 * @returns Hydration feature for disabling HTTP transfer cache
 */
function withNoHttpTransferCache(): HydrationFeature<HydrationFeatureKind.NoHttpTransferCache>;

/**
 * Configures HTTP transfer cache options for hydration.
 * @param options - Configuration options for HTTP transfer cache
 * @returns Hydration feature with HTTP transfer cache options
 */
function withHttpTransferCacheOptions(
  options: HttpTransferCacheOptions
): HydrationFeature<HydrationFeatureKind.HttpTransferCacheOptions>;

import { 
  provideClientHydration,
  withHttpTransferCacheOptions,
  withNoHttpTransferCache 
} from "@angular/platform-browser";

// Disable HTTP transfer cache
await bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(
      withNoHttpTransferCache()
    )
  ]
});

// Configure HTTP transfer cache
await bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        includePostRequests: true,
        filter: (req) => !req.url.includes('/api/dynamic')
      })
    )
  ]
});

/**
 * Enables support for hydrating i18n blocks.
 * Use when your application uses Angular i18n features.
 * @returns Hydration feature for i18n support
 */
function withI18nSupport(): HydrationFeature<HydrationFeatureKind.I18nSupport>;

import { provideClientHydration, withI18nSupport } from "@angular/platform-browser";

// Enable i18n hydration support
await bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(
      withI18nSupport()
    )
  ]
});

/**
 * Enables event replay functionality for hydration.
 * Captures user events that occur before hydration is complete and replays them afterward.
 * @returns Hydration feature for event replay
 */
function withEventReplay(): HydrationFeature<HydrationFeatureKind.EventReplay>;

import { provideClientHydration, withEventReplay } from "@angular/platform-browser";

// Enable event replay
await bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(
      withEventReplay()
    )
  ]
});

/**
 * Enables incremental hydration functionality.
 * Allows components to be hydrated progressively as they become visible or needed.
 * @returns Hydration feature for incremental hydration
 */
function withIncrementalHydration(): HydrationFeature<HydrationFeatureKind.IncrementalHydration>;

import { provideClientHydration, withIncrementalHydration } from "@angular/platform-browser";

// Enable incremental hydration
await bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(
      withIncrementalHydration()
    )
  ]
});

import { 
  bootstrapApplication,
  provideClientHydration,
  withHttpTransferCacheOptions,
  withEventReplay,
  withI18nSupport,
  withIncrementalHydration
} from "@angular/platform-browser";

// Full-featured hydration setup
await bootstrapApplication(AppComponent, {
  providers: [
    // Other providers
    provideRouter(routes),
    provideHttpClient(),
    
    // Comprehensive hydration setup
    provideClientHydration(
      withHttpTransferCacheOptions({
        includePostRequests: true,
        includeRequestsWithAuthHeaders: false,
        filter: (req) => {
          // Only cache GET requests to API endpoints
          return req.method === 'GET' && req.url.startsWith('/api/');
        }
      }),
      withEventReplay(),
      withI18nSupport(),
      withIncrementalHydration()
    )
  ]
});

/**
 * The list of features as an enum to uniquely type each HydrationFeature.
 */
enum HydrationFeatureKind {
  NoHttpTransferCache,
  HttpTransferCacheOptions,
  I18nSupport,
  EventReplay,
  IncrementalHydration
}

/**
 * Helper type to represent a Hydration feature.
 */
interface HydrationFeature<FeatureKind extends HydrationFeatureKind> {
  ɵkind: FeatureKind;
  ɵproviders: Provider[];
}

// ✅ DO: Use hydration with SSR/SSG applications
import { provideClientHydration } from "@angular/platform-browser";

@NgModule({
  providers: [
    provideClientHydration()
  ]
})
export class AppModule {}

// ✅ DO: Configure features based on your needs
const hydrationConfig = [
  // Use HTTP transfer cache for API calls
  withHttpTransferCacheOptions({ includePostRequests: false }),
  
  // Enable event replay for better UX
  withEventReplay(),
  
  // Add i18n support if using internationalization
  withI18nSupport()
];

// ✅ DO: Test hydration in production-like environment
// Hydration behavior can differ between dev and prod builds

// ❌ DON'T: Use hydration without SSR/SSG
// Hydration is only needed for server-rendered applications

// ❌ DON'T: Enable features you don't need
// Each feature adds overhead, only enable what you use

// Enable hydration debugging in development
if (!environment.production) {
  // Add to your main.ts or app.config.ts
  providers.push(
    {
      provide: 'HYDRATION_DEBUG',
      useValue: true
    }
  );
}

// Common hydration issues to watch for:
// 1. Mismatched DOM structure between server and client
// 2. Different data on server vs client render
// 3. Browser-only APIs used during SSR
// 4. Race conditions with HTTP requests

// Before: Traditional module bootstrap
platformBrowserDynamic()
  .bootstrapModule(AppModule)
  .catch(err => console.error(err));

// After: Standalone bootstrap with hydration
bootstrapApplication(AppComponent, {
  providers: [
    // Migrate your module providers here
    importProvidersFrom(AppModule),
    
    // Add hydration
    provideClientHydration(
      withHttpTransferCacheOptions({ includePostRequests: true }),
      withEventReplay()
    )
  ]
});