tailwind + lint = tailwint ~≈∼〜 a tiny linter for your Tailwind CSS
---
The same diagnostics VS Code shows — but from the command line. Catches class conflicts, suggests canonical rewrites, and applies available quick fixes. Powered by the official `@tailwindcss/language-server` — not a custom parser, not a regex hack.
**Works with Tailwind CSS v4.**
## What it catches
tailwint detects two categories of issues:
**⚡ Conflicts** — classes that apply the same CSS properties and compete in the CSS cascade:
```
⚡ 3:21 conflict 'w-full' applies the same CSS properties as 'w-auto'
⚡ 3:28 conflict 'w-auto' applies the same CSS properties as 'w-full'
```
**○ Canonical** — classes that can be written in a shorter or more idiomatic form:
```
○ 3:21 canonical The class `flex-shrink-0` can be written as `shrink-0`
○ 3:35 canonical The class `z-[1]` can be written as `z-1`
○ 3:41 canonical The class `min-w-[200px]` can be written as `min-w-50`
```
## Install
```bash
npm install -D tailwint @tailwindcss/language-server
```
## Usage
```bash
# Scan default file types (tsx, jsx, html, vue, svelte, astro, mdx, css)
npx tailwint
# Scan specific files
npx tailwint "src/**/*.tsx"
# Apply available quick fixes
npx tailwint --fix
npx tailwint -f
# Fix specific files
npx tailwint --fix "app/**/*.tsx"
# Exclude generated files (repeat --ignore for additional patterns)
npx tailwint --ignore "release/**"
# Adjust the language-server wait limit, in milliseconds
npx tailwint --timeout 60000
# Verbose LSP logging
DEBUG=1 npx tailwint
```
## Example output
```
~≈∼〜~≈∼〜~≈∼〜~≈∼〜~≈~ tailwint ~∼〜~≈∼〜~≈∼〜~≈∼〜~≈∼~
tailwind css linter // powered by the official lsp
✔ language server ready ~≈∼〜~≈∼〜~≈∼〜~≈∼〜~≈∼〜~≈∼〜~
✔ sent 42 files to lsp ~≈∼〜~≈∼〜~≈∼〜~≈∼〜~≈∼〜~≈∼〜~~
✔ 42/42 files received ~≈∼〜~≈∼〜~≈∼〜~≈∼〜~≈∼〜~≈∼〜~~
42 files scanned // 8 conflicts │ 12 canonical
┌ components/Card.tsx (3)
⚡ 5:21 conflict 'w-full' applies the same CSS properties as 'w-auto'
○ 5:35 canonical The class `flex-shrink-0` can be written as `shrink-0`
○ 5:49 canonical The class `z-[1]` can be written as `z-1`
└~≈∼
≈∼〜~≈ ✘ FAIL 20 issues in 3 files 2.1s ≈∼〜~≈
run with --fix to auto-fix
```
With `--fix`:
```
⚙ FIX conflicts first, then canonical
✔ ┃━━━━━━━━━━━━━━━━━━┃ Card.tsx 3 fixed
✔ ┃━━━━━━━━━━━━━━━━━━┃ Header.tsx 12 fixed
✔ ┃━━━━━━━━━━━━━━━━━━┃ Sidebar.tsx 5 fixed
≈∼〜~≈ ✔ FIXED 20 of 20 issues across 3 files 3.4s ≈∼〜~≈
```
## Supported file types
| Extension | Language ID | Notes |
| --------- | --------------- | ----------------------------------------- |
| `.tsx` | typescriptreact | React / Next.js components |
| `.jsx` | javascriptreact | React components |
| `.html` | html | Static HTML files |
| `.vue` | html | Vue single-file components |
| `.svelte` | html | Svelte components |
| `.astro` | html | Astro components |
| `.mdx` | mdx | MDX documents |
| `.css` | css | `@apply` directives and Tailwind at-rules |
## Tailwind v4 support
tailwint fully supports Tailwind CSS v4 features:
- **Opacity shorthand** — `bg-red-500/50`, `text-blue-500/75`
- **`size-*` utility** — `size-10`, `size-full`
- **Container queries** — `@container`, `@lg:flex`, `@md:grid`
- **`has-*` / `not-*` variants** — `has-checked:bg-blue-500`, `not-disabled:opacity-100`
- **`aria-*` variants** — `aria-expanded:bg-blue-500`, `aria-disabled:opacity-50`
- **`data-*` variants** — `data-[state=open]:bg-blue-500`
- **`supports-*` variants** — `supports-[display:grid]:grid`
- **`forced-colors` variant** — `forced-colors:bg-[ButtonFace]`
- **Logical properties** — `ms-4`, `me-4`, `ps-4`, `pe-4`
- **Text wrap utilities** — `text-balance`, `text-pretty`, `text-nowrap`
- **Named groups/peers** — `group/sidebar`, `group-hover/sidebar:bg-blue-500`
- **CSS-first config** — `@import "tailwindcss"` with `@theme` directive
## Programmatic API
```ts
import { run } from "tailwint";
const exitCode = await run({
patterns: ["src/**/*.tsx"],
fix: true,
cwd: "/path/to/project",
timeoutMs: 30_000,
});
```
Call `run()` sequentially. A concurrent call returns `2` without interrupting the active scan.
### Options
| Option | Type | Default | Description |
| ---------- | ---------- | -------------------------------------------------- | -------------------------------------------------- |
| `patterns` | `string[]` | `["**/*.{tsx,jsx,html,vue,svelte,astro,mdx,css}"]` | Glob patterns for files to scan |
| `ignore` | `string[]` | `[]` | Additional exclusions, relative to `cwd`, alongside built-in output/cache exclusions |
| `fix` | `boolean` | `false` | Auto-fix issues using LSP code actions |
| `timeoutMs` | `number` | `30000` | Maximum wait per LSP operation; initial diagnostics share one deadline. Integer 1–2147483647 |
| `cwd` | `string` | `process.cwd()` | Working directory for glob resolution and LSP root |
### Exports
| Export | Description |
| ---------------------------- | ---------------------------------- |
| `run(options?)` | Run the linter, returns exit code |
| `applyEdits(content, edits)` | Apply LSP text edits to a string |
| `TextEdit` | TypeScript type for LSP text edits |
## Configuration
Tailwint reads `.vscode/settings.json` from the working directory and forwards
its settings to the language server. JSONC line/block comments and trailing
commas are supported; malformed settings cause exit `2` rather than silently
using default lint rules. For example:
```jsonc
{
"tailwindCSS.lint.cssConflict": "error",
"tailwindCSS.experimental.classRegex": ["tw`([^`]*)`"],
}
```
Language-server installs hoisted into a parent workspace or installed beside
Tailwint are resolved automatically. Windows file patterns may use either slash
style. Unknown CLI options exit `2`; use `--` before an option-like filename.
## CI integration
tailwint exits with meaningful codes for CI pipelines:
| Exit code | Meaning |
| --------- | ---------------------------------------------------------------- |
| `0` | No issues found, or all issues fixed with `--fix` |
| `1` | Issues found, or unfixable issues remain after `--fix` |
| `2` | Incomplete scan or fatal error (missing project, timeout, server failure) |
A timeout or missing Tailwind project is an incomplete scan, so it exits with `2`
instead of reporting “all clear.” Check the Tailwind configuration with
`DEBUG=1 npx tailwint`. Narrow the patterns if they include files outside your
Tailwind projects, or use `--ignore "release/**"` to exclude generated artifacts.
For unusually slow projects, increase `--timeout 60000` (API: `timeoutMs`). A
smaller value fails faster on a stalled server. This is a maximum wait, not a
delay: successful operations finish as soon as their responses arrive.
The initial hover readiness request, project lookups, and diagnostic publications
share one timeout budget, rather than restarting it at each stage. The LSP
initialize handshake and subsequent autofix requests/publications each have
their own budget, so this is not a total CLI runtime limit. Removing the limit
would allow an unresponsive server to hang CI indefinitely. Failed fix validation
leaves that file unchanged.
### GitHub Actions
```yaml
- name: Lint Tailwind classes
run: npx tailwint
```
### Pre-commit hook
```bash
npx tailwint --fix && git add -u
```
## How it works
1. **Boot** — spawns `@tailwindcss/language-server` over stdio
2. **Pre-scan** — skips CSS files with no Tailwind signals
3. **Open** — sends matched files to the server via `textDocument/didOpen`
4. **Analyze** — waits for workspace initialization using the server's `textDocument/hover` handler, checks each opened file with `@/tailwindCSS/getProject`, then waits for every file's `textDocument/publishDiagnostics` notification. CSS entry points need not be in the requested glob. Gaps between notifications do not end the scan.
5. **Report** — collects diagnostics, categorizes as conflicts or canonical
6. **Fix** _(if `--fix`)_ — requests `textDocument/codeAction` quickfixes and repeats until diagnostics clear or no supported fix changes the file
There is no fixed pass limit: fixing a conflict can reveal another issue. Repeated
fix cycles and invalid edits fail with exit `2`, preserving that file on disk.
Overlapping actions are deferred until fresh diagnostics, and files changed
during the scan are not overwritten. Actions requiring multiple files or
commands are left unresolved; remaining diagnostics produce exit `1`.
## Requirements
- Node.js 18+
- `@tailwindcss/language-server` >= 0.14.0 (peer dependency)
## License
MIT