0
# UnoCSS Core
1

2
UnoCSS Core is the foundation atomic CSS engine that generates CSS on-demand without any presets or default utilities. It provides a highly performant and customizable framework for building atomic CSS systems with instant CSS generation, zero parsing overhead, and comprehensive TypeScript support.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { createGenerator, UnoGenerator } from "@unocss/core";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { createGenerator, UnoGenerator } = require("@unocss/core");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { createGenerator } from "@unocss/core";
27

28
// Create a generator with custom rules
29
const uno = await createGenerator({
30
  rules: [
31
    ['m-1', { margin: '0.25rem' }], // Static rule
32
    [/^m-(\d+)$/, ([, d]) => ({ margin: `${d}px` })] // Dynamic rule
33
  ],
34
  variants: [
35
    (matcher) => {
36
      if (matcher.startsWith('hover:'))
37
        return {
38
          selector: s => `${s}:hover`
39
        }
40
    }
41
  ]
42
});
43

44
// Generate CSS from utility classes
45
const result = await uno.generate('m-1 m-4 hover:m-2');
46
console.log(result.css);
47
// Output: .m-1{margin:0.25rem;}.m-4{margin:4px;}.\:m-2:hover{margin:2px;}
48
```
49

50
## Architecture
51

52
UnoCSS Core is built around several key components:
53

54
- **Generator Engine**: Core `UnoGenerator` class that orchestrates CSS generation with efficient caching and optimization
55
- **Configuration System**: Powerful configuration resolver that merges user configs, presets, and defaults with proper precedence
56
- **Rule Matching**: Sophisticated pattern matching for both static and dynamic CSS rules with regex support
57
- **Variant Processing**: Flexible variant system for pseudo-classes, media queries, and custom modifiers
58
- **Content Extraction**: Pluggable extractors for finding utility classes in source code across different file types
59
- **Layer Management**: CSS layer organization with configurable ordering and cascading control
60
- **Type System**: Full TypeScript support with generic theme typing and comprehensive type definitions
61

62
## Capabilities
63

64
### Generator Creation and Management
65

66
Core functionality for creating and configuring UnoCSS generator instances with custom rules, variants, and settings.
67

68
```typescript { .api }
69
function createGenerator<Theme extends object = object>(
70
  config?: UserConfig<Theme>,
71
  defaults?: UserConfigDefaults<Theme>
72
): Promise<UnoGenerator<Theme>>;
73

74
class UnoGenerator<Theme extends object = object> {
75
  readonly version: string;
76
  readonly config: ResolvedConfig<Theme>;
77
  generate(
78
    input: string | Set<string> | CountableSet<string> | string[],
79
    options?: GenerateOptions<boolean>
80
  ): Promise<GenerateResult<unknown>>;
81
  setConfig(
82
    userConfig?: UserConfig<Theme>,
83
    defaults?: UserConfigDefaults<Theme>
84
  ): Promise<void>;
85
}
86
```
87

88
[Generator and CSS Generation](./generator.md)
89

90
### Layer Constants
91

92
Built-in layer constants for organizing CSS output with predefined ordering.
93

94
```typescript { .api }
95
const LAYER_DEFAULT = 'default';
96
const LAYER_PREFLIGHTS = 'preflights';
97
const LAYER_SHORTCUTS = 'shortcuts';
98
const LAYER_IMPORTS = 'imports';
99

100
const DEFAULT_LAYERS: Record<string, number> = {
101
  [LAYER_IMPORTS]: -200,
102
  [LAYER_PREFLIGHTS]: -100,
103
  [LAYER_SHORTCUTS]: -10,
104
  [LAYER_DEFAULT]: 0,
105
};
106
```
107

108
### Configuration Management
109

110
Configuration resolution system that handles merging user configs, presets, themes, and defaults with proper precedence and validation.
111

112
```typescript { .api }
113
function resolveConfig<Theme extends object = object>(
114
  userConfig?: UserConfig<Theme>,
115
  defaults?: UserConfigDefaults<Theme>
116
): Promise<ResolvedConfig<Theme>>;
117

118
function resolvePreset<Theme extends object = object>(
119
  presetInput: PresetOrFactoryAwaitable<Theme>
120
): Promise<Preset<Theme>>;
121

122
function resolvePresets<Theme extends object = object>(
123
  preset: PresetOrFactoryAwaitable<Theme>
124
): Promise<Preset<Theme>[]>;
125

126
function mergeConfigs<Theme extends object = object>(
127
  configs: UserConfig<Theme>[]
128
): UserConfig<Theme>;
129

130
function definePreset<Options = object, Theme extends object = object>(
131
  preset: PresetFactory<Theme, Options>
132
): PresetFactory<Theme, Options>;
133

134
function resolveShortcuts<Theme extends object = object>(
135
  shortcuts: UserShortcuts<Theme>
136
): Shortcut<Theme>[];
137
```
138

139
[Configuration System](./config.md)
140

141
### Rule and Variant System
142

143
Powerful rule definition system supporting both static and dynamic patterns, along with variant processing for pseudo-classes and modifiers.
144

145
```typescript { .api }
146
type Rule<Theme extends object = object> = 
147
  | [string, CSSObject | CSSEntries, RuleMeta?] // Static rule
148
  | [RegExp, DynamicMatcher<Theme>, RuleMeta?]; // Dynamic rule
149

150
type Variant<Theme extends object = object> = 
151
  | VariantFunction<Theme>
152
  | VariantObject<Theme>;
153

154
interface RuleContext<Theme extends object = object> {
155
  rawSelector: string;
156
  currentSelector: string;
157
  generator: UnoGenerator<Theme>;
158
  theme: Theme;
159
  constructCSS: (body: CSSEntries | CSSObject, overrideSelector?: string) => string;
160
}
161
```
162

163
[Rules and Variants](./rules-variants.md)
164

165
### Content Extraction
166

167
Pluggable content extraction system for finding utility classes in source code with support for custom extractors and file type handling.
168

169
```typescript { .api }
170
interface Extractor {
171
  name: string;
172
  order?: number;
173
  extract?: (ctx: ExtractorContext) => Awaitable<Set<string> | CountableSet<string> | string[] | undefined | void>;
174
}
175

176
interface ExtractorContext {
177
  readonly original: string;
178
  code: string;
179
  id?: string;
180
  extracted: Set<string> | CountableSet<string>;
181
  envMode?: 'dev' | 'build';
182
}
183

184
const extractorSplit: Extractor;
185
```
186

187
[Content Extraction](./extraction.md)
188

189
### Utility Functions and Helpers
190

191
Comprehensive utility library with functions for CSS processing, type manipulation, selector escaping, and development helpers.
192

193
```typescript { .api }
194
function escapeSelector(str: string): string;
195
function toArray<T>(value: T | T[]): T[];
196
function mergeDeep<T>(original: T, patch: DeepPartial<T>, mergeArray?: boolean): T;
197
function expandVariantGroup(str: string, separators?: string[], depth?: number): string;
198
function warnOnce(msg: string): void;
199

200
class CountableSet<K> extends Set<K> {
201
  getCount(key: K): number;
202
  setCount(key: K, count: number): this;
203
}
204

205
class BetterMap<K, V> extends Map<K, V> {
206
  getFallback(key: K, fallback: V): V;
207
  map<R>(mapFn: (value: V, key: K) => R): R[];
208
}
209

210
class TwoKeyMap<K1, K2, V> {
211
  get(key1: K1, key2: K2): V | undefined;
212
  set(key1: K1, key2: K2, value: V): this;
213
}
214

215
function createNanoEvents<Events>(): Emitter<Events>;
216
```
217

218
[Utilities and Helpers](./utilities.md)
219

220
### Type Definitions
221

222
Complete TypeScript type definitions for all configuration options, contexts, and API surfaces with generic theme support.
223

224
```typescript { .api }
225
interface UserConfig<Theme extends object = object> {
226
  rules?: Rule<Theme>[];
227
  variants?: Variant<Theme>[];
228
  shortcuts?: UserShortcuts<Theme>;
229
  theme?: Theme;
230
  presets?: (PresetOrFactoryAwaitable<Theme> | PresetOrFactoryAwaitable<Theme>[])[];
231
  extractors?: Extractor[];
232
  blocklist?: BlocklistRule[];
233
  safelist?: (string | ((context: SafeListContext<Theme>) => Arrayable<string>))[];
234
  preflights?: Preflight<Theme>[];
235
  layers?: Record<string, number>;
236
  separators?: Arrayable<string>;
237
}
238

239
interface ResolvedConfig<Theme extends object = object> extends UserConfig<Theme> {
240
  presets: Preset<Theme>[];
241
  shortcuts: Shortcut<Theme>[];
242
  variants: VariantObject<Theme>[];
243
  rulesStaticMap: Record<string, StaticRule | undefined>;
244
  rulesDynamic: readonly DynamicRule<Theme>[];
245
}
246
```
247

248
[Type Definitions](./types.md)