0
# Project Maintenance
1

2
Update checking, upgrade utilities, migration tools, and environment diagnostics for Vue CLI projects.
3

4
## Capabilities
5

6
### Outdated Command
7

8
Check for outdated Vue CLI service and plugins in current project.
9

10
```bash { .api }
11
/**
12
 * (experimental) Check for outdated vue cli service / plugins
13
 * Scans project dependencies and compares with latest versions
14
 */
15
vue outdated
16

17
Options:
18
  --next    Also check for alpha / beta / rc versions when upgrading
19
```
20

21
**Usage Examples:**
22

23
```bash
24
# Check for outdated dependencies
25
vue outdated
26

27
# Include pre-release versions in check
28
vue outdated --next
29
```
30

31
### Upgrade Command
32

33
Upgrade Vue CLI service and plugins to newer versions.
34

35
```bash { .api }
36
/**
37
 * (experimental) Upgrade vue cli service / plugins
38
 * @param plugin-name - Specific plugin to upgrade (optional)
39
 */
40
vue upgrade [plugin-name]
41

42
Options:
43
  -t, --to <version>         Upgrade <package-name> to a version that is not latest
44
  -f, --from <version>       Skip probing installed plugin, assuming it is upgraded from the designated version
45
  -r, --registry <url>       Use specified npm registry when installing dependencies
46
  --all                      Upgrade all plugins
47
  --next                     Also check for alpha / beta / rc versions when upgrading
48
```
49

50
**Usage Examples:**
51

52
```bash
53
# Upgrade all plugins
54
vue upgrade --all
55

56
# Upgrade specific plugin
57
vue upgrade @vue/cli-plugin-router
58

59
# Upgrade to specific version
60
vue upgrade @vue/cli-service --to 5.0.8
61

62
# Upgrade with custom registry
63
vue upgrade --all --registry https://registry.example.com
64

65
# Include pre-release versions
66
vue upgrade --all --next
67

68
# Upgrade assuming specific current version
69
vue upgrade @vue/cli-service --from 4.5.0
70
```
71

72
### Migrate Command
73

74
Run migration scripts for plugins after version upgrades.
75

76
```bash { .api }
77
/**
78
 * (experimental) Run migrator for an already-installed cli plugin
79
 * @param plugin-name - Plugin to migrate (optional, defaults to all)
80
 */
81
vue migrate [plugin-name]
82

83
Options:
84
  -f, --from <version>    (Required) The base version for the migrator to migrate from
85
```
86

87
**Usage Examples:**
88

89
```bash
90
# Migrate all plugins from version 4.x
91
vue migrate --from 4.0.0
92

93
# Migrate specific plugin
94
vue migrate @vue/cli-plugin-router --from 3.1.0
95

96
# Migrate TypeScript plugin from specific version
97
vue migrate @vue/cli-plugin-typescript --from 4.5.0
98
```
99

100
### Info Command
101

102
Print debugging information about the development environment.
103

104
```bash { .api }
105
/**
106
 * Print debugging information about your environment
107
 * Displays system info, installed versions, and project dependencies
108
 */
109
vue info
110
```
111

112
**Usage Examples:**
113

114
```bash
115
# Display environment information
116
vue info
117
```
118

119
### Outdated Function (Programmatic)
120

121
Programmatic interface for checking outdated dependencies.
122

123
```typescript { .api }
124
/**
125
 * Check for outdated Vue CLI dependencies programmatically
126
 * @param options - Options for outdated check
127
 * @param context - Project directory path
128
 */
129
async function outdated(
130
  options?: OutdatedOptions,
131
  context?: string
132
): Promise<OutdatedResult>;
133

134
interface OutdatedOptions {
135
  /** Include pre-release versions */
136
  next?: boolean;
137
}
138

139
interface OutdatedResult {
140
  /** Outdated packages found */
141
  outdated: OutdatedPackage[];
142
  /** Current Vue CLI service version */
143
  currentService: string;
144
  /** Latest Vue CLI service version */
145
  latestService: string;
146
}
147

148
interface OutdatedPackage {
149
  /** Package name */
150
  name: string;
151
  /** Current installed version */
152
  current: string;
153
  /** Latest available version */
154
  latest: string;
155
  /** Whether update is recommended */
156
  updateRecommended: boolean;
157
}
158
```
159

160
**Usage Examples:**
161

162
```typescript
163
import { outdated } from "@vue/cli";
164

165
// Check for outdated packages
166
const result = await outdated({}, "/path/to/project");
167

168
console.log("Outdated packages:", result.outdated);
169
console.log("Current service:", result.currentService);
170
console.log("Latest service:", result.latestService);
171

172
// Include pre-release versions
173
const nextResult = await outdated({ next: true }, "/path/to/project");
174
```
175

176
### Upgrade Function (Programmatic)
177

178
Programmatic interface for upgrading dependencies.
179

180
```typescript { .api }
181
/**
182
 * Upgrade Vue CLI dependencies programmatically
183
 * @param packageName - Specific package to upgrade (optional)
184
 * @param options - Upgrade options
185
 * @param context - Project directory path
186
 */
187
async function upgrade(
188
  packageName?: string,
189
  options?: UpgradeOptions,
190
  context?: string
191
): Promise<UpgradeResult>;
192

193
interface UpgradeOptions {
194
  /** Upgrade to specific version */
195
  to?: string;
196
  /** Assume current version without probing */
197
  from?: string;
198
  /** NPM registry URL */
199
  registry?: string;
200
  /** Upgrade all packages */
201
  all?: boolean;
202
  /** Include pre-release versions */
203
  next?: boolean;
204
}
205

206
interface UpgradeResult {
207
  /** Successfully upgraded packages */
208
  upgraded: UpgradedPackage[];
209
  /** Failed upgrades */
210
  failed: FailedUpgrade[];
211
  /** Whether any migrations are needed */
212
  migrationsNeeded: boolean;
213
}
214

215
interface UpgradedPackage {
216
  /** Package name */
217
  name: string;
218
  /** Previous version */
219
  from: string;
220
  /** New version */
221
  to: string;
222
}
223

224
interface FailedUpgrade {
225
  /** Package name */
226
  name: string;
227
  /** Error message */
228
  error: string;
229
}
230
```
231

232
### Migrate Function (Programmatic)
233

234
Programmatic interface for running migrations.
235

236
```typescript { .api }
237
/**
238
 * Run plugin migrations programmatically
239
 * @param packageName - Plugin to migrate (optional)
240
 * @param options - Migration options
241
 * @param context - Project directory path
242
 */
243
async function migrate(
244
  packageName?: string,
245
  options?: MigrateOptions,
246
  context?: string
247
): Promise<MigrationResult>;
248

249
interface MigrateOptions {
250
  /** Base version to migrate from (required) */
251
  from: string;
252
}
253

254
interface MigrationResult {
255
  /** Successfully migrated plugins */
256
  migrated: MigratedPlugin[];
257
  /** Failed migrations */
258
  failed: FailedMigration[];
259
  /** Files that were modified */
260
  modifiedFiles: string[];
261
}
262

263
interface MigratedPlugin {
264
  /** Plugin name */
265
  name: string;
266
  /** Version migrated from */
267
  from: string;
268
  /** Version migrated to */
269
  to: string;
270
  /** Migration steps applied */
271
  steps: string[];
272
}
273

274
interface FailedMigration {
275
  /** Plugin name */
276
  name: string;
277
  /** Error message */
278
  error: string;
279
}
280
```
281

282
### Version Checking
283

284
Version detection and comparison utilities.
285

286
```typescript { .api }
287
/**
288
 * Get version information for project dependencies
289
 * @param context - Project directory path
290
 * @returns Version information object
291
 */
292
async function getVersions(context?: string): Promise<VersionInfo>;
293

294
interface VersionInfo {
295
  /** Vue CLI version */
296
  cli: string;
297
  /** Vue CLI service version */
298
  service: string;
299
  /** Vue.js version */
300
  vue: string;
301
  /** Node.js version */
302
  node: string;
303
  /** NPM version */
304
  npm: string;
305
  /** Yarn version (if available) */
306
  yarn?: string;
307
  /** pnpm version (if available) */
308
  pnpm?: string;
309
  /** Installed plugins with versions */
310
  plugins: Record<string, string>;
311
}
312

313
/**
314
 * Check if current CLI version satisfies requirement
315
 * @param range - Semver range requirement
316
 * @returns Whether version is satisfied
317
 */
318
function assertCliVersion(range: string): boolean;
319

320
/**
321
 * Check if current CLI service version satisfies requirement
322
 * @param range - Semver range requirement  
323
 * @returns Whether version is satisfied
324
 */
325
function assertCliServiceVersion(range: string): boolean;
326
```
327

328
### Environment Diagnostics
329

330
Environment information collection for debugging.
331

332
```typescript { .api }
333
/**
334
 * Collect environment diagnostic information
335
 * @returns Environment information object
336
 */
337
async function collectEnvironmentInfo(): Promise<EnvironmentInfo>;
338

339
interface EnvironmentInfo {
340
  /** System information */
341
  system: {
342
    OS: string;
343
    CPU: string;
344
    Memory: string;
345
  };
346
  /** Binary versions */
347
  binaries: {
348
    Node: string;
349
    Yarn: string;
350
    npm: string;
351
  };
352
  /** Browser versions */
353
  browsers: {
354
    Chrome?: string;
355
    Edge?: string;
356
    Firefox?: string;
357
    Safari?: string;
358
  };
359
  /** Vue-related npm packages */
360
  npmPackages: Record<string, string>;
361
  /** Global Vue CLI packages */
362
  npmGlobalPackages: Record<string, string>;
363
}
364
```
365

366
### Migration System
367

368
Plugin migration system for handling breaking changes.
369

370
```typescript { .api }
371
/**
372
 * Plugin migration system structure
373
 */
374
interface Migrator {
375
  /** Plugin ID */
376
  plugin: string;
377
  /** Migration function */
378
  migrate: MigrationFunction;
379
  /** Version range this migration applies to */
380
  version: string;
381
}
382

383
interface MigrationFunction {
384
  (api: MigratorAPI, options: any): Promise<void> | void;
385
}
386

387
/**
388
 * API provided to migration functions
389
 */
390
interface MigratorAPI {
391
  /** Project context path */
392
  context: string;
393
  /** Transform code files */
394
  transformScript(file: string, codemod: any, options?: any): void;
395
  /** Modify package.json */
396
  extendPackage(fields: object): void;
397
  /** Add/modify files */
398
  render(source: string, data?: object): void;
399
  /** Post-process files */
400
  postProcessFiles(callback: (files: any) => void): void;
401
}
402

403
/**
404
 * Common migration scenarios:
405
 * - Update import statements
406
 * - Modify configuration files
407
 * - Transform deprecated API calls
408
 * - Update dependency versions
409
 * - Rename or move files
410
 * - Update webpack configuration
411
 */
412
```
413

414
### Upgrade Strategies
415

416
Different strategies for handling dependency upgrades.
417

418
```typescript { .api }
419
/**
420
 * Upgrade strategies for different scenarios:
421
 */
422
const upgradeStrategies = {
423
  /** Conservative: Only patch and minor updates */
424
  conservative: {
425
    allowMajor: false,
426
    allowMinor: true,
427
    allowPatch: true
428
  },
429
  /** Moderate: Minor and patch updates, selective major */
430
  moderate: {
431
    allowMajor: false,
432
    allowMinor: true,
433
    allowPatch: true,
434
    majorPlugins: ['@vue/cli-service']
435
  },
436
  /** Aggressive: All updates including major versions */
437
  aggressive: {
438
    allowMajor: true,
439
    allowMinor: true,
440
    allowPatch: true
441
  },
442
  /** Security: Only security patches */
443
  security: {
444
    securityOnly: true
445
  }
446
};
447
```
448

449
### Compatibility Checking
450

451
Version compatibility validation and warnings.
452

453
```typescript { .api }
454
/**
455
 * Check compatibility between Vue CLI components
456
 * @param versions - Current version information
457
 * @returns Compatibility report
458
 */
459
function checkCompatibility(versions: VersionInfo): CompatibilityReport;
460

461
interface CompatibilityReport {
462
  /** Overall compatibility status */
463
  compatible: boolean;
464
  /** Compatibility warnings */
465
  warnings: CompatibilityWarning[];
466
  /** Compatibility errors */
467
  errors: CompatibilityError[];
468
  /** Recommendations for fixes */
469
  recommendations: string[];
470
}
471

472
interface CompatibilityWarning {
473
  /** Component with compatibility issue */
474
  component: string;
475
  /** Version with issue */
476
  version: string;
477
  /** Warning message */
478
  message: string;
479
  /** Severity level */
480
  severity: 'low' | 'medium' | 'high';
481
}
482

483
interface CompatibilityError {
484
  /** Component with compatibility error */
485
  component: string;
486
  /** Version with error */
487
  version: string;
488
  /** Error message */
489
  message: string;
490
  /** Whether this blocks functionality */
491
  blocking: boolean;
492
}
493
```