0
# UnoCSS ESLint Plugin
1

2
UnoCSS ESLint Plugin provides essential ESLint rules for projects using UnoCSS, the instant on-demand Atomic CSS engine. It offers four specialized rules to maintain code quality and consistency: class ordering, attributify ordering, blocklist enforcement, and class compilation verification. The plugin integrates seamlessly with ESLint configurations and supports JavaScript, TypeScript, Vue, Svelte, and other frameworks.
3

4
## Package Information
5

6
- **Package Name**: @unocss/eslint-plugin
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @unocss/eslint-plugin`
10

11
## Core Imports
12

13
```typescript
14
import unocssPlugin from "@unocss/eslint-plugin";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const unocssPlugin = require("@unocss/eslint-plugin");
21
```
22

23
## Basic Usage
24

25
```javascript
26
// ESLint Flat Config (ESLint 9+)
27
import unocssPlugin from "@unocss/eslint-plugin";
28

29
export default [
30
  unocssPlugin.configs.flat,
31
  {
32
    rules: {
33
      "unocss/order": "warn",
34
      "unocss/blocklist": "error",
35
    },
36
  },
37
];
38
```
39

40
```javascript
41
// Legacy ESLint Config
42
module.exports = {
43
  extends: ["@unocss/eslint-plugin/recommended"],
44
  rules: {
45
    "@unocss/order": "warn",
46
    "@unocss/blocklist": "error",
47
  },
48
};
49
```
50

51
## Architecture
52

53
The UnoCSS ESLint Plugin is built around several key components:
54

55
- **Rule Engine**: Four specialized ESLint rules targeting different aspects of UnoCSS usage
56
- **Worker System**: Background processing for UnoCSS operations (sorting, blocklist checking)
57
- **Configuration Integration**: UnoCSS config file integration for context-aware rule enforcement
58
- **Multi-Framework Support**: AST visitor patterns supporting Vue, Svelte, JSX, and standard JavaScript/TypeScript
59
- **Synchronous Operations**: Worker-based synchronous execution of UnoCSS utilities within ESLint context
60

61
## Capabilities
62

63
### Class Ordering Rules
64

65
Rules for enforcing consistent ordering of UnoCSS utility classes in various contexts including class attributes, function calls, and template literals.
66

67
```typescript { .api }
68
// Main plugin export (default export)
69
interface UnoCSSSLintPlugin {
70
  rules: {
71
    order: ESLintRule;
72
    "order-attributify": ESLintRule;
73
    blocklist: ESLintRule;
74
    "enforce-class-compile": ESLintRule;
75
  };
76
  configs: {
77
    recommended: ESLintConfig;
78
    flat: ESLintConfig;
79
  };
80
}
81

82
// Order rule specific configuration
83
interface OrderRuleOptions {
84
  unoFunctions?: string[];
85
  unoVariables?: string[];
86
}
87
```
88

89
[Class Ordering Rules](./class-ordering.md)
90

91
### Attributify Ordering
92

93
Specialized rule for ordering UnoCSS utilities in Vue, Svelte, and other frameworks that support attributify mode.
94

95
```typescript { .api }
96
// Order attributify rule for framework templates
97
interface OrderAttributifyRule extends ESLintRule {
98
  name: "order-attributify";
99
  meta: {
100
    type: "layout";
101
    fixable: "code";
102
    docs: {
103
      description: "Order of UnoCSS utilities in attributify mode";
104
    };
105
  };
106
}
107
```
108

109
[Attributify Ordering](./attributify-ordering.md)
110

111
### Blocklist Enforcement
112

113
Prevents usage of specific CSS utilities or patterns based on UnoCSS blocklist configuration, with context-aware error reporting.
114

115
```typescript { .api }
116
// Blocklist rule configuration
117
interface BlocklistRule extends ESLintRule {
118
  meta: {
119
    type: "problem";
120
    fixable: "code";
121
    messages: {
122
      "in-blocklist": string;
123
    };
124
  };
125
}
126
```
127

128
[Blocklist Enforcement](./blocklist.md)
129

130
### Class Compilation Verification
131

132
Ensures proper class compilation prefix usage for UnoCSS processing, with configurable prefix and auto-fixing capabilities.
133

134
```typescript { .api }
135
// Enforce class compile rule options
136
interface EnforceClassCompileOptions {
137
  prefix: string; // Default: ":uno:"
138
  enableFix: boolean; // Default: true
139
}
140
```
141

142
[Class Compilation](./class-compilation.md)
143

144
### Configuration Presets
145

146
Pre-configured ESLint configurations for quick setup in both legacy and flat config formats.
147

148
```typescript { .api }
149
// Configuration preset structure
150
interface ConfigPresets {
151
  recommended: {
152
    plugins: string[];
153
    rules: Record<string, string>;
154
  };
155
  flat: {
156
    plugins: Record<string, any>;
157
    rules: Record<string, string>;
158
  };
159
}
160
```
161

162
[Configuration Setup](./configuration.md)
163

164
## Types
165

166
```typescript { .api }
167
// ESLint shared configuration settings extension
168
interface SharedConfigurationSettings {
169
  unocss?: {
170
    configPath?: string;
171
  };
172
}
173

174
// Core ESLint rule type used by all plugin rules
175
interface ESLintRule {
176
  meta: {
177
    type: "problem" | "suggestion" | "layout";
178
    fixable?: "code" | "whitespace";
179
    docs: {
180
      description: string;
181
    };
182
    messages: Record<string, string>;
183
    schema?: any[];
184
  };
185
  create: (context: any) => Record<string, Function>;
186
}
187

188
// Configuration presets for different ESLint config formats
189
interface ESLintConfig {
190
  plugins: string[] | Record<string, any>;
191
  rules: Record<string, string>;
192
}
193

194
// Worker function types for synchronous UnoCSS operations
195
type SyncAction = {
196
  (configPath: string | undefined, action: "sort", classes: string): string;
197
  (
198
    configPath: string | undefined,
199
    action: "blocklist",
200
    classes: string,
201
    id?: string
202
  ): [string, BlocklistMeta | undefined][];
203
};
204

205
// Blocklist metadata for error reporting
206
interface BlocklistMeta {
207
  message?: string | ((raw: string) => string);
208
}
209

210
// Enforce class compile rule options
211
interface EnforceClassCompileOptions {
212
  prefix: string;
213
  enableFix: boolean;
214
}
215
```