analogjs · brandonroberts · Apr 14, 2026 · Apr 6, 2026 · Apr 6, 2026 · Apr 6, 2026
@@ -0,0 +1,165 @@
+# Tailwind CSS v4
+
+Analog supports Tailwind CSS v4 for both:
+
+- utility classes in templates
+- `@apply` inside Angular component styles
+
+The supported v3 `alpha` setup is:
+
+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`
+
+Generated apps already follow this shape.
+
+## Install
+
+```sh
+npm install -D tailwindcss @tailwindcss/vite @tailwindcss/postcss postcss
+```
+
+## Vite Config
+
+```ts
+/// <reference types="vitest" />
+
+import { resolve } from 'node:path';
+import { defineConfig } from 'vite';
+import analog from '@analogjs/platform';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig(() => ({
+  plugins: [
+    analog({
+      vite: {
+        tailwindCss: {
+          rootStylesheet: resolve(__dirname, 'src/styles.css'),
+        },
+      },
+    }),
+    tailwindcss(),
+  ],
+}));
+```
+
+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:
+
+```ts
+import { resolve } from 'node:path';
+import { defineConfig } from 'vite';
+import angular from '@analogjs/vite-plugin-angular';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig(() => ({
+  plugins: [
+    angular({
+      tailwindCss: {
+        rootStylesheet: resolve(__dirname, 'src/styles.css'),
+      },
+    }),
+    tailwindcss(),
+  ],
+}));
+```
+
+## Root Stylesheet
+
+In `src/styles.css`:
+
+```css
+@import 'tailwindcss';
+```
+
+You can keep your theme, `@source`, plugins, and prefixes there as well:
+
+```css
+@import 'tailwindcss' prefix(tw);
+
+@source './src';
+
+@theme {
+  --color-primary: #3b82f6;
+}
+```
+
+## 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.
+
+## How Component Styles Work
+
+Angular compiles component styles in isolation. When a component stylesheet contains `@apply`, Tailwind still needs access to the root stylesheet that defines prefixes, theme values, and plugins.
+
+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
+
+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:
+
+```ts
+analog({
+  vite: {
+    tailwindCss: {
+      rootStylesheet: resolve(__dirname, 'src/styles.css'),
+      prefixes: ['tw:'],
+    },
+  },
+});
+```
+
+Without `prefixes`, Analog falls back to its default Tailwind usage detection for component styles.
+
+## Generated Apps
+
+Current `create-analog` and Nx app scaffolds both generate:
+
+- `@import 'tailwindcss';` in `src/styles.css`
+- `@tailwindcss/vite` in `vite.config.ts`
+- `postcss.config.mjs` with `@tailwindcss/postcss`
+
+If you start from a generated app, keep that structure unless you have a specific reason to diverge from the supported path.
+
+## Related
+
+- [Using CSS Pre-processors](/docs/packages/vite-plugin-angular/css-preprocessors)
+- [create-analog](/docs/packages/create-analog/overview)
@@ -47,14 +47,15 @@ pnpm create analog
 
 ### Tailwind v4
 
-`create-analog` scaffolds Tailwind v4 with the Vite plugin by default for the current Analog templates. Generated projects use `@tailwindcss/vite`, add `@import 'tailwindcss';` to `src/styles.css`, and also generate a `postcss.config.mjs` with `@tailwindcss/postcss` so the build path and tool integrations use the same Tailwind setup.
+`create-analog` scaffolds Tailwind v4 with the current supported Analog setup. Generated projects include:
 
-This is the recommended Analog v3 direction:
+- one root stylesheet, usually `src/styles.css`, with `@import 'tailwindcss';`
+- `@tailwindcss/vite` in `vite.config.ts`
+- `postcss.config.mjs` with `@tailwindcss/postcss`
 
-- Keep one root stylesheet, usually `src/styles.css`, that contains `@import 'tailwindcss';`
-- Keep `@tailwindcss/vite` enabled in `vite.config.ts`
-- Let Analog handle component-level `@reference` injection through its Tailwind-aware stylesheet pipeline instead of adding `@reference` directives manually in every component stylesheet
-- Prefer the `hmr` option over `liveReload` when you need to configure Angular HMR explicitly
+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 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.
 

@@ -6,15 +6,18 @@ The Vite Plugin supports CSS pre-processing using external `styleUrls` and inlin
 
 ## Recommended Tailwind v4 setup
 
-If your app uses Tailwind v4, the recommended Analog setup is opinionated:
+If your app uses Tailwind v4, keep the supported Analog setup:
 
 - 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).
+
 ```ts
 /// <reference types="vitest" />
 
@@ -42,6 +45,16 @@ 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.
 
 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.

@@ -55,7 +55,7 @@ const expectTailwindScaffold = () => {
   expect(readGeneratedStyles()).toContain(`@import 'tailwindcss';`);
   expect(viteConfig).toContain(`import tailwindcss from '@tailwindcss/vite';`);
   expect(viteConfig).toMatch(
-    /plugins:\s*\[[\s\S]*tailwindcss\(\),[\s\S]*analog\(/,
+    /plugins:\s*\[[\s\S]*analog\(\),[\s\S]*tailwindcss\(\)/,
   );
   expect(readFileSync(join(genPath, 'postcss.config.mjs'), 'utf-8')).toContain(
     `'@tailwindcss/postcss': {}`,

@@ -12,8 +12,8 @@ export default defineConfig(({ mode }) => ({
     mainFields: ['module'],
   },
   plugins: [
-__TAILWIND_PLUGIN__    analog(),
-  ],
+    analog(),
+__TAILWIND_PLUGIN__  ],
   test: {
     globals: true,
     environment: 'jsdom',

@@ -23,10 +23,10 @@ export default defineConfig(({ mode }) => {
       },
     },
     plugins: [
+      analog(),
       <% if (addTailwind) { %>
       tailwindcss(),
       <% } %>
-      analog(),
     ],
     test: {
       globals: true,

@@ -22,10 +22,10 @@ export default defineConfig(({ mode }) => {
       },
     },
     plugins: [
-       <% if (addTailwind) { %>
+      analog(),
+      <% if (addTailwind) { %>
       tailwindcss(),
       <% } %>
-      analog(),
     ],
     test: {
       globals: true,

@@ -22,10 +22,10 @@ export default defineConfig(({ mode }) => {
       },
     },
     plugins: [
+      analog(),
       <% if (addTailwind) { %>
       tailwindcss(),
       <% } %>
-      analog(),
     ],
     test: {
       globals: true,

@@ -22,10 +22,10 @@ export default defineConfig(({ mode }) => {
       },
     },
     plugins: [
+      analog(),
       <% if (addTailwind) { %>
       tailwindcss(),
       <% } %>
-      analog(),
     ],
     test: {
       globals: true,

@@ -114,7 +114,7 @@ describe('nx-plugin generator', () => {
       `import tailwindcss from '@tailwindcss/vite';`,
     );
     expect(viteConfig).toMatch(
-      /plugins:\s*\[[\s\S]*tailwindcss\(\),[\s\S]*analog\(/,
+      /plugins:\s*\[[\s\S]*analog\(\),[\s\S]*tailwindcss\(\)/,
     );
   };
 

@@ -21,6 +21,17 @@ const versionedTemplates = readdirSync(templatesDir).filter((d) =>
 );
 
 describe('generator templates', () => {
+  describe.each(versionedTemplates)('%s vite.config.ts', (template) => {
+    const viteConfig = readFileSync(
+      join(templatesDir, template, 'vite.config.ts__template__'),
+      'utf-8',
+    );
+
+    it('registers analog exactly once', () => {
+      expect(viteConfig.match(/analog\(\)/g)).toHaveLength(1);
+    });
+  });
+
   describe.each(versionedTemplates)('%s tsconfig.json', (template) => {
     const tsconfig = readTemplateJson(template, 'tsconfig.json__template__');
 

@@ -119,7 +119,7 @@ export default defineConfig(({ mode }) => {
         allow: ['.'],
       },
     },
-    plugins: [tailwindcss(), analog()],
+    plugins: [analog(), tailwindcss()],
     test: {
       globals: true,
       environment: 'jsdom',

@@ -89,3 +89,14 @@ Create a `tsconfig.app.json` in the root of the project.
   "include": ["src/**/*.ts"]
 }
 ```
+
+## Tailwind CSS v4
+
+The plugin supports Tailwind CSS v4 for Angular component styles, including `@apply` in `.component.css` files.
+
+See the [Tailwind CSS integration guide](/docs/integrations/tailwind) for the supported setup, including:
+
+- `tailwindCss.rootStylesheet`
+- `@tailwindcss/vite` in `vite.config.ts`
+- `postcss.config.mjs` with `@tailwindcss/postcss`
+- generated app defaults