tessl/npm-unocss--core

The core atomic CSS engine for UnoCSS that generates CSS on-demand without any presets or default utilities.

—

Pending

Overview

Eval results

Files

Configuration System

Name: tessl/npm-unocss--core
Author: tessl

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.

Configuration Resolution

function resolveConfig<Theme extends object = object>(
  userConfig?: UserConfig<Theme>,
  defaults?: UserConfigDefaults<Theme>
): Promise<ResolvedConfig<Theme>>;

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

Parameters:

userConfig: User-provided configuration object
defaults: Default configuration values

Returns: Promise resolving to a fully resolved configuration

Configuration Merging

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

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

Preset Management

Preset Resolution

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

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

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

Preset Definition

function definePreset<Options extends object | undefined = undefined, Theme extends object = object>(
  preset: PresetFactory<Theme, Options>
): PresetFactory<Theme, Options>;
function definePreset<Theme extends object = object>(
  preset: Preset<Theme>
): Preset<Theme>;

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

Shortcut Resolution

function resolveShortcuts<Theme extends object = object>(
  shortcuts: UserShortcuts<Theme>
): Shortcut<Theme>[];

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

User Configuration Interface

interface UserConfig<Theme extends object = object> {
  rules?: Rule<Theme>[];
  variants?: Variant<Theme>[];
  shortcuts?: UserShortcuts<Theme>;
  theme?: Theme;
  presets?: (PresetOrFactoryAwaitable<Theme> | PresetOrFactoryAwaitable<Theme>[])[];
  extractors?: Extractor[];
  extractorDefault?: Extractor | null | false;
  blocklist?: BlocklistRule[];
  safelist?: (string | ((context: SafeListContext<Theme>) => Arrayable<string>))[];
  preflights?: Preflight<Theme>[];
  layers?: Record<string, number>;
  outputToCssLayers?: boolean | OutputCssLayersOptions;
  sortLayers?: (layers: string[]) => string[];
  separators?: Arrayable<string>;
  preprocess?: Arrayable<Preprocessor>;
  postprocess?: Arrayable<Postprocessor>;
  extendTheme?: Arrayable<ThemeExtender<Theme>>;
  autocomplete?: {
    templates?: Arrayable<AutoCompleteFunction | AutoCompleteTemplate>;
    extractors?: Arrayable<AutoCompleteExtractor>;
    shorthands?: Record<string, string | string[]>;
  };
  configResolved?: (config: ResolvedConfig<Theme>) => void;
  details?: boolean;
  content?: ContentOptions;
  transformers?: SourceCodeTransformer[];
  mergeSelectors?: boolean;
  warn?: boolean;
  shortcutsLayer?: string;
  envMode?: 'dev' | 'build';
}

Resolved Configuration Interface

interface ResolvedConfig<Theme extends object = object> {
  presets: Preset<Theme>[];
  rules: readonly Rule<Theme>[];
  rulesSize: number;
  rulesStaticMap: Record<string, StaticRule | undefined>;
  rulesDynamic: readonly DynamicRule<Theme>[];
  shortcuts: Shortcut<Theme>[];
  variants: VariantObject<Theme>[];
  theme: Theme;
  layers: Record<string, number>;
  extractors: Extractor[];
  blocklist: BlocklistRule[];
  safelist: (string | ((context: SafeListContext<Theme>) => Arrayable<string>))[];
  preflights: Preflight<Theme>[];
  preprocess: Preprocessor[];
  postprocess: Postprocessor[];
  autocomplete: {
    templates: (AutoCompleteFunction | AutoCompleteTemplate)[];
    extractors: AutoCompleteExtractor[];
    shorthands: Record<string, string>;
  };
  separators: string[];
  sortLayers: (layers: string[]) => string[];
  mergeSelectors: boolean;
  warn: boolean;
  shortcutsLayer: string;
  envMode: 'dev' | 'build';
  details: boolean;
  content: ContentOptions;
  transformers: SourceCodeTransformer[];
}

Preset Interface

interface Preset<Theme extends object = object> extends ConfigBase<Theme> {
  name: string;
  enforce?: 'pre' | 'post';
  options?: PresetOptions;
  prefix?: string | string[];
  layer?: string;
  api?: any;
  meta?: Record<string, any>;
}

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

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

Configuration Examples

Basic Configuration

import { createGenerator } from '@unocss/core';

const uno = await createGenerator({
  // Custom rules
  rules: [
    ['btn', { 
      padding: '0.5rem 1rem',
      'border-radius': '0.25rem',
      'font-weight': '500'
    }],
    [/^text-size-(\d+)$/, ([, size]) => ({ 'font-size': `${size}px` })]
  ],
  
  // Custom theme
  theme: {
    colors: {
      primary: '#3b82f6',
      secondary: '#6b7280'
    },
    spacing: {
      xs: '0.5rem',
      sm: '1rem',
      md: '1.5rem'
    }
  },
  
  // Layer configuration
  layers: {
    'components': 1,
    'utilities': 2
  }
});

Preset Usage

const customPreset = definePreset({
  name: 'my-preset',
  rules: [
    ['card', { 
      padding: '1rem',
      'border-radius': '0.5rem',
      'box-shadow': '0 1px 3px rgba(0,0,0,0.1)'
    }]
  ],
  theme: {
    colors: {
      brand: '#ff6b6b'
    }
  }
});

const uno = await createGenerator({
  presets: [customPreset],
  // Additional user config...
});

Dynamic Preset Factory

const responsivePreset = definePreset((options: { breakpoints?: Record<string, string> } = {}) => ({
  name: 'responsive-preset',
  variants: [
    (matcher) => {
      for (const [name, size] of Object.entries(options.breakpoints || {})) {
        if (matcher.startsWith(`${name}:`)) {
          return {
            matcher: matcher.slice(name.length + 1),
            parent: `@media (min-width: ${size})`
          };
        }
      }
    }
  ]
}));

const uno = await createGenerator({
  presets: [
    responsivePreset({
      breakpoints: {
        sm: '640px',
        md: '768px',
        lg: '1024px'
      }
    })
  ]
});

Configuration Lifecycle

User Config Processing: User configuration is validated and normalized
Preset Resolution: All presets are resolved, including factory functions and nested presets
Precedence Application: Presets are sorted by enforce property (pre → default → post)
Property Merging: Configuration properties are merged with proper precedence rules
Rule Processing: Rules are categorized into static and dynamic, with static rules indexed for fast lookup
Variant Normalization: Variants are normalized to consistent object format and sorted by order
Theme Merging: Theme objects are deep-merged with proper handling of nested objects
Final Validation: Resolved configuration is validated and frozen