@teages/nuxt-legacy

A Nuxt module for supporting legacy browsers.

• ✨  Release Notes

Setup

Install the module to your Nuxt application with one command:

# vite
pnpm add @teages/nuxt-legacy @vitejs/plugin-legacy

Then configure it in your nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@teages/nuxt-legacy'
  ],

  legacy: {
    vite: {}, // `@vitejs/plugin-legacy` options
  },
})

maximum compatibility (not recommended)

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@teages/nuxt-legacy'
  ],

  legacy: {
    vite: {
      targets: ['fully supports proxy'],
      modernPolyfills: true,
    },
  },
})

Compatibility

Nuxt & @vitejs/plugin-legacy

The module is compatible with Nuxt ^3.18.0 || >=4.0.3 and @vitejs/plugin-legacy ^7.0.0 with this version.

Since the module does not depend on any implicit behavior, it should works with any later Nuxt version. But I will recheck compatibility after Nuxt release minor or major versions.

Check the results for current module version:

The test result runs with custom AbortController polyfill, which is not included in this module and you need to add it by yourself, see Custom Polyfills.

Nuxt Version	@vitejs/plugin-legacy	Chrome 49	Chrome 61	Chrome 91
3.20.1	7.0.0	✅ PASS	✅ PASS	✅ PASS
4.2.1	7.0.0	✅ PASS	✅ PASS	✅ PASS

Browser support

The module is tested with the following browsers:

• Chrome 49: The minimum required version for Vue 3
• Chrome 61: supports ESM but does not support widely-available features
• Chrome 91: not support Object.hasOwn but can be polyfilled
• latest Chrome

You can test by yourself by visiting the playground with your target browsers.

Content Security Policy

It injects some inline scripts to fix legacy browser compatibility. The hashes keep sync with the latest version of @vitejs/plugin-legacy, the current value is:

• sha256-MS6/3FCg4WjP9gwgaBGwLpRCY6fZBgwmhVCdrPrNf3E=
• sha256-tQjf8gvb2ROOMapIxFvFAYBeUJ0v1HCbOcSmDNXGtDo=
• sha256-ZxAi3a7m9Mzbc+Z1LGuCCK5Xee6reDkEPRas66H9KSo=
• sha256-+5XkZFazzJo8n0iOP4ti/cLCMUudTf//Mzkb7xNPXIc=

cspHashes is also available in the module:

import { cspHashes } from '@teages/nuxt-legacy'

Custom Polyfills

The module supports custom polyfills to provide additional compatibility for legacy browsers.

This allows you to add polyfills for specific APIs that may not be covered by the Vite legacy plugin (it uses babel and core-js).

Since Nuxt 4.2 and Nuxt 3.20, you need to add AbortController polyfill because it will be used in useFetch and useAsyncData and its polyfill is not included in core-js.

Configuration

You can customize the polyfill behavior in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@teages/nuxt-legacy'],

  legacy: {
    vite: {
      targets: ['fully supports proxy'],
    },

    // Custom polyfills configuration
    customPolyfills: {
      // Specify custom scan directories
      scanDirs: ['polyfills', 'other-polyfills'],

      // Or manually specify polyfill files
      polyfills: [
        './compat/event-target.ts',
        './compat/abort-controller.ts'
      ]
    }
  }
})

Writing Polyfills

Polyfill is a script that runs before your application code.

Here's an example:

// polyfills/event-target.ts
import { EventTarget } from 'event-target-shim'

setup(window)

function setup(self: typeof window) {
  // Check if polyfill is needed
  let isPolyfillNeeded = false
  try {
    const _ = new self.EventTarget()
  }
  catch {
    isPolyfillNeeded = true
  }

  if (!isPolyfillNeeded) {
    return
  }

  // Apply polyfill
  self.EventTarget = EventTarget
}

Credits

• IlyaSemenov/nuxt-vite-legacy: module by @IlyaSemenov with his idea

• BrowserStack. This project is tested with BrowserStack.

Contribution

Local development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release