Use Vite Today

out-of-box for vue-cli projects without any codebase modifications.

Table of Contents

• Usage
• Motivation
• Options
• Underlying principle
  • Compatibility
  • Differences between vue-cli and vite
• Milestones
• Examples
• Troubleshooting
  • Vite Build Support
  • How to completely migrate to vite in the future
  • Some module response 404 not found
  • Custom Style missing fonts
  • JSX support
  • Vue3 support
• Benefits
  • Best development-experience right now
  • Migration to vite smoothly
  • Lint the codebase
  • Use vue-cli ecosystem
• Relevant Vite Plugins

Usage

# 1. first step
vue add vite

# 2. second step
# NOTE you cannot directly use `vite` or `npx vite` since it is origin vite not this plugin.
yarn vite // or npm run vite

the plugin's generator will write some main.html for corresponding main.{js,ts}, since vite need html file for dev-server entry file

Motivation

• We have lots of exists vue-cli(3.x / 4.x) projects.
• In Production: vue-cli based on webpack is still the best practice for bundling webapp(with code spliting, legecy-build for old browsers).
• In Development: instant server start and lightning fast HMR by vite is interesting.
• Why not use them together ?

Options

// vue.config.js
{
  // ...
  pluginOptions: {
    vite: {
      ///**
      // * deprecated since v0.2.2. we can auto-resolve alias from vue.config.js
      // * @ is setted by the plugin, you can set others used in your projects, like @components
      // * Record<string, string>
      // * @default {}
      // */
      // alias: {
      //   '@components': path.resolve(__dirname, './src/components'),
      // },
      /**
       * Plugin[]
       * @default []
       */
      plugins: [], // other vite plugins list, will be merge into this plugin\'s underlying vite.config.ts
      /**
       * you can enable jsx support by setting { jsx: true }
       * @see https://github.com/underfin/vite-plugin-vue2#options
       * @default {}
       */
      vitePluginVue2Options: {},
      /**
       * Vite UserConfig.optimizeDeps options
       * @default {}
       */
      optimizeDeps: {}
    }
  },
}

Underlying principle

Compatibility

• NO EXTRA files, code and dependencies injected
  • injected corresponding main.html
    • SPA: projectRoot/main.html
    • MPA: projectRoot/src/pages/*/main.html(s)
  • injected one devDependency vue-cli-plugin-vite
  • injected one line code in package.json#scripts#vite and one file at bin/vite
• auto-resolved as much options as we can from vue.config.js (publicPath, alias, outputDir...)
• compatible the differences between vue-cli and vite(environment variables, special syntax...)

Differences between vue-cli and vite

Milestones

• ✅ Plugin
  • ✅ we can do nothing but rewrite corresponding vite-plugin, most code and tools can be reused
• ✅ Environment Variables Compatibility
  • ✅ load to process.env.XXX (all env with or without prefix will be loaded)
  • ✅ recognize VUE_APP_ prefix (you can use other instead by config, e.g. REACT_APP_)
  • ✅ define as process.env.${PREFIX}_XXX for client-side
• ✅ Entry Files (we can do nothing)
• ✅ Config File (vue.config.js Options auto-resolved)
  • ✅ vite#base - resolved from process.env.PUBLIC_URL || vue.config.js#publicPath || baseUrl
  • ✅ vite#css - resolved from vue.config.js#css
    • ✅ preprocessorOptions: css.loaderOptions
  • ✅ vite#server- resolved from vue.config.js#devServer
    • ✅ host - resolved from process.env.DEV_HOST || devServer.public
    • ✅ port - resolved from Number(process.env.PORT) || devServer.port
    • ✅ https - resolved from devServer.https
    • ✅ open - resolved from process.platform === 'darwin' || devServer.open
    • ✅ proxy - resolved from devServer.proxy
    • ✅ before
      • use middlewares to improve viteDevServer(connect instance) to express instance
  • ✅ vite#build
    • ✅ outDir - resolved from vue.config.js#outputDir
    • ✅ cssCodeSplit - resolved from css.extract
    • ✅ sourcemap - resolved from process.env.GENERATE_SOURCEMAP === 'true' || productionSourceMap || css.sourceMap
  • ✅ Alias - resolved from configureWebpack or chainWebpack
    • ✅ also resolved from vue.config.js#runtimeCompiler
• ✅ MPA Support
  • ✅ same development experience and build result
• ✅ Special Synatax
  • ❌ require('xxx') or require('xxx').default, most of the case, it can be replaced by dynamicImport ( import('xxx') or import('xxx').then(module => module.default) )
  • ❌ '~some-module' syntax for Import CSS (maybe #2185)
  • ✅ require.context compatibility
  • ✅ module.hot compatibility

Examples

• simple vue-cli SPA project
• simple vue-cli MPA TypeScript project
• complex chrisvfritz/vue-enterprise-boilerplate project

you can clone/fork this repo, under examples/*

Troubleshooting

Vite Build Support

• Currently only support vite dev for development, you should still use yarn build(vue-cli-service build)
• But you can use BUILD=true MODERN=true yarn vite to invoke vite build(no legacy and use esbuild minify, not recommended, please use yarn build instead)

How to completely migrate to vite in the future

• if this plugin help you fix error and use vite successfully, it is not too hard to migrate, compared to directly migrate from vue-cli or others
• safely replace all VUE_APP_ to VITE_ code (e.g. .env.*)
• safely replace all process.env.VUE_APP_ to import.meta.env.VITE_ in client-side code.
• safely copy ./node_modules/vite-plugin-vue-cli/config/index.ts to $projectRoot/vite.config.ts and install corresponding vite-plugin list by it
• add npm scripts dev: vite & build: vite build, remove other vue-cli scripts, like serve
• migrate all require.context to import.meta.glob/globEager
• remove all webpack plugins/vue-cli plugins and migrate all vue.config.js setted chainWebpack/configureWebpack to corresponding vite plugin or options
• deps & devDeps cleanup
• other cleanup and tests

Some module response 404 not found

• if not compiler errors, maybe you import vue file without .vue ext, added it and it is required for vite and recommended for vue-cli (and required in vue-cli 5.x)

Custom Style missing fonts

• e.g. element-plus: https://element-plus.gitee.io/#/en-US/component/custom-theme

/* theme color */
$--color-primary: teal;

/* icon font path, required */
$--font-path: '~element-plus/lib/theme-chalk/fonts'; // changed to 'path/to/node_modules/element-plus/lib/theme-chalk/fonts;' (TOOD: can vite support it ?)

@import "~element-plus/packages/theme-chalk/src/index"; // remove '~', both css-loader and vite support it

JSX support

• see options above, vitePluginVue2Options: { jsx: true }
• you may also see that React is not defined, it is you use jsx without set vitePluginVue2Options: { jsx: true }

Vue3 support

• currently only support Vue2.x, since Vue3.x you can use vite directly

Benefits

Best development-experience right now

• Instant server start and lightning fast HMR

Migration to vite smoothly

• In the future, migration to vite is only the replacement of special syntax between webpack and vite

Lint the codebase

• lint dependencies, which is incorrectly use main/module/exports field in package.json
• lint codebase, which is more esmodule compatible
  • use import('xxx') not require('xxx')
  • use import.meta.xxx not module.xxx

Use vue-cli ecosystem

• first-class unit-test integration (by @vue/cli-plugin-unit-jest)
• first-class e2e integration (by @vue/cli-plugin-cypress)
• first-class eslint/stylelint integration
• first-class xyz support by the official and community plugins.

Relevant Vite Plugins

• [email protected]
• vite-plugin-env-compatible
• vite-plugin-vue-cli
• vite-plugin-mpa