Skip to content

Commit 8fb2979

Browse files
benpsnyderbenpsnyder
committed
docs(vite-plugin-angular): align tailwind guidance with generated setup
1 parent ae795e6 commit 8fb2979

4 files changed

Lines changed: 195 additions & 7 deletions

File tree

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

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Tailwind CSS v4
2+
3+
Analog supports Tailwind CSS v4 for both:
4+
5+
- utility classes in templates
6+
- `@apply` inside Angular component styles
7+
8+
The supported v3 `alpha` setup is:
9+
10+
1. keep one root stylesheet such as `src/styles.css`
11+
2. put `@import 'tailwindcss';` in that stylesheet
12+
3. enable `@tailwindcss/vite` in `vite.config.ts`
13+
4. keep a `postcss.config.mjs` with `@tailwindcss/postcss`
14+
5. configure Analog with `tailwindCss.rootStylesheet`
15+
16+
Generated apps already follow this shape.
17+
18+
## Install
19+
20+
```sh
21+
npm install -D tailwindcss @tailwindcss/vite @tailwindcss/postcss postcss
22+
```
23+
24+
## Vite Config
25+
26+
```ts
27+
/// <reference types="vitest" />
28+
29+
import { resolve } from 'node:path';
30+
import { defineConfig } from 'vite';
31+
import analog from '@analogjs/platform';
32+
import tailwindcss from '@tailwindcss/vite';
33+
34+
export default defineConfig(() => ({
35+
plugins: [
36+
analog({
37+
vite: {
38+
tailwindCss: {
39+
rootStylesheet: resolve(__dirname, 'src/styles.css'),
40+
},
41+
},
42+
}),
43+
tailwindcss(),
44+
],
45+
}));
46+
```
47+
48+
Use an absolute `rootStylesheet` path. Analog may serve component styles through virtual stylesheet ids during dev, so relative `@reference` paths are not reliable there.
49+
50+
If you are using `@analogjs/vite-plugin-angular` directly instead of `@analogjs/platform`, the same Tailwind option lives on the Angular plugin itself:
51+
52+
```ts
53+
import { resolve } from 'node:path';
54+
import { defineConfig } from 'vite';
55+
import angular from '@analogjs/vite-plugin-angular';
56+
import tailwindcss from '@tailwindcss/vite';
57+
58+
export default defineConfig(() => ({
59+
plugins: [
60+
angular({
61+
tailwindCss: {
62+
rootStylesheet: resolve(__dirname, 'src/styles.css'),
63+
},
64+
}),
65+
tailwindcss(),
66+
],
67+
}));
68+
```
69+
70+
## Root Stylesheet
71+
72+
In `src/styles.css`:
73+
74+
```css
75+
@import 'tailwindcss';
76+
```
77+
78+
You can keep your theme, `@source`, plugins, and prefixes there as well:
79+
80+
```css
81+
@import 'tailwindcss' prefix(tw);
82+
83+
@source './src';
84+
85+
@theme {
86+
--color-primary: #3b82f6;
87+
}
88+
```
89+
90+
## PostCSS Config
91+
92+
Create `postcss.config.mjs`:
93+
94+
```js
95+
export default {
96+
plugins: {
97+
'@tailwindcss/postcss': {},
98+
},
99+
};
100+
```
101+
102+
Keep this even if dev already works with `@tailwindcss/vite`. Current Analog builds still rely on the PostCSS path for production CSS processing.
103+
104+
## How Component Styles Work
105+
106+
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.
107+
108+
Analog handles that by:
109+
110+
- detecting Tailwind usage in component CSS
111+
- injecting the correct `@reference` to the configured root stylesheet
112+
- externalizing component styles during dev when needed so they flow through Vite's CSS pipeline
113+
- preserving the build path through PostCSS for production
114+
115+
That means you should not manually add `@reference` to every component stylesheet in the normal setup.
116+
117+
## Plugin Order
118+
119+
List `analog()` before `tailwindcss()` in your Vite config. That is now how the generators scaffold it.
120+
121+
```ts
122+
plugins: [analog({ vite: { tailwindCss: { ... } } }), tailwindcss()];
123+
```
124+
125+
This keeps the config aligned with the generated apps and the current documentation.
126+
127+
## HMR
128+
129+
Prefer `hmr` over `liveReload` when you need to configure Angular HMR explicitly. `liveReload` remains a compatibility alias.
130+
131+
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.
132+
133+
## Prefixes
134+
135+
If your component styles use custom-prefixed utilities, configure `prefixes` so Analog knows which stylesheets need Tailwind `@reference` injection:
136+
137+
```ts
138+
analog({
139+
vite: {
140+
tailwindCss: {
141+
rootStylesheet: resolve(__dirname, 'src/styles.css'),
142+
prefixes: ['tw:'],
143+
},
144+
},
145+
});
146+
```
147+
148+
Without `prefixes`, Analog falls back to its default Tailwind usage detection for component styles.
149+
150+
## Generated Apps
151+
152+
Current `create-analog` and Nx app scaffolds both generate:
153+
154+
- `@import 'tailwindcss';` in `src/styles.css`
155+
- `@tailwindcss/vite` in `vite.config.ts`
156+
- `postcss.config.mjs` with `@tailwindcss/postcss`
157+
158+
If you start from a generated app, keep that structure unless you have a specific reason to diverge from the supported path.
159+
160+
## Related
161+
162+
- [Using CSS Pre-processors](/docs/packages/vite-plugin-angular/css-preprocessors)
163+
- [create-analog](/docs/packages/create-analog/overview)

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

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -47,14 +47,15 @@ pnpm create analog
4747

4848
### Tailwind v4
4949

50-
`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.
50+
`create-analog` scaffolds Tailwind v4 with the current supported Analog setup. Generated projects include:
5151

52-
This is the recommended Analog v3 direction:
52+
- one root stylesheet, usually `src/styles.css`, with `@import 'tailwindcss';`
53+
- `@tailwindcss/vite` in `vite.config.ts`
54+
- `postcss.config.mjs` with `@tailwindcss/postcss`
5355

54-
- Keep one root stylesheet, usually `src/styles.css`, that contains `@import 'tailwindcss';`
55-
- Keep `@tailwindcss/vite` enabled in `vite.config.ts`
56-
- Let Analog handle component-level `@reference` injection through its Tailwind-aware stylesheet pipeline instead of adding `@reference` directives manually in every component stylesheet
57-
- Prefer the `hmr` option over `liveReload` when you need to configure Angular HMR explicitly
56+
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.
57+
58+
For the full Tailwind v4 setup and behavior details, see the [Tailwind CSS integration guide](/docs/integrations/tailwind).
5859

5960
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.
6061

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

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,18 @@ The Vite Plugin supports CSS pre-processing using external `styleUrls` and inlin
66

77
## Recommended Tailwind v4 setup
88

9-
If your app uses Tailwind v4, the recommended Analog setup is opinionated:
9+
If your app uses Tailwind v4, keep the supported Analog setup:
1010

1111
- keep a single root stylesheet such as `src/styles.css`
1212
- put `@import 'tailwindcss';` in that root stylesheet
1313
- keep `@tailwindcss/vite` enabled in `vite.config.ts`
14+
- keep `postcss.config.mjs` with `@tailwindcss/postcss`
1415
- configure Analog with `tailwindCss.rootStylesheet`
1516

1617
This lets Analog preprocess component stylesheets and inject the correct `@reference` directive automatically for component CSS that uses Tailwind utilities.
1718

19+
For the complete setup and Tailwind-specific guidance, see the [Tailwind CSS integration guide](/docs/integrations/tailwind).
20+
1821
```ts
1922
/// <reference types="vitest" />
2023

@@ -42,6 +45,16 @@ And in `src/styles.css`:
4245
@import 'tailwindcss';
4346
```
4447

48+
And in `postcss.config.mjs`:
49+
50+
```js
51+
export default {
52+
plugins: {
53+
'@tailwindcss/postcss': {},
54+
},
55+
};
56+
```
57+
4558
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.
4659

4760
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.

‎packages/vite-plugin-angular/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,3 +89,14 @@ Create a `tsconfig.app.json` in the root of the project.
8989
"include": ["src/**/*.ts"]
9090
}
9191
```
92+
93+
## Tailwind CSS v4
94+
95+
The plugin supports Tailwind CSS v4 for Angular component styles, including `@apply` in `.component.css` files.
96+
97+
See the [Tailwind CSS integration guide](/docs/integrations/tailwind) for the supported setup, including:
98+
99+
- `tailwindCss.rootStylesheet`
100+
- `@tailwindcss/vite` in `vite.config.ts`
101+
- `postcss.config.mjs` with `@tailwindcss/postcss`
102+
- generated app defaults

0 commit comments

Comments
 (0)