Migrating a Webpack Project to Vite Using the Golden Circle Framework

Introduction

In modern frontend development, the choice of build tool is critical. While Webpack has long been the dominant solution, Vite has emerged as a faster, more modern alternative. This article combines the Golden Circle framework (Why, How, What) with a practical migration from Webpack to Vite.

Why Migrate (Why)

The existing Webpack‑based system suffers from several issues:

Complex functionality with over 7,000 module dependencies.

Extremely slow development builds (≈120 s on macOS, even slower on Windows).

Hot‑module replacement takes about 2 s on macOS.

Large bundle size that cannot be further optimized via configuration.

These problems motivate a move to a tool that can accelerate development and reduce bundle size.

How Vite Improves the Experience (How)

Vite leverages native ES‑module support in browsers, eliminating the need to bundle the entire project during development. This results in dramatically faster startup and HMR, especially for large projects. Vite also offers modern features such as built‑in TypeScript support, Rollup‑based production builds, and a concise configuration format.

Migration Steps (What)

1. Initialize Vite Core Dependencies

npm i [email protected] [email protected] -D

2. Install Vite Plugins for Vue 2 Compatibility

npm i [email protected] [email protected] [email protected] [email protected] [email protected] [email protected]

3. Restructure the Project

Copy the original public/index.html to the project root.

Update template variables in the new index.html .

Add a custom environment variable VITE_APP_TITLE in a .env file.

4. Configure Vite

Create or edit vite.config.js with the following example configuration:

import { defineConfig } from 'vite'
import { createVuePlugin } from 'vite-plugin-vue2'
import envCompatible from 'vite-plugin-env-compatible'
import { viteCommonjs } from 'vite-plugin-commonjs'
import viteRequireContext from 'vite-plugin-require-context'
import dynamicImport from 'vite-plugin-dynamic-import'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

function vitePluginTransDeep() {
  return {
    name: 'vite-plugin-transform-scss',
    enforce: 'pre',
    transform(src, id) {
      if (/\.(js|vue)(\?)*/.test(id) && id.includes('lang.scss') && !id.includes('node_modules')) {
        return { code: src.replace(/(\/deep\/|>>>)/gi, '::v-deep') }
      }
    }
  }
}

export default defineConfig({
  // Common configuration
  plugins: [
    createVuePlugin({ jsx: true }),
    dynamicImport(),
    viteCommonjs(),
    viteRequireContext(),
    envCompatible(),
    nodePolyfills(),
    vitePluginTransDeep()
  ],
  envPrefix: ['VUE_APP_'], // Compatibility with VUE_APP_ prefix

  // Project‑specific configuration
  base: '/dd/',
  server: { host: 'me.jr.jd.com' },
  resolve: { extensions: ['.js', '.vue', '.json'], alias: {} },
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@import './src/variables/index.scss';`
      }
    }
  }
})

5. Handle CSS Modules

If the project uses CSS modules, rename SCSS files to *.module.scss and ensure they are imported correctly. Example snippet:

$menuText: red;
:export {
  menuText: $menuText;
}

6. Transform Deep Selectors

Vite 2 does not support the legacy /deep/ selector. Replace it with ::v-deep using the custom plugin shown above.

7. Configure Global SCSS Variables

css: {
  preprocessorOptions: {
    scss: {
      additionalData: `@import "src/styles/variables.scss";`
    }
  }
}

Migration Results

After applying the migration steps, the build time dropped from roughly 120 seconds to 1.5 seconds—a 98 % improvement. The bundle size was also significantly reduced, and development feedback became much faster.

Conclusion

By applying the Golden Circle framework, the article clarifies the motivation, method, and concrete actions for migrating a Webpack project to Vite. Vite’s rapid development experience, modern feature set, and streamlined configuration make it an attractive choice for frontend engineers seeking performance gains.