or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

config.mdextraction.mdgenerator.mdindex.mdrules-variants.mdtypes.mdutilities.md
tile.json

tessl/npm-unocss--core

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@unocss/core@66.5.x

To install, run

npx @tessl/cli install tessl/npm-unocss--core@66.5.0

index.mddocs/

UnoCSS Core

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.

Package Information

  • Package Name: @unocss/core
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @unocss/core

Core Imports

import { createGenerator, UnoGenerator } from "@unocss/core";

For CommonJS:

const { createGenerator, UnoGenerator } = require("@unocss/core");

Basic Usage

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

// Create a generator with custom rules
const uno = await createGenerator({
  rules: [
    ['m-1', { margin: '0.25rem' }], // Static rule
    [/^m-(\d+)$/, ([, d]) => ({ margin: `${d}px` })] // Dynamic rule
  ],
  variants: [
    (matcher) => {
      if (matcher.startsWith('hover:'))
        return {
          selector: s => `${s}:hover`
        }
    }
  ]
});

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

Architecture

UnoCSS Core is built around several key components:

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

Capabilities

Generator Creation and Management

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

function createGenerator<Theme extends object = object>(
  config?: UserConfig<Theme>,
  defaults?: UserConfigDefaults<Theme>
): Promise<UnoGenerator<Theme>>;

class UnoGenerator<Theme extends object = object> {
  readonly version: string;
  readonly config: ResolvedConfig<Theme>;
  generate(
    input: string | Set<string> | CountableSet<string> | string[],
    options?: GenerateOptions<boolean>
  ): Promise<GenerateResult<unknown>>;
  setConfig(
    userConfig?: UserConfig<Theme>,
    defaults?: UserConfigDefaults<Theme>
  ): Promise<void>;
}

Generator and CSS Generation

Layer Constants

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

const LAYER_DEFAULT = 'default';
const LAYER_PREFLIGHTS = 'preflights';
const LAYER_SHORTCUTS = 'shortcuts';
const LAYER_IMPORTS = 'imports';

const DEFAULT_LAYERS: Record<string, number> = {
  [LAYER_IMPORTS]: -200,
  [LAYER_PREFLIGHTS]: -100,
  [LAYER_SHORTCUTS]: -10,
  [LAYER_DEFAULT]: 0,
};

Configuration Management

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

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

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

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

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

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

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

Configuration System

Rule and Variant System

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

type Rule<Theme extends object = object> = 
  | [string, CSSObject | CSSEntries, RuleMeta?] // Static rule
  | [RegExp, DynamicMatcher<Theme>, RuleMeta?]; // Dynamic rule

type Variant<Theme extends object = object> = 
  | VariantFunction<Theme>
  | VariantObject<Theme>;

interface RuleContext<Theme extends object = object> {
  rawSelector: string;
  currentSelector: string;
  generator: UnoGenerator<Theme>;
  theme: Theme;
  constructCSS: (body: CSSEntries | CSSObject, overrideSelector?: string) => string;
}

Rules and Variants

Content Extraction

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

interface Extractor {
  name: string;
  order?: number;
  extract?: (ctx: ExtractorContext) => Awaitable<Set<string> | CountableSet<string> | string[] | undefined | void>;
}

interface ExtractorContext {
  readonly original: string;
  code: string;
  id?: string;
  extracted: Set<string> | CountableSet<string>;
  envMode?: 'dev' | 'build';
}

const extractorSplit: Extractor;

Content Extraction

Utility Functions and Helpers

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

function escapeSelector(str: string): string;
function toArray<T>(value: T | T[]): T[];
function mergeDeep<T>(original: T, patch: DeepPartial<T>, mergeArray?: boolean): T;
function expandVariantGroup(str: string, separators?: string[], depth?: number): string;
function warnOnce(msg: string): void;

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

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

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

function createNanoEvents<Events>(): Emitter<Events>;

Utilities and Helpers

Type Definitions

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

interface UserConfig<Theme extends object = object> {
  rules?: Rule<Theme>[];
  variants?: Variant<Theme>[];
  shortcuts?: UserShortcuts<Theme>;
  theme?: Theme;
  presets?: (PresetOrFactoryAwaitable<Theme> | PresetOrFactoryAwaitable<Theme>[])[];
  extractors?: Extractor[];
  blocklist?: BlocklistRule[];
  safelist?: (string | ((context: SafeListContext<Theme>) => Arrayable<string>))[];
  preflights?: Preflight<Theme>[];
  layers?: Record<string, number>;
  separators?: Arrayable<string>;
}

interface ResolvedConfig<Theme extends object = object> extends UserConfig<Theme> {
  presets: Preset<Theme>[];
  shortcuts: Shortcut<Theme>[];
  variants: VariantObject<Theme>[];
  rulesStaticMap: Record<string, StaticRule | undefined>;
  rulesDynamic: readonly DynamicRule<Theme>[];
}

Type Definitions