tessl/npm-unocss--cli

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

—

Pending

Overview

Eval results

Files

Programmatic API

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

Core build functionality for CSS generation that can be integrated into scripts and build processes, supporting both one-time builds and watch mode operations.

Capabilities

Build Function

Main build function that processes files and generates CSS output with full transformer processing and configuration support.

/**
 * Main build function that processes files and generates CSS output
 * @param options - Build configuration options
 * @returns Promise that resolves when build completes (or starts watching)
 * @throws PrettyError if patterns are not provided
 */
function build(options: CliOptions): Promise<void>;

Usage Examples:

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

// Basic one-time build
await build({
  patterns: ["src/**/*.html"],
  outFile: "dist/styles.css",
});

// Build with minification
await build({
  patterns: ["src/**/*.{html,js}", "components/**/*.tsx"],
  outFile: "dist/uno.css",
  minify: true,
  preflights: true,
});

// Output to stdout
await build({
  patterns: ["src/**/*.html"],
  stdout: true,
});

// Watch mode for development
await build({
  patterns: ["src/**/*.html", "src/**/*.js"],
  outFile: "dist/styles.css",
  watch: true,
  config: "uno.config.ts",
});

// Transform source files
await build({
  patterns: ["src/**/*.html"],
  outFile: "dist/styles.css",
  writeTransformed: true,
});

// Custom working directory
await build({
  cwd: "/path/to/project",
  patterns: ["**/*.html"],
  outFile: "styles.css",
});

Resolve Options

Validates and resolves CLI options, ensuring required patterns are provided and options are properly formatted.

/**
 * Validates and resolves CLI options, ensuring patterns are provided
 * @param options - CLI configuration options to validate
 * @returns Promise resolving to validated options with required patterns
 * @throws PrettyError if no patterns are provided
 */
function resolveOptions(options: CliOptions): Promise<ResolvedCliOptions>;

Usage Examples:

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

// Validate options before processing
try {
  const resolved = await resolveOptions({
    patterns: ["src/**/*.html"],
    outFile: "dist/styles.css",
  });
  console.log("Options are valid:", resolved);
} catch (error) {
  console.error("Invalid options:", error.message);
}

// Handle missing patterns
try {
  await resolveOptions({ outFile: "styles.css" }); // Missing patterns
} catch (error) {
  console.error(error.message); // "No glob patterns, try unocss <path/to/**/*>"
}

Build Process Flow

The build function follows this processing flow:

Option Resolution: Validates options and ensures patterns are provided
Configuration Loading: Loads UnoCSS configuration from specified file or defaults
File Discovery: Uses glob patterns to find matching files
File Reading: Reads content from all discovered files into memory cache
Transformer Processing: Applies transformers in three phases:
- Pre-transformers
- Default transformers
- Post-transformers
Token Extraction: Scans transformed content for utility class tokens
CSS Generation: Generates CSS from extracted tokens using UnoCSS
Output Writing: Writes CSS to specified file or stdout
Watch Setup (if enabled): Monitors files for changes and rebuilds

Integration Patterns

Script Integration

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

async function buildStyles() {
  console.log("Building CSS...");
  
  await build({
    patterns: ["src/**/*.{html,js,ts,jsx,tsx}"],
    outFile: "public/styles.css",
    minify: process.env.NODE_ENV === "production",
    preflights: true,
  });
  
  console.log("CSS build complete!");
}

buildStyles().catch(console.error);

Build Tool Integration

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

// Custom build script
export async function generateUnoCSS(options: {
  sourceDir: string;
  outputDir: string;
  watch?: boolean;
}) {
  await build({
    patterns: [`${options.sourceDir}/**/*.{html,js,ts}`],
    outFile: `${options.outputDir}/uno.css`,
    watch: options.watch,
    minify: !options.watch,
  });
}

Error Handling

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

async function safeBuild(options: CliOptions) {
  try {
    await build(options);
  } catch (error) {
    if (error instanceof PrettyError) {
      console.error("Build failed:", error.message);
    } else {
      console.error("Unexpected error:", error);
    }
    process.exit(1);
  }
}

Install with Tessl CLI