0
# @unocss/cli
1
2
@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.
3
4
## Package Information
5
6
- **Package Name**: @unocss/cli
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @unocss/cli`
10
11
## Core Imports
12
13
Main functionality:
14
15
```typescript
16
import {
17
build,
18
resolveOptions,
19
type CliOptions,
20
type ResolvedCliOptions
21
} from "@unocss/cli";
22
```
23
24
Additional functionality (require specific import paths or may not be directly exported):
25
26
```typescript
27
// These functions are not directly exported from main entry point
28
// They may be available via separate build outputs or internal modules
29
// import { startCli } from "@unocss/cli/cli-start";
30
// import { PrettyError, handleError } from "@unocss/cli/errors";
31
// import { getWatcher } from "@unocss/cli/watcher";
32
// import { defaultConfig } from "@unocss/cli/config";
33
```
34
35
For CommonJS:
36
37
```javascript
38
const { build, resolveOptions } = require("@unocss/cli");
39
// Additional functions may not be directly available from main export
40
```
41
42
## Basic Usage
43
44
### CLI Usage
45
46
```bash
47
# Generate CSS from HTML files
48
unocss "src/**/*.html" -o dist/styles.css
49
50
# Watch mode for development
51
unocss "src/**/*.html" -o dist/styles.css --watch
52
53
# Output to stdout
54
unocss "src/**/*.html" --stdout
55
56
# Use custom config
57
unocss "src/**/*.html" -c uno.config.ts --watch
58
```
59
60
### Programmatic Usage
61
62
```typescript
63
import { build } from "@unocss/cli";
64
65
// Basic CSS generation
66
await build({
67
patterns: ["src/**/*.html"],
68
outFile: "dist/styles.css",
69
minify: true,
70
});
71
72
// Watch mode programmatically
73
await build({
74
patterns: ["src/**/*.html", "src/**/*.js"],
75
outFile: "dist/styles.css",
76
watch: true,
77
preflights: true,
78
});
79
```
80
81
## Architecture
82
83
@unocss/cli is built around several key components:
84
85
- **CLI Interface**: Command-line parsing and option handling via CAC
86
- **Build Engine**: Core CSS generation from utility class scanning
87
- **File Watching**: Development workflow with automatic rebuilding via Chokidar
88
- **Configuration Loading**: Integration with UnoCSS configuration files
89
- **Transformer Processing**: Support for UnoCSS transformers (pre/default/post)
90
91
## Capabilities
92
93
### Command Line Interface
94
95
Full-featured CLI for CSS generation with extensive configuration options including watch mode, custom output paths, and transformer support.
96
97
```typescript { .api }
98
function startCli(
99
cwd?: string,
100
argv?: string[],
101
options?: CliOptions
102
): Promise<void>;
103
```
104
105
[Command Line Interface](./cli.md)
106
107
### Programmatic Build API
108
109
Core build functionality for CSS generation that can be integrated into scripts and build processes.
110
111
```typescript { .api }
112
function build(options: CliOptions): Promise<void>;
113
114
function resolveOptions(options: CliOptions): Promise<ResolvedCliOptions>;
115
116
interface CliOptions {
117
cwd?: string;
118
patterns?: Array<string>;
119
outFile?: string;
120
watch?: boolean;
121
config?: string;
122
stdout?: boolean;
123
writeTransformed?: boolean;
124
preflights?: boolean;
125
minify?: boolean;
126
}
127
128
type ResolvedCliOptions = MarkRequired<CliOptions, 'patterns'>;
129
```
130
131
[Programmatic API](./programmatic.md)
132
133
### File Watching
134
135
Development-focused file watching system for automatic CSS regeneration when source files change.
136
137
```typescript { .api }
138
function getWatcher(options?: CliOptions): Promise<FSWatcher>;
139
```
140
141
[File Watching](./watching.md)
142
143
### Error Handling
144
145
Specialized error handling for CLI operations with user-friendly messages and proper exit codes.
146
147
```typescript { .api }
148
class PrettyError extends Error {
149
constructor(message: string);
150
}
151
152
function handleError(error: unknown): void;
153
```
154
155
[Error Handling](./errors.md)
156
157
### Default Configuration
158
159
Default UnoCSS configuration optimized for CLI usage with build environment settings and preset configurations.
160
161
```typescript { .api }
162
const defaultConfig: UserConfig;
163
```
164
165
The default configuration includes:
166
167
- **envMode**: Set to `'build'` for production-optimized CSS generation
168
- **presets**: Includes `@unocss/preset-uno` for Tailwind-compatible utilities
169
170
**Usage Examples:**
171
172
```typescript
173
import { defaultConfig } from "@unocss/cli";
174
175
// Use default config as base
176
const customConfig = {
177
...defaultConfig,
178
theme: {
179
colors: {
180
primary: '#ff0000'
181
}
182
}
183
};
184
185
// Access default settings
186
console.log(defaultConfig.envMode); // 'build'
187
console.log(defaultConfig.presets); // [presetUno()]
188
```
189
190
## Types
191
192
```typescript { .api }
193
// External types from dependencies
194
import type { FSWatcher } from 'chokidar';
195
import type { UserConfig } from '@unocss/core';
196
197
// Internal utility type for marking properties as required (not exported)
198
declare type MarkRequired<T, RK extends keyof T> = Exclude<T, RK> & Required<Pick<T, RK>>;
199
200
interface CliOptions {
201
/** Working directory for file operations */
202
cwd?: string;
203
/** Glob patterns for files to process */
204
patterns?: Array<string>;
205
/** Output CSS file path */
206
outFile?: string;
207
/** Enable file watching mode */
208
watch?: boolean;
209
/** Path to UnoCSS configuration file */
210
config?: string;
211
/** Output CSS to stdout instead of file */
212
stdout?: boolean;
213
/** Write transformed source files back to disk */
214
writeTransformed?: boolean;
215
/** Enable CSS preflights */
216
preflights?: boolean;
217
/** Minify generated CSS output */
218
minify?: boolean;
219
}
220
221
type ResolvedCliOptions = MarkRequired<CliOptions, 'patterns'>;
222
```