0
# Configuration System
1

2
The UnoCSS Core configuration system handles merging user configs, presets, themes, and defaults with proper precedence rules. It resolves complex configuration hierarchies and provides a unified configuration interface.
3

4
## Configuration Resolution
5

6
```typescript { .api }
7
function resolveConfig<Theme extends object = object>(
8
  userConfig?: UserConfig<Theme>,
9
  defaults?: UserConfigDefaults<Theme>
10
): Promise<ResolvedConfig<Theme>>;
11
```
12

13
Resolves user configuration and defaults into a complete, validated configuration object. This function handles preset resolution, theme merging, rule processing, and variant normalization.
14

15
**Parameters:**
16
- `userConfig`: User-provided configuration object
17
- `defaults`: Default configuration values
18

19
**Returns:** Promise resolving to a fully resolved configuration
20

21
## Configuration Merging
22

23
```typescript { .api }
24
function mergeConfigs<Theme extends object = object>(
25
  configs: UserConfig<Theme>[]
26
): UserConfig<Theme>;
27
```
28

29
Merges multiple configuration objects with proper precedence. Later configurations override earlier ones for most properties, while arrays are merged.
30

31
## Preset Management
32

33
### Preset Resolution
34

35
```typescript { .api }
36
function resolvePreset<Theme extends object = object>(
37
  presetInput: PresetOrFactoryAwaitable<Theme>
38
): Promise<Preset<Theme>>;
39

40
function resolvePresets<Theme extends object = object>(
41
  preset: PresetOrFactoryAwaitable<Theme>
42
): Promise<Preset<Theme>[]>;
43
```
44

45
Resolves preset definitions, including factory functions and nested presets. Handles async preset loading and dependency resolution.
46

47
### Preset Definition
48

49
```typescript { .api }
50
function definePreset<Options extends object | undefined = undefined, Theme extends object = object>(
51
  preset: PresetFactory<Theme, Options>
52
): PresetFactory<Theme, Options>;
53
function definePreset<Theme extends object = object>(
54
  preset: Preset<Theme>
55
): Preset<Theme>;
56
```
57

58
Type-safe helper for defining presets with proper TypeScript inference.
59

60
## Shortcut Resolution
61

62
```typescript { .api }
63
function resolveShortcuts<Theme extends object = object>(
64
  shortcuts: UserShortcuts<Theme>
65
): Shortcut<Theme>[];
66
```
67

68
Processes shortcut definitions from various input formats (objects, arrays, functions) into a normalized array format.
69

70
## User Configuration Interface
71

72
```typescript { .api }
73
interface UserConfig<Theme extends object = object> {
74
  rules?: Rule<Theme>[];
75
  variants?: Variant<Theme>[];
76
  shortcuts?: UserShortcuts<Theme>;
77
  theme?: Theme;
78
  presets?: (PresetOrFactoryAwaitable<Theme> | PresetOrFactoryAwaitable<Theme>[])[];
79
  extractors?: Extractor[];
80
  extractorDefault?: Extractor | null | false;
81
  blocklist?: BlocklistRule[];
82
  safelist?: (string | ((context: SafeListContext<Theme>) => Arrayable<string>))[];
83
  preflights?: Preflight<Theme>[];
84
  layers?: Record<string, number>;
85
  outputToCssLayers?: boolean | OutputCssLayersOptions;
86
  sortLayers?: (layers: string[]) => string[];
87
  separators?: Arrayable<string>;
88
  preprocess?: Arrayable<Preprocessor>;
89
  postprocess?: Arrayable<Postprocessor>;
90
  extendTheme?: Arrayable<ThemeExtender<Theme>>;
91
  autocomplete?: {
92
    templates?: Arrayable<AutoCompleteFunction | AutoCompleteTemplate>;
93
    extractors?: Arrayable<AutoCompleteExtractor>;
94
    shorthands?: Record<string, string | string[]>;
95
  };
96
  configResolved?: (config: ResolvedConfig<Theme>) => void;
97
  details?: boolean;
98
  content?: ContentOptions;
99
  transformers?: SourceCodeTransformer[];
100
  mergeSelectors?: boolean;
101
  warn?: boolean;
102
  shortcutsLayer?: string;
103
  envMode?: 'dev' | 'build';
104
}
105
```
106

107
## Resolved Configuration Interface
108

109
```typescript { .api }
110
interface ResolvedConfig<Theme extends object = object> {
111
  presets: Preset<Theme>[];
112
  rules: readonly Rule<Theme>[];
113
  rulesSize: number;
114
  rulesStaticMap: Record<string, StaticRule | undefined>;
115
  rulesDynamic: readonly DynamicRule<Theme>[];
116
  shortcuts: Shortcut<Theme>[];
117
  variants: VariantObject<Theme>[];
118
  theme: Theme;
119
  layers: Record<string, number>;
120
  extractors: Extractor[];
121
  blocklist: BlocklistRule[];
122
  safelist: (string | ((context: SafeListContext<Theme>) => Arrayable<string>))[];
123
  preflights: Preflight<Theme>[];
124
  preprocess: Preprocessor[];
125
  postprocess: Postprocessor[];
126
  autocomplete: {
127
    templates: (AutoCompleteFunction | AutoCompleteTemplate)[];
128
    extractors: AutoCompleteExtractor[];
129
    shorthands: Record<string, string>;
130
  };
131
  separators: string[];
132
  sortLayers: (layers: string[]) => string[];
133
  mergeSelectors: boolean;
134
  warn: boolean;
135
  shortcutsLayer: string;
136
  envMode: 'dev' | 'build';
137
  details: boolean;
138
  content: ContentOptions;
139
  transformers: SourceCodeTransformer[];
140
}
141
```
142

143
## Preset Interface
144

145
```typescript { .api }
146
interface Preset<Theme extends object = object> extends ConfigBase<Theme> {
147
  name: string;
148
  enforce?: 'pre' | 'post';
149
  options?: PresetOptions;
150
  prefix?: string | string[];
151
  layer?: string;
152
  api?: any;
153
  meta?: Record<string, any>;
154
}
155

156
type PresetFactory<Theme extends object = object, PresetOptions extends object | undefined = undefined> = 
157
  (options?: PresetOptions) => Preset<Theme>;
158

159
type PresetFactoryAwaitable<Theme extends object = object, PresetOptions extends object | undefined = undefined> = 
160
  (options?: PresetOptions) => Awaitable<Preset<Theme>>;
161
```
162

163
## Configuration Examples
164

165
### Basic Configuration
166

167
```typescript
168
import { createGenerator } from '@unocss/core';
169

170
const uno = await createGenerator({
171
  // Custom rules
172
  rules: [
173
    ['btn', { 
174
      padding: '0.5rem 1rem',
175
      'border-radius': '0.25rem',
176
      'font-weight': '500'
177
    }],
178
    [/^text-size-(\d+)$/, ([, size]) => ({ 'font-size': `${size}px` })]
179
  ],
180
  
181
  // Custom theme
182
  theme: {
183
    colors: {
184
      primary: '#3b82f6',
185
      secondary: '#6b7280'
186
    },
187
    spacing: {
188
      xs: '0.5rem',
189
      sm: '1rem',
190
      md: '1.5rem'
191
    }
192
  },
193
  
194
  // Layer configuration
195
  layers: {
196
    'components': 1,
197
    'utilities': 2
198
  }
199
});
200
```
201

202
### Preset Usage
203

204
```typescript
205
const customPreset = definePreset({
206
  name: 'my-preset',
207
  rules: [
208
    ['card', { 
209
      padding: '1rem',
210
      'border-radius': '0.5rem',
211
      'box-shadow': '0 1px 3px rgba(0,0,0,0.1)'
212
    }]
213
  ],
214
  theme: {
215
    colors: {
216
      brand: '#ff6b6b'
217
    }
218
  }
219
});
220

221
const uno = await createGenerator({
222
  presets: [customPreset],
223
  // Additional user config...
224
});
225
```
226

227
### Dynamic Preset Factory
228

229
```typescript
230
const responsivePreset = definePreset((options: { breakpoints?: Record<string, string> } = {}) => ({
231
  name: 'responsive-preset',
232
  variants: [
233
    (matcher) => {
234
      for (const [name, size] of Object.entries(options.breakpoints || {})) {
235
        if (matcher.startsWith(`${name}:`)) {
236
          return {
237
            matcher: matcher.slice(name.length + 1),
238
            parent: `@media (min-width: ${size})`
239
          };
240
        }
241
      }
242
    }
243
  ]
244
}));
245

246
const uno = await createGenerator({
247
  presets: [
248
    responsivePreset({
249
      breakpoints: {
250
        sm: '640px',
251
        md: '768px',
252
        lg: '1024px'
253
      }
254
    })
255
  ]
256
});
257
```
258

259
## Configuration Lifecycle
260

261
1. **User Config Processing**: User configuration is validated and normalized
262
2. **Preset Resolution**: All presets are resolved, including factory functions and nested presets
263
3. **Precedence Application**: Presets are sorted by `enforce` property (pre → default → post)
264
4. **Property Merging**: Configuration properties are merged with proper precedence rules
265
5. **Rule Processing**: Rules are categorized into static and dynamic, with static rules indexed for fast lookup
266
6. **Variant Normalization**: Variants are normalized to consistent object format and sorted by order
267
7. **Theme Merging**: Theme objects are deep-merged with proper handling of nested objects
268
8. **Final Validation**: Resolved configuration is validated and frozen