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

npm install -D tailwint @tailwindcss/language-server

Usage

# 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

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:

{
  "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

- name: Lint Tailwind classes
  run: npx tailwint

Pre-commit hook

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