{"_id":"@damir-sh/tailwind-formatter","_rev":"2-7217a6fa91b59128e04b220a2a9d72ec","name":"@damir-sh/tailwind-formatter","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@damir-sh/tailwind-formatter","version":"0.0.1","_id":"@damir-sh/tailwind-formatter@0.0.1","maintainers":[{"name":"damir-sh","email":"greatestdamir@gmail.com"}],"bin":{"tailwind-formatter":"bin/cli.js"},"dist":{"shasum":"7244b7dcc38b8ab62e2dc3d10f717e926a7b2608","tarball":"https://registry.npmjs.org/@damir-sh/tailwind-formatter/-/tailwind-formatter-0.0.1.tgz","fileCount":11,"integrity":"sha512-jXXF0CemXHNZZcm06mCmjhQIPzReMbhZz7S+n6cxcG2skRelAKMrJnpkXWwNA1kPPKUNhnB3xj/k1U+SRBKpbA==","signatures":[{"sig":"MEQCIFvFxHMmGggVaQtMqDtAnj06l7BnrTd7gkDZ5K5v0HRnAiBo/vmtnqCx5kft64LzD8loQbgJrASY19KmO9fVo8sDAg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28561},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"86bd35cffa3f173aa6c9309f7d32752c9a679a6d","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","dev:test":"vitest"},"_npmUser":{"name":"damir-sh","email":"greatestdamir@gmail.com"},"_npmVersion":"11.4.2","description":"**A Tailwind CSS class formatter** that groups utilities into semantic buckets (layout, spacing, colors, etc.) and outputs them in a consistent, readable order.","directories":{},"_nodeVersion":"20.19.2","dependencies":{"fast-glob":"^3.3.3","@babel/types":"^7.28.2","@babel/parser":"^7.28.0","@babel/traverse":"^7.28.0","@babel/generator":"^7.28.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.4","typescript":"^5.5.4","@types/node":"^20.12.12","@types/babel__traverse":"^7.28.0","@types/babel__generator":"^7.27.0"},"_npmOperationalInternal":{"tmp":"tmp/tailwind-formatter_0.0.1_1755366066799_0.4330537901982636","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@damir-sh/tailwind-formatter","version":"0.0.2","type":"module","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","dev:test":"vitest"},"devDependencies":{"@types/babel__generator":"^7.27.0","@types/babel__traverse":"^7.28.0","@types/node":"^20.12.12","typescript":"^5.5.4","vitest":"^3.2.4"},"publishConfig":{"access":"public"},"dependencies":{"@babel/generator":"^7.28.0","@babel/parser":"^7.28.0","@babel/traverse":"^7.28.0","@babel/types":"^7.28.2","fast-glob":"^3.3.3"},"bin":{"tailwind-formatter":"bin/cli.js"},"_id":"@damir-sh/tailwind-formatter@0.0.2","gitHead":"8f2f2038d77ce4abd293e2343e106459736b81a4","description":"**A Tailwind CSS class formatter** that groups utilities into semantic buckets and outputs them in a consistent, readable order. Perfect for maintaining clean, organized Tailwind code across your project.","_nodeVersion":"20.19.2","_npmVersion":"11.4.2","dist":{"integrity":"sha512-87mR7kAE47WWVBqPUb7tuKc2/sP8WRidp+vgGwkCq5syQvjgcbOLPY/Uii8FIwjqtl+OWKQqQpRDkMvUEq20zQ==","shasum":"1e53622abe49a36a8c812614f8186e421e127147","tarball":"https://registry.npmjs.org/@damir-sh/tailwind-formatter/-/tailwind-formatter-0.0.2.tgz","fileCount":11,"unpackedSize":34650,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICLX0QpjDg05Py4pdmIUMcln1J0B6NXKVDk2P3g/D47lAiEAhqK23TaSdbxdol9TmKxX5vnbLjNakzDROZk+eMn8ZcY="}]},"_npmUser":{"name":"damir-sh","email":"greatestdamir@gmail.com"},"directories":{},"maintainers":[{"name":"damir-sh","email":"greatestdamir@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tailwind-formatter_0.0.2_1755367087317_0.4353015021583919"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-16T17:41:06.712Z","modified":"2025-08-16T17:58:07.733Z","0.0.1":"2025-08-16T17:41:06.987Z","0.0.2":"2025-08-16T17:58:07.506Z"},"description":"**A Tailwind CSS class formatter** that groups utilities into semantic buckets and outputs them in a consistent, readable order. Perfect for maintaining clean, organized Tailwind code across your project.","maintainers":[{"name":"damir-sh","email":"greatestdamir@gmail.com"}],"readme":"# @damir-sh/tailwind-formatter\n\n**A Tailwind CSS class formatter** that groups utilities into semantic buckets and outputs them in a consistent, readable order. Perfect for maintaining clean, organized Tailwind code across your project.\n\n## ✨ Features\n\n- **Semantic Grouping**: Organizes classes into logical groups (layout, spacing, colors, etc.)\n- **Variant Preservation**: Respects all variant prefixes (`sm:`, `hover:`, `[&>*]:`, etc.)\n- **Arbitrary Value Support**: Handles arbitrary values like `bg-[color:var(--x)]` correctly\n- **CLI & Programmatic API**: Use as a command-line tool or import into your code\n- **cn() Integration**: Special support for `cn()`, `clsx()`, and similar utility functions\n- **Configurable**: Custom prefixes, variants, and plugin utilities\n- **Idempotent**: Safe to run multiple times without changes\n\n## 📦 Installation\n\n```bash\nnpm install @damir-sh/tailwind-formatter --save-dev\n```\n\n## 🚀 Quick Start\n\n### Command Line Usage\n\nFormat all files in your `src` directory:\n\n```bash\nnpx @damir-sh/tailwind-formatter src\n```\n\nPreview changes without modifying files:\n\n```bash\nnpx @damir-sh/tailwind-formatter src --dry\n```\n\nGroup classes with `cn()` function calls:\n\n```bash\nnpx @damir-sh/tailwind-formatter src --use-cn\n```\n\n### Programmatic Usage\n\n```javascript\nimport { formatClasses } from \"@damir-sh/tailwind-formatter\";\n\n// Basic formatting\nconst formatted = formatClasses(\n\t\"text-red-500 p-4 flex hover:bg-blue-500 rounded-lg items-center\"\n);\nconsole.log(formatted);\n// Output: \"flex items-center p-4 text-red-500 hover:bg-blue-500 rounded-lg\"\n\n// Split into semantic groups\nconst groups = formatClasses(\"flex p-4 text-red-500 rounded-lg\", {\n\tsplitPerGroup: true,\n});\nconsole.log(groups);\n// Output: [\"flex\", \"p-4\", \"text-red-500\", \"rounded-lg\"]\n```\n\n## 📚 API Reference\n\n### `formatClasses(input, options?)`\n\nFormats and sorts Tailwind CSS classes.\n\n**Parameters:**\n\n- `input` (string): Space-separated class names\n- `options` (FormatOptions, optional): Configuration options\n\n**Returns:**\n\n- `string`: Formatted class string (default)\n- `string[]`: Array of group strings (when `splitPerGroup: true`)\n\n### `categorize(input, options?)`\n\nCategorizes classes into groups without formatting.\n\n```javascript\nimport { categorize } from \"@damir-sh/tailwind-formatter\";\n\nconst categories = categorize(\"flex p-2 text-red-500\");\nconsole.log(categories);\n// Output: { layout: ['flex'], spacing: ['p-2'], colors: ['text-red-500'], ... }\n```\n\n### `tokenize(input)`\n\nSplits class string into individual tokens while preserving arbitrary values.\n\n```javascript\nimport { tokenize } from \"@damir-sh/tailwind-formatter\";\n\nconst tokens = tokenize(\"bg-[var(--color)] text-sm\");\nconsole.log(tokens);\n// Output: ['bg-[var(--color)]', 'text-sm']\n```\n\n## ⚙️ Configuration\n\n### CLI Options\n\n| Flag       | Description                               |\n| ---------- | ----------------------------------------- |\n| `--dry`    | Preview changes without modifying files   |\n| `--use-cn` | Group classes with `cn()`, `clsx()`, etc. |\n| `--debug`  | Enable debug logging                      |\n\n### FormatOptions\n\n```typescript\ninterface FormatOptions {\n\tgroupOrder?: GroupKey[]; // Custom group order\n\tsplitPerGroup?: boolean; // Return array of groups\n\ttailwind?: {\n\t\tprefix?: string; // Custom prefix (e.g., \"tw-\")\n\t\tvariants?: string[]; // Custom variant priority\n\t\tcustomUtilities?: (RegExp | string)[]; // Plugin utilities\n\t};\n}\n```\n\n### Group Order\n\nClasses are organized into these semantic groups by default:\n\n1. **layout** - `display`, `position`, `flex`, `grid` properties\n2. **spacing** - `padding`, `margin`, `space` utilities\n3. **sizing** - `width`, `height`, `min/max` dimensions\n4. **typography** - `font`, `text`, `leading`, `tracking`\n5. **colors** - `background`, `text` colors, `gradients`\n6. **borders** - `border`, `rounded`, `divide`, `outline`\n7. **effects** - `shadow`, `transform`, `filter`, `backdrop`\n8. **interactivity** - `cursor`, `transition`, `animation`\n9. **accessibility** - `sr-only`, `aria-*`, `data-*`\n10. **misc** - everything else\n\n## 🎯 Examples\n\n### Basic Formatting\n\n**Input:**\n\n```html\n<div\n\tclassName=\"text-red-500 p-4 flex md:hover:bg-blue-500 rounded-lg items-center\"\n></div>\n```\n\n**Output:**\n\n```html\n<div\n\tclassName=\"flex items-center p-4 text-red-500 md:hover:bg-blue-500 rounded-lg\"\n></div>\n```\n\n### With Custom Configuration\n\n```javascript\nconst formatted = formatClasses(\"hover:bg-blue-500 sm:bg-red-500\", {\n\ttailwind: {\n\t\tvariants: [\"sm\", \"md\", \"lg\", \"hover\"], // sm has higher priority\n\t},\n});\n// Output: \"sm:bg-red-500 hover:bg-blue-500\"\n```\n\n### Using `--use-cn` Flag\n\n**Before:**\n\n```javascript\nconst className = cn(\"text-red-500 p-4 flex rounded-lg\");\n```\n\n**After:**\n\n```javascript\nconst className = cn(\"flex\", \"p-4\", \"text-red-500\", \"rounded-lg\");\n```\n\n### Arbitrary Values\n\n```javascript\nformatClasses(\"bg-[color:var(--primary)] p-[2.5rem] text-[14px]\");\n// Output: \"p-[2.5rem] text-[14px] bg-[color:var(--primary)]\"\n```\n\n### Complex Variants\n\n```javascript\nformatClasses(\"sm:hover:focus:text-blue-500 lg:group-hover:bg-red-500\");\n// Preserves all variant chains intact\n```\n\n## 🔧 CLI Usage Examples\n\n```bash\n# Format all TypeScript/JavaScript files in src\nnpx @damir-sh/tailwind-formatter src\n\n# Format specific directory with dry run\nnpx @damir-sh/tailwind-formatter components --dry\n\n# Use cn() grouping with debug output\nnpx @damir-sh/tailwind-formatter src --use-cn --debug\n\n# Use --debug for debug output\nnpx @damir-sh/tailwind-formatter src --debug\n```\n\n## 🤝 Integration\n\n### With Prettier\n\nAdd to your `.prettierignore` to avoid conflicts:\n\n```\n# Let tailwind-formatter handle class ordering\n*.tsx\n*.jsx\n```\n\n### With ESLint\n\nWorks well alongside ESLint rules. Run tailwind-formatter first, then ESLint.\n\n### With VS Code\n\nYou can set up a task or use with extensions that support custom formatters.\n\n## 📝 Supported File Types\n\n- `.js`, `.jsx` - JavaScript and JSX files\n- `.ts`, `.tsx` - TypeScript and TSX files\n\nThe formatter automatically detects and processes:\n\n- JSX `className` and `class` attributes\n- `cn()`, `clsx()`, `cx()`, `classnames()`, `classNames()` function calls\n\n## 🐛 Troubleshooting\n\n### Debug Mode\n\nEnable debug logging to see what the formatter is doing:\n\n```bash\nnpx @damir-sh/tailwind-formatter src --debug\n```\n\n### Common Issues\n\n1. **Classes not being formatted**: Ensure they're in string literals, not template literals with expressions\n2. **Variant order unexpected**: Check your custom variant configuration\n3. **Plugin utilities not recognized**: Add them to `customUtilities` in your config\n\n## 📄 License\n\nMIT\n\n## 🙏 Contributing\n\nIssues and pull requests are welcome! Please check the existing issues before creating a new one.\n","readmeFilename":"README.md"}