CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-vue--repl

Vue component for editing Vue components with interactive REPL functionality.

—

Pending
Overview
Eval results
Files

import-map-management.mddocs/

Import Map Management

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.

Capabilities

Vue Import Map Factory

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

/**
 * Creates Vue-specific import map configuration with version management
 * @param defaults - Default URL configurations for Vue runtime
 * @returns Reactive import map system with version controls
 */
function useVueImportMap(defaults?: {
  /** Custom development Vue runtime URL or URL factory function */
  runtimeDev?: string | (() => string);
  /** Custom production Vue runtime URL or URL factory function */
  runtimeProd?: string | (() => string);
  /** Custom Vue server-renderer URL or URL factory function */
  serverRenderer?: string | (() => string);
  /** Initial Vue version to use */
  vueVersion?: string | null;
}): {
  /** Reactive flag for production vs development mode */
  productionMode: Ref<boolean>;
  /** Computed import map configuration */
  importMap: ComputedRef<ImportMap>;
  /** Reactive Vue version reference */
  vueVersion: Ref<string | null>;
  /** Default Vue version from package dependencies */
  defaultVersion: string;
};

Usage Examples:

import { useVueImportMap } from "@vue/repl/core";

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

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

// Switch to production mode
productionMode.value = true;

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

// Access the computed import map
console.log(importMap.value);
// {
//   imports: {
//     "vue": "https://cdn.jsdelivr.net/npm/@vue/runtime-dom@3.4.0/dist/runtime-dom.esm-browser.js",
//     "vue/server-renderer": "https://cdn.jsdelivr.net/npm/@vue/server-renderer@3.4.0/dist/server-renderer.esm-browser.js"
//   }
// }

Import Map Interface

Standard ES import map structure for browser module resolution.

/**
 * Standard ES import map structure for module resolution
 */
interface ImportMap {
  /** Module specifier to URL mappings */
  imports?: Record<string, string | undefined>;
  /** Scoped module mappings for specific URL prefixes */
  scopes?: Record<string, Record<string, string>>;
}

Import Map Utilities

Utility functions for working with import map objects.

/**
 * Merge two import map objects, with second taking precedence
 * @param a - Base import map
 * @param b - Import map to merge (takes precedence)
 * @returns Merged import map with combined imports and scopes
 */
function mergeImportMap(a: ImportMap, b: ImportMap): ImportMap;

Usage Examples:

import { mergeImportMap } from "@vue/repl/core";

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

const additionalMap: ImportMap = {
  imports: {
    'axios': 'https://cdn.skypack.dev/axios',
    'vue': 'https://unpkg.com/vue@3.3.0/dist/vue.esm-browser.js' // Override
  },
  scopes: {
    'https://cdn.skypack.dev/': {
      'vue': 'https://cdn.skypack.dev/vue@3.4.0'
    }
  }
};

const merged = mergeImportMap(baseMap, additionalMap);
console.log(merged);
// {
//   imports: {
//     'vue': 'https://unpkg.com/vue@3.3.0/dist/vue.esm-browser.js', // Override from b
//     'lodash': 'https://cdn.skypack.dev/lodash',
//     'axios': 'https://cdn.skypack.dev/axios'
//   },
//   scopes: {
//     'https://cdn.skypack.dev/': {
//       'vue': 'https://cdn.skypack.dev/vue@3.4.0'
//     }
//   }
// }

Version Management

Utilities for handling Vue version compatibility and feature detection.

/**
 * Parse version string into numeric array for comparison
 * @param version - Semantic version string (e.g., "3.4.0")
 * @returns Array of version numbers [major, minor, patch]
 */
function getVersions(version: string): number[];

/**
 * Check if Vue version supports vapor mode (experimental)
 * @param version - Vue version string
 * @returns True if vapor mode is supported (3.6+)
 */
function isVaporSupported(version: string): boolean;

Usage Examples:

import { getVersions, isVaporSupported } from "@vue/repl/core";

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

// Feature detection
console.log(isVaporSupported('3.5.0')); // false
console.log(isVaporSupported('3.6.0')); // true
console.log(isVaporSupported('3.7.2')); // true

// Version comparison
const [major, minor, patch] = getVersions('3.4.0');
const supportsFeature = major > 3 || (major === 3 && minor >= 4);

CDN URL Generation

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

Development URLs (default mode):

  • Vue 3.6+ with vapor: vue.runtime-with-vapor.esm-browser.js
  • Vue 3.5 and below: runtime-dom.esm-browser.js

Production URLs (when productionMode.value = true):

  • Adds .prod suffix before .js extension
  • Optimized builds with smaller bundle size

CDN Sources:

  • Primary: cdn.jsdelivr.net (fast, reliable)
  • Format: https://cdn.jsdelivr.net/npm/{package}@{version}/dist/{file}
// URLs are automatically generated based on version and mode
const { importMap, vueVersion, productionMode } = useVueImportMap();

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

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

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

Integration with Store

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

// Create store with Vue import map
const { importMap, vueVersion } = useVueImportMap({ vueVersion: '3.4.0' });
const store = useStore({
  builtinImportMap: importMap,
  vueVersion
});

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

// Version changes trigger recompilation
vueVersion.value = '3.3.0'; // Store automatically updates

Custom Module Resolution

Add custom modules to the import map for preview execution:

// Get current store import map
const currentMap = store.getImportMap();

// Add custom dependencies
store.setImportMap({
  ...currentMap,
  imports: {
    ...currentMap.imports,
    'my-library': 'https://cdn.skypack.dev/my-library',
    'utils': './src/utils.js' // Relative imports
  }
});

// Merge approach (preserves existing mappings)
store.setImportMap({
  imports: {
    'lodash': 'https://cdn.skypack.dev/lodash',
    '@vueuse/core': 'https://cdn.skypack.dev/@vueuse/core'
  }
}, true); // merge = true

Error Handling

Import map management includes robust error handling:

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

Install with Tessl CLI

npx tessl i tessl/npm-vue--repl

docs

editor-components.md

file-system.md

import-map-management.md

index.md

preview-system.md

repl-component.md

store-management.md

tile.json