Resolving global variable conflicts in Minified JavaScript: A Case Study with Vite and Terser

Recently, I've faced an issue that my JavaScript library, which my clients use on their site, doesn't work because there is a conflict of global variables, as another JavaScript code uses the same global variable as mine.

Of course, this is a common problem, especially when multiple scripts are included on a web page. It’s well-known that JavaScript is very flexible with its global namespace, which means any variable declared without var, let, or const (or declared with var in the global scope) becomes a global variable. If two different scripts declare the same global variable, they will conflict with each other. If some of external JavaScript libraries are using a variable with the same name in the global scope, one script's variable will overwrite the variable from the other script. This can cause unexpected behavior or errors, as one of the libraries might not work as intended with the overwritten variable.

My code doesn't work in this scenario because it loads into the DOM after another library that uses the same naming convention. To resolve this issue, the first step is to rename my variable, verify if it's necessary in the global scope, or consider encapsulating it within namespaces, among other solutions.

The problem is that my library consists of minified JS code, which essentially contains an entire single-page application from Vue.js 3. Therefore, my conflicting global variable is a shorter name of something else, which acquired its naming during the mangling process that occurs during code compilation and minification.

Let’s breakdown what is mangling. In the context of JavaScript minification, the "mangling" process is a specific step that involves renaming variables and function names to shorter ones. It helps to reduce the overall length of code and size of code file. It’s a part of minification. So, for example, variable named userInput might be renamed to a.

Directly and brutally renaming a conflicting variable in a minified JS file is not a good idea, as it will probably cause additional problems and errors in the code. So, I found another solution - it's related to instructing the code compiler not to use certain names during the mangling process. In other words, to set up a directive that prevents certain names from being used as shortened versions of normal variables.

I compile my code with Vite, so my solution is related to adjust build settings in vite.config.js.

By default, Vite uses **Esbuild**web bundler for minifing code. I didn’t find easy options in Esbuild to fix my issue, so I switched from Esbuild to Terser - beautiful javascript mangler and compressor.

First of all, we need to install terser in our project:

npm install terser

My conflicting variable is called ‘dc’. So we need to configure directive in build part to not use this variable in naming shorten variables in classes during compilation.

So let’s modify our vite.config.js.

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

export default defineConfig({
  plugins: [vue()],
  resolve: {
   // some other code
  },
  // Build configuration
  build: {
    minify: 'terser', // here we set up terser instead default esbuild
    terserOptions: { 
     mangle: {
      reserved: ['dc'] // here we set up variable we want to exclude //from naming
     }
    },
    rollupOptions: {
      // some other code
    },
  },
});

Let's break it down:

build: This section of the configuration is specific to the build process of Vite project. The settings within this block are applied when you build your project for production.

minify: 'terser', This line tells Vite to use the terser plugin for minification.

terserOptions: This part allows to specify custom options that will be passed to terser during the minification process

mangle: This is a specific option within terser.

reserved: ['dc'] Under the mangle option, this array reserved lists identifiers that should not be mangled. In this case, it's specifying that terser should not rename any variables or functions named dc during the minification process.

So after changing my vite.config.js, I’ve re-built the script and not found any more ‘dc’ variable there.

My example is related to Vite + Terser. However, it's just an example, so if you are using other tools to build your applications, libraries, and scripts, you may employ a similar strategy to handle such conflicts.

By instructing the compiler not to use specific names during the mangling process, you effectively prevent it from creating name clashes with other variables or libraries. This method is much safer and more reliable than manually renaming variables in the already minified code, which could indeed lead to further errors and issues. Your solution shows an understanding of how to handle potential conflicts in a controlled and systematic way.

Thanks for you attention and happy coding!

P.S. Subscribe for more interesting and useful posts about web development (especially if you are curious in Laravel and Vue.js).