Skip to content

Commit 570b031

Browse files
bloveclaude
andcommitted
docs(chat): document Tailwind v4 requirement for compositions
Verified against a fresh-install consumer of @ngaf/chat@0.0.2: without Tailwind configured (and without `@source "../node_modules/@ngaf/chat"`), ChatComponent's utility classes (flex, gap-3, max-w-[75%], md:flex, ...) are tree-shaken away and the chat collapses to a column of unstyled full-width blocks. The library does not ship a precompiled stylesheet, so this is a hard consumer-side requirement. Surface it explicitly: - Quickstart gets a Tailwind setup step between install and provider config. - Installation Requirements step calls out Tailwind v4 alongside Angular 20+ and Node 18+. - Tailwind CSS section is rewritten with concrete steps (postcss config, @import, @source) rather than just an `npm install` line. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 614cfd6 commit 570b031

2 files changed

Lines changed: 78 additions & 2 deletions

File tree

apps/website/content/docs/chat/getting-started/installation.mdx

Lines changed: 50 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ The chat components read streaming state from `LangGraphAgent`, which is returne
1414
<Step title="Node.js 18+">
1515
Required for the build toolchain and package installation.
1616
</Step>
17+
<Step title="Tailwind CSS v4 (for compositions)">
18+
The `ChatComponent` and `ChatDebugComponent` compositions use Tailwind utility classes for layout. Consumers must have Tailwind v4 configured in their project and `@source "../node_modules/@ngaf/chat"` declared in their stylesheet. See [Tailwind CSS](#tailwind-css) below. Primitives-only consumers can skip this.
19+
</Step>
1720
</Steps>
1821

1922
## Install the package
@@ -77,13 +80,58 @@ export const appConfig: ApplicationConfig = {
7780

7881
## Tailwind CSS
7982

80-
The composition components use Tailwind CSS utility classes for layout. If you are using compositions like `ChatComponent` or `ChatDebugComponent`, make sure Tailwind is configured in your project.
83+
<Callout type="warning" title="Required for compositions">
84+
Compositions like `ChatComponent` and `ChatDebugComponent` use Tailwind CSS utility classes (`flex`, `gap-3`, `max-w-[75%]`, `md:flex`, ...) for layout. **The library does not ship a precompiled stylesheet**, so without Tailwind the chat renders as a column of full-width boxes with no spacing or alignment.
85+
86+
The primitives layer (e.g. `ChatMessagesComponent`, `ChatInputComponent` used directly) does not depend on Tailwind — it uses inline styles and CSS custom properties only.
87+
</Callout>
88+
89+
If your project already uses Tailwind v4, skip ahead to [Scan the chat package](#scan-the-ngafchat-package). Otherwise:
90+
91+
<Steps>
92+
<Step title="Install Tailwind">
8193

8294
```bash
8395
npm install -D tailwindcss @tailwindcss/postcss
8496
```
8597

86-
The primitives layer does not depend on Tailwind -- it uses only inline styles and content projection.
98+
</Step>
99+
<Step title="Add a PostCSS config">
100+
101+
Create `.postcssrc.json` at the project root:
102+
103+
```json
104+
{
105+
"plugins": {
106+
"@tailwindcss/postcss": {}
107+
}
108+
}
109+
```
110+
111+
</Step>
112+
<Step title="Import Tailwind in src/styles.css">
113+
114+
```css
115+
@import "tailwindcss";
116+
117+
/* Tell Tailwind to scan @ngaf/chat for utility classes used in the
118+
composition templates. Without this, layout classes from the
119+
library are tree-shaken away. */
120+
@source "../node_modules/@ngaf/chat";
121+
```
122+
123+
</Step>
124+
</Steps>
125+
126+
### Scan the @ngaf/chat package
127+
128+
Tailwind v4 auto-discovers source files in your project but ignores `node_modules` by default. Because the chat compositions ship their utility classes inside the published bundle, you must opt those files in with `@source`:
129+
130+
```css
131+
@source "../node_modules/@ngaf/chat";
132+
```
133+
134+
Without this directive, classes like `flex`, `w-10`, `gap-3`, and `max-w-[75%]` will not appear in your compiled CSS, and the chat will visibly collapse to an unstyled column. Restart `ng serve` after adding `.postcssrc.json` so the new PostCSS pipeline takes effect.
87135

88136
## Verify the Setup
89137

apps/website/content/docs/chat/getting-started/quickstart.mdx

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,34 @@ Angular 20+ project with `@ngaf/agent` already configured. If you need setup hel
1313
npm install @ngaf/chat
1414
```
1515

16+
</Step>
17+
<Step title="Set up Tailwind CSS">
18+
19+
`ChatComponent` ships its layout as Tailwind utility classes and does not include a precompiled stylesheet. If your project does not already use Tailwind v4, add it now:
20+
21+
```bash
22+
npm install -D tailwindcss @tailwindcss/postcss
23+
```
24+
25+
Create `.postcssrc.json` at the project root:
26+
27+
```json
28+
{
29+
"plugins": {
30+
"@tailwindcss/postcss": {}
31+
}
32+
}
33+
```
34+
35+
Add the following to `src/styles.css`:
36+
37+
```css
38+
@import "tailwindcss";
39+
@source "../node_modules/@ngaf/chat";
40+
```
41+
42+
The `@source` directive opts the published `@ngaf/chat` bundle into Tailwind's class scan; without it the chat renders as a column of unstyled blocks. Restart `ng serve` after creating `.postcssrc.json`. See [Installation → Tailwind CSS](/docs/chat/getting-started/installation#tailwind-css) for details.
43+
1644
</Step>
1745
<Step title="Configure providers">
1846

0 commit comments

Comments
 (0)