@its-thepoe/tailwindcss 1.0.0 → 1.0.1

package/SKILL.md

@@ -41,6 +41,49 @@ Example test:
 <div class="m-4 rounded-md bg-blue-600 px-3 py-2 text-white">Tailwind OK</div>
 ```
 
+## Next.js monorepos: the "Tailwind runs but generates no CSS" trap (v3 + sometimes v4)
+
+Symptom pattern:
+
+- Dev server runs, Tailwind appears "installed", but utilities do not apply.
+- Tailwind warns it cannot find any classes / content, or the generated CSS is tiny.
+
+Root cause (common in monorepos):
+
+- Tailwind v3 only generates utilities for files it scans via `content` globs in `tailwind.config.*`.
+- In a monorepo, Next can run with a different working directory than you think (especially when you run `next dev apps/web`, have multiple lockfiles, or the repo is ESM with `"type": "module"`).
+- Relative paths inside `tailwind.config.*` and `postcss.config.*` then resolve from the wrong place, so Tailwind effectively scans nothing.
+
+Hardening rules (do these when Tailwind scanning is flaky):
+
+1. Run Next from the app directory (so all relative config paths line up):
+
+```bash
+cd apps/web && next dev -p 3000
+```
+
+2. Prefer `.cjs` for config files in ESM repos:
+
+- If repo `package.json` has `"type": "module"`, then `postcss.config.js` / `tailwind.config.js` are treated as ESM and `module.exports` will crash.
+- Use `postcss.config.cjs` / `tailwind.config.cjs` when you want CommonJS config.
+
+3. If PostCSS is used, make it load the exact Tailwind config file explicitly (v3):
+
+```js
+// postcss.config.cjs
+module.exports = {
+  plugins: {
+    tailwindcss: { config: "./tailwind.config.cjs" },
+    autoprefixer: {},
+  },
+};
+```
+
+Verification:
+
+- Add the "Tailwind OK" test element to a real page and refresh.
+- Re-run `next dev` from inside the app folder.
+
 ## Setup selection (pick one)
 
 - Tailwind v4 + Vite plugin (`@tailwindcss/vite`) is the clean default for Vite apps.
@@ -92,7 +135,7 @@ CSS entry:
 @tailwind utilities;
 ```
 
-- `tailwind.config.js` (or `.ts`) must exist and include correct `content` globs.
+- `tailwind.config.*` must exist and include correct `content` globs.
 - PostCSS uses `tailwindcss` + `autoprefixer`.
 
 Install (v3):
@@ -102,7 +145,7 @@ npm install -D tailwindcss postcss autoprefixer
 npx tailwindcss init -p
 ```
 
-`tailwind.config.js` example:
+`tailwind.config.cjs` example (safe in ESM repos):
 
 ```js
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-thepoe/tailwindcss",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Agent Skill: implement Tailwind CSS (v3/v4), debug setup issues, and apply consistent utility-first patterns.",
   "license": "MIT",
   "keywords": [

package/reference.md

@@ -10,6 +10,48 @@ Use this when setup is non-standard or the project is mid-migration.
 - Identify build pipeline (Vite plugin vs PostCSS).
 - Confirm content scanning covers files that contain class strings.
 
+## Next.js monorepo + ESM pitfalls (high leverage)
+
+If utilities don't apply but Tailwind "seems installed", assume **config resolution** is wrong until proven otherwise.
+
+### 1) Working directory mismatch
+
+In monorepos, `next dev` can effectively behave like it's running from a different root than you expect. If Tailwind config uses relative paths, content globs can silently stop matching.
+
+Preferred fix:
+
+```bash
+cd apps/web && next dev
+```
+
+If you have a repo-level `dev:web` script, make it `cd apps/web && next dev ...` rather than `next dev apps/web ...`.
+
+### 2) ESM repo breaks `.js` CommonJS configs
+
+If your repo root `package.json` includes `"type": "module"`:
+
+- `postcss.config.js` and `tailwind.config.js` are treated as ESM.
+- `module.exports = ...` will throw `ReferenceError: module is not defined`.
+
+Fix: use `.cjs` for those configs when you want CommonJS:
+
+- `postcss.config.cjs`
+- `tailwind.config.cjs`
+
+### 3) Pin Tailwind's config in PostCSS (v3)
+
+When Tailwind v3 is running through PostCSS, explicitly point it at the right config so it can't "discover" the wrong one (or none):
+
+```js
+// postcss.config.cjs
+module.exports = {
+  plugins: {
+    tailwindcss: { config: "./tailwind.config.cjs" },
+    autoprefixer: {},
+  },
+};
+```
+
 ## Setup recipes (minimal)
 
 ### V4 + Vite