0
# Programmatic API
1

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

4
## Capabilities
5

6
### Build Function
7

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

10
```typescript { .api }
11
/**
12
 * Main build function that processes files and generates CSS output
13
 * @param options - Build configuration options
14
 * @returns Promise that resolves when build completes (or starts watching)
15
 * @throws PrettyError if patterns are not provided
16
 */
17
function build(options: CliOptions): Promise<void>;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { build } from "@unocss/cli";
24

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

31
// Build with minification
32
await build({
33
  patterns: ["src/**/*.{html,js}", "components/**/*.tsx"],
34
  outFile: "dist/uno.css",
35
  minify: true,
36
  preflights: true,
37
});
38

39
// Output to stdout
40
await build({
41
  patterns: ["src/**/*.html"],
42
  stdout: true,
43
});
44

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

53
// Transform source files
54
await build({
55
  patterns: ["src/**/*.html"],
56
  outFile: "dist/styles.css",
57
  writeTransformed: true,
58
});
59

60
// Custom working directory
61
await build({
62
  cwd: "/path/to/project",
63
  patterns: ["**/*.html"],
64
  outFile: "styles.css",
65
});
66
```
67

68
### Resolve Options
69

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

72
```typescript { .api }
73
/**
74
 * Validates and resolves CLI options, ensuring patterns are provided
75
 * @param options - CLI configuration options to validate
76
 * @returns Promise resolving to validated options with required patterns
77
 * @throws PrettyError if no patterns are provided
78
 */
79
function resolveOptions(options: CliOptions): Promise<ResolvedCliOptions>;
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
import { resolveOptions } from "@unocss/cli";
86

87
// Validate options before processing
88
try {
89
  const resolved = await resolveOptions({
90
    patterns: ["src/**/*.html"],
91
    outFile: "dist/styles.css",
92
  });
93
  console.log("Options are valid:", resolved);
94
} catch (error) {
95
  console.error("Invalid options:", error.message);
96
}
97

98
// Handle missing patterns
99
try {
100
  await resolveOptions({ outFile: "styles.css" }); // Missing patterns
101
} catch (error) {
102
  console.error(error.message); // "No glob patterns, try unocss <path/to/**/*>"
103
}
104
```
105

106
## Build Process Flow
107

108
The build function follows this processing flow:
109

110
1. **Option Resolution**: Validates options and ensures patterns are provided
111
2. **Configuration Loading**: Loads UnoCSS configuration from specified file or defaults
112
3. **File Discovery**: Uses glob patterns to find matching files
113
4. **File Reading**: Reads content from all discovered files into memory cache
114
5. **Transformer Processing**: Applies transformers in three phases:
115
   - Pre-transformers
116
   - Default transformers  
117
   - Post-transformers
118
6. **Token Extraction**: Scans transformed content for utility class tokens
119
7. **CSS Generation**: Generates CSS from extracted tokens using UnoCSS
120
8. **Output Writing**: Writes CSS to specified file or stdout
121
9. **Watch Setup** (if enabled): Monitors files for changes and rebuilds
122

123
## Integration Patterns
124

125
### Script Integration
126

127
```typescript
128
import { build } from "@unocss/cli";
129

130
async function buildStyles() {
131
  console.log("Building CSS...");
132
  
133
  await build({
134
    patterns: ["src/**/*.{html,js,ts,jsx,tsx}"],
135
    outFile: "public/styles.css",
136
    minify: process.env.NODE_ENV === "production",
137
    preflights: true,
138
  });
139
  
140
  console.log("CSS build complete!");
141
}
142

143
buildStyles().catch(console.error);
144
```
145

146
### Build Tool Integration
147

148
```typescript
149
import { build } from "@unocss/cli";
150

151
// Custom build script
152
export async function generateUnoCSS(options: {
153
  sourceDir: string;
154
  outputDir: string;
155
  watch?: boolean;
156
}) {
157
  await build({
158
    patterns: [`${options.sourceDir}/**/*.{html,js,ts}`],
159
    outFile: `${options.outputDir}/uno.css`,
160
    watch: options.watch,
161
    minify: !options.watch,
162
  });
163
}
164
```
165

166
### Error Handling
167

168
```typescript
169
import { build, PrettyError } from "@unocss/cli";
170

171
async function safeBuild(options: CliOptions) {
172
  try {
173
    await build(options);
174
  } catch (error) {
175
    if (error instanceof PrettyError) {
176
      console.error("Build failed:", error.message);
177
    } else {
178
      console.error("Unexpected error:", error);
179
    }
180
    process.exit(1);
181
  }
182
}
183
```