refactor: update Angular live-reload configuration and Tailwind integration

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 `liveReload` as opt-in rather than mandatory rewrites
+- treat optional helpers such as `withTypedRouter`, `withRouteContext`, `withLoaderCaching`, `withDebugRoutes`, and compatibility aliases such as `hmr` as opt-in rather than mandatory rewrites

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

@@ -190,8 +190,11 @@ export default defineConfig(({ mode }) => ({
 
 ## Enabling HMR
 
-Angular supports HMR where in most cases components can be updated without a full page reload. In Analog, prefer the `hmr` option. `liveReload` is still accepted as a compatibility alias, but `hmr` is the primary API.
-Analog requires Angular v19 or newer for `hmr` / `liveReload` to work. On Angular v17-v18, `hmr` and its `liveReload` alias are forcibly disabled at runtime with a console warning, so HMR is unavailable on those versions.
+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`.
+
+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.
 
 ```ts
 /// <reference types="vitest" />
@@ -204,7 +207,7 @@ export default defineConfig(({ mode }) => ({
   // .. other configuration
   plugins: [
     analog({
-      hmr: true,
+      liveReload: true,
     }),
   ],
 }));
@@ -223,7 +226,7 @@ import tailwindcss from '@tailwindcss/vite';
 export default defineConfig(() => ({
   plugins: [
     analog({
-      hmr: true,
+      liveReload: true,
       vite: {
         tailwindCss: {
           rootStylesheet: resolve(import.meta.dirname, 'src/styles.css'),

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

@@ -91,7 +91,9 @@ const config: StorybookConfig = {
 export default config;
 ```
 
-For current Analog projects, prefer `framework.options.hmr` if you need to configure Angular HMR. `liveReload` is still accepted as a compatibility alias, but `hmr` is the recommended option.
+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.
 
 Remove the existing `webpackFinal` config function if present.
 
@@ -148,7 +150,7 @@ If your project uses Tailwind v4, keep Storybook aligned with the same opinionat
 - one root stylesheet such as `src/styles.css`
 - `@import 'tailwindcss';` in that stylesheet
 - `framework.options.tailwindCss.rootStylesheet` pointing at that stylesheet
-- `framework.options.hmr` for Angular HMR behavior
+- `framework.options.liveReload` for Angular reload behavior
 
 ```ts
 import { resolve } from 'node:path';
@@ -158,7 +160,7 @@ const config: StorybookConfig = {
   framework: {
     name: '@analogjs/storybook-angular',
     options: {
-      hmr: true,
+      liveReload: true,
       tailwindCss: {
         rootStylesheet: resolve(__dirname, '../src/styles.css'),
       },

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

@@ -1,27 +1,29 @@
 # Tailwind CSS v4
 
-Analog supports Tailwind CSS v4 for both:
+Analog does not replace Tailwind's installation guides. Start with one Tailwind setup that matches your project:
 
-- utility classes in templates
-- `@apply` inside Angular component styles
+- [Install Tailwind with Vite](https://tailwindcss.com/docs/installation/using-vite)
+- [Install Tailwind with PostCSS](https://tailwindcss.com/docs/installation/using-postcss)
+- [Install Tailwind with Angular](https://tailwindcss.com/docs/installation/framework-guides/angular)
 
-The supported v3 `alpha` setup is:
+Once Tailwind is installed, Analog adds the Angular-specific part: component stylesheet handling for `@apply` and Tailwind-aware `@reference` injection.
 
-1. keep one root stylesheet such as `src/styles.css`
-2. put `@import 'tailwindcss';` in that stylesheet
-3. enable `@tailwindcss/vite` in `vite.config.ts`
-4. keep a `postcss.config.mjs` with `@tailwindcss/postcss`
-5. configure Analog with `tailwindCss.rootStylesheet`
+## What Analog adds
 
-Generated apps already follow this shape.
+Use Analog's `tailwindCss.rootStylesheet` option when you want Tailwind utilities inside Angular component styles.
 
-## Install
+That option lets Analog:
 
-```sh
-npm install -D tailwindcss @tailwindcss/vite @tailwindcss/postcss postcss
-```
+- detect component stylesheets that use Tailwind utilities
+- inject the correct `@reference` to your root stylesheet
+- keep component styles aligned with your root Tailwind theme, prefixes, and plugins
+- avoid manual `@reference` directives in every component stylesheet
+
+If you only use Tailwind utilities in templates and a global stylesheet, you can follow Tailwind's install docs and keep your generated scaffold defaults without adding extra Analog configuration.
 
-## Vite Config
+## Component Styles Setup
+
+When you enable `tailwindCss.rootStylesheet`, keep Tailwind wired through Vite for the component stylesheet path:
 
 ```ts
 /// <reference types="vitest" />
@@ -45,9 +47,7 @@ export default defineConfig(() => ({
 }));
 ```
 
-Use an absolute `rootStylesheet` path. Analog may serve component styles through virtual stylesheet ids during dev, so relative `@reference` paths are not reliable there.
-
-If you are using `@analogjs/vite-plugin-angular` directly instead of `@analogjs/platform`, the same Tailwind option lives on the Angular plugin itself:
+If you are using `@analogjs/vite-plugin-angular` directly instead of `@analogjs/platform`, the same option lives on the Angular plugin:
 
 ```ts
 import { resolve } from 'node:path';
@@ -67,6 +67,8 @@ export default defineConfig(() => ({
 }));
 ```
 
+List `analog()` before `tailwindcss()` in your Vite config. Current generators now scaffold that order.
+
 ## Root Stylesheet
 
 In `src/styles.css`:
@@ -87,19 +89,7 @@ You can keep your theme, `@source`, plugins, and prefixes there as well:
 }
 ```
 
-## PostCSS Config
-
-Create `postcss.config.mjs`:
-
-```js
-export default {
-  plugins: {
-    '@tailwindcss/postcss': {},
-  },
-};
-```
-
-Keep this even if dev already works with `@tailwindcss/vite`. Current Analog builds still rely on the PostCSS path for production CSS processing.
+Use an absolute `rootStylesheet` path. Analog may serve component styles through virtual stylesheet ids during dev, so relative `@reference` paths are not reliable there.
 
 ## How Component Styles Work
 
@@ -108,30 +98,11 @@ Angular compiles component styles in isolation. When a component stylesheet cont
 Analog handles that by:
 
 - detecting Tailwind usage in component CSS
-- injecting the correct `@reference` to the configured root stylesheet
-- externalizing component styles during dev when needed so they flow through Vite's CSS pipeline
-- preserving the build path through PostCSS for production
+- injecting `@reference` to the configured root stylesheet
+- routing those component styles through the Vite CSS pipeline when needed
 
 That means you should not manually add `@reference` to every component stylesheet in the normal setup.
 
-## Plugin Order
-
-List `analog()` before `tailwindcss()` in your Vite config. That is now how the generators scaffold it.
-
-```ts
-plugins: [analog({ vite: { tailwindCss: { ... } } }), tailwindcss()];
-```
-
-This keeps the config aligned with the generated apps and the current documentation.
-
-## HMR
-
-Prefer `hmr` over `liveReload` when you need to configure Angular HMR explicitly. `liveReload` remains a compatibility alias.
-
-Angular HMR requires Angular v19 or newer. On Angular v16-v18, `hmr` and `liveReload` are intentionally disabled at runtime and emit a console warning, so HMR is unavailable on those versions. For the broader migration guidance, see [Enabling HMR](/docs/guides/migrating#enabling-hmr).
-
-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.
-
 ## Prefixes
 
 If your component styles use custom-prefixed utilities, configure `prefixes` so Analog knows which stylesheets need Tailwind `@reference` injection:
@@ -149,15 +120,25 @@ analog({
 
 Without `prefixes`, Analog falls back to its default Tailwind usage detection for component styles.
 
+## HMR
+
+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`.
+
+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).
+
+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.
+
 ## Generated Apps
 
-Current `create-analog` and Nx app scaffolds both generate:
+Current `create-analog` and Nx app scaffolds already:
 
-- `@import 'tailwindcss';` in `src/styles.css`
-- `@tailwindcss/vite` in `vite.config.ts`
-- `postcss.config.mjs` with `@tailwindcss/postcss`
+- import Tailwind in `src/styles.css`
+- register Tailwind in `vite.config.ts`
+- keep the generated Vite plugin order aligned with the current Analog templates
 
-If you start from a generated app, keep that structure unless you have a specific reason to diverge from the supported path.
+Some templates may also include additional Tailwind tooling config files. Treat the generated scaffold as your project default, and only diverge after validating your own dev and build behavior.
 
 ## Related
 

apps/docs-app/docs/packages/create-analog/overview.md

@@ -47,15 +47,11 @@ pnpm create analog
 
 ### Tailwind v4
 
-`create-analog` scaffolds Tailwind v4 with the current supported Analog setup. Generated projects include:
+`create-analog` scaffolds Tailwind v4 for the current Analog templates. Generated projects import Tailwind in `src/styles.css` and wire the Tailwind-related Vite config the template expects.
 
-- one root stylesheet, usually `src/styles.css`, with `@import 'tailwindcss';`
-- `@tailwindcss/vite` in `vite.config.ts`
-- `postcss.config.mjs` with `@tailwindcss/postcss`
+If you only need Tailwind utilities in templates and global styles, keep the scaffold defaults.
 
-Analog then handles component-level `@reference` injection through its Tailwind-aware stylesheet pipeline, so you do not need to add `@reference` directives manually to every component stylesheet.
-
-For the full Tailwind v4 setup and behavior details, see the [Tailwind CSS integration guide](/docs/integrations/tailwind).
+If you also want `@apply` inside Angular component styles, add Analog's `tailwindCss.rootStylesheet` option and follow the [Tailwind CSS guide](/docs/integrations/tailwind).
 
 If you do not want Tailwind in the generated app, pass `--skipTailwind true`. The default Tailwind v4 flow expects a plain CSS entry file for global styles.
 

apps/docs-app/docs/packages/vite-plugin-angular/css-preprocessors.md

@@ -4,19 +4,18 @@ title: 'Using CSS Pre-processors'
 
 The Vite Plugin supports CSS pre-processing using external `styleUrls` and inline `styles` in the Component decorator metadata.
 
-## Recommended Tailwind v4 setup
+## Tailwind v4 component styles
 
-If your app uses Tailwind v4, keep the supported Analog setup:
+Tailwind installation itself should follow Tailwind's docs. The Analog-specific configuration below is for Angular component styles that use Tailwind utilities such as `@apply`.
 
 - keep a single root stylesheet such as `src/styles.css`
 - put `@import 'tailwindcss';` in that root stylesheet
 - keep `@tailwindcss/vite` enabled in `vite.config.ts`
-- keep `postcss.config.mjs` with `@tailwindcss/postcss`
 - configure Analog with `tailwindCss.rootStylesheet`
 
 This lets Analog preprocess component stylesheets and inject the correct `@reference` directive automatically for component CSS that uses Tailwind utilities.
 
-For the complete setup and Tailwind-specific guidance, see the [Tailwind CSS integration guide](/docs/integrations/tailwind).
+For the broader Tailwind + Analog overview, see the [Tailwind CSS guide](/docs/integrations/tailwind).
 
 ```ts
 /// <reference types="vitest" />
@@ -32,7 +31,7 @@ export default defineConfig(() => ({
       tailwindCss: {
         rootStylesheet: resolve(__dirname, 'src/styles.css'),
       },
-      hmr: true,
+      liveReload: true,
     }),
     tailwindcss(),
   ],
@@ -45,20 +44,14 @@ And in `src/styles.css`:
 @import 'tailwindcss';
 ```
 
-And in `postcss.config.mjs`:
-
-```js
-export default {
-  plugins: {
-    '@tailwindcss/postcss': {},
-  },
-};
-```
-
 Use an absolute path for `rootStylesheet`. Analog serves some component styles through virtual stylesheet ids during dev, so relative `@reference` paths are not reliable there.
 
+Use `liveReload` to control Analog's Angular reload behavior. Vite's top-level `server.hmr` option remains available when you need to configure the HMR websocket transport separately.
+
 You only need `tailwindCss.prefixes` when your component styles use custom-prefixed utilities and you want Analog to look for those prefixes instead of the default `@apply` detection.
 
+If you only use Tailwind utilities in templates and a global stylesheet, you can keep your Tailwind install path and skip `tailwindCss.rootStylesheet`.
+
 External `styleUrls` can be used without any additional configuration.
 
 An example with `styleUrls`:

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`, `hmr`, `liveReload`, `inlineStylesExtension`,
+   * `disableTypeChecking`, `liveReload`, `hmr`, `inlineStylesExtension`,
    * `fileReplacements`, and `include`.
    *
    * Use this to configure the embedded Angular integration itself, not as the
@@ -116,15 +116,18 @@ export interface Options {
    */
   inlineStylesExtension?: string;
   /**
-   * Enables Angular's HMR during development/watch mode.
+   * Enables Analog's Angular live-reload/HMR pipeline during development/watch mode.
+   *
+   * This is separate from Vite's `server.hmr` option, which configures the
+   * HMR client transport.
    *
    * Defaults to `true` for watch mode.
    */
-  hmr?: boolean;
+  liveReload?: boolean;
   /**
-   * @deprecated Use `hmr` instead. Kept as a compatibility alias.
+   * Compatibility alias for `liveReload`.
    */
-  liveReload?: boolean;
+  hmr?: boolean;
   /**
    * Enable debug logging for specific scopes.
    *

packages/storybook-angular/README.md

@@ -35,7 +35,7 @@ const config: StorybookConfig = {
   framework: {
     name: '@analogjs/storybook-angular',
     options: {
-      hmr: true,
+      liveReload: true,
     },
   },
 };
@@ -123,7 +123,9 @@ In your global stylesheet, import Tailwind with:
 
 Storybook does not automatically infer the Tailwind plugin from your app's `vite.config.ts`, so add it in `viteFinal` when your stories depend on Tailwind utilities.
 
-Angular HMR is controlled with `framework.options.hmr`. `liveReload` is still accepted as a compatibility alias, but `hmr` is the preferred option.
+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.
 
 ## Enabling Zoneless Change Detection
 

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

@@ -132,28 +132,28 @@ describe('viteFinal', () => {
   };
 
   describe('Angular plugin options', () => {
-    it('prefers hmr over liveReload and keeps liveReload as compatibility input', async () => {
-      const options = makeOptions({ hmr: true, liveReload: false });
+    it('prefers liveReload over hmr and keeps hmr as compatibility input', async () => {
+      const options = makeOptions({ liveReload: false, hmr: true });
 
       await viteFinal(baseConfig, options);
 
       expect(angularPluginMock).toHaveBeenCalledWith(
         expect.objectContaining({
-          hmr: true,
           liveReload: false,
+          hmr: false,
         }),
       );
     });
 
-    it('falls back to liveReload when hmr is omitted', async () => {
-      const options = makeOptions({ liveReload: true });
+    it('falls back to hmr when liveReload is omitted', async () => {
+      const options = makeOptions({ hmr: true });
 
       await viteFinal(baseConfig, options);
 
       expect(angularPluginMock).toHaveBeenCalledWith(
         expect.objectContaining({
-          hmr: true,
           liveReload: true,
+          hmr: true,
         }),
       );
     });