@gustcss/eslint-plugin

ESLint plugin that reports class names which generate no CSS in a GustCSS project.

The plugin delegates to the gustcss CLI (gustcss lint --json <file>), so the rules, theme resolution, and configuration are exactly the same as running the CLI by hand. Nothing is reimplemented in JavaScript, which means the editor and CI can never disagree.

Requirements

• ESLint 9.30 or later (flat config)
• gustcss installed in the project (the plugin resolves it from node_modules)

Install

npm install -D eslint @gustcss/eslint-plugin gustcss

Usage

// eslint.config.mjs
import gustcss from "@gustcss/eslint-plugin";

export default [
  {
    files: ["**/*.{js,jsx,ts,tsx,astro}"],
    plugins: { gustcss },
    rules: {
      "gustcss/unknown-class": "error",
      "gustcss/unsupported-syntax": "error",
      "gustcss/duplicate-class": "warn",
      "gustcss/conflicting-class": "warn",
    },
  },
];

Severity, lint.rules, lint.ignore, baselines, and suppression comments are read from the project's gustcss.config.json by the CLI. The ESLint severity only decides how ESLint reports the diagnostic (warn maps to a warning, everything else to an error).

Rules

| Rule | Reports | | --- | --- | | gustcss/unknown-class | Classes that do not resolve (typos, unknown theme colors, values outside the scale) | | gustcss/unsupported-syntax | Arbitrary values p-[13px], arbitrary CSS variables, unknown variants, unsupported variant combinations | | gustcss/unscanned-class | Static classes passed to helper functions the build does not extract | | gustcss/dynamic-class | Class names built at runtime (template interpolation, string concatenation) | | gustcss/invalid-safelist | safelist entries that do not resolve | | gustcss/duplicate-class | The same class twice in one class attribute | | gustcss/conflicting-class | Classes fully overridden by a later class in the generated CSS | | gustcss/no-inline-style | Inline style= attributes | | gustcss/raw-color | Palette colors used while the project defines theme colors | | gustcss/repeated-class-set | The same class set repeated across the project | | gustcss/invalid-suppression | Suppression comments that name a rule that does not exist | | gustcss/component-contract | Classes disallowed by a configured JSX component contract |

Configure component contracts in gustcss.config.json. When source is omitted, the CLI resolves default, named, and namespace imports from matching JSX elements. It supports relative paths and single-wildcard baseUrl / paths aliases from the nearest tsconfig.json or jsconfig.json, including a chain of relative single-file extends, then follows relative named and star re-exports, including export * as Namespace members. An import or re-export that cannot be resolved is skipped rather than failing the run. An explicit source points to a component definition relative to the config file. For automatically resolved imports, static cva() / tv() variants referenced by the resolved component export supply omitted sizes and variants, while unrelated definitions in the same file are excluded. A top-level function, variable, or class that renders one uppercase JSX component inherits that component's contract and detected options. Base names are tied to the file that uses them, so a same-named component in another file is unaffected. Only well-formed start tags count as rendered children, and an import that cannot be resolved is skipped rather than failing the run. Wrappers that render multiple components are left unresolved. The CLI remains the source of truth for matching and suggestions.

Automatic inference requires a public export mapped to a local declaration; private declarations with the same name are excluded. Named and default exports of named async function declarations and local export aliases such as export { Internal as Button } are supported. The single-definition fallback also requires that export-to-declaration mapping. The tsconfig search starts at the GustCSS configuration directory, not at each source file.

Settings

{
  settings: {
    gustcss: {
      // Use a specific CLI entry point (a native binary or the npm wrapper).
      cliPath: "./node_modules/.bin/gustcss",
      // Use a specific config file instead of auto-detection.
      configPath: "./gustcss.config.json",
    },
  },
}

Both settings can also be passed per rule as options (["error", { cliPath, configPath }]), which takes precedence.

Notes

• The CLI reads the file from disk, so the plugin only reports for files that exist in the project. Unsaved editor buffers are not linted until they are saved.

• Diagnostics are cached per file using its modification time, so ESLint's multiple passes over the same file do not spawn the CLI repeatedly.

• For whole-project checks (cross-file rules, baselines, CI) run gustcss lint directly. For example:

  npx gustcss lint --max-warnings 0