Why Vite Builds Blank on iOS 11 and How to Fix It with esbuild Target Settings

Background

After switching the build tool to Vite, users reported that video content could not be opened and the article page rendered completely blank, especially on iPhone devices running iOS 11. The issue was traced to compatibility problems introduced by the new build process.

Related Technology

Vite is a modern bundler that leverages native ES2015 modules and esbuild for fast compilation. Its plugin system simplifies configuration compared with Webpack.

Root Cause Analysis

Legacy Compatibility Plugin

The @vite/plugin-legacy adds a <script nomodule> fallback for browsers that do not support ES modules. However, the plugin’s targets option was set to ['ie >= 11'], which does not cover iOS 11 devices, so the fallback was never applied.

legacy({
  targets: ['ie >= 11'],
  additionalLegacyPolyfills: ['regenerator-runtime/runtime'],
})

Minify Process

In production the code is minified. Vite’s default build.minify option uses esbuild. Tests showed that only the esbuild minifier reproduced the blank‑page bug, while terser did not, indicating that the problem lies in esbuild’s minification.

esbuild Configuration

When minification is enabled, esbuild assumes a modern JavaScript target and may rewrite code using newer syntax (e.g., converting a === undefined || a === null ? 1 : a to a ?? 1). Without an explicit target, this transformation breaks on iOS 11.

You should probably also set the target option when minification is enabled. By default esbuild takes advantage of modern JavaScript features to make your code smaller.

Solution

Explicitly set esbuild.target (or build.target) to 'es6' in the Vite configuration, or switch the minifier to terser. This prevents esbuild from emitting syntax that iOS 11 cannot execute.

// source code
console.log('before do');
if (import.meta.env.DEV) console.log('do it');
console.log('after do');

// after build with dead‑code elimination
console.log('before do');
console.log('after do');

Additional Notes

When import.meta is used, Vite may replace it with an empty object ( __importMeta = {}) during the build, which can also cause runtime errors. Using terser slows down minification compared with esbuild, but provides a safe fallback for older browsers.

Conclusion

The blank‑page issue on iOS 11 was caused by not specifying an explicit esbuild target, leading to modern syntax being emitted during minification. Setting the target to a lower ECMAScript version or switching to terser resolves the compatibility problem.