or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcsp.mdindex.mdpolyfills.md
tile.json

tessl/npm-vitejs--plugin-legacy

Vite plugin to support legacy browsers that do not support native ESM

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@vitejs/plugin-legacy@7.2.x

To install, run

npx @tessl/cli install tessl/npm-vitejs--plugin-legacy@7.2.0

index.mddocs/

@vitejs/plugin-legacy

@vitejs/plugin-legacy is a Vite plugin that provides comprehensive legacy browser support by automatically generating SystemJS-compatible chunks and polyfills. It enables modern Vite applications to run in browsers that don't support native ESM modules, dynamic imports, or import.meta.

Package Information

  • Package Name: @vitejs/plugin-legacy
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @vitejs/plugin-legacy

Core Imports

import legacy from '@vitejs/plugin-legacy';

For CommonJS:

const legacy = require('@vitejs/plugin-legacy');
// Or using destructuring
const { default: legacy } = require('@vitejs/plugin-legacy');

Basic Usage

import { defineConfig } from 'vite';
import legacy from '@vitejs/plugin-legacy';

export default defineConfig({
  plugins: [
    legacy({
      targets: ['defaults', 'not IE 11'],
    }),
  ],
});

Note: Terser must be installed as a peer dependency:

npm install -D terser

Architecture

@vitejs/plugin-legacy implements a comprehensive legacy browser support system through:

  • Build Configuration: Automatically configures Vite build settings for legacy and modern builds
  • Dual Bundle Generation: Creates both modern ESM bundles and legacy SystemJS bundles
  • Polyfill Detection: Uses Babel preset-env to automatically detect and inject required polyfills
  • HTML Injection: Conditionally loads legacy bundles using nomodule script tags
  • Code Transformation: Transforms modern JavaScript to legacy-compatible code using Babel

Capabilities

Main Plugin Function

Creates Vite plugins for legacy browser support with automatic polyfill detection and dual bundle generation.

/**
 * Main plugin factory function that creates legacy browser support plugins
 * @param options - Configuration options for legacy browser support
 * @returns Array of three Vite plugins for complete legacy support
 */
function viteLegacyPlugin(options?: Options): Plugin[];

Plugin Configuration

Polyfill Detection

Analyzes code to detect required polyfills for specified browser targets.

/**
 * Detects required polyfills by analyzing code with Babel preset-env
 * @param code - JavaScript/TypeScript code to analyze
 * @param targets - Browser targets for polyfill detection
 * @param assumptions - Babel assumptions for code analysis
 * @param list - Set to populate with discovered polyfill imports
 */
function detectPolyfills(
  code: string,
  targets: any,
  assumptions: Record<string, boolean>,
  list: Set<string>
): Promise<void>;

Polyfill Detection

CSP Hash Values

SHA-256 hashes for Content Security Policy script-src allowlist.

/**
 * Array of SHA-256 hash values for inline scripts used by the plugin
 * Use these in your CSP script-src directive to allow plugin-generated inline scripts
 */
const cspHashes: string[];

CSP Configuration

CommonJS Compatibility

The plugin provides full CommonJS compatibility through a dedicated export.

/**
 * CommonJS-compatible version of the plugin with all exports
 * Includes viteLegacyPlugin as default, plus detectPolyfills and cspHashes
 */
const viteLegacyPluginCjs: typeof viteLegacyPlugin & {
  default: typeof viteLegacyPlugin;
  detectPolyfills: typeof detectPolyfills;
  cspHashes: typeof cspHashes;
};

Types

interface Options {
  /** Browser targets for legacy builds (default: 'defaults') */
  targets?: string | string[] | Record<string, string>;
  /** Browser targets for modern builds */
  modernTargets?: string | string[];
  /** Polyfill configuration (default: true) */
  polyfills?: boolean | string[];
  /** Additional polyfills for legacy builds */
  additionalLegacyPolyfills?: string[];
  /** Additional polyfills for modern builds */
  additionalModernPolyfills?: string[];
  /** Modern polyfill configuration (default: false) */
  modernPolyfills?: boolean | string[];
  /** Generate legacy SystemJS chunks (default: true) */
  renderLegacyChunks?: boolean;
  /** Use external SystemJS loading (default: false) */
  externalSystemJS?: boolean;
  /** Generate modern ESM chunks (default: true) */
  renderModernChunks?: boolean;
  /** Babel assumptions for code transformation (default: {}) */
  assumptions?: Record<string, boolean>;
}