tailwind-unwind 0.1.1 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # tailwind-unwind
 
+[![npm version](https://img.shields.io/npm/v/tailwind-unwind.svg)](https://www.npmjs.com/package/tailwind-unwind)
+
 CLI tool to analyze, extract, and refactor repeated Tailwind CSS utility patterns in React and Next.js projects.
 
 **Repository:** [github.com/AVPletnev/tailwind-unwind](https://github.com/AVPletnev/tailwind-unwind)
@@ -23,6 +25,52 @@ npx tailwind-unwind analyze ./src
 
 Requires **Node.js 18+**.
 
+## Configuration
+
+Copy [`tailwind-unwind.config.example.json`](tailwind-unwind.config.example.json) to your project root:
+
+```bash
+cp node_modules/tailwind-unwind/tailwind-unwind.config.example.json tailwind-unwind.config.json
+```
+
+Supported filenames: `tailwind-unwind.config.json`, `.tailwind-unwindrc`, `tailwind-unwind.config.js` / `.mjs` / `.cjs`.
+
+```json
+{
+  "include": ["src/**/*.tsx"],
+  "exclude": ["**/*.test.tsx", "**/*.stories.tsx"],
+  "names": {
+    "flex items-center justify-between p-4": "page-header",
+    "w-full h-auto object-cover rounded-lg": "media-cover"
+  },
+  "analyze": {
+    "minOccurrences": 5,
+    "top": 10
+  },
+  "generate": {
+    "minOccurrences": 3,
+    "prefix": "twu-",
+    "output": "src/styles/components.css"
+  },
+  "apply": {
+    "output": "src/styles/components.css"
+  }
+}
+```
+
+| Key | Description |
+|-----|-------------|
+| `include` / `exclude` | Glob patterns for file scanning |
+| `names` | Custom class names (utilities string → base name, prefix added automatically) |
+| `analyze` / `generate` / `apply` | Per-command overrides (`minOccurrences`, `top`, `prefix`, `output`, …) |
+
+Config is discovered from the current directory **and** ancestors of `<path>`. CLI flags override config values.
+
+```bash
+npx tailwind-unwind analyze ./src --config ./tailwind-unwind.config.json
+npx tailwind-unwind generate ./src --include "src/components/**/*.tsx"
+```
+
 ## Quick start
 
 ```bash
@@ -57,6 +105,9 @@ npx tailwind-unwind analyze <path>
 | `--top <n>` | `10` | Number of top combinations to show |
 | `--format <type>` | `console` | Output format: `console` or `json` |
 | `--no-dedupe-subsets` | — | Include subset combinations in results |
+| `--config <file>` | — | Path to config file |
+| `--include <patterns>` | all `src` | Comma-separated glob include patterns |
+| `--exclude <patterns>` | — | Comma-separated glob exclude patterns |
 
 ```bash
 # JSON report for CI
@@ -80,6 +131,7 @@ Unique class combinations: 89
 1. "flex items-center justify-between p-4"
    Occurrences: 24
    Suggestion: .page-header
+   Extractable: yes — use generate/apply
    Found in: src/components/Header.tsx:12, src/layout/Toolbar.tsx:5 (+18 more)
 
 💡 Potential code reduction: 38%
@@ -107,11 +159,15 @@ npx tailwind-unwind generate <path> --output <file.css>
 | `--max-size <n>` | `5` | Maximum classes per set |
 | `--top <n>` | `10` | Max number of component classes to generate |
 | `--prefix <name>` | `twu-` | Namespace prefix for generated classes |
+| `--format <type>` | `console` | Output format: `console` or `json` |
+| `--from-report <file>` | — | Generate from `analyze --format json` output |
+| `--extractable-only` | — | Only patterns marked extractable in analyze |
 
 ```bash
 npx tailwind-unwind generate ./src --output styles.css
-npx tailwind-unwind generate ./src --output styles.css --prefix app-
-npx tailwind-unwind generate ./src --output styles.css --min-occurrences 2 --top 20
+npx tailwind-unwind analyze ./src --format json > report.json
+npx tailwind-unwind generate --from-report report.json --output styles.css
+npx tailwind-unwind generate ./src --output styles.css --extractable-only --format json
 ```
 
 **Example output (`styles.css`):**
@@ -154,10 +210,13 @@ Supports the same flags as `generate`, plus:
 | Flag | Description |
 |------|-------------|
 | `--dry-run` | Preview replacements without writing files |
+| `--prettier` | Format modified files with Prettier (optional peer dependency) |
+| `--format json` | Machine-readable output for CI |
 
 ```bash
 npx tailwind-unwind apply ./src --output styles.css --dry-run
-npx tailwind-unwind apply ./src --output styles.css
+npx tailwind-unwind apply ./src --output styles.css --prettier
+npx tailwind-unwind apply ./src --output styles.css --from-report report.json --format json
 ```
 
 **What gets replaced:**
@@ -166,8 +225,10 @@ npx tailwind-unwind apply ./src --output styles.css
 |---------|-----------|
 | `className="flex items-center p-4"` | ✅ |
 | `className={cn('flex', 'items-center', 'p-4')}` | ✅ (static args only) |
+| `className={cn('flex p-4', isActive && 'bg-blue')}` | ✅ partial |
+| `` className={`flex p-4 ${active ? 'bg-blue' : ''}`} `` | ✅ partial (static part) |
+| `className={buttonVariants()}` | ✅ (cva/tv, no args) |
 | `className={getClasses()}` | ❌ skipped |
-| `` className={`flex ${active ? 'p-4' : ''}`} `` | ❌ skipped (dynamic) |
 
 **Before → After:**
 
@@ -193,7 +254,18 @@ Generated classes use a **`twu-` prefix** by default to avoid conflicts with exi
 | `grid grid-cols-3 gap-4` | `twu-card-grid` |
 | `fixed inset-0 bg-black/50` | `twu-backdrop` |
 
-Customize with `--prefix app-` → `.app-page-header`, etc.
+Customize with `--prefix app-` or the `names` field in config:
+
+```json
+{
+  "names": {
+    "flex items-center justify-between p-4": "page-header"
+  },
+  "generate": { "prefix": "app-" }
+}
+```
+
+→ `.app-page-header`
 
 ---
 
@@ -204,6 +276,7 @@ Scans `.tsx`, `.jsx`, `.ts`, `.js` recursively. Ignores `node_modules`, `.next`,
 - **Static strings:** `className="flex p-4"` / `class="flex p-4"`
 - **Template literals:** static segments extracted; `${...}` expressions flagged
 - **Merge utilities:** `cn()`, `clsx()`, `classnames()`, `twMerge()`, `cx()`
+- **Variant APIs:** `cva()`, `tv()` definitions and no-arg calls like `buttonVariants()`
 - **Dynamic expressions:** `className={getClasses()}` — warning, skipped
 
 Class order is normalized: `flex p-4` and `p-4 flex` are treated as the same set.