0
# Project Migration
1

2
Migration utilities for upgrading existing projects to TypeScript support with version-specific transformations and dependency management.
3

4
## Capabilities
5

6
### Migrator Function
7

8
Main migration function for existing projects upgrading to TypeScript support.
9

10
```javascript { .api }
11
/**
12
 * Migrates existing projects to TypeScript support
13
 * Handles dependency updates and Vue version-specific transformations
14
 * @param api - Migrator API instance providing project modification methods
15
 * @param options - Migration configuration options
16
 * @param rootOptions - Root project options including Vue version information
17
 */
18
function migrator(api, options: any, rootOptions: RootOptions): void;
19

20
interface RootOptions {
21
  vueVersion?: number;         // Vue major version (2 or 3)
22
  [key: string]: any;          // Additional project configuration
23
}
24
```
25

26
**Usage Example:**
27

28
```javascript
29
// Applied automatically during Vue CLI plugin migration
30
const migrator = require('@vue/cli-plugin-typescript/migrator');
31

32
// Called during project upgrade or migration
33
migrator(api, {}, { vueVersion: 3 });
34
```
35

36
### Dependency Management
37

38
Automatic TypeScript dependency installation with version compatibility.
39

40
```javascript { .api }
41
/**
42
 * Dependency configuration for migration
43
 * Ensures TypeScript is added without version conflicts
44
 */
45
const migrationDependencies = {
46
  devDependencies: {
47
    typescript: string  // Version from plugin's package.json
48
  }
49
};
50

51
// Installation options
52
const installOptions = {
53
  warnIncompatibleVersions: false  // Suppress version warnings during migration
54
};
55
```
56

57
### Vue 3 Migration Support
58

59
Specialized migration support for Vue 3 projects with component type updates.
60

61
```javascript { .api }
62
/**
63
 * Vue 3 specific migration logic
64
 * Updates Vue component type declarations for Vue 3 compatibility
65
 */
66
if (rootOptions.vueVersion === 3) {
67
  // Apply Vue 3 component type migration
68
  api.transformScript('src/shims-vue.d.ts', codemod);
69
}
70
```
71

72
### Component Type Migration
73

74
AST transformation for Vue 3 component type declarations:
75

76
```javascript { .api }
77
/**
78
 * Component type migration using AST transformations
79
 * Updates outdated Vue 3 component type patterns
80
 * @param filePath - Path to the file being transformed
81
 * @param codemod - JSCodeshift transformation function
82
 */
83
api.transformScript(
84
  'src/shims-vue.d.ts', 
85
  require('../codemods/migrateComponentType')
86
);
87
```
88

89
## Codemod Transformations
90

91
### Component Type Codemod
92

93
JSCodeshift transformation for migrating Vue 3 component type definitions:
94

95
```javascript { .api }
96
/**
97
 * Migrates Vue 3 component type definitions from outdated patterns
98
 * Transforms ReturnType<typeof defineComponent> to DefineComponent
99
 * @param file - File AST and source information
100
 * @param api - JSCodeshift API instance
101
 * @returns Transformed source code
102
 */
103
function migrateComponentType(file, api): string;
104
```
105

106
### Migration Pattern
107

108
Specific transformation pattern for Vue 3 component types:
109

110
```typescript
111
// Before migration (outdated pattern)
112
declare module '*.vue' {
113
  import { defineComponent } from 'vue';
114
  const component: ReturnType<typeof defineComponent>;
115
  export default component;
116
}
117

118
// After migration (current pattern)  
119
declare module '*.vue' {
120
  import { DefineComponent } from 'vue';
121
  const component: DefineComponent<{}, {}, any>;
122
  export default component;
123
}
124
```
125

126
### AST Transformation Details
127

128
Low-level AST transformation operations:
129

130
```javascript { .api }
131
/**
132
 * AST transformation configuration for component type migration
133
 * Identifies and replaces specific TypeScript type patterns
134
 */
135
const transformationConfig = {
136
  // Target pattern: ReturnType<typeof defineComponent>
137
  targetPattern: {
138
    typeName: { name: 'ReturnType' },
139
    typeParameters: {
140
      params: [{
141
        exprName: { name: 'defineComponent' }
142
      }]
143
    }
144
  },
145
  
146
  // Replacement pattern: DefineComponent<{}, {}, any>
147
  replacementPattern: {
148
    typeName: 'DefineComponent',
149
    typeParameters: ['{}', '{}', 'any']
150
  }
151
};
152
```
153

154
### Import Statement Management
155

156
Automatic import statement updates during transformation:
157

158
```javascript { .api }
159
/**
160
 * Import statement management during component type migration
161
 * Updates Vue imports to include DefineComponent type
162
 */
163
const importManagement = {
164
  // Add DefineComponent to existing Vue imports
165
  addImport: 'DefineComponent',
166
  
167
  // Remove unused defineComponent import (if no other usage)
168
  removeUnusedImport: 'defineComponent'
169
};
170
```
171

172
### Parser Configuration
173

174
JSCodeshift parser configuration for TypeScript files:
175

176
```javascript { .api }
177
/**
178
 * Parser configuration for TypeScript file transformations
179
 * Ensures proper TypeScript AST parsing
180
 */
181
migrateComponentType.parser = 'ts';
182
```
183

184
### Code Quality Preservation
185

186
Source code formatting and style preservation:
187

188
```javascript { .api }
189
/**
190
 * Code formatting preservation during transformation
191
 * Maintains original code style and formatting preferences
192
 */
193
const formattingConfig = {
194
  lineTerminator: '\n',        // Preserve line endings
195
  quote: 'single' | 'double'   // Detect and preserve quote style
196
};
197
```
198

199
### Usage Detection
200

201
Smart import usage detection to avoid breaking changes:
202

203
```javascript { .api }
204
/**
205
 * Import usage detection for safe transformations
206
 * Prevents removal of imports that are still needed
207
 */
208
const usageDetection = {
209
  // Find all references to defineComponent
210
  findUsages: (ast, identifier) => {
211
    // Filter out import/export statements
212
    // Return actual usage locations
213
  },
214
  
215
  // Safe to remove import if no usages found
216
  canRemoveImport: boolean
217
};
218
```
219

220
### Migration Examples
221

222
**Successful Migration:**
223

224
```typescript
225
// Input file (src/shims-vue.d.ts)
226
declare module '*.vue' {
227
  import { defineComponent } from 'vue';
228
  const component: ReturnType<typeof defineComponent>;
229
  export default component;
230
}
231

232
// Output after migration
233
declare module '*.vue' {
234
  import { DefineComponent } from 'vue';
235
  const component: DefineComponent<{}, {}, any>;
236
  export default component;
237
}
238
```
239

240
**Import Cleanup:**
241

242
```typescript
243
// Before - defineComponent not used elsewhere
244
import { defineComponent } from 'vue';
245

246
// After - defineComponent removed, DefineComponent added
247
import { DefineComponent } from 'vue';
248
```
249

250
**Conditional Migration:**
251

252
```javascript
253
// Migration only applies to specific patterns
254
// Files without target pattern remain unchanged
255
if (componentDecl.length !== 1) {
256
  return file.source; // No changes made
257
}
258
```
259

260
**Migration Process:**
261
1. Check if project is using Vue 3
262
2. Install TypeScript dependency with compatibility settings
263
3. Apply component type transformation to `src/shims-vue.d.ts`
264
4. Update import statements (add DefineComponent, remove unused defineComponent)
265
5. Preserve code formatting and style preferences  
266
6. Return transformed source code or original if no changes needed