tessl/npm-unocss--core

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

UnoCSS Core

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

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