0
# Configuration System
1

2
Flexible configuration management for build settings, site generation, and development workflows through `vant.config.mjs` configuration files.
3

4
## Capabilities
5

6
### Configuration File
7

8
The `vant.config.mjs` file defines project settings that control the build process, site generation, and development workflows.
9

10
```typescript { .api }
11
/**
12
 * Main Vant CLI configuration interface for vant.config.mjs
13
 */
14
interface VantConfig {
15
  /** Project name */
16
  name?: string;
17
  /** Build-related configuration */
18
  build?: BuildConfig;
19
  /** Documentation site configuration */
20
  site?: SiteConfig;
21
}
22
```
23

24
**Basic Configuration:**
25
```javascript
26
// vant.config.mjs
27
export default {
28
  name: 'my-ui-library',
29
  build: {
30
    srcDir: 'src',
31
    tagPrefix: 'my'
32
  }
33
};
34
```
35

36
### Build Configuration
37

38
Configuration options for the build pipeline and output generation.
39

40
```typescript { .api }
41
/**
42
 * Build configuration options
43
 */
44
interface BuildConfig {
45
  /** Source directory path (default: 'src') */
46
  srcDir?: string;
47
  /** Component tag prefix for generated types */
48
  tagPrefix?: string;
49
  /** Enable named exports instead of default exports */
50
  namedExport?: boolean;
51
  /** Dependencies to skip during installation */
52
  skipInstall?: string[];
53
  /** Package manager to use (npm, yarn, pnpm) */
54
  packageManager?: 'npm' | 'yarn' | 'pnpm';
55
  /** File extension configuration */
56
  extensions?: {
57
    /** ESM file extension */
58
    esm?: string;
59
  };
60
  /** Bundle generation options */
61
  bundleOptions?: BundleOption[];
62
  /** Site build configuration */
63
  site?: {
64
    /** Public path for site assets */
65
    publicPath?: string;
66
  };
67
  /** Vetur IDE support configuration */
68
  vetur?: {
69
    /** Tag prefix for Vetur */
70
    tagPrefix?: string;
71
  };
72
  /** CSS processing configuration */
73
  css?: CSSConfig;
74
  /** Custom Vite configuration function */
75
  configureVite?: (config: InlineConfig) => InlineConfig | void;
76
}
77

78
/**
79
 * CSS processing configuration
80
 */
81
interface CSSConfig {
82
  /** CSS preprocessor to use */
83
  preprocessor?: 'css' | 'less' | 'sass';
84
  /** Base CSS file path */
85
  base?: string;
86
  /** Remove source files after compilation */
87
  removeSourceFile?: boolean;
88
}
89

90
/**
91
 * Bundle configuration for different output formats
92
 */
93
interface BundleOption {
94
  /** Enable minification */
95
  minify?: boolean;
96
  /** Output formats to generate */
97
  formats: LibraryFormats[];
98
  /** External dependencies to exclude */
99
  external?: string[];
100
}
101
```
102

103
**Usage:**
104
```javascript
105
// vant.config.mjs
106
export default {
107
  name: 'my-ui-library',
108
  build: {
109
    srcDir: 'components',
110
    tagPrefix: 'my',
111
    namedExport: true,
112
    packageManager: 'pnpm',
113
    css: {
114
      preprocessor: 'less',
115
      base: 'style/base.less'
116
    },
117
    bundleOptions: [
118
      {
119
        minify: true,
120
        formats: ['es', 'cjs'],
121
        external: ['vue']
122
      }
123
    ]
124
  }
125
};
126
```
127

128
### Site Configuration
129

130
Configuration for documentation site generation and appearance.
131

132
```typescript { .api }
133
/**
134
 * Documentation site configuration
135
 */
136
interface SiteConfig {
137
  /** Default language for the site */
138
  defaultLang?: string;
139
  /** CSS class for dark mode */
140
  darkModeClass?: string;
141
  /** CSS class for light mode */
142
  lightModeClass?: string;
143
  /** Enable vConsole for mobile debugging */
144
  enableVConsole?: boolean;
145
  /** Version links for documentation */
146
  versions?: Array<{ label: string; link: string }>;
147
  /** Baidu Analytics configuration */
148
  baiduAnalytics?: {
149
    seed: string;
150
  };
151
  /** ICP license information */
152
  icpLicense?: {
153
    text: string;
154
    link: string;
155
  };
156
  /** Custom HTML to inject in head */
157
  headHtml?: string;
158
  /** Locale-specific configuration */
159
  locales?: Record<string, LocaleConfig>;
160
}
161

162
/**
163
 * Locale-specific configuration for internationalization
164
 */
165
interface LocaleConfig {
166
  /** Language name */
167
  title?: string;
168
  /** Language description */
169
  description?: string;
170
  /** Language code */
171
  lang?: string;
172
  /** Navigation links */
173
  nav?: Array<{
174
    title: string;
175
    items?: Array<{
176
      path: string;
177
      title: string;
178
    }>;
179
  }>;
180
}
181
```
182

183
**Usage:**
184
```javascript
185
// vant.config.mjs
186
export default {
187
  site: {
188
    defaultLang: 'en-US',
189
    darkModeClass: 'theme-dark',
190
    lightModeClass: 'theme-light',
191
    enableVConsole: true,
192
    versions: [
193
      { label: 'v2.x', link: '/v2/' },
194
      { label: 'v3.x', link: '/v3/' }
195
    ],
196
    locales: {
197
      'en-US': {
198
        title: 'My UI Library',
199
        description: 'A Vue.js component library',
200
        lang: 'en-US'
201
      },
202
      'zh-CN': {
203
        title: '我的UI库',
204
        description: 'Vue.js 组件库',
205
        lang: 'zh-CN'
206
      }
207
    }
208
  }
209
};
210
```
211

212
### Path Constants
213

214
Predefined paths used throughout the build system.
215

216
```typescript { .api }
217
/** Current working directory */
218
const CWD: string;
219

220
/** Project root directory (contains vant.config.mjs) */
221
const ROOT: string;
222

223
/** ES modules output directory */
224
const ES_DIR: string;
225

226
/** CommonJS output directory */
227
const LIB_DIR: string;
228

229
/** Documentation directory */
230
const DOCS_DIR: string;
231

232
/** Site build output directory */
233
const SITE_DIST_DIR: string;
234

235
/** Path to vant.config.mjs file */
236
const VANT_CONFIG_FILE: string;
237

238
/** Path to package.json file */
239
const PACKAGE_JSON_FILE: string;
240

241
/** Source directory (configurable via build.srcDir) */
242
const SRC_DIR: string;
243

244
/** Style directory within source */
245
const STYLE_DIR: string;
246

247
/** Supported script file extensions */
248
const SCRIPT_EXTS: string[];
249

250
/** Supported style file extensions */
251
const STYLE_EXTS: string[];
252
```
253

254
**Usage:**
255
```typescript
256
import { SRC_DIR, ES_DIR, LIB_DIR, DOCS_DIR } from "@vant/cli";
257

258
console.log('Source directory:', SRC_DIR);
259
console.log('ES output:', ES_DIR);
260
console.log('CommonJS output:', LIB_DIR);
261
console.log('Documentation:', DOCS_DIR);
262
```
263

264
### Vite Integration
265

266
Integration utilities for custom Vite configuration.
267

268
```typescript { .api }
269
/**
270
 * Merges custom Vite configuration with base configuration
271
 * Loads user's vite.config.js and merges with build-specific config
272
 * @param config - Base Vite configuration
273
 * @param mode - Build mode ('production' | 'development')
274
 * @returns Merged Vite configuration
275
 */
276
function mergeCustomViteConfig(
277
  config: InlineConfig,
278
  mode: 'production' | 'development'
279
): Promise<InlineConfig>;
280
```
281

282
**Usage:**
283
```typescript
284
import { mergeCustomViteConfig } from "@vant/cli";
285
import { type InlineConfig } from 'vite';
286

287
// In build pipeline
288
const baseConfig: InlineConfig = {
289
  build: {
290
    lib: {
291
      entry: './src/index.ts'
292
    }
293
  }
294
};
295

296
const finalConfig = await mergeCustomViteConfig(baseConfig, 'production');
297
```
298

299
## Configuration File Examples
300

301
### Basic Configuration
302

303
```javascript
304
// vant.config.mjs
305
export default {
306
  name: 'my-components',
307
  build: {
308
    srcDir: 'src',
309
    tagPrefix: 'my',
310
    css: {
311
      preprocessor: 'less'
312
    }
313
  }
314
};
315
```
316

317
### Advanced Configuration
318

319
```javascript
320
// vant.config.mjs
321
import { defineConfig } from '@vant/cli';
322

323
export default defineConfig({
324
  name: 'enterprise-ui',
325
  build: {
326
    srcDir: 'packages/components',
327
    tagPrefix: 'ent',
328
    namedExport: true,
329
    packageManager: 'pnpm',
330
    skipInstall: ['@types/node'],
331
    css: {
332
      preprocessor: 'scss',
333
      base: 'styles/foundation.scss',
334
      removeSourceFile: false
335
    },
336
    bundleOptions: [
337
      {
338
        minify: false,
339
        formats: ['es'],
340
        external: ['vue', '@vue/shared']
341
      },
342
      {
343
        minify: true,
344
        formats: ['umd'],
345
        external: []
346
      }
347
    ],
348
    configureVite: (config) => {
349
      config.define = {
350
        __VERSION__: JSON.stringify(process.env.npm_package_version)
351
      };
352
      return config;
353
    }
354
  },
355
  site: {
356
    defaultLang: 'en-US',
357
    darkModeClass: 'dark-theme',
358
    enableVConsole: process.env.NODE_ENV === 'development',
359
    versions: [
360
      { label: 'v1.x', link: 'https://v1.example.com' },
361
      { label: 'v2.x', link: 'https://v2.example.com' }
362
    ],
363
    locales: {
364
      'en-US': {
365
        title: 'Enterprise UI',
366
        description: 'Vue 3 Enterprise Component Library'
367
      },
368
      'zh-CN': {
369
        title: 'Enterprise UI',
370
        description: 'Vue 3 企业级组件库'
371
      }
372
    }
373
  }
374
});
375
```
376

377
### Custom Vite Configuration
378

379
```javascript
380
// vant.config.mjs
381
export default {
382
  name: 'custom-build',
383
  build: {
384
    configureVite: (config) => {
385
      // Add custom plugins
386
      config.plugins = config.plugins || [];
387
      config.plugins.push(
388
        // Custom plugin here
389
      );
390

391
      // Modify build options
392
      config.build = {
393
        ...config.build,
394
        rollupOptions: {
395
          external: ['lodash'],
396
          output: {
397
            globals: {
398
              lodash: '_'
399
            }
400
          }
401
        }
402
      };
403

404
      return config;
405
    }
406
  }
407
};
408
```
409

410
## Environment Variables
411

412
Configuration system respects the following environment variables:
413

414
```typescript
415
// Set by CLI commands
416
process.env.NODE_ENV          // 'development' | 'production' | 'test'
417
process.env.BABEL_MODULE      // 'esmodule' | 'commonjs'
418
process.env.BUILD_TARGET      // 'site' | 'package'
419
process.env.VANT_CLI_VERSION  // Current CLI version
420
```
421

422
## Configuration Validation
423

424
The system provides built-in validation for configuration options:
425

426
- Validates file paths exist
427
- Checks preprocessor availability
428
- Validates package manager existence
429
- Ensures required dependencies are available
430
- Provides helpful error messages for common misconfigurations
431

432
## Migration and Compatibility
433

434
When upgrading Vant CLI versions:
435

436
1. Configuration format is backward compatible
437
2. Deprecated options show warning messages
438
3. Default values handle missing configuration keys
439
4. Migration guides available for major version changes