@tailwind-ts/eslint-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eslint-plugin-tailwind-ts contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @tailwind-ts/eslint-plugin
+
+ESLint plugin for detecting invalid Tailwind CSS v4 class names — typos, undefined utilities, and bad `@apply` usage — in JavaScript, TypeScript, CSS, and Vue projects.
+
+## Features
+
+- **`cva()` variant validation** — lints base classes and variant values inside `class-variance-authority` configs
+- **CSS `@apply` linting** — catches invalid classes inside `.css` files
+- **Typo suggestions** — reports `Did you mean "flex"?` when a close match exists in your design system
+- **Import-aware helpers** — validates `cn()` / `clsx()` even when imported from `@/lib/utils`
+- **Vue `:class` support** — lints static and object-style class bindings in `.vue` files
+- **More helpers** — `tv()` (tailwind-variants) added to defaults
+- **Config presets** — `react`, `vue`, and `css` presets for faster setup
+- **Multi-entry CSS** — `cssConfigPath` accepts a string or array for monorepos
+- **Batch validation** — faster lint runs via batched worker calls and shared design-system cache
+- Tailwind CSS v4 support via `@tailwindcss/node`
+- ESLint flat config (`eslint.config.js`)
+- TypeScript-native settings with exported `PluginSettings` type
+
+## Requirements
+
+- Node.js `>= 20.19.0`
+- ESLint `^9.0.0 || ^10.0.0`
+- Tailwind CSS `^4.0.0`
+- `@tailwindcss/node` `^4.0.0`
+- `vue-eslint-parser` (optional, for Vue SFC support)
+
+## Installation
+
+```bash
+npm install -D eslint @tailwind-ts/eslint-plugin tailwindcss @tailwindcss/node
+```
+
+For Vue projects:
+
+```bash
+npm install -D vue-eslint-parser
+```
+
+## Quick start
+
+```js
+// eslint.config.js
+import tailwindTs from "@tailwind-ts/eslint-plugin";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  {
+    extends: [tailwindTs.configs.recommended],
+    settings: {
+      tailwindTs: {
+        cssConfigPath: "./src/styles/tailwind.css",
+      },
+    },
+  },
+]);
+```
+
+Your CSS entry file should import Tailwind v4:
+
+```css
+@import "tailwindcss";
+```
+
+## Config presets
+
+```js
+import tailwindTs from "@tailwind-ts/eslint-plugin";
+
+export default [
+  {
+    extends: [tailwindTs.configs.react],
+    settings: {
+      tailwindTs: { cssConfigPath: "./src/styles/tailwind.css" },
+    },
+  },
+];
+```
+
+| Preset | Files | Notes |
+|--------|-------|-------|
+| `recommended` | `*.{js,jsx,ts,tsx}` | Default JSX + helper validation |
+| `react` | Same as recommended | Alias for React/Next.js apps |
+| `vue` | `*.{vue,js,ts}` | Enables `:class` parsing (requires `vue-eslint-parser`) |
+| `css` | `**/*.css` | Enables `@apply` validation |
+
+## Rules
+
+| Rule | Description | Default |
+|------|-------------|---------|
+| [`no-invalid-classname`](./docs/rules/no-invalid-classname.md) | Disallow invalid Tailwind classes in JSX, helpers, and Vue bindings | `error` |
+| [`no-invalid-apply`](./docs/rules/no-invalid-apply.md) | Disallow invalid classes in CSS `@apply` directives | `error` |
+
+## Settings
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cssConfigPath` | `string \| string[]` | — | **Required.** Tailwind v4 CSS entry path(s) |
+| `attributes` | `string[]` | `["class", "className"]` | JSX/Vue attributes to lint |
+| `functions` | `string[]` | `["cn", "clsx", "cva", "tv", "twMerge", "twJoin"]` | Helper calls to lint |
+| `whitelist` | `string[]` | `[]` | Regex patterns for allowed non-Tailwind classes |
+| `suggestSimilarClasses` | `boolean` | `true` | Include "Did you mean …?" hints for typos |
+
+### Typesafe settings
+
+```js
+settings: {
+  tailwindTs:
+    /** @type {import('@tailwind-ts/eslint-plugin').PluginSettings} */
+    ({
+      cssConfigPath: "./src/styles/tailwind.css",
+    }),
+},
+```
+
+## Limitations
+
+- Dynamic template interpolation (e.g. `` className={`p-${size}`} ``) is not validated
+- Vue support requires `vue-eslint-parser` in your ESLint config
+
+## License
+
+MIT

package/docs/rules/no-invalid-apply.md

@@ -0,0 +1,37 @@
+# no-invalid-apply
+
+Disallow invalid Tailwind CSS class names inside `@apply` directives in CSS files.
+
+## Rule details
+
+Parses `@apply` blocks in `*.css` files and validates each class token against your Tailwind v4 design system.
+
+### Examples
+
+```css
+/* bad */
+.card {
+  @apply flexs items-center rounded-lg;
+}
+
+/* good */
+.card {
+  @apply flex items-center rounded-lg;
+}
+```
+
+## Options
+
+```ts
+{
+  whitelist?: string[];
+}
+```
+
+## Enable
+
+Use the `css` preset or enable manually:
+
+```js
+extends: [tailwindTs.configs.css]
+```

package/docs/rules/no-invalid-classname.md

@@ -0,0 +1,39 @@
+# `no-invalid-classname`
+
+Disallow invalid or typo Tailwind CSS class names in JSX attributes and common utility functions.
+
+## Rule details
+
+This rule validates class strings against your project's Tailwind CSS v4 design system loaded from `settings.tailwindTs.cssConfigPath`.
+
+### Examples
+
+```jsx
+// bad
+<div className="flexs items-center" />
+
+// good
+<div className="flex items-center" />
+```
+
+```ts
+// bad
+const cls = cn("p-4", "text-lgg");
+
+// good
+const cls = cn("p-4", "text-lg");
+```
+
+## Options
+
+```ts
+{
+  whitelist?: string[];
+}
+```
+
+Regex patterns for classes that should be ignored by this rule.
+
+## Shared settings
+
+This rule uses `settings.tailwindTs` from the plugin. See the package README for the full settings reference.

package/lib/index.cjs

@@ -0,0 +1,370 @@
+'use strict';
+
+const utils = require('@typescript-eslint/utils');
+const node_fs = require('node:fs');
+const node_path = require('node:path');
+const node_url = require('node:url');
+const synckit = require('synckit');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const name = "@tailwind-ts/eslint-plugin";
+const version = "0.1.0";
+const packageJson = {
+	name: name,
+	version: version};
+
+function isStringLiteral(node) {
+  return node.type === "Literal" && typeof node.value === "string";
+}
+function collectFromExpression(node, ignoredKeys, functionNames, literals) {
+  if (!node || node.type === "SpreadElement") {
+    return;
+  }
+  if (isStringLiteral(node)) {
+    literals.push({ value: node.value, node });
+    return;
+  }
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0) {
+    const value = node.quasis.map((quasi) => quasi.value.cooked ?? "").join("");
+    literals.push({ value, node });
+    return;
+  }
+  if (node.type === "LogicalExpression") {
+    collectFromExpression(node.left, ignoredKeys, functionNames, literals);
+    collectFromExpression(node.right, ignoredKeys, functionNames, literals);
+    return;
+  }
+  if (node.type === "ConditionalExpression") {
+    collectFromExpression(node.consequent, ignoredKeys, functionNames, literals);
+    collectFromExpression(node.alternate, ignoredKeys, functionNames, literals);
+    return;
+  }
+  if (node.type === "ArrayExpression") {
+    for (const element of node.elements) {
+      collectFromExpression(element, ignoredKeys, functionNames, literals);
+    }
+    return;
+  }
+  if (node.type === "ObjectExpression") {
+    for (const property of node.properties) {
+      if (property.type === "Property") {
+        if (property.key.type === "Identifier") {
+          if (ignoredKeys.has(property.key.name)) {
+            continue;
+          }
+        }
+        collectFromExpression(
+          property.value,
+          ignoredKeys,
+          functionNames,
+          literals
+        );
+      }
+    }
+    return;
+  }
+  if (node.type === "CallExpression" && node.callee.type === "Identifier") {
+    if (functionNames.has(node.callee.name)) {
+      for (const argument of node.arguments) {
+        collectFromExpression(
+          argument,
+          ignoredKeys,
+          functionNames,
+          literals
+        );
+      }
+    }
+  }
+}
+function extractClassLiteralsFromJsxAttribute(attribute, options) {
+  const literals = [];
+  const ignoredKeys = new Set(options.ignoredKeys);
+  const functionNames = new Set(options.functions);
+  if (!attribute.value) {
+    return literals;
+  }
+  if (attribute.value.type === "Literal" && typeof attribute.value.value === "string") {
+    literals.push({ value: attribute.value.value, node: attribute.value });
+    return literals;
+  }
+  if (attribute.value.type === "JSXExpressionContainer") {
+    collectFromExpression(
+      attribute.value.expression,
+      ignoredKeys,
+      functionNames,
+      literals
+    );
+  }
+  return literals;
+}
+function extractClassLiteralsFromCallExpression(callExpression, options) {
+  if (callExpression.callee.type !== "Identifier") {
+    return [];
+  }
+  const functionNames = new Set(options.functions);
+  if (!functionNames.has(callExpression.callee.name)) {
+    return [];
+  }
+  const literals = [];
+  const ignoredKeys = new Set(options.ignoredKeys);
+  for (const argument of callExpression.arguments) {
+    collectFromExpression(
+      argument,
+      ignoredKeys,
+      functionNames,
+      literals
+    );
+  }
+  return literals;
+}
+
+const DEFAULT_ATTRIBUTES = ["class", "className"];
+const DEFAULT_FUNCTIONS = [
+  "cn",
+  "clsx",
+  "cva",
+  "twMerge",
+  "twJoin"
+];
+const DEFAULT_IGNORED_KEYS = [
+  "defaultVariants",
+  "compoundVariants",
+  "compoundSlots"
+];
+function toRegExp(pattern) {
+  return new RegExp(pattern);
+}
+function parsePluginSettings(settings) {
+  if (!settings?.cssConfigPath) {
+    throw new Error(
+      "eslint-plugin-tailwind-ts: settings.tailwindTs.cssConfigPath is required (path to your Tailwind v4 CSS entry file)."
+    );
+  }
+  const whitelist = (settings.whitelist ?? []).map(toRegExp);
+  return {
+    cssConfigPath: settings.cssConfigPath,
+    attributes: settings.attributes ?? [...DEFAULT_ATTRIBUTES],
+    functions: settings.functions ?? [...DEFAULT_FUNCTIONS],
+    whitelist,
+    ignoredKeys: settings.ignoredKeys ?? [...DEFAULT_IGNORED_KEYS]
+  };
+}
+function isWhitelisted(className, whitelist) {
+  return whitelist.some((pattern) => pattern.test(className));
+}
+function splitClassTokens(classString) {
+  return classString.trim().split(/\s+/).filter(Boolean);
+}
+
+const CACHE_TTL_MS = 10 * 60 * 1e3;
+const resultCache = /* @__PURE__ */ new Map();
+const compilerMtimeCache = /* @__PURE__ */ new Map();
+function resolveWorkerPath() {
+  const dir = node_path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))));
+  const candidates = [
+    node_path.join(dir, "../worker/validate.mjs"),
+    node_path.join(dir, "../../worker/validate.mjs")
+  ];
+  for (const candidate of candidates) {
+    if (node_fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error("eslint-plugin-tailwind-ts: validation worker not found");
+}
+const runValidate = synckit.createSyncFn(resolveWorkerPath());
+function resolveCssConfigPath(cssConfigPath, cwd) {
+  return node_path.isAbsolute(cssConfigPath) ? cssConfigPath : node_path.resolve(cwd, cssConfigPath);
+}
+function getCssMtime(cssConfigPath) {
+  return node_fs.statSync(cssConfigPath).mtimeMs;
+}
+function isCompilerCacheValid(cssConfigPath) {
+  const cached = compilerMtimeCache.get(cssConfigPath);
+  if (!cached) {
+    return false;
+  }
+  try {
+    return cached.mtimeMs === getCssMtime(cssConfigPath);
+  } catch {
+    return false;
+  }
+}
+function touchCompilerCache(cssConfigPath) {
+  compilerMtimeCache.set(cssConfigPath, {
+    mtimeMs: getCssMtime(cssConfigPath)
+  });
+}
+function invalidateResultCacheForConfig(cssConfigPath) {
+  for (const key of resultCache.keys()) {
+    if (key.startsWith(`${cssConfigPath}::`)) {
+      resultCache.delete(key);
+    }
+  }
+}
+function validateTailwindClass(request) {
+  const resolvedCssPath = resolveCssConfigPath(
+    request.cssConfigPath,
+    request.cwd
+  );
+  if (!isCompilerCacheValid(resolvedCssPath)) {
+    invalidateResultCacheForConfig(resolvedCssPath);
+    touchCompilerCache(resolvedCssPath);
+  }
+  const cacheKey = `${resolvedCssPath}::${request.className}`;
+  const cached = resultCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now()) {
+    return { valid: cached.valid };
+  }
+  const response = runValidate({
+    cssConfigPath: resolvedCssPath,
+    className: request.className,
+    cwd: request.cwd
+  });
+  resultCache.set(cacheKey, {
+    valid: response.valid,
+    expiresAt: Date.now() + CACHE_TTL_MS
+  });
+  return response;
+}
+
+const RULE_NAME = "no-invalid-classname";
+const noInvalidClassname = utils.ESLintUtils.RuleCreator.withoutDocs({
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow invalid or typo Tailwind CSS class names in JSX and utility functions."
+    },
+    schema: [
+      {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          whitelist: {
+            type: "array",
+            items: { type: "string" }
+          }
+        }
+      }
+    ],
+    messages: {
+      invalidClass: 'Class "{{ className }}" is not a valid Tailwind CSS class.'
+    }
+  },
+  defaultOptions: [{}],
+  create(context) {
+    const pluginSettings = context.settings.tailwindTs;
+    let resolvedSettings;
+    try {
+      resolvedSettings = parsePluginSettings(pluginSettings);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Invalid plugin settings.";
+      context.report({
+        loc: { line: 1, column: 0 },
+        message
+      });
+      return {};
+    }
+    const ruleWhitelist = (context.options[0]?.whitelist ?? []).map(
+      (pattern) => new RegExp(pattern)
+    );
+    const whitelist = [...resolvedSettings.whitelist, ...ruleWhitelist];
+    const attributeNames = new Set(resolvedSettings.attributes);
+    const cwd = context.cwd ?? process.cwd();
+    function reportInvalidClasses(literals) {
+      for (const literal of literals) {
+        for (const className of splitClassTokens(literal.value)) {
+          if (isWhitelisted(className, whitelist)) {
+            continue;
+          }
+          const result = validateTailwindClass({
+            cssConfigPath: resolvedSettings.cssConfigPath,
+            className,
+            cwd
+          });
+          if (!result.valid) {
+            context.report({
+              node: literal.node,
+              messageId: "invalidClass",
+              data: { className }
+            });
+          }
+        }
+      }
+    }
+    return {
+      JSXAttribute(node) {
+        if (node.name.type !== "JSXIdentifier" || !attributeNames.has(node.name.name)) {
+          return;
+        }
+        reportInvalidClasses(
+          extractClassLiteralsFromJsxAttribute(node, {
+            functions: resolvedSettings.functions,
+            ignoredKeys: resolvedSettings.ignoredKeys
+          })
+        );
+      },
+      CallExpression(node) {
+        reportInvalidClasses(
+          extractClassLiteralsFromCallExpression(node, {
+            functions: resolvedSettings.functions,
+            ignoredKeys: resolvedSettings.ignoredKeys
+          })
+        );
+      }
+    };
+  }
+});
+
+const createConfig = (rules) => {
+  const result = {};
+  for (const [ruleName, value] of Object.entries(rules)) {
+    result[`tailwind-ts/${ruleName}`] = value;
+  }
+  return result;
+};
+const plugin = {
+  meta: {
+    name: packageJson.name,
+    version: packageJson.version
+  },
+  configs: {
+    get recommended() {
+      return sharedConfigs.recommended;
+    }
+  },
+  rules: {
+    [RULE_NAME]: noInvalidClassname
+  }
+};
+const recommendedRules = {
+  [RULE_NAME]: "error"
+};
+const configBase = {
+  name: "tailwind-ts/base",
+  plugins: {
+    "tailwind-ts": plugin
+  },
+  settings: {
+    tailwindTs: {}
+  },
+  files: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
+  languageOptions: {
+    parserOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      ecmaFeatures: {
+        jsx: true
+      }
+    }
+  }
+};
+const sharedConfigs = {
+  recommended: {
+    ...configBase,
+    name: "tailwind-ts/recommended",
+    rules: createConfig(recommendedRules)
+  }
+};
+
+module.exports = plugin;

package/lib/index.d.cts

@@ -0,0 +1,33 @@
+import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
+import { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
+
+interface PluginSettings {
+    /** Required. Path to Tailwind v4 CSS entry, e.g. "./src/styles/tailwind.css" */
+    cssConfigPath: string;
+    /** Attributes/props that may contain Tailwind CSS classes */
+    attributes?: string[];
+    /** Functions whose arguments will be parsed for class strings */
+    functions?: string[];
+    /** Whitelist regex patterns for non-Tailwind classes */
+    whitelist?: string[];
+    /** Keys to ignore in object expressions */
+    ignoredKeys?: string[];
+}
+
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    configs: {
+        readonly recommended: FlatConfig.Config | FlatConfig.ConfigArray;
+    };
+    rules: {
+        "no-invalid-classname": _typescript_eslint_utils_ts_eslint.RuleModule<"invalidClass", [({
+            whitelist?: string[];
+        } | undefined)?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener>;
+    };
+};
+
+export = plugin;
+export type { PluginSettings };

package/lib/index.d.mts

@@ -0,0 +1,33 @@
+import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
+import { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
+
+interface PluginSettings {
+    /** Required. Path to Tailwind v4 CSS entry, e.g. "./src/styles/tailwind.css" */
+    cssConfigPath: string;
+    /** Attributes/props that may contain Tailwind CSS classes */
+    attributes?: string[];
+    /** Functions whose arguments will be parsed for class strings */
+    functions?: string[];
+    /** Whitelist regex patterns for non-Tailwind classes */
+    whitelist?: string[];
+    /** Keys to ignore in object expressions */
+    ignoredKeys?: string[];
+}
+
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    configs: {
+        readonly recommended: FlatConfig.Config | FlatConfig.ConfigArray;
+    };
+    rules: {
+        "no-invalid-classname": _typescript_eslint_utils_ts_eslint.RuleModule<"invalidClass", [({
+            whitelist?: string[];
+        } | undefined)?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener>;
+    };
+};
+
+export { plugin as default };
+export type { PluginSettings };

package/lib/index.d.ts

@@ -0,0 +1,33 @@
+import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
+import { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
+
+interface PluginSettings {
+    /** Required. Path to Tailwind v4 CSS entry, e.g. "./src/styles/tailwind.css" */
+    cssConfigPath: string;
+    /** Attributes/props that may contain Tailwind CSS classes */
+    attributes?: string[];
+    /** Functions whose arguments will be parsed for class strings */
+    functions?: string[];
+    /** Whitelist regex patterns for non-Tailwind classes */
+    whitelist?: string[];
+    /** Keys to ignore in object expressions */
+    ignoredKeys?: string[];
+}
+
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    configs: {
+        readonly recommended: FlatConfig.Config | FlatConfig.ConfigArray;
+    };
+    rules: {
+        "no-invalid-classname": _typescript_eslint_utils_ts_eslint.RuleModule<"invalidClass", [({
+            whitelist?: string[];
+        } | undefined)?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener>;
+    };
+};
+
+export = plugin;
+export type { PluginSettings };

package/lib/index.mjs

@@ -0,0 +1,367 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+import { existsSync, statSync } from 'node:fs';
+import { dirname, join, isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createSyncFn } from 'synckit';
+
+const name = "@tailwind-ts/eslint-plugin";
+const version = "0.1.0";
+const packageJson = {
+	name: name,
+	version: version};
+
+function isStringLiteral(node) {
+  return node.type === "Literal" && typeof node.value === "string";
+}
+function collectFromExpression(node, ignoredKeys, functionNames, literals) {
+  if (!node || node.type === "SpreadElement") {
+    return;
+  }
+  if (isStringLiteral(node)) {
+    literals.push({ value: node.value, node });
+    return;
+  }
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0) {
+    const value = node.quasis.map((quasi) => quasi.value.cooked ?? "").join("");
+    literals.push({ value, node });
+    return;
+  }
+  if (node.type === "LogicalExpression") {
+    collectFromExpression(node.left, ignoredKeys, functionNames, literals);
+    collectFromExpression(node.right, ignoredKeys, functionNames, literals);
+    return;
+  }
+  if (node.type === "ConditionalExpression") {
+    collectFromExpression(node.consequent, ignoredKeys, functionNames, literals);
+    collectFromExpression(node.alternate, ignoredKeys, functionNames, literals);
+    return;
+  }
+  if (node.type === "ArrayExpression") {
+    for (const element of node.elements) {
+      collectFromExpression(element, ignoredKeys, functionNames, literals);
+    }
+    return;
+  }
+  if (node.type === "ObjectExpression") {
+    for (const property of node.properties) {
+      if (property.type === "Property") {
+        if (property.key.type === "Identifier") {
+          if (ignoredKeys.has(property.key.name)) {
+            continue;
+          }
+        }
+        collectFromExpression(
+          property.value,
+          ignoredKeys,
+          functionNames,
+          literals
+        );
+      }
+    }
+    return;
+  }
+  if (node.type === "CallExpression" && node.callee.type === "Identifier") {
+    if (functionNames.has(node.callee.name)) {
+      for (const argument of node.arguments) {
+        collectFromExpression(
+          argument,
+          ignoredKeys,
+          functionNames,
+          literals
+        );
+      }
+    }
+  }
+}
+function extractClassLiteralsFromJsxAttribute(attribute, options) {
+  const literals = [];
+  const ignoredKeys = new Set(options.ignoredKeys);
+  const functionNames = new Set(options.functions);
+  if (!attribute.value) {
+    return literals;
+  }
+  if (attribute.value.type === "Literal" && typeof attribute.value.value === "string") {
+    literals.push({ value: attribute.value.value, node: attribute.value });
+    return literals;
+  }
+  if (attribute.value.type === "JSXExpressionContainer") {
+    collectFromExpression(
+      attribute.value.expression,
+      ignoredKeys,
+      functionNames,
+      literals
+    );
+  }
+  return literals;
+}
+function extractClassLiteralsFromCallExpression(callExpression, options) {
+  if (callExpression.callee.type !== "Identifier") {
+    return [];
+  }
+  const functionNames = new Set(options.functions);
+  if (!functionNames.has(callExpression.callee.name)) {
+    return [];
+  }
+  const literals = [];
+  const ignoredKeys = new Set(options.ignoredKeys);
+  for (const argument of callExpression.arguments) {
+    collectFromExpression(
+      argument,
+      ignoredKeys,
+      functionNames,
+      literals
+    );
+  }
+  return literals;
+}
+
+const DEFAULT_ATTRIBUTES = ["class", "className"];
+const DEFAULT_FUNCTIONS = [
+  "cn",
+  "clsx",
+  "cva",
+  "twMerge",
+  "twJoin"
+];
+const DEFAULT_IGNORED_KEYS = [
+  "defaultVariants",
+  "compoundVariants",
+  "compoundSlots"
+];
+function toRegExp(pattern) {
+  return new RegExp(pattern);
+}
+function parsePluginSettings(settings) {
+  if (!settings?.cssConfigPath) {
+    throw new Error(
+      "eslint-plugin-tailwind-ts: settings.tailwindTs.cssConfigPath is required (path to your Tailwind v4 CSS entry file)."
+    );
+  }
+  const whitelist = (settings.whitelist ?? []).map(toRegExp);
+  return {
+    cssConfigPath: settings.cssConfigPath,
+    attributes: settings.attributes ?? [...DEFAULT_ATTRIBUTES],
+    functions: settings.functions ?? [...DEFAULT_FUNCTIONS],
+    whitelist,
+    ignoredKeys: settings.ignoredKeys ?? [...DEFAULT_IGNORED_KEYS]
+  };
+}
+function isWhitelisted(className, whitelist) {
+  return whitelist.some((pattern) => pattern.test(className));
+}
+function splitClassTokens(classString) {
+  return classString.trim().split(/\s+/).filter(Boolean);
+}
+
+const CACHE_TTL_MS = 10 * 60 * 1e3;
+const resultCache = /* @__PURE__ */ new Map();
+const compilerMtimeCache = /* @__PURE__ */ new Map();
+function resolveWorkerPath() {
+  const dir = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(dir, "../worker/validate.mjs"),
+    join(dir, "../../worker/validate.mjs")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error("eslint-plugin-tailwind-ts: validation worker not found");
+}
+const runValidate = createSyncFn(resolveWorkerPath());
+function resolveCssConfigPath(cssConfigPath, cwd) {
+  return isAbsolute(cssConfigPath) ? cssConfigPath : resolve(cwd, cssConfigPath);
+}
+function getCssMtime(cssConfigPath) {
+  return statSync(cssConfigPath).mtimeMs;
+}
+function isCompilerCacheValid(cssConfigPath) {
+  const cached = compilerMtimeCache.get(cssConfigPath);
+  if (!cached) {
+    return false;
+  }
+  try {
+    return cached.mtimeMs === getCssMtime(cssConfigPath);
+  } catch {
+    return false;
+  }
+}
+function touchCompilerCache(cssConfigPath) {
+  compilerMtimeCache.set(cssConfigPath, {
+    mtimeMs: getCssMtime(cssConfigPath)
+  });
+}
+function invalidateResultCacheForConfig(cssConfigPath) {
+  for (const key of resultCache.keys()) {
+    if (key.startsWith(`${cssConfigPath}::`)) {
+      resultCache.delete(key);
+    }
+  }
+}
+function validateTailwindClass(request) {
+  const resolvedCssPath = resolveCssConfigPath(
+    request.cssConfigPath,
+    request.cwd
+  );
+  if (!isCompilerCacheValid(resolvedCssPath)) {
+    invalidateResultCacheForConfig(resolvedCssPath);
+    touchCompilerCache(resolvedCssPath);
+  }
+  const cacheKey = `${resolvedCssPath}::${request.className}`;
+  const cached = resultCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now()) {
+    return { valid: cached.valid };
+  }
+  const response = runValidate({
+    cssConfigPath: resolvedCssPath,
+    className: request.className,
+    cwd: request.cwd
+  });
+  resultCache.set(cacheKey, {
+    valid: response.valid,
+    expiresAt: Date.now() + CACHE_TTL_MS
+  });
+  return response;
+}
+
+const RULE_NAME = "no-invalid-classname";
+const noInvalidClassname = ESLintUtils.RuleCreator.withoutDocs({
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow invalid or typo Tailwind CSS class names in JSX and utility functions."
+    },
+    schema: [
+      {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          whitelist: {
+            type: "array",
+            items: { type: "string" }
+          }
+        }
+      }
+    ],
+    messages: {
+      invalidClass: 'Class "{{ className }}" is not a valid Tailwind CSS class.'
+    }
+  },
+  defaultOptions: [{}],
+  create(context) {
+    const pluginSettings = context.settings.tailwindTs;
+    let resolvedSettings;
+    try {
+      resolvedSettings = parsePluginSettings(pluginSettings);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Invalid plugin settings.";
+      context.report({
+        loc: { line: 1, column: 0 },
+        message
+      });
+      return {};
+    }
+    const ruleWhitelist = (context.options[0]?.whitelist ?? []).map(
+      (pattern) => new RegExp(pattern)
+    );
+    const whitelist = [...resolvedSettings.whitelist, ...ruleWhitelist];
+    const attributeNames = new Set(resolvedSettings.attributes);
+    const cwd = context.cwd ?? process.cwd();
+    function reportInvalidClasses(literals) {
+      for (const literal of literals) {
+        for (const className of splitClassTokens(literal.value)) {
+          if (isWhitelisted(className, whitelist)) {
+            continue;
+          }
+          const result = validateTailwindClass({
+            cssConfigPath: resolvedSettings.cssConfigPath,
+            className,
+            cwd
+          });
+          if (!result.valid) {
+            context.report({
+              node: literal.node,
+              messageId: "invalidClass",
+              data: { className }
+            });
+          }
+        }
+      }
+    }
+    return {
+      JSXAttribute(node) {
+        if (node.name.type !== "JSXIdentifier" || !attributeNames.has(node.name.name)) {
+          return;
+        }
+        reportInvalidClasses(
+          extractClassLiteralsFromJsxAttribute(node, {
+            functions: resolvedSettings.functions,
+            ignoredKeys: resolvedSettings.ignoredKeys
+          })
+        );
+      },
+      CallExpression(node) {
+        reportInvalidClasses(
+          extractClassLiteralsFromCallExpression(node, {
+            functions: resolvedSettings.functions,
+            ignoredKeys: resolvedSettings.ignoredKeys
+          })
+        );
+      }
+    };
+  }
+});
+
+const createConfig = (rules) => {
+  const result = {};
+  for (const [ruleName, value] of Object.entries(rules)) {
+    result[`tailwind-ts/${ruleName}`] = value;
+  }
+  return result;
+};
+const plugin = {
+  meta: {
+    name: packageJson.name,
+    version: packageJson.version
+  },
+  configs: {
+    get recommended() {
+      return sharedConfigs.recommended;
+    }
+  },
+  rules: {
+    [RULE_NAME]: noInvalidClassname
+  }
+};
+const recommendedRules = {
+  [RULE_NAME]: "error"
+};
+const configBase = {
+  name: "tailwind-ts/base",
+  plugins: {
+    "tailwind-ts": plugin
+  },
+  settings: {
+    tailwindTs: {}
+  },
+  files: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
+  languageOptions: {
+    parserOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      ecmaFeatures: {
+        jsx: true
+      }
+    }
+  }
+};
+const sharedConfigs = {
+  recommended: {
+    ...configBase,
+    name: "tailwind-ts/recommended",
+    rules: createConfig(recommendedRules)
+  }
+};
+
+export { plugin as default };

package/lib/worker/validate.mjs

@@ -0,0 +1,65 @@
+import { readFileSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+import { __unstable__loadDesignSystem } from "@tailwindcss/node";
+
+/** @typedef {{ cssConfigPath: string, className: string, cwd: string }} ValidateClassRequest */
+/** @typedef {{ valid: boolean, error?: string }} ValidateClassResponse */
+
+/** @type {Map<string, { mtimeMs: number, designSystem: Awaited<ReturnType<typeof __unstable__loadDesignSystem>> }>} */
+const designSystemCache = new Map();
+
+/**
+ * @param {string} cssConfigPath
+ */
+async function getDesignSystem(cssConfigPath) {
+  const mtimeMs = statSync(cssConfigPath).mtimeMs;
+  const cached = designSystemCache.get(cssConfigPath);
+
+  if (cached && cached.mtimeMs === mtimeMs) {
+    return cached.designSystem;
+  }
+
+  const css = readFileSync(cssConfigPath, "utf8");
+  const designSystem = await __unstable__loadDesignSystem(css, {
+    base: dirname(cssConfigPath),
+  });
+
+  designSystemCache.set(cssConfigPath, { mtimeMs, designSystem });
+  return designSystem;
+}
+
+/**
+ * @param {ValidateClassRequest} request
+ * @returns {Promise<ValidateClassResponse>}
+ */
+async function validateClass(request) {
+  try {
+    const designSystem = await getDesignSystem(request.cssConfigPath);
+    const cssResults = designSystem.candidatesToCss([request.className]);
+    const valid = cssResults[0] !== null;
+
+    return { valid };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * @param {ValidateClassRequest} request
+ * @returns {ValidateClassResponse}
+ */
+function run(request) {
+  return validateClass(request);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const { runAsWorker } = await import("synckit");
+
+  runAsWorker(run);
+}
+
+export { run };

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@tailwind-ts/eslint-plugin",
+  "version": "0.1.0",
+  "description": "ESLint plugin for detecting invalid Tailwind CSS v4 class names with cva, @apply, and typo suggestions",
+  "license": "MIT",
+  "type": "module",
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tailwind-ts/eslint-plugin.git"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "tailwind",
+    "tailwindcss",
+    "typescript",
+    "v4",
+    "cva",
+    "apply"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.mjs",
+  "types": "./lib/index.d.cts",
+  "exports": {
+    ".": {
+      "module": {
+        "types": "./lib/index.d.mts",
+        "default": "./lib/index.mjs"
+      },
+      "import": {
+        "types": "./lib/index.d.mts",
+        "default": "./lib/index.mjs"
+      },
+      "require": {
+        "types": "./lib/index.d.cts",
+        "default": "./lib/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "docs/",
+    "lib/"
+  ],
+  "scripts": {
+    "build": "unbuild --config unbuild.config.ts && node scripts/copy-worker.mjs",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@typescript-eslint/utils": "^8.37.0",
+    "synckit": "^0.11.11"
+  },
+  "peerDependencies": {
+    "@tailwindcss/node": "^4.0.0",
+    "eslint": "^9.0.0 || ^10.0.0",
+    "tailwindcss": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    },
+    "vue-eslint-parser": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.31.0",
+    "@tailwindcss/node": "^4.3.2",
+    "@types/node": "^22.15.0",
+    "@typescript-eslint/parser": "^8.37.0",
+    "@typescript-eslint/rule-tester": "^8.37.0",
+    "eslint": "^9.31.0",
+    "tailwindcss": "^4.3.2",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.42.0",
+    "unbuild": "^3.3.1",
+    "vitest": "^3.2.4"
+  }
+}