0
# File Conversion
1

2
Utilities for converting JavaScript files to TypeScript during project setup with configurable conversion strategies.
3

4
## Capabilities
5

6
### Convert Function
7

8
Main conversion function that handles JavaScript to TypeScript file conversion.
9

10
```javascript { .api }
11
/**
12
 * Converts JavaScript files to TypeScript during project generation
13
 * Handles file renaming and content preservation with configurable strategies
14
 * @param api - Generator API instance providing file manipulation methods
15
 * @param options - Conversion configuration options
16
 */
17
function convert(api, options: ConvertOptions = {}): void;
18

19
interface ConvertOptions {
20
  convertJsToTs?: boolean;     // Convert all .js files to .ts (default: true)
21
}
22
```
23

24
**Usage Example:**
25

26
```javascript
27
// Used internally by the generator module
28
const convert = require('@vue/cli-plugin-typescript/generator/convert');
29

30
// Applied during project generation
31
convert(api, { convertJsToTs: true });
32
```
33

34
### File Processing Strategy
35

36
Post-processing logic for handling JavaScript to TypeScript conversion:
37

38
```javascript { .api }
39
/**
40
 * File processing logic applied after template rendering
41
 * Uses api.postProcessFiles to modify generated file structure
42
 * @param files - File object containing generated files
43
 */
44
api.postProcessFiles((files) => {
45
  // Conversion logic applied here
46
});
47
```
48

49
### Full Conversion Mode
50

51
When `convertJsToTs` is true (default), converts all applicable JavaScript files:
52

53
```javascript { .api }
54
/**
55
 * Full conversion mode configuration
56
 * Converts all .js files to .ts except excluded patterns
57
 */
58
const fullConversionConfig = {
59
  jsRE: /\.js$/,                              // Matches .js files
60
  excludeRE: /^tests\/e2e\/|(\.config|rc)\.js$/, // Default exclusions
61
  
62
  // Modified exclusions when e2e-webdriverio plugin is present
63
  webdriverioExcludeRE: /(\.config|rc)\.js$/
64
};
65
```
66

67
**Full Conversion Process:**
68
1. Identify all `.js` files in the project
69
2. Skip files matching exclusion patterns (config files, e2e tests)
70
3. For each `.js` file, create corresponding `.ts` file with same content
71
4. If `.ts` file already exists, prioritize existing `.ts` file
72
5. Remove original `.js` file after successful conversion
73

74
### Selective Conversion Mode  
75

76
When `convertJsToTs` is false, only converts the main entry file:
77

78
```javascript { .api }
79
/**
80
 * Selective conversion mode configuration
81
 * Only converts the main application entry file to TypeScript
82
 */
83
const selectiveConversionConfig = {
84
  entryFile: api.entryFile,        // Main entry file (usually src/main.js)
85
  targetFile: string               // Converted .ts version of entry file
86
};
87
```
88

89
**Selective Conversion Process:**
90
1. Identify main entry file (typically `src/main.js`)
91
2. Create TypeScript version (e.g., `src/main.ts`)
92
3. Copy content from JavaScript file to TypeScript file
93
4. Remove original JavaScript entry file
94
5. Leave all other JavaScript files unchanged
95

96
### File Exclusion Patterns
97

98
Regular expressions for excluding files from conversion:
99

100
```javascript { .api }
101
/**
102
 * File exclusion pattern configuration
103
 * Defines which files should not be converted to TypeScript
104
 */
105
const exclusionPatterns = {
106
  // Default exclusions
107
  default: /^tests\/e2e\/|(\.config|rc)\.js$/,
108
  
109
  // WebDriverIO specific exclusions (less restrictive)
110
  webdriverio: /(\.config|rc)\.js$/
111
};
112
```
113

114
**Excluded File Types:**
115
- Configuration files: `*.config.js`, `*rc.js`
116
- E2E test files: `tests/e2e/**/*.js` (unless using WebDriverIO)
117
- Build and tooling configuration files
118

119
### File Content Preservation
120

121
Content handling during conversion process:
122

123
```javascript { .api }
124
/**
125
 * File content preservation during conversion
126
 * Ensures no content is lost during .js to .ts conversion
127
 */
128
const contentPreservation = {
129
  sourceContent: files[jsFile],     // Original JavaScript content
130
  targetContent: files[tsFile],     // Existing TypeScript content (if any)
131
  
132
  // Priority: existing .ts file > converted .js file content
133
  finalContent: files[tsFile] || files[jsFile]
134
};
135
```
136

137
### Integration with Plugin System
138

139
E2E testing plugin integration affecting conversion behavior:
140

141
```javascript { .api }
142
/**
143
 * Plugin integration affecting file conversion behavior
144
 * Different exclusion patterns based on installed plugins
145
 */
146
if (api.hasPlugin('e2e-webdriverio')) {
147
  // Use less restrictive exclusion pattern
148
  // Allows WebDriverIO test files to be converted to TypeScript
149
  excludeRE = /(\.config|rc)\.js$/;
150
} else {
151
  // Use default exclusion pattern  
152
  // Excludes all e2e test files from conversion
153
  excludeRE = /^tests\/e2e\/|(\.config|rc)\.js$/;
154
}
155
```
156

157
### Conversion Examples
158

159
**Full Conversion Example:**
160

161
```javascript
162
// Before conversion (project files)
163
files = {
164
  'src/main.js': 'import Vue from "vue"...',
165
  'src/components/HelloWorld.js': 'export default {...}',
166
  'vue.config.js': 'module.exports = {...}',
167
  'tests/e2e/specs/test.js': 'describe(...)'
168
};
169

170
// After conversion (convertJsToTs: true)
171
files = {
172
  'src/main.ts': 'import Vue from "vue"...',
173
  'src/components/HelloWorld.ts': 'export default {...}',
174
  'vue.config.js': 'module.exports = {...}', // Excluded
175
  'tests/e2e/specs/test.js': 'describe(...)'  // Excluded
176
};
177
```
178

179
**Selective Conversion Example:**
180

181
```javascript
182
// Before conversion (project files)
183
files = {
184
  'src/main.js': 'import Vue from "vue"...',
185
  'src/components/HelloWorld.js': 'export default {...}',
186
  'src/utils/helpers.js': 'export function helper() {...}'
187
};
188

189
// After conversion (convertJsToTs: false)
190
files = {
191
  'src/main.ts': 'import Vue from "vue"...',           // Converted
192
  'src/components/HelloWorld.js': 'export default {...}', // Unchanged
193
  'src/utils/helpers.js': 'export function helper() {...}' // Unchanged
194
};
195
```
196

197
**Conflict Resolution:**
198

199
```javascript
200
// When both .js and .ts files exist
201
files = {
202
  'src/component.js': '// JavaScript version',
203
  'src/component.ts': '// TypeScript version (existing)'
204
};
205

206
// Result: TypeScript version is preserved
207
files = {
208
  'src/component.ts': '// TypeScript version (existing)'
209
  // JavaScript version is removed
210
};
211
```