🎨 Tidywind

A powerful CLI tool that automatically formats and groups Tailwind CSS classes in React components. Tidywind organizes your classes into logical groups and supports both join(" ") and clsx() formatting styles.

✨ Features

• Smart Class Grouping: Automatically groups classes by category (layout, spacing, colors, borders, etc.)
• Multiple Format Support: Choose between join(" ") (default) or clsx() formatting
• Re-formatting Support: Can re-format already formatted className attributes
• Auto-import Management: Automatically imports clsx when using --clsx flag
• Next.js Support: Respects "use client" directive placement
• Optional Prettier Integration: Run prettier/format commands with --prettier flag
• Smart Package Management: Auto-detects package manager and prompts for missing dependencies
• Batch Processing: Process single files, directories, or glob patterns
• Dry Run Mode: Preview changes before applying them

📦 Installation

Global Installation (Recommended)

npm install -g tidywind

Local Installation

npm install --save-dev tidywind

🚀 Usage

Basic Usage

# Format all supported files in current directory
tidywind

# Format specific file
tidywind component.jsx

# Format all files in src directory
tidywind src/

# Preview changes without modifying files
tidywind --dry-run src/

# Watch for changes and auto-format
tidywind --watch src/

# Watch with custom delay and clsx formatting
tidywind --watch --clsx --delay 500 src/

Using clsx Format

# Format using clsx() and auto-import clsx
tidywind --clsx src/

# Convert existing join(" ") format to clsx()
tidywind --clsx component.jsx

# Run prettier/format after changes
tidywind --prettier src/

🎯 Examples

Before Formatting

export function Button() {
    return (
        <button className="bg-blue-500 hover:bg-blue-600 text-white font-bold py-2 px-4 rounded-lg shadow-md transition-colors flex items-center justify-center">
            Click me
        </button>
    );
}

After Formatting (Default - join)

export function Button() {
    return (
        <button
            className={[
                "flex items-center justify-center",
                "py-2 px-4",
                "bg-blue-500 text-white hover:bg-blue-600",
                "rounded-lg",
                "font-bold",
                "shadow-md transition-colors",
            ].join(" ")}
        >
            Click me
        </button>
    );
}

After Formatting (--clsx flag)

import clsx from "clsx";

export function Button() {
    return (
        <button
            className={clsx(
                "flex items-center justify-center",
                "py-2 px-4",
                "bg-blue-500 text-white hover:bg-blue-600",
                "rounded-lg",
                "font-bold",
                "shadow-md transition-colors",
            )}
        >
            Click me
        </button>
    );
}

📋 Class Grouping Categories

Tidywind organizes classes into these logical groups:

1. Layout: flex, grid, absolute, relative, hidden, etc.
2. Size: w-*, h-*, min-w-*, max-h-*, etc.
3. Spacing: p-*, m-*, gap-*, space-*, etc.
4. Colors: bg-*, text-*, border-* (colors), etc.
5. Borders: border, rounded-*, ring-*, outline-*, etc.
6. Typography: font-*, text-*, leading-*, tracking-*, etc.
7. Effects: opacity-*, shadow-*, transition-*, transform, etc.
8. Interactivity: cursor-*, pointer-events-*, select-*, etc.
9. Pseudo-elements: before:*, after:* classes

🛠️ CLI Options

| Option | Description | | ----------------- | ----------------------------------------------------------------------- | | -h, --help | Show help message | | -v, --version | Show version number | | -r, --recursive | Process directories recursively (default: true) | | --dry-run | Preview changes without modifying files | | --clsx | Use clsx() instead of join(" ") for formatting | | --prettier | Run prettier/format command after changes (not available in watch mode) | | --watch | Watch files for changes and auto-format | | --delay <ms> | Debounce delay for watch mode (default: 2000ms) |

📁 Supported File Types

• .jsx - React JSX files
• .js - JavaScript files with JSX
• .tsx - TypeScript JSX files
• .ts - TypeScript files with JSX

🔄 Re-formatting Support

Tidywind can re-format already formatted className attributes:

// This mismatched grouping...
className={[
  "bg-blue-500 flex items-center text-white p-4 rounded-lg",
  "hover:bg-blue-600 shadow-md"
].join(" ")}

// ...gets properly regrouped to:
className={[
  "flex items-center",
  "p-4",
  "bg-blue-500 text-white hover:bg-blue-600",
  "rounded-lg",
  "shadow-md"
].join(" ")}

👀 Watch Mode

Tidywind includes a powerful watch mode that automatically formats your files as you make changes, providing real-time Tailwind class organization.

Basic Watch Usage

# Watch current directory
tidywind --watch

# Watch specific directory
tidywind --watch src/

# Watch with clsx formatting
tidywind --watch --clsx src/

# Watch with prettier integration
tidywind --watch --prettier src/

# Watch with custom debounce delay (500ms)
tidywind --watch --delay 500 src/

Watch Mode Features

• Initial formatting: Formats all existing files once before starting to watch
• Real-time formatting: Automatically formats files when they change
• Debounced processing: Configurable delay (default 2000ms) to avoid excessive formatting
• Smart file filtering: Only processes supported file types (.jsx, .js, .tsx, .ts)
• Directory exclusions: Automatically ignores node_modules, .git, dist, build, .next, etc.
• Graceful shutdown: Press Ctrl+C to stop watching
• Integration support: Works with --clsx and --prettier flags

Watch Mode Output

$ tidywind --watch --clsx src/

🎨 Tidywind - Tailwind CSS Class Formatter

👀 Starting watch mode...
⏱️  Debounce delay: 2000ms
📦 Using clsx() for formatting
📁 Watching paths: src/
🔍 Watching extensions: .jsx, .js, .tsx, .ts

🎨 Performing initial formatting of existing files...

✅ Formatted: src/components/Button.jsx
✅ Formatted: src/components/Card.jsx
⏭️  No changes: src/pages/Home.tsx

📊 Initial formatting summary:
   Files processed: 3
   Files changed: 2

✨ Initial formatting complete! Now watching for changes... (Press Ctrl+C to stop)

[2:30:45 PM] 🎨 Formatting src/components/Button.jsx...
[2:30:45 PM] ✅ Formatted: src/components/Button.jsx

[2:31:12 PM] 🎨 Formatting src/pages/Home.tsx...
[2:31:12 PM] ⏭️  No changes needed: src/pages/Home.tsx

Watch Mode Limitations

• Cannot be used with --dry-run (requires file modifications)
• Requires the chokidar dependency (automatically installed with Tidywind)
• Only watches files that match supported extensions

🎨 Prettier Integration

Tidywind can optionally run prettier or other format commands after making changes to ensure your code stays consistently formatted.

Format Command Detection

When using the --prettier flag, Tidywind detects and runs format commands in this priority order:

1. npm run format - if format script exists in package.json
2. npm run prettier - if prettier script exists in package.json
3. npm run fmt - if fmt script exists in package.json
4. bun format - if bun.lockb exists or packageManager is set to bun

Using Prettier Integration

Use the --prettier flag to run formatting after Tidywind changes:

tidywind --prettier src/

Example Output with --prettier

🎨 Tidywind - Tailwind CSS Class Formatter

🎨 Will run prettier/format after changes

✅ Formatted: src/components/Button.jsx

📊 Summary:
   Files processed: 1
   Files changed: 1

✨ Tidywind formatting complete!

🎨 Running npm run format...
✨ Code formatting completed!

📦 Smart Package Management

Tidywind automatically detects your package manager and handles missing dependencies intelligently.

Package Manager Detection

Tidywind detects your package manager by checking for lock files:

• Bun: bun.lockb → bun add <package> --dev
• PNPM: pnpm-lock.yaml → pnpm add <package> --save-dev
• Yarn: yarn.lock → yarn add <package> --dev
• NPM: package-lock.json → npm install <package> --save-dev

Dependency Checking

When using --clsx or --prettier flags, Tidywind checks if required packages are installed:

For --clsx flag:

• Checks if clsx is installed
• Prompts to install if missing
• Falls back to join(" ") if declined or installation fails

For --prettier flag:

• Checks if prettier is installed or format scripts exist
• Prompts to install prettier if no format command is available
• Disables prettier integration if declined or installation fails

Example Interaction

$ tidywind --clsx src/

🎨 Tidywind - Tailwind CSS Class Formatter

📦 Package 'clsx' is not installed.
   To use this feature, you need to install it first.
   Suggested command: yarn add clsx --dev

💡 If you choose not to install clsx, Tidywind will use join(" ") formatting instead.

Would you like to install 'clsx' now? (Y/n): y

🔧 Installing clsx using yarn...
✅ Successfully installed clsx!

📦 Using clsx() for formatting
✅ Formatted: src/component.jsx

If user declines installation:

📝 Using join(" ") formatting instead of clsx.
✅ Formatted with join(" ") arrays

🎨 Next.js Support

Tidywind respects Next.js "use client" directives:

"use client";

import clsx from "clsx"; // Import placed after "use client"
import React from "react";

export default function Component() {
    // ...
}

📊 Output Examples

🎨 Tidywind - Tailwind CSS Class Formatter

📦 Using clsx() for formatting

✅ Formatted: src/components/Button.jsx
✅ Formatted: src/components/Card.jsx
⏭️  No changes: src/components/Header.jsx

📊 Summary:
   Files processed: 3
   Files changed: 2

✨ Formatting complete!

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see the LICENSE file for details.

🐛 Issues

If you encounter any issues or have feature requests, please file them on the GitHub Issues page.