tessl/npm-unocss--eslint-plugin

ESLint plugin for UnoCSS providing rules for class ordering, attributify ordering, blocklist enforcement, and class compilation

—

Pending

Overview

Eval results

Files

Blocklist Enforcement

Name: tessl/npm-unocss--eslint-plugin
Author: tessl

Prevents usage of specific CSS utilities or patterns based on UnoCSS blocklist configuration, providing context-aware error reporting and integration with UnoCSS generator.

Capabilities

Blocklist Rule

Enforces UnoCSS blocklist restrictions across class attributes and attributify syntax.

/**
 * ESLint rule for enforcing UnoCSS blocklist restrictions
 * Prevents usage of utilities marked as blocked in UnoCSS configuration
 */
interface BlocklistRule extends ESLintRule {
  name: "blocklist";
  meta: {
    type: "problem";
    fixable: "code";
    docs: {
      description: "Utilities in UnoCSS blocklist";
    };
    messages: {
      "in-blocklist": '"{{name}}" is in blocklist{{reason}}';
    };
    schema: [];
  };
  defaultOptions: [];
}

interface BlocklistMeta {
  /** Optional message explaining why utility is blocked */
  message?: string | ((raw: string) => string);
}

type BlocklistResult = [string, BlocklistMeta | undefined][];

Usage Examples:

// ESLint configuration
{
  rules: {
    "@unocss/blocklist": "error"
  }
}

UnoCSS Configuration:

// uno.config.ts
export default {
  blocklist: [
    "container", // Block specific utility
    /^debug-/, // Block utilities matching pattern
    {
      rule: "text-red-500",
      message: "Use semantic color tokens instead"
    }
  ]
}

Supported Contexts

The blocklist rule checks utilities in various contexts:

Class Attributes:

// JSX - Will error if utilities are blocked
<div className="container p-4" /> // Error if 'container' is blocked

// Vue templates  
<div class="debug-outline m-4" /> // Error if 'debug-outline' is blocked

// Svelte components
<div class="text-red-500" /> // Error with custom message

Attributify Syntax (Vue):

<!-- Will check each attributify attribute -->
<div container p-4 debug-outline /> 
<!-- Errors for blocked: container, debug-outline -->

Implementation Details

Blocklist Integration

The rule integrates with UnoCSS generator to check blocklist:

/**
 * Worker function for checking utilities against blocklist
 * @param configPath - Path to UnoCSS config file
 * @param classes - String containing utility classes
 * @param id - Optional file identifier for context
 * @returns Array of blocked utilities with metadata
 */
function actionBlocklist(
  configPath: string | undefined,
  classes: string,
  id?: string
): Promise<[string, BlocklistMeta | undefined][]>;

AST Node Processing

JavaScript/TypeScript/JSX:

// Processes literal nodes containing class strings
interface LiteralProcessor {
  /** Check string literal for blocked utilities */
  checkLiteral(node: TSESTree.Literal): void;
}

Vue Templates:

// Processes Vue template attributes
interface VueProcessor {
  /** Check class attribute values */
  VAttribute(node: VAttribute): void;
  /** Check attributify attributes on start tags */
  VStartTag(node: VStartTag): void;
}

Svelte Components:

// Processes Svelte component attributes  
interface SvelteProcessor {
  /** Check Svelte class attributes */
  SvelteAttribute(node: SvelteAttribute): void;
}

Error Reporting

The rule provides detailed error messages with optional explanations:

interface BlocklistError {
  /** The blocked utility name */
  name: string;
  /** Optional reason from UnoCSS configuration */
  reason: string; // Empty string or ": <message>"
}

Error Message Examples:

"container" is in blocklist
"text-red-500" is in blocklist: Use semantic color tokens instead  
"debug-outline" is in blocklist

Configuration Integration

The rule reads UnoCSS configuration for blocklist definitions:

// ESLint settings for UnoCSS config path
interface ESLintSettings {
  unocss?: {
    configPath?: string;
  };
}

ESLint Configuration:

module.exports = {
  settings: {
    unocss: {
      configPath: "./uno.config.ts"
    }
  },
  rules: {
    "@unocss/blocklist": "error"
  }
};

Framework Support

JSX Support:

Checks className and class attributes
Processes string literals in JSX expressions

Vue Support:

Checks class attributes in templates
Processes attributify attributes on elements
Requires vue-eslint-parser

Svelte Support:

Checks class attributes in components
Processes Svelte literal values
Requires svelte-eslint-parser

Standard HTML/JavaScript:

Checks class attributes in template strings
Processes string literals and template literals

Install with Tessl CLI

npx tessl i tessl/npm-unocss--eslint-plugin

docs

attributify-ordering.md