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
```