or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mderrors.mdindex.mdprogrammatic.mdwatching.md
tile.json

tessl/npm-unocss--cli

CLI for UnoCSS that enables CSS generation from utility classes in traditional backends and static environments.

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

To install, run

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

index.mddocs/

@unocss/cli

@unocss/cli is a command-line interface for UnoCSS, providing CSS generation from utility classes in traditional backends and static environments. It offers both CLI and programmatic APIs with file watching capabilities, making it ideal for projects that need atomic CSS generation without build-time integration.

Package Information

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

Core Imports

Main functionality:

import { 
  build, 
  resolveOptions,
  type CliOptions,
  type ResolvedCliOptions 
} from "@unocss/cli";

Additional functionality (require specific import paths or may not be directly exported):

// These functions are not directly exported from main entry point
// They may be available via separate build outputs or internal modules
// import { startCli } from "@unocss/cli/cli-start";
// import { PrettyError, handleError } from "@unocss/cli/errors";
// import { getWatcher } from "@unocss/cli/watcher";
// import { defaultConfig } from "@unocss/cli/config";

For CommonJS:

const { build, resolveOptions } = require("@unocss/cli");
// Additional functions may not be directly available from main export

Basic Usage

CLI Usage

# Generate CSS from HTML files
unocss "src/**/*.html" -o dist/styles.css

# Watch mode for development
unocss "src/**/*.html" -o dist/styles.css --watch

# Output to stdout
unocss "src/**/*.html" --stdout

# Use custom config
unocss "src/**/*.html" -c uno.config.ts --watch

Programmatic Usage

import { build } from "@unocss/cli";

// Basic CSS generation
await build({
  patterns: ["src/**/*.html"],
  outFile: "dist/styles.css",
  minify: true,
});

// Watch mode programmatically
await build({
  patterns: ["src/**/*.html", "src/**/*.js"],
  outFile: "dist/styles.css",
  watch: true,
  preflights: true,
});

Architecture

@unocss/cli is built around several key components:

  • CLI Interface: Command-line parsing and option handling via CAC
  • Build Engine: Core CSS generation from utility class scanning
  • File Watching: Development workflow with automatic rebuilding via Chokidar
  • Configuration Loading: Integration with UnoCSS configuration files
  • Transformer Processing: Support for UnoCSS transformers (pre/default/post)

Capabilities

Command Line Interface

Full-featured CLI for CSS generation with extensive configuration options including watch mode, custom output paths, and transformer support.

function startCli(
  cwd?: string,
  argv?: string[],
  options?: CliOptions
): Promise<void>;

Command Line Interface

Programmatic Build API

Core build functionality for CSS generation that can be integrated into scripts and build processes.

function build(options: CliOptions): Promise<void>;

function resolveOptions(options: CliOptions): Promise<ResolvedCliOptions>;

interface CliOptions {
  cwd?: string;
  patterns?: Array<string>;
  outFile?: string;
  watch?: boolean;
  config?: string;
  stdout?: boolean;
  writeTransformed?: boolean;
  preflights?: boolean;
  minify?: boolean;
}

type ResolvedCliOptions = MarkRequired<CliOptions, 'patterns'>;

Programmatic API

File Watching

Development-focused file watching system for automatic CSS regeneration when source files change.

function getWatcher(options?: CliOptions): Promise<FSWatcher>;

File Watching

Error Handling

Specialized error handling for CLI operations with user-friendly messages and proper exit codes.

class PrettyError extends Error {
  constructor(message: string);
}

function handleError(error: unknown): void;

Error Handling

Default Configuration

Default UnoCSS configuration optimized for CLI usage with build environment settings and preset configurations.

const defaultConfig: UserConfig;

The default configuration includes:

  • envMode: Set to 'build' for production-optimized CSS generation
  • presets: Includes @unocss/preset-uno for Tailwind-compatible utilities

Usage Examples:

import { defaultConfig } from "@unocss/cli";

// Use default config as base
const customConfig = {
  ...defaultConfig,
  theme: {
    colors: {
      primary: '#ff0000'
    }
  }
};

// Access default settings
console.log(defaultConfig.envMode); // 'build'
console.log(defaultConfig.presets); // [presetUno()]

Types

// External types from dependencies
import type { FSWatcher } from 'chokidar';
import type { UserConfig } from '@unocss/core';

// Internal utility type for marking properties as required (not exported)
declare type MarkRequired<T, RK extends keyof T> = Exclude<T, RK> & Required<Pick<T, RK>>;

interface CliOptions {
  /** Working directory for file operations */
  cwd?: string;
  /** Glob patterns for files to process */
  patterns?: Array<string>;
  /** Output CSS file path */
  outFile?: string;
  /** Enable file watching mode */
  watch?: boolean;
  /** Path to UnoCSS configuration file */
  config?: string;
  /** Output CSS to stdout instead of file */
  stdout?: boolean;
  /** Write transformed source files back to disk */
  writeTransformed?: boolean;
  /** Enable CSS preflights */
  preflights?: boolean;
  /** Minify generated CSS output */
  minify?: boolean;
}

type ResolvedCliOptions = MarkRequired<CliOptions, 'patterns'>;