{"id":50120434,"url":"https://github.com/ph1p/tailwind-lint","last_synced_at":"2026-05-23T18:34:38.170Z","repository":{"id":334730558,"uuid":"1142035606","full_name":"ph1p/tailwind-lint","owner":"ph1p","description":"A command-line tool that uses the Tailwind CSS IntelliSense plugin to show linting suggestions for your Tailwind CSS classes","archived":false,"fork":false,"pushed_at":"2026-05-22T08:30:11.000Z","size":246,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T15:45:48.325Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ph1p.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-25T21:07:02.000Z","updated_at":"2026-05-22T08:29:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ph1p/tailwind-lint","commit_stats":null,"previous_names":["ph1p/tailwind-lint"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/ph1p/tailwind-lint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ph1p%2Ftailwind-lint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ph1p%2Ftailwind-lint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ph1p%2Ftailwind-lint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ph1p%2Ftailwind-lint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ph1p","download_url":"https://codeload.github.com/ph1p/tailwind-lint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ph1p%2Ftailwind-lint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33408490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-23T18:34:37.793Z","updated_at":"2026-05-23T18:34:38.160Z","avatar_url":"https://github.com/ph1p.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tailwind CSS Linter (CLI)\n\n[![](https://img.shields.io/npm/v/tailwind-lint)](https://www.npmjs.com/package/tailwind-lint) ![](https://github.com/ph1p/tailwind-lint/actions/workflows/ci.yml/badge.svg) ![](https://github.com/ph1p/tailwind-lint/actions/workflows/release.yml/badge.svg)\n\nIt just lints your Tailwind project as the IDE will do, just on the command line.\nSupports **Tailwind CSS v4** (CSS config files and Vite projects using `@tailwindcss/vite`) and **v3** (JavaScript config, legacy).\n\n## Installation\n\n```bash\n# npm\nnpm install -g tailwind-lint\n\n# pnpm\npnpm add -g tailwind-lint\n\n# npx (no installation)\nnpx tailwind-lint \"src/**/*.html\"\n\n# pnpm dlx (no installation)\npnpm dlx tailwind-lint \"src/**/*.html\"\n```\n\n## Usage\n\n```bash\n# fastest way to lint and fix issues\nnpx tailwind-lint --auto --fix\n\ntailwind-lint [options] [files...]\n```\n\n### Quick Start\n\nSimply run `tailwind-lint` in your project directory - it automatically discovers your Tailwind config and files:\n\n```bash\n# Auto-discover config and lint files\ntailwind-lint\n\n# Fix issues automatically\ntailwind-lint --fix\n\n# Verbose mode for debugging\ntailwind-lint --verbose\n```\n\n### How Auto-Discovery Works\n\n**Tailwind CSS v4:**\n\n- Finds CSS config files in common locations: `app.css`, `index.css`, `tailwind.css`, `global.css`, etc.\n- Searches in project root and subdirectories: `./`, `./src/`, `./src/styles/`, `./app/`, etc.\n- Detects `vite.config.*` files that use `@tailwindcss/vite`\n- Prefers real CSS configs when present, so custom `@theme` tokens and `@source` directives are available to diagnostics\n- Uses file patterns from `@source` directives if present\n- Falls back to default pattern: `./**/*.{js,jsx,ts,tsx,html,vue,svelte,astro,mdx}`\n- **Note:** When CSS config is in a subdirectory (e.g., `src/styles/global.css`), files are discovered from the project root\n\n**Tailwind CSS v3:**\n\n- Finds JavaScript config files: `tailwind.config.js`, `tailwind.config.cjs`, `tailwind.config.mjs`, `tailwind.config.ts`\n- Uses file patterns from the `content` array in your config\n\n### Options\n\n- `-c, --config \u003cpath\u003e` - Path to Tailwind config file (default: auto-discover)\n- `-a, --auto` - Auto-discover files from the resolved Tailwind config or CSS `@source` directives\n- `--fix` - Automatically fix problems that can be fixed\n- `--format \u003ctext|json\u003e` - Output format (`text` default, `json` for machine-readable output)\n- `-v, --verbose` - Enable verbose logging for debugging\n- `-h, --help` - Show help message\n- `--version` - Show version number\n\n### Advanced Examples\n\n```bash\n# Lint specific files only\ntailwind-lint \"src/**/*.{js,jsx,ts,tsx}\"\n\n# Specify a custom config location\ntailwind-lint --config ./config/tailwind.config.js\n\n# Scan files based on an explicit config\ntailwind-lint --config ./src/app.css\n\n# Lint and fix specific file types\ntailwind-lint \"**/*.vue\" --fix\n\n# Lint with a specific CSS config (v4)\ntailwind-lint --config ./styles/app.css\n\n# Lint a Vite-based Tailwind v4 project\ntailwind-lint --auto\n\n# Machine-readable output for LLMs/agents\ntailwind-lint --auto --format json\n```\n\n## LLM / Agent Integration\n\nUse JSON output to avoid brittle text parsing:\n\n```bash\ntailwind-lint --auto --format json\n```\n\nThe JSON payload includes:\n\n- `ok` - `true` when no errors are found\n- `summary` - counts for `errors`, `warnings`, `fixed`, `filesWithIssues`, `totalFilesProcessed`\n- `config` - resolved runtime values (`cwd`, `configPath`, `autoDiscover`, `fix`, `patterns`)\n- `files[]` - per-file diagnostics with 1-based `line`/`column` ranges\n\nOn JSON errors, the CLI keeps the same top-level shape and adds `error` so agent integrations do not need a separate parser for failure cases.\n\nTypical agent flow:\n\n1. Run `tailwind-lint --auto --format json`.\n2. If `summary.errors \u003e 0`, fail the check and surface diagnostics.\n3. If only warnings exist, optionally continue and open a cleanup task.\n4. Re-run with `--fix` when autofix is allowed.\n\n## Configuration\n\n### Tailwind CSS v4\n\nCreate a CSS config file (`app.css`, `index.css`, or `tailwind.css`):\n\n```css\n@import \"tailwindcss\";\n\n@theme {\n\t--color-primary: #3b82f6;\n}\n\n@source \"./src/**/*.{js,jsx,ts,tsx,html}\";\n```\n\nThe CLI auto-detects configs at: `app.css`, `src/app.css`, `index.css`, `src/index.css`, `tailwind.css`, `src/tailwind.css`\n\nYou can also use a Vite-based Tailwind v4 project with `@tailwindcss/vite` and no standalone Tailwind CSS config file:\n\n```ts\nimport tailwindcss from \"@tailwindcss/vite\";\nimport { defineConfig } from \"vite\";\n\nexport default defineConfig({\n\tplugins: [tailwindcss()],\n});\n```\n\nIf a real CSS config is also present, the CLI uses that file so custom `@theme` tokens and `@source` directives are available to diagnostics.\n\n### Workspace Settings\n\nThe CLI also reads Tailwind workspace settings from common editor config files so extraction behavior can match your editor more closely.\n\nSupported locations:\n\n- `.zed/settings.json`\n- `.vscode/settings.json`\n\nSupported settings:\n\n- `classFunctions`\n- `experimental.classRegex`\n- `classAttributes`\n- `includeLanguages`\n- `files.exclude`\n- `lint`\n\nZed format:\n\n```json\n{\n\t\"lsp\": {\n\t\t\"tailwindcss-language-server\": {\n\t\t\t\"settings\": {\n\t\t\t\t\"classFunctions\": [\"cva\", \"cx\"],\n\t\t\t\t\"experimental\": {\n\t\t\t\t\t\"classRegex\": [\"tw=\\\"([^\\\"]*)\\\"\"]\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\nVS Code format:\n\n```json\n{\n\t\"tailwindCSS.classFunctions\": [\"cva\", \"cx\"],\n\t\"tailwindCSS.experimental\": {\n\t\t\"classRegex\": [\"tw=\\\"([^\\\"]*)\\\"\"]\n\t}\n}\n```\n\n### Tailwind CSS v3 (Legacy)\n\nCreate a JavaScript config file (`tailwind.config.js`):\n\n```javascript\n/** @type {import('tailwindcss').Config} */\nmodule.exports = {\n\tcontent: [\"./src/**/*.{js,jsx,ts,tsx}\"],\n\ttheme: {\n\t\textend: {},\n\t},\n\tplugins: [],\n};\n```\n\n## Autofix\n\nUse `--fix` to automatically resolve issues:\n\n- **Canonical class suggestions** (v4) - Replaces arbitrary values with standard classes\n- **Recommended variant order** (v3 \u0026 v4) - Reorders variants correctly\n\nFiles are written atomically with multiple iterations to ensure all fixes are applied. The autofix process has a safety limit of 100 iterations per file to prevent infinite loops.\n\n## Features\n\n**Core (v3 \u0026 v4):**\n\n- CSS Conflicts - Detects when multiple classes apply the same CSS properties (e.g., `block flex`, `text-left text-center`) - **Note:** Works reliably in v4, limited support in v3 - no autofix\n- Invalid @apply Usage - Validates if a class can be used with `@apply`\n- Invalid @screen References - Detects references to non-existent breakpoints\n- Invalid Config Paths - Validates references in `config()` and `theme()` functions\n- Invalid @tailwind Directives - Validates `@tailwind` layer values\n- Recommended Variant Order - Suggests preferred ordering of variants\n- Blocklisted Classes - Detects usage of blocklisted classes\n- Autofix - Automatically fix issues with `--fix` flag\n- Quoted class string extraction - Lints class-like strings in common helper patterns, not only direct `class` and `className` attributes\n\n**v4-Specific:**\n\n- Canonical Class Suggestions - Suggests shorthand equivalents for arbitrary values (e.g., `top-[60px]` → `top-15`)\n- Invalid @source Directives - Validates `@source` directive paths\n- Full theme loading - Automatically loads Tailwind's default theme\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build for production\npnpm build\n\n# Development mode (watch)\npnpm dev\n\n# Run tests\npnpm test\n\n# Run tests in watch mode\npnpm test:watch\n\n# Run tests with coverage\npnpm test:coverage\n\n# Format and lint code\npnpm format\n\n# Check code without fixing\npnpm lint\n\n# Preview next version locally (no publish)\npnpm release:dry\n```\n\n## Releases\n\nReleases are automated with Semantic Release on pushes to `main`.\n\n- Version bump is derived from Conventional Commits.\n- npm release and GitHub release are generated automatically.\n- npm publish uses npm Trusted Publishing (OIDC), no `NPM_TOKEN` required.\n\nCommit examples:\n\n- `feat: add json output mode` -\u003e minor release\n- `fix: resolve v4 config discovery in monorepos` -\u003e patch release\n- `feat: drop Node 20 support` + commit body `BREAKING CHANGE: Node 20 is no longer supported` -\u003e major release\n- `perf: speed up config discovery` -\u003e patch release\n- `docs: update readme` -\u003e no release\n\n`pnpm release:dry` runs against the local repo metadata (`--repository-url .`) so it does not require GitHub remote access.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fph1p%2Ftailwind-lint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fph1p%2Ftailwind-lint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fph1p%2Ftailwind-lint/lists"}