0
# Core Utilities
1

2
Essential utilities for file operations, path manipulation, string transformations, and component analysis. These are internal APIs used throughout the build system. While technically accessible, they are not part of the public API and may change between versions.
3

4
**⚠️ Important Note**: The functions documented below are internal implementation details and are NOT exported from the main @vant/cli package. They cannot be imported and used programmatically. The usage examples are provided for documentation purposes only to understand the build system's internal workings.
5

6
## Capabilities
7

8
### File Type Detection
9

10
Utilities for detecting different types of files in Vue component libraries.
11

12
```typescript { .api }
13
/**
14
 * Checks if path is a directory
15
 * @param dir - Path to check
16
 * @returns True if path is a directory
17
 */
18
function isDir(dir: string): boolean;
19

20
/**
21
 * Checks if path is a demo directory
22
 * @param dir - Path to check
23
 * @returns True if path matches demo directory pattern
24
 */
25
function isDemoDir(dir: string): boolean;
26

27
/**
28
 * Checks if path is a test directory
29
 * @param dir - Path to check  
30
 * @returns True if path matches test directory pattern
31
 */
32
function isTestDir(dir: string): boolean;
33

34
/**
35
 * Checks if file is an asset (image, font, etc.)
36
 * @param path - File path to check
37
 * @returns True if file matches asset pattern
38
 */
39
function isAsset(path: string): boolean;
40

41
/**
42
 * Checks if file is a Vue Single File Component
43
 * @param path - File path to check
44
 * @returns True if file has .vue extension
45
 */
46
function isSfc(path: string): boolean;
47

48
/**
49
 * Checks if file is a style file (CSS, Less, Sass)
50
 * @param path - File path to check
51
 * @returns True if file matches style pattern
52
 */
53
function isStyle(path: string): boolean;
54

55
/**
56
 * Checks if file is a script file (JS, TS, JSX, TSX)
57
 * @param path - File path to check
58
 * @returns True if file matches script pattern
59
 */
60
function isScript(path: string): boolean;
61

62
/**
63
 * Checks if file is JSX/TSX
64
 * @param path - File path to check
65
 * @returns True if file matches JSX pattern
66
 */
67
function isJsx(path: string): boolean;
68
```
69

70
**Usage (Internal API - Not Recommended):**
71
```typescript
72
// Note: These functions are not publicly exported and may change
73
import { isSfc, isStyle, isScript, isAsset } from "@vant/cli";
74

75
const files = [
76
  "Button.vue",
77
  "button.less", 
78
  "index.ts",
79
  "logo.png"
80
];
81

82
files.forEach(file => {
83
  if (isSfc(file)) console.log(`${file} is a Vue component`);
84
  if (isStyle(file)) console.log(`${file} is a style file`);
85
  if (isScript(file)) console.log(`${file} is a script file`);
86
  if (isAsset(file)) console.log(`${file} is an asset`);
87
});
88
```
89

90
### Path Manipulation
91

92
Utilities for working with file paths and extensions.
93

94
```typescript { .api }
95
/**
96
 * Removes file extension from path
97
 * @param path - File path with extension
98
 * @returns Path without extension
99
 */
100
function removeExt(path: string): string;
101

102
/**
103
 * Replaces file extension
104
 * @param path - Original file path
105
 * @param ext - New extension (with or without dot)
106
 * @returns Path with new extension
107
 */
108
function replaceExt(path: string, ext: string): string;
109

110
/**
111
 * Normalizes path separators for cross-platform compatibility
112
 * @param path - Path to normalize
113
 * @returns Path with forward slashes
114
 */
115
function normalizePath(path: string): string;
116
```
117

118
**Usage:**
119
```typescript
120
import { removeExt, replaceExt, normalizePath } from "@vant/cli";
121

122
console.log(removeExt("button.vue"));        // "button"
123
console.log(replaceExt("button.ts", ".js")); // "button.js"
124
console.log(normalizePath("src\\components\\Button.vue")); // "src/components/Button.vue"
125
```
126

127
### String Transformations
128

129
Case conversion utilities commonly used in Vue component development.
130

131
```typescript { .api }
132
/**
133
 * Converts kebab-case to camelCase
134
 * @param str - String in kebab-case
135
 * @returns String in camelCase
136
 */
137
function camelize(str: string): string;
138

139
/**
140
 * Converts string to PascalCase
141
 * @param str - String to convert
142
 * @returns String in PascalCase
143
 */
144
function pascalize(str: string): string;
145

146
/**
147
 * Converts camelCase to kebab-case
148
 * @param str - String in camelCase
149
 * @param sep - Separator character (default: '-')
150
 * @returns String in kebab-case
151
 */
152
function decamelize(str: string, sep?: string): string;
153
```
154

155
**Usage:**
156
```typescript
157
import { camelize, pascalize, decamelize } from "@vant/cli";
158

159
console.log(camelize("user-profile"));     // "userProfile"
160
console.log(pascalize("user-profile"));    // "UserProfile"
161
console.log(decamelize("UserProfile"));    // "user-profile"
162
console.log(decamelize("UserProfile", "_")); // "user_profile"
163
```
164

165
### Component Analysis
166

167
Utilities for analyzing Vue component structure and exports.
168

169
```typescript { .api }
170
/**
171
 * Gets all component directory names from src directory
172
 * Filters for directories with valid entry files containing exports
173
 * @returns Array of component directory names
174
 */
175
function getComponents(): string[];
176

177
/**
178
 * Checks if code contains export statements or defineOptions
179
 * @param code - Source code to analyze
180
 * @returns True if code has valid exports
181
 */
182
function hasExportOrDefineOptions(code: string): boolean;
183
```
184

185
**Usage:**
186
```typescript
187
import { getComponents, hasExportOrDefineOptions } from "@vant/cli";
188

189
// Get all component directories
190
const components = getComponents();
191
console.log(components); // ["button", "input", "dialog"]
192

193
// Check if file has valid exports
194
const code = `
195
export default {
196
  name: 'Button'
197
};
198
`;
199
console.log(hasExportOrDefineOptions(code)); // true
200
```
201

202
### Environment Management
203

204
Utilities for managing build environment and detecting development mode.
205

206
```typescript { .api }
207
/**
208
 * Sets module environment for Babel transpilation
209
 * @param value - Module environment type
210
 */
211
function setModuleEnv(value: ModuleEnv): void;
212

213
/**
214
 * Sets Node.js environment
215
 * @param value - Node environment type
216
 */
217
function setNodeEnv(value: NodeEnv): void;
218

219
/**
220
 * Sets build target for conditional logic
221
 * @param value - Build target type
222
 */
223
function setBuildTarget(value: BuildTarget): void;
224

225
/**
226
 * Checks if currently in development mode
227
 * @returns True if NODE_ENV is 'development'
228
 */
229
function isDev(): boolean;
230

231
// Environment types
232
type ModuleEnv = 'esmodule' | 'commonjs';
233
type NodeEnv = 'production' | 'development' | 'test';
234
type BuildTarget = 'site' | 'package';
235
```
236

237
**Usage:**
238
```typescript
239
import { setNodeEnv, setModuleEnv, isDev } from "@vant/cli";
240

241
// Set production environment
242
setNodeEnv('production');
243
setModuleEnv('esmodule');
244

245
// Check development mode
246
if (isDev()) {
247
  console.log('Development mode active');
248
}
249
```
250

251
### File Operations
252

253
Advanced file operation utilities.
254

255
```typescript { .api }
256
/**
257
 * Writes file only if content has changed (smart output)
258
 * Prevents unnecessary file system writes and timestamp updates
259
 * @param filePath - Path to output file
260
 * @param content - Content to write
261
 */
262
function smartOutputFile(filePath: string, content: string): void;
263
```
264

265
**Usage:**
266
```typescript
267
import { smartOutputFile } from "@vant/cli";
268

269
// Only writes if content is different from existing file
270
smartOutputFile("./dist/bundle.js", generatedCode);
271
```
272

273
### Configuration Integration
274

275
Utilities for integrating with Vite configuration.
276

277
```typescript { .api }
278
/**
279
 * Merges custom Vite configuration with base configuration
280
 * @param config - Base Vite configuration
281
 * @param mode - Build mode ('production' | 'development')
282
 * @returns Merged configuration
283
 */
284
function mergeCustomViteConfig(
285
  config: InlineConfig, 
286
  mode: 'production' | 'development'
287
): Promise<InlineConfig>;
288
```
289

290
**Usage:**
291
```typescript
292
import { mergeCustomViteConfig } from "@vant/cli";
293
import { type InlineConfig } from 'vite';
294

295
const baseConfig: InlineConfig = {
296
  // Base configuration
297
};
298

299
const finalConfig = await mergeCustomViteConfig(baseConfig, 'production');
300
```
301

302
## Regular Expression Constants
303

304
Predefined patterns for file type detection:
305

306
```typescript { .api }
307
// File extension patterns
308
const EXT_REGEXP: RegExp;        // /\.\w+$/
309
const SFC_REGEXP: RegExp;        // /\.(vue)$/
310
const DEMO_REGEXP: RegExp;       // /\/demo$/
311
const TEST_REGEXP: RegExp;       // /\/test$/
312
const ASSET_REGEXP: RegExp;      // /\.(png|jpe?g|gif|webp|ico|jfif|svg|woff2?|ttf)$/i
313
const STYLE_REGEXP: RegExp;      // /\.(css|less|scss)$/
314
const SCRIPT_REGEXP: RegExp;     // /\.(js|ts|jsx|tsx)$/
315
const JSX_REGEXP: RegExp;        // /\.(j|t)sx$/
316

317
// Supported file extensions
318
const ENTRY_EXTS: string[];      // ['js', 'ts', 'tsx', 'jsx', 'vue']
319
```
320

321
**Usage:**
322
```typescript
323
import { STYLE_REGEXP, SCRIPT_REGEXP } from "@vant/cli";
324

325
function categorizeFile(filename: string) {
326
  if (STYLE_REGEXP.test(filename)) return 'style';
327
  if (SCRIPT_REGEXP.test(filename)) return 'script';
328
  return 'other';
329
}
330
```
331

332
## Package Management Utilities
333

334
Additional utilities for package management:
335

336
```typescript { .api }
337
/**
338
 * Checks if Yarn is available in the system
339
 * @returns True if Yarn is installed and accessible
340
 */
341
function hasYarn(): boolean;
342

343
/**
344
 * Gets the configured package manager
345
 * @returns Package manager name ('yarn', 'npm', or custom)
346
 */
347
function getPackageManager(): 'yarn' | 'npm' | string;
348

349
/**
350
 * Installs project dependencies using detected package manager
351
 * @returns Promise that resolves when installation is complete
352
 */
353
function installDependencies(): Promise<void>;
354
```
355

356
## Logging Utilities
357

358
```typescript { .api }
359
/**
360
 * Returns a colored, shortened path relative to project root
361
 * @param path - Full file path
362
 * @returns Shortened, colored path for logging
363
 */
364
function slimPath(path: string): string;
365
```