Use Vite Today

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

demo/boilerplate

Table of Contents

• Usage
• Motivation
• Options
• Underlying principle
  • Compatibility
  • Differences between vue-cli and vite
• Milestones
• Examples
• Troubleshooting
• 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

# 3. add optimizeDeps#include (optional and will speedup devServer start time a lot)
# added in vue.config.js#pluginOptions.vite.optimizeDeps.include
# e.g.: ['vue', 'vue-router', 'vuex']
# all scanned deps(logged in terminal) can be added for speedup.

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: {
      /**
       * Plugin[]
       * @default []
       */
      plugins: [], // other vite plugins list, will be merge into this plugin\'s underlying vite.config.ts
      /**
       * Vite UserConfig.optimizeDeps options
       * recommended set `include` for speedup page-loaded time, e.g. include: ['vue', 'vue-router', '@scope/xxx']
       * @default {}
       */
      optimizeDeps: {},
      /**
       * type-checker, recommended disabled for large-scale old project.
       * @default false
       */
      disabledTypeChecker: true,
      /**
       * lint code by eslint
       * @default false
       */
      disabledLint: false,
    }
  },
}

• see all

Underlying principle

Compatibility

• NO EXTRA files, code and dependencies injected
  • 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...)
• auto reuse public/index.html as vite html entry template
• compatible the differences between vue-cli and vite(environment variables, special syntax...)

Differences between vue-cli and vite

| Dimension | vue-cli | vite | |----------------------------------|---------------------|--------------------| | Plugin | 1. based on webpack. 2. have service and generator lifecycles. 3. hooks based on each webpack plugin hooks | 1. based on rollup. 2. no generator lifecycle. 3. universal hooks based on rollup plugin hooks and vite self designed | | Environment Variables | 1. loaded on process.env. 2. prefixed by VUE_APP_. 3. client-side use process.env.VUE_APP_XXX by webpack definePlugin | 1. not loaded on process.env. 2. prefixed by VITE_. 3. client-side use import.meta.env.VITE_XXX by vite inner define plugin | | Entry Files | 1. main.{js,ts}. | 1. *.html | | Config File | 1. vue.config.js | 1. vite.config.ts. 2. support use --config to locate | | MPA Support | 1. native support by options.pages. 2. with history rewrite support | 1. native support by rollupOptions.input | | Special Syntax | 1. require(by webpack) 2. require.context(by webpack) 2. use ~some-module/dist/index.css(by css-loader) 3. module.hot for HMR | 1. import.meta.glob/globEager 2. native support by vite, use module/dist/index.css directly 3. import.meta.hot for HMR | | Local devServer | 1. webpack dev-server 2. express-style middleware and many extension api. | 1. connect 2. connect middleware | | Type Checker | 1. fork-ts-checker-webpack-plugin | 1. No built-in, we can use vite-plugin-checker(based on vetur and vue-tsc) | | Lint | 1. @vue/cli-plugin-eslint | 1. No built-in we can use vite-plugin-eslint, | | Jest | 1. @vue/cli-plugin-jest | 1. will have first-class jest support |

Milestones

• Done ✅ vs WIP ⬜️ vs ❌ Won't support
• ✅ 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
  • ✅ 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
• ✅ Build Support (as of 1.0.0-rc.0, no real html entry file generated, just reuse public/index.html of vue-cli)
  • ✅ Support SPA Build
  • ✅ Support MPA Build
• ✅ 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) )
  • ✅ import '~some-module/theme/index.css' syntax for Import CSS supported by vite#2185)
  • ✅ import '~@some-module/theme/index.css' syntax for Import CSS supported by vite#2185)
  • ✅ ~public & ~/public support
  • ✅ require.context compatibility
  • ✅ module.hot compatibilite
• ✅ Type Checker
  • ✅ vite-plugin-checker & vite-plugin-checker-vls
• ✅ Lint
  • ✅ vite-plugin-eslint
• ⬜️ Eject and Codemod
  • ⬜️ eject vite.config.ts
  • ⬜️ eject vite deps
  • ⬜️ remove vue-cli and webpack deps
  • ⬜️ codemod webpack special syntax to vite-specific( import.meta.{hot, env} )

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

• see #9

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 es-module compatible
  • use import('xxx') not require('xxx')
  • ~~use import.meta.xxx not module.xxx~~

Use vue-cli ecosystem

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

Relevant Vite Plugins

• vite-plugin-vue2@underfin - Vue 2 support for vite.
• @vitejs/plugin-vue - Official Vue 3 plugin.
• @vitejs/plugin-vue-jsx - Official Vue 3 jsx plugin.
• vite-plugin-vue-cli@IndexXuan - Infer vite config from vue.config.js.
• vite-plugin-html-template@IndexXuan - Like html-webpack-plugin for webpack.
• vite-plugin-mpa@IndexXuan - MPA support for vite.
• vite-plugin-checker@fi3ework - Type checker for vite.
• vite-plugin-eslint@gxmari007 - Eslint for vite.
• vite-plugin-env-compatible@IndexXuan - Env compatibility for vite with vue-cli.