0
# Import Map Management
1

2
Import map management provides Vue-specific utilities for managing CDN URLs, version switching, and ES module resolution in the browser environment. It handles Vue runtime imports, version compatibility, and module resolution for the preview system.
3

4
## Capabilities
5

6
### Vue Import Map Factory
7

8
Creates Vue-specific import map configuration with version management and production/development mode switching.
9

10
```typescript { .api }
11
/**
12
 * Creates Vue-specific import map configuration with version management
13
 * @param defaults - Default URL configurations for Vue runtime
14
 * @returns Reactive import map system with version controls
15
 */
16
function useVueImportMap(defaults?: {
17
  /** Custom development Vue runtime URL or URL factory function */
18
  runtimeDev?: string | (() => string);
19
  /** Custom production Vue runtime URL or URL factory function */
20
  runtimeProd?: string | (() => string);
21
  /** Custom Vue server-renderer URL or URL factory function */
22
  serverRenderer?: string | (() => string);
23
  /** Initial Vue version to use */
24
  vueVersion?: string | null;
25
}): {
26
  /** Reactive flag for production vs development mode */
27
  productionMode: Ref<boolean>;
28
  /** Computed import map configuration */
29
  importMap: ComputedRef<ImportMap>;
30
  /** Reactive Vue version reference */
31
  vueVersion: Ref<string | null>;
32
  /** Default Vue version from package dependencies */
33
  defaultVersion: string;
34
};
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { useVueImportMap } from "@vue/repl/core";
41

42
// Basic usage with defaults
43
const { importMap, vueVersion, productionMode } = useVueImportMap();
44

45
// Custom configuration
46
const { importMap, vueVersion, productionMode } = useVueImportMap({
47
  runtimeDev: 'https://unpkg.com/vue@3.4.0/dist/vue.esm-browser.js',
48
  runtimeProd: 'https://unpkg.com/vue@3.4.0/dist/vue.esm-browser.prod.js',
49
  serverRenderer: 'https://unpkg.com/@vue/server-renderer@3.4.0/dist/server-renderer.esm-browser.js',
50
  vueVersion: '3.4.0'
51
});
52

53
// Switch to production mode
54
productionMode.value = true;
55

56
// Change Vue version dynamically
57
vueVersion.value = '3.3.0'; // Automatically updates import map
58

59
// Access the computed import map
60
console.log(importMap.value);
61
// {
62
//   imports: {
63
//     "vue": "https://cdn.jsdelivr.net/npm/@vue/runtime-dom@3.4.0/dist/runtime-dom.esm-browser.js",
64
//     "vue/server-renderer": "https://cdn.jsdelivr.net/npm/@vue/server-renderer@3.4.0/dist/server-renderer.esm-browser.js"
65
//   }
66
// }
67
```
68

69
### Import Map Interface
70

71
Standard ES import map structure for browser module resolution.
72

73
```typescript { .api }
74
/**
75
 * Standard ES import map structure for module resolution
76
 */
77
interface ImportMap {
78
  /** Module specifier to URL mappings */
79
  imports?: Record<string, string | undefined>;
80
  /** Scoped module mappings for specific URL prefixes */
81
  scopes?: Record<string, Record<string, string>>;
82
}
83
```
84

85
### Import Map Utilities
86

87
Utility functions for working with import map objects.
88

89
```typescript { .api }
90
/**
91
 * Merge two import map objects, with second taking precedence
92
 * @param a - Base import map
93
 * @param b - Import map to merge (takes precedence)
94
 * @returns Merged import map with combined imports and scopes
95
 */
96
function mergeImportMap(a: ImportMap, b: ImportMap): ImportMap;
97
```
98

99
**Usage Examples:**
100

101
```typescript
102
import { mergeImportMap } from "@vue/repl/core";
103

104
const baseMap: ImportMap = {
105
  imports: {
106
    'vue': 'https://cdn.jsdelivr.net/npm/vue@3.4.0/dist/vue.esm-browser.js',
107
    'lodash': 'https://cdn.skypack.dev/lodash'
108
  }
109
};
110

111
const additionalMap: ImportMap = {
112
  imports: {
113
    'axios': 'https://cdn.skypack.dev/axios',
114
    'vue': 'https://unpkg.com/vue@3.3.0/dist/vue.esm-browser.js' // Override
115
  },
116
  scopes: {
117
    'https://cdn.skypack.dev/': {
118
      'vue': 'https://cdn.skypack.dev/vue@3.4.0'
119
    }
120
  }
121
};
122

123
const merged = mergeImportMap(baseMap, additionalMap);
124
console.log(merged);
125
// {
126
//   imports: {
127
//     'vue': 'https://unpkg.com/vue@3.3.0/dist/vue.esm-browser.js', // Override from b
128
//     'lodash': 'https://cdn.skypack.dev/lodash',
129
//     'axios': 'https://cdn.skypack.dev/axios'
130
//   },
131
//   scopes: {
132
//     'https://cdn.skypack.dev/': {
133
//       'vue': 'https://cdn.skypack.dev/vue@3.4.0'
134
//     }
135
//   }
136
// }
137
```
138

139
### Version Management
140

141
Utilities for handling Vue version compatibility and feature detection.
142

143
```typescript { .api }
144
/**
145
 * Parse version string into numeric array for comparison
146
 * @param version - Semantic version string (e.g., "3.4.0")
147
 * @returns Array of version numbers [major, minor, patch]
148
 */
149
function getVersions(version: string): number[];
150

151
/**
152
 * Check if Vue version supports vapor mode (experimental)
153
 * @param version - Vue version string
154
 * @returns True if vapor mode is supported (3.6+)
155
 */
156
function isVaporSupported(version: string): boolean;
157
```
158

159
**Usage Examples:**
160

161
```typescript
162
import { getVersions, isVaporSupported } from "@vue/repl/core";
163

164
// Version parsing
165
const versions = getVersions('3.4.15');
166
console.log(versions); // [3, 4, 15]
167

168
// Feature detection
169
console.log(isVaporSupported('3.5.0')); // false
170
console.log(isVaporSupported('3.6.0')); // true
171
console.log(isVaporSupported('3.7.2')); // true
172

173
// Version comparison
174
const [major, minor, patch] = getVersions('3.4.0');
175
const supportsFeature = major > 3 || (major === 3 && minor >= 4);
176
```
177

178
### CDN URL Generation
179

180
The import map system automatically generates appropriate CDN URLs based on Vue version and mode:
181

182
**Development URLs** (default mode):
183
- Vue 3.6+ with vapor: `vue.runtime-with-vapor.esm-browser.js`
184
- Vue 3.5 and below: `runtime-dom.esm-browser.js`
185

186
**Production URLs** (when `productionMode.value = true`):
187
- Adds `.prod` suffix before `.js` extension
188
- Optimized builds with smaller bundle size
189

190
**CDN Sources:**
191
- Primary: `cdn.jsdelivr.net` (fast, reliable)
192
- Format: `https://cdn.jsdelivr.net/npm/{package}@{version}/dist/{file}`
193

194
```typescript
195
// URLs are automatically generated based on version and mode
196
const { importMap, vueVersion, productionMode } = useVueImportMap();
197

198
vueVersion.value = '3.4.0';
199
productionMode.value = false;
200
// Generates: https://cdn.jsdelivr.net/npm/@vue/runtime-dom@3.4.0/dist/runtime-dom.esm-browser.js
201

202
productionMode.value = true;
203
// Generates: https://cdn.jsdelivr.net/npm/@vue/runtime-dom@3.4.0/dist/runtime-dom.esm-browser.prod.js
204

205
vueVersion.value = '3.6.0';
206
// Generates: https://cdn.jsdelivr.net/npm/vue@3.6.0/dist/vue.runtime-with-vapor.esm-browser.prod.js
207
```
208

209
### Integration with Store
210

211
Import maps integrate seamlessly with the store system for dynamic module resolution:
212

213
```typescript
214
// Create store with Vue import map
215
const { importMap, vueVersion } = useVueImportMap({ vueVersion: '3.4.0' });
216
const store = useStore({
217
  builtinImportMap: importMap,
218
  vueVersion
219
});
220

221
// Import map is automatically applied to preview
222
store.init();
223

224
// Version changes trigger recompilation
225
vueVersion.value = '3.3.0'; // Store automatically updates
226
```
227

228
### Custom Module Resolution
229

230
Add custom modules to the import map for preview execution:
231

232
```typescript
233
// Get current store import map
234
const currentMap = store.getImportMap();
235

236
// Add custom dependencies
237
store.setImportMap({
238
  ...currentMap,
239
  imports: {
240
    ...currentMap.imports,
241
    'my-library': 'https://cdn.skypack.dev/my-library',
242
    'utils': './src/utils.js' // Relative imports
243
  }
244
});
245

246
// Merge approach (preserves existing mappings)
247
store.setImportMap({
248
  imports: {
249
    'lodash': 'https://cdn.skypack.dev/lodash',
250
    '@vueuse/core': 'https://cdn.skypack.dev/@vueuse/core'
251
  }
252
}, true); // merge = true
253
```
254

255
## Error Handling
256

257
Import map management includes robust error handling:
258

259
- **Invalid URLs**: Malformed URLs are automatically corrected when possible
260
- **Version resolution**: Fallback to default version on invalid version strings  
261
- **CDN failures**: Import map validation and error reporting
262
- **Merge conflicts**: Predictable precedence rules for conflicting imports