Registry / web-framework / nuxt-vite-legacy

nuxt-vite-legacy

library2.0.1jsnpmunverified

The `nuxt-vite-legacy` module integrates `@vitejs/plugin-legacy` into Nuxt 3 applications, enabling support for older web browsers that do not fully adhere to modern JavaScript standards, specifically those lacking `<script type="module">` support. It provides polyfills and a separate legacy bundle, addressing a gap that the core Nuxt team opted not to address directly. The current stable version is 2.0.1, which proactively supports Vite v7. This package maintains an irregular release cadence, typically updating to align with major or minor releases of Nuxt and Vite. Its primary differentiator is offering a practical solution for targeting very old browsers, which is not an out-of-the-box feature in modern Nuxt applications.

web-framework devops

npm install nuxt-vite-legacy

github ↗package ↗

INSTALL

IMPORT

SIG · NUXT-VITE-LEGACY

nuxt-vite-legacy

web-frameworkjavascriptv2.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

module activation string

✓ modules: ["nuxt-vite-legacy"]

✗ import nuxtViteLegacy from 'nuxt-vite-legacy'

Nuxt modules are enabled by adding their package name string to the `modules` array in `nuxt.config.ts`, not by direct import.

legacy configuration object

✓ legacy: { targets: ['chrome 49'], additionalLegacyPolyfills: [...] }

✗ legacy: { }

While the `legacy` property is optional, omitting `targets` or providing an empty object will result in no specific legacy browser support being configured by the plugin.

defineNuxtConfig

✓ import { defineNuxtConfig } from 'nuxt'

✗ const defineNuxtConfig = require('nuxt').defineNuxtConfig

All modern Nuxt configurations should use `defineNuxtConfig` from 'nuxt' with ESM imports for proper type inference and module resolution.

This quickstart demonstrates how to install `nuxt-vite-legacy` and configure it in your `nuxt.config.ts` to target specific legacy browsers like Chrome 49, including additional polyfills.

import { defineNuxtConfig } from 'nuxt' export default defineNuxtConfig({ // Ensure Nuxt.js is configured for SSR if you intend to use it with legacy browser detection. ssr: true, // Add 'nuxt-vite-legacy' to the modules array to enable the plugin. // This makes the module active in your Nuxt application. modules: [ "nuxt-vite-legacy" ], // Optionally, provide specific configuration options for @vitejs/plugin-legacy. // This object is passed directly to the underlying Vite plugin. legacy: { // Define the browser targets for the legacy build. These are standard Browserslist queries. // For example, 'chrome 49' targets Chrome version 49. // For wider support, you might include 'ie 11' or 'safari 9'. targets: [ "chrome 49", "IE 11" ], // Add additional polyfills if certain APIs are missing in your target browsers // and not automatically provided by @vitejs/plugin-legacy. additionalLegacyPolyfills: [ // Example: Polyfilling getAttributeNames for very old browsers. "mdn-polyfills/Element.prototype.getAttributeNames" ], // By default, the plugin generates both modern and legacy bundles. // You can disable modern bundle generation if only legacy support is needed, // but this is generally not recommended for performance. modernPolyfills: true } })

Debug

Known issues

breakingVersion 2.0.0 introduced breaking changes by updating core dependencies to Nuxt 3.15 and Vite 6. Applications on older Nuxt or Vite versions may experience build failures or runtime issues.

fix

Upgrade your Nuxt application to Nuxt 3.15+ and Vite 6+. Ensure all related dependencies are also compatible with these versions.

affects: >=2.0.0

gotchaThe module's legacy build primarily targets browsers that *do not* support `<script type="module">`. However, some legacy browsers (e.g., Chrome 61-62) support modules but lack modern JavaScript features like async generators. This module does not inject the special detection scripts provided by vanilla `@vitejs/plugin-legacy` into SSR HTML, potentially leading to incompatibility in this specific 'in-between' browser segment.

fix

For comprehensive support in browsers that support `<script type="module">` but lack modern features, manual implementation of feature detection or further polyfilling might be required, or consider contributing to the module to add the missing detection scripts.

affects: >=1.0.0

gotchaThe module's compatibility matrix with varying Nuxt and `@vitejs/plugin-legacy` versions is not extensively tested. Using a newer Nuxt with an older `@vitejs/plugin-legacy` (or vice versa) can lead to unexpected build issues or incorrect behavior.

fix

Always install `nuxt-vite-legacy` along with the recommended Nuxt and Vite versions specified in its release notes. If issues arise after an upgrade, verify the compatibility of all three packages. Consider reviewing the module's GitHub issues for reported version mismatches.

affects: >=1.0.0

Errors

Common errors & fixes

Module not found: Can't resolve 'nuxt-vite-legacy'

The package was not installed or is incorrectly referenced in `nuxt.config.ts`.

fix

Run `npm install nuxt-vite-legacy --save-dev` or `pnpm add nuxt-vite-legacy --save-dev` and ensure it's listed in the `modules` array as a string: `modules: ["nuxt-vite-legacy"]`.

Error: [vite]: A legacy build is required but none was found. This usually means that @vitejs/plugin-legacy is not installed or configured correctly.

The `@vitejs/plugin-legacy` is either missing or not correctly integrated via `nuxt-vite-legacy`'s configuration.

fix

Ensure `nuxt-vite-legacy` is installed and added to `modules` in `nuxt.config.ts`. Verify that your `legacy` configuration block includes valid `targets`.

Unhandled Promise Rejection: SyntaxError: Unexpected token 'async'

This error occurs in legacy browsers that receive the modern bundle, often because they support `<script type="module">` but lack support for modern JS features like async/await, and the legacy bundle isn't being served.

fix

Review the 'Caveats' section in the documentation. Ensure your `legacy.targets` configuration correctly identifies the problematic browsers. If using SSR, confirm the server-side rendering logic correctly identifies and serves the legacy bundle based on browser capabilities (though this module has known limitations here).

Upgrade

Version history

2.0.1latest on npm

Audit

Dependencies

nuxtrequiredRequired peer dependency as this is a Nuxt module.

@vitejs/plugin-legacyrequiredCore functionality is provided by this Vite plugin.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/IlyaSemenov/nuxt-vite-legacy ↗

packagehttps://www.npmjs.com/package/nuxt-vite-legacy ↗