0
# Blocklist Enforcement
1

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

4
## Capabilities
5

6
### Blocklist Rule
7

8
Enforces UnoCSS blocklist restrictions across class attributes and attributify syntax.
9

10
```typescript { .api }
11
/**
12
 * ESLint rule for enforcing UnoCSS blocklist restrictions
13
 * Prevents usage of utilities marked as blocked in UnoCSS configuration
14
 */
15
interface BlocklistRule extends ESLintRule {
16
  name: "blocklist";
17
  meta: {
18
    type: "problem";
19
    fixable: "code";
20
    docs: {
21
      description: "Utilities in UnoCSS blocklist";
22
    };
23
    messages: {
24
      "in-blocklist": '"{{name}}" is in blocklist{{reason}}';
25
    };
26
    schema: [];
27
  };
28
  defaultOptions: [];
29
}
30

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

36
type BlocklistResult = [string, BlocklistMeta | undefined][];
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
// ESLint configuration
43
{
44
  rules: {
45
    "@unocss/blocklist": "error"
46
  }
47
}
48
```
49

50
**UnoCSS Configuration:**
51

52
```typescript
53
// uno.config.ts
54
export default {
55
  blocklist: [
56
    "container", // Block specific utility
57
    /^debug-/, // Block utilities matching pattern
58
    {
59
      rule: "text-red-500",
60
      message: "Use semantic color tokens instead"
61
    }
62
  ]
63
}
64
```
65

66
### Supported Contexts
67

68
The blocklist rule checks utilities in various contexts:
69

70
**Class Attributes:**
71

72
```jsx
73
// JSX - Will error if utilities are blocked
74
<div className="container p-4" /> // Error if 'container' is blocked
75

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

79
// Svelte components
80
<div class="text-red-500" /> // Error with custom message
81
```
82

83
**Attributify Syntax (Vue):**
84

85
```vue
86
<!-- Will check each attributify attribute -->
87
<div container p-4 debug-outline /> 
88
<!-- Errors for blocked: container, debug-outline -->
89
```
90

91
## Implementation Details
92

93
### Blocklist Integration
94

95
The rule integrates with UnoCSS generator to check blocklist:
96

97
```typescript { .api }
98
/**
99
 * Worker function for checking utilities against blocklist
100
 * @param configPath - Path to UnoCSS config file
101
 * @param classes - String containing utility classes
102
 * @param id - Optional file identifier for context
103
 * @returns Array of blocked utilities with metadata
104
 */
105
function actionBlocklist(
106
  configPath: string | undefined,
107
  classes: string,
108
  id?: string
109
): Promise<[string, BlocklistMeta | undefined][]>;
110
```
111

112
### AST Node Processing
113

114
**JavaScript/TypeScript/JSX:**
115

116
```typescript { .api }
117
// Processes literal nodes containing class strings
118
interface LiteralProcessor {
119
  /** Check string literal for blocked utilities */
120
  checkLiteral(node: TSESTree.Literal): void;
121
}
122
```
123

124
**Vue Templates:**
125

126
```typescript { .api }
127
// Processes Vue template attributes
128
interface VueProcessor {
129
  /** Check class attribute values */
130
  VAttribute(node: VAttribute): void;
131
  /** Check attributify attributes on start tags */
132
  VStartTag(node: VStartTag): void;
133
}
134
```
135

136
**Svelte Components:**
137

138
```typescript { .api }
139
// Processes Svelte component attributes  
140
interface SvelteProcessor {
141
  /** Check Svelte class attributes */
142
  SvelteAttribute(node: SvelteAttribute): void;
143
}
144
```
145

146
### Error Reporting
147

148
The rule provides detailed error messages with optional explanations:
149

150
```typescript { .api }
151
interface BlocklistError {
152
  /** The blocked utility name */
153
  name: string;
154
  /** Optional reason from UnoCSS configuration */
155
  reason: string; // Empty string or ": <message>"
156
}
157
```
158

159
**Error Message Examples:**
160

161
```text
162
"container" is in blocklist
163
"text-red-500" is in blocklist: Use semantic color tokens instead  
164
"debug-outline" is in blocklist
165
```
166

167
### Configuration Integration
168

169
The rule reads UnoCSS configuration for blocklist definitions:
170

171
```typescript { .api }
172
// ESLint settings for UnoCSS config path
173
interface ESLintSettings {
174
  unocss?: {
175
    configPath?: string;
176
  };
177
}
178
```
179

180
**ESLint Configuration:**
181

182
```javascript
183
module.exports = {
184
  settings: {
185
    unocss: {
186
      configPath: "./uno.config.ts"
187
    }
188
  },
189
  rules: {
190
    "@unocss/blocklist": "error"
191
  }
192
};
193
```
194

195
### Framework Support
196

197
**JSX Support:**
198
- Checks `className` and `class` attributes
199
- Processes string literals in JSX expressions
200

201
**Vue Support:**
202
- Checks `class` attributes in templates
203
- Processes attributify attributes on elements
204
- Requires `vue-eslint-parser`
205

206
**Svelte Support:**
207
- Checks `class` attributes in components
208
- Processes Svelte literal values
209
- Requires `svelte-eslint-parser`
210

211
**Standard HTML/JavaScript:**
212
- Checks class attributes in template strings
213
- Processes string literals and template literals