SoFunction
Updated on 2025-04-13

Solutions to the browser compatibility issue after Vite project packaging

1. Problem description

After the vite+vue3 project is developed, you will find that the packaged project can be displayed normally in the new version of the browser, but when running on some older browsers such as Chrome < 23, Firefox < 21, and IE, it will be blank and there will be no error prompts.

2. Problem analysis

At this time, your brain may be blank like the page, but don't panic. Let's first analyze the possible reasons for this problem: those browsers with lower versions do not support ES6 syntax and new APIs, while Babel only converts new JavaScript syntax by default, and does not convert new APIs, such as global objects such as Proxy, Symbol, Promise, and some methods defined on global objects will not be transcoded.

3. Solution

Plan A: Configure browser compatibility in.

Our project is built with vite, so I first thought of using vite's own API to configure browser compatibility.
Configuration and

  build: {
      target: ['chrome52'],
      cssTarget: ["chrome52"],
      }

After packaging and running it to the browser, I found that it was still blank. I checked the packaged files and found that there are still new syntax and APIs such as const and Promise, which did not convert for us. Plan A ,No.

Plan B: First configure the TypeScript conversion syntax, and then make vite compatible with the target.

Configure the target to "es5" in the file and start packaging.
error: Transforming const to the configured target environment ("es5") is not supported yet
The error message basically tells us: there is a syntax in the code that the target environment such as const does not support, and it does not currently support converting const to the target environment "es5". Well, that's a bit interesting. Plan B, NO.

Plan C: Introducing babel-polyfill environmental gaskets

After the above scheme of converting syntax failed, I tried to ask the browser environment for a foreign aid: babel-polyfill, and let it do things that low-version browser environments cannot do.
What is polyfill? The official explanation is: "Code used to implement the browser that does not support native functions". We can simply understand that polyfill can simulate APIs that are not supported in the current running environment. It provides a shim for our current environment, and we can use the new API on this shim.

First, we install babel-polyfill:

npm install --save babel-polyfill

Then introduce it in:

import ‘babel-polyfill'

Then we repackage, start and run it to the browser. Some partners may succeed at this point, but mine is still blank!
Are you panicked? You said you were panicked, panicked! I also feel panicked, why? So many people online have succeeded in using this method, but we have failed. How can we not panic? Plan C, No!

Plan D: Use @vitejs/plugin-legacy plugin

After the above three solutions failed, I returned to the vite area. In the vite official documentation, I found the plug-in library with vite, and found a plug-in about browser compatibility support in the plug-in library: @vitejs/plugin-legacy
First install the plugin:npm i @vitejs/plugin-legacy -D

Then configure it in

import legacyPlugin from '@vitejs/plugin-legacy'
export default defineConfig( {
    plugins: [
        legacyPlugin({
            targets:['chrome 52'],  // Requires a compatible target list, multiple targets can be set            additionalLegacyPolyfills:['regenerator-runtime/runtime'] // This plugin is required when targeting IE11        })
    ]
})

Package and run to the browser.

The new version of the browser is running normally! The old version of the browser works fine! Plan D, yes!

Here is a brief introduction to @vitejs/plugin-legacy plugin:
Plugin default behavior:
1. Use @babel/preset-env conversion to generate the corresponding legacy block for each block in the package.
2. Generate a polyfill block containing the SystemJS runtime.
3. Use

Changes after packaging:

  • After enabling the plug-in, there are some additional files with the word legacy in the directory that is packaged. Each js script file has a corresponding legacy version.
  • Some new scripts have been added to the html file. These scripts dynamically introduce normal version files or legacy version files with the word legacy according to the browser's support level.
  • At this time, when the project is running in some browsers with lower versions, the scripts added by the plugin will automatically load the legacy version of the file.

4. Other problems encountered in the process

After Plan D successfully ran in a lower version of the browser, I found that some CSS styles were displayed abnormally, and then I confirmed that the CSS variable that rewrites Vant did not take effect.
At first I thought that CSS did not have compatibility when packaging, so I tried to solve the compatibility support of CSS. The css interpreter, postcss plugin and vite configure the css target environment are useless.

I didn't have any ideas later. Later I remembered that there was a plug-in for style loading on demand in the configuration:

At this time, I wondered if this plugin affected the normal effect of my CSS. When I removed it and repackaged it, the style returned to normal. It seems that it was indeed affected by it.
After using this on-demand plug-in, when the page is loaded, it will determine which style files need to be loaded and which do not need to be loaded according to some of its rules. When loading these style files, if there is a duplicate name for our custom global style in the style file, then according to the css rules, the customized global styles will be overwritten.
In this case, we rewritten some variables of the Vant component and introduced them globally. When opening a page containing these variables, the plug-in loading on demand will only load the Vant style file at this time. The variables we rewritten globally are rewritten again, so the rewritten global variables do not take effect.

This is the end of this article about the solution to the browser compatibility problem after Vite project packaging. For more related content on Vite packaging browser compatibility, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!