tailwind-check

Headless Tailwind v4 semantic linting for application code and CSS.

tailwind-check loads the checked project's Tailwind entry CSS, builds a Tailwind design system in memory, and reports semantic diagnostics for class usage and Tailwind CSS directives.

Requirements

• Node 24+
• Tailwind v4 in the project being checked
• a Tailwind entry CSS file such as src/app.css

tailwind-check resolves tailwindcss from the checked project.

CLI

tailwind-check
tailwind-check --changed
tailwind-check --changed --base origin/main
tailwind-check --entry src/app.css
tailwind-check src/components/button.tsx src/app.css

Options:

• --cwd <path> project root to lint
• --config <path> explicit config file
• --entry <path> Tailwind entry CSS override
• --changed only lint changed files
• --base <ref> include <ref>...HEAD in changed-file mode

Config

Auto-discovered config files:

• tailwind-check.json
• .tailwind-check.json

Example:

{
  "entry": "src/app.css",
  "roots": ["src"],
  "extensions": [".ts", ".tsx", ".js", ".jsx", ".css"],
  "classAttributes": ["class", "className"],
  "classFunctions": ["cn", "clsx", "cva"],
  "enableClassList": true
}

Supported extraction surfaces

• class="..."
• className="..."
• class={...} static string segments
• cn(...)
• clsx(...)
• cva(...)
• classList={{ ... }} static object keys
• @apply ...

Diagnostics

• tailwind/cssConflict
• tailwind/suggestCanonicalClasses
• tailwind/invalidApply
• tailwind/invalidTailwindDirective
• tailwind/invalidSourceDirective
• tailwind/deprecatedAtRule
• tailwind/invalidConfigPath

Output

path/to/file.tsx:12:5 tailwind/<rule> <message>
  suggestion: <replacement>

Exit codes:

• 0 no diagnostics
• 1 diagnostics found
• 2 infrastructure or config failure

Attribution

tailwind-check is inspired by and partially adapted from Tailwind CSS IntelliSense, which is licensed under the MIT License by Tailwind Labs, Inc. See THIRD_PARTY_NOTICES.md for details.

Library API

import { formatDiagnostic, runTailwindCheck } from "@earendil-works/tailwind-check"

const result = await runTailwindCheck({
  cwd: process.cwd(),
  entry: "src/app.css",
  changed: true,
})

for (const diagnostic of result.diagnostics) {
  console.error(formatDiagnostic(result.cwd, diagnostic))
}

runTailwindCheck(...) returns:

• cwd
• configPath
• entryPath
• filePaths
• diagnostics
• scanMode