refactor: remove hmr compatibility alias and streamline live-reload configuration across Angular and Storybook integrations

Author: benpsnyder

apps/docs-app/docs/guides/migrating-v2-to-v3.md

@@ -158,4 +158,4 @@ Keep automated migration tooling focused on the breaking changes above:
 - rewrite only the legacy `@analogjs/vite-plugin-angular/setup-vitest` setup import
 - flag `@analogjs/trpc` as a removed package that needs a manual migration plan
 - flag `experimental.useAnalogCompiler`, `analogCompilationMode`, and `@analogjs/angular-compiler` as unsupported on the current v3 alpha line rather than removed outright
-- treat optional helpers such as `withTypedRouter`, `withRouteContext`, `withLoaderCaching`, `withDebugRoutes`, and compatibility aliases such as `hmr` as opt-in rather than mandatory rewrites
+- treat optional helpers such as `withTypedRouter`, `withRouteContext`, `withLoaderCaching`, `withDebugRoutes`, and `liveReload` as opt-in rather than mandatory rewrites

apps/docs-app/docs/guides/migrating.md

@@ -192,9 +192,9 @@ export default defineConfig(({ mode }) => ({
 
 Angular supports HMR where in most cases components can be updated without a full page reload. In Analog, use `liveReload` to control the Angular live-reload pipeline.
 
-This is separate from Vite's `server.hmr` option, which configures the HMR websocket transport. You can use `server.hmr` together with `liveReload` when you need custom host, port, or path settings. `hmr` is still accepted as a compatibility alias for `liveReload`.
+This is separate from Vite's `server.hmr` option, which configures the HMR websocket transport. You can use `server.hmr` together with `liveReload` when you need custom host, port, or path settings.
 
-Analog requires Angular v19 or newer for `liveReload` / `hmr` to work. On Angular v17-v18, `liveReload` and its `hmr` alias are forcibly disabled at runtime with a console warning, so HMR is unavailable on those versions.
+Analog requires Angular v19 or newer for `liveReload` to work. On Angular v17-v18, `liveReload` is forcibly disabled at runtime with a console warning, so HMR is unavailable on those versions.
 
 ```ts
 /// <reference types="vitest" />

apps/docs-app/docs/integrations/storybook/index.md

@@ -93,7 +93,7 @@ export default config;
 
 For current Analog projects, use `framework.options.liveReload` to control Analog's Angular live-reload behavior.
 
-This is separate from Vite's `server.hmr` option, which configures the HMR websocket transport. You can use `server.hmr` together with `framework.options.liveReload` when Storybook needs custom host, port, or path settings. `framework.options.hmr` is still accepted as a compatibility alias.
+This is separate from Vite's `server.hmr` option, which configures the HMR websocket transport. You can use `server.hmr` together with `framework.options.liveReload` when Storybook needs custom host, port, or path settings.
 
 Remove the existing `webpackFinal` config function if present.
 

apps/docs-app/docs/integrations/tailwind/index.md

@@ -124,9 +124,9 @@ Without `prefixes`, Analog falls back to its default Tailwind usage detection fo
 
 Use `liveReload` when you need to configure Analog's Angular live-reload behavior explicitly.
 
-Vite's `server.hmr` option is separate. It controls the HMR websocket transport, so you can use `server.hmr` together with `liveReload` when your dev server needs custom host, port, or path settings. `hmr` is still accepted as a compatibility alias for `liveReload`.
+Vite's `server.hmr` option is separate. It controls the HMR websocket transport, so you can use `server.hmr` together with `liveReload` when your dev server needs custom host, port, or path settings.
 
-Angular HMR requires Angular v19 or newer. On Angular v17-v18, `liveReload` and its `hmr` alias are intentionally disabled at runtime and emit a console warning, so HMR is unavailable on those versions. For broader migration guidance, see the [migration guide](/docs/guides/migrating).
+Angular HMR requires Angular v19 or newer. On Angular v17-v18, `liveReload` is intentionally disabled at runtime and emits a console warning, so HMR is unavailable on those versions. For broader migration guidance, see the [migration guide](/docs/guides/migrating).
 
 Tailwind support does not require you to enable HMR manually. The stylesheet pipeline is handled independently from whether Angular can produce a hot component update for a given edit.
 

packages/platform/src/lib/options.ts

@@ -98,7 +98,7 @@ export interface Options {
    *
    * When `false`, the following top-level options are ignored because they
    * are only forwarded to the internal Angular plugin: `jit`,
-   * `disableTypeChecking`, `liveReload`, `hmr`, `inlineStylesExtension`,
+   * `disableTypeChecking`, `liveReload`, `inlineStylesExtension`,
    * `fileReplacements`, and `include`.
    *
    * Use this to configure the embedded Angular integration itself, not as the
@@ -124,10 +124,6 @@ export interface Options {
    * Defaults to `true` for watch mode.
    */
   liveReload?: boolean;
-  /**
-   * Compatibility alias for `liveReload`.
-   */
-  hmr?: boolean;
   /**
    * Enable debug logging for specific scopes.
    *

packages/platform/src/lib/platform-plugin.ts

@@ -30,6 +30,11 @@ export function platformPlugin(opts: Options = {}): Plugin[] {
 
   const isTest = process.env['NODE_ENV'] === 'test' || !!process.env['VITEST'];
   const viteOptions = opts?.vite === false ? undefined : opts?.vite;
+  const {
+    experimental: viteExperimental,
+    hmr: _removedViteHmrOption,
+    ...forwardedViteOptions
+  } = viteOptions ?? {};
   const { ...platformOptions } = {
     ssr: true,
     ...opts,
@@ -56,7 +61,7 @@ export function platformPlugin(opts: Options = {}): Plugin[] {
 
   const useAngularCompilationAPI =
     platformOptions.experimental?.useAngularCompilationAPI ??
-    viteOptions?.experimental?.useAngularCompilationAPI;
+    viteExperimental?.useAngularCompilationAPI;
   debugPlatform('experimental options resolved', {
     useAngularCompilationAPI: !!useAngularCompilationAPI,
     typedRouter: platformOptions.experimental?.typedRouter,
@@ -112,7 +117,6 @@ export function platformPlugin(opts: Options = {}): Plugin[] {
               ),
             ],
             additionalContentDirs: platformOptions.additionalContentDirs,
-            hmr: platformOptions.hmr,
             liveReload: platformOptions.liveReload,
             inlineStylesExtension: platformOptions.inlineStylesExtension,
             fileReplacements: platformOptions.fileReplacements,
@@ -124,9 +128,9 @@ export function platformPlugin(opts: Options = {}): Plugin[] {
                     platformOptions.experimental.stylePipeline.angularPlugins,
                 }
               : undefined,
-            ...(viteOptions ?? {}),
+            ...forwardedViteOptions,
             experimental: {
-              ...(viteOptions?.experimental ?? {}),
+              ...(viteExperimental ?? {}),
               useAngularCompilationAPI,
             },
           }),

packages/storybook-angular/README.md

@@ -125,7 +125,7 @@ Storybook does not automatically infer the Tailwind plugin from your app's `vite
 
 Angular reload behavior is controlled with `framework.options.liveReload`.
 
-This is separate from Vite's `server.hmr` option, which configures the HMR websocket transport. You can use `server.hmr` together with `framework.options.liveReload` when Storybook needs custom host, port, or path settings. `framework.options.hmr` is still accepted as a compatibility alias.
+This is separate from Vite's `server.hmr` option, which configures the HMR websocket transport. You can use `server.hmr` together with `framework.options.liveReload` when Storybook needs custom host, port, or path settings.
 
 ## Enabling Zoneless Change Detection
 

packages/storybook-angular/src/lib/preset.spec.ts

@@ -132,30 +132,24 @@ describe('viteFinal', () => {
   };
 
   describe('Angular plugin options', () => {
-    it('prefers liveReload over hmr and keeps hmr as compatibility input', async () => {
-      const options = makeOptions({ liveReload: false, hmr: true });
+    it('forwards liveReload without a duplicate hmr flag', async () => {
+      const options = makeOptions({ liveReload: false });
 
       await viteFinal(baseConfig, options);
 
-      expect(angularPluginMock).toHaveBeenCalledWith(
-        expect.objectContaining({
-          liveReload: false,
-          hmr: false,
-        }),
-      );
+      const [angularOptions] = angularPluginMock.mock.calls[0];
+      expect(angularOptions.liveReload).toBe(false);
+      expect(angularOptions).not.toHaveProperty('hmr');
     });
 
-    it('falls back to hmr when liveReload is omitted', async () => {
-      const options = makeOptions({ hmr: true });
+    it('defaults liveReload to false when omitted', async () => {
+      const options = makeOptions();
 
       await viteFinal(baseConfig, options);
 
-      expect(angularPluginMock).toHaveBeenCalledWith(
-        expect.objectContaining({
-          liveReload: true,
-          hmr: true,
-        }),
-      );
+      const [angularOptions] = angularPluginMock.mock.calls[0];
+      expect(angularOptions.liveReload).toBe(false);
+      expect(angularOptions).not.toHaveProperty('hmr');
     });
   });
 

packages/storybook-angular/src/lib/preset.ts

@@ -75,16 +75,16 @@ export const viteFinal = async (config: any, options: any): Promise<any> => {
 
   // @ts-expect-error - untyped storybook presets API
   const framework = await options.presets.apply('framework');
+  const { hmr: _removedHmrOption, ...frameworkOptions } =
+    framework.options ?? {};
   const experimentalZoneless = await resolveExperimentalZoneless(
-    framework.options,
+    frameworkOptions,
     options?.angularBuilderOptions,
   );
   const liveReload =
-    typeof framework.options?.liveReload !== 'undefined'
-      ? framework.options?.liveReload
-      : typeof framework.options?.hmr !== 'undefined'
-        ? framework.options?.hmr
-        : false;
+    typeof frameworkOptions.liveReload !== 'undefined'
+      ? frameworkOptions.liveReload
+      : false;
   return vite.mergeConfig(config, {
     // Add dependencies to pre-optimization
     optimizeDeps: {
@@ -106,18 +106,17 @@ export const viteFinal = async (config: any, options: any): Promise<any> => {
     plugins: [
       angular({
         jit:
-          typeof framework.options?.jit !== 'undefined'
-            ? framework.options?.jit
+          typeof frameworkOptions.jit !== 'undefined'
+            ? frameworkOptions.jit
             : true,
         liveReload,
-        hmr: liveReload,
         tsconfig:
-          typeof framework.options?.tsconfig !== 'undefined'
-            ? framework.options?.tsconfig
+          typeof frameworkOptions.tsconfig !== 'undefined'
+            ? frameworkOptions.tsconfig
             : (options?.tsConfig ?? './.storybook/tsconfig.json'),
         inlineStylesExtension:
-          typeof framework.options?.inlineStylesExtension !== 'undefined'
-            ? framework.options?.inlineStylesExtension
+          typeof frameworkOptions.inlineStylesExtension !== 'undefined'
+            ? frameworkOptions.inlineStylesExtension
             : 'css',
       }),
       angularOptionsPlugin(options, {

packages/storybook-angular/src/types.ts

@@ -17,10 +17,6 @@ export type FrameworkOptions = {
    * HMR client transport.
    */
   liveReload?: boolean;
-  /**
-   * Compatibility alias for `liveReload`.
-   */
-  hmr?: boolean;
   inlineStylesExtension?: string;
   tsconfig?: string;
   experimentalZoneless?: boolean;