/vue-cli-plugin-vite

Use vite today, with vue-cli.

Primary LanguageTypeScriptMIT LicenseMIT

Use Vite Today

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

demo/boilerplate

logo

wakatime npm version downloads download monthly
CI Maintenance License: MIT

Table of Contents

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,
    }
  },
}

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
  • ✅ Lint
  • ⬜️ 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

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

Troubleshooting

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

Use vue-cli ecosystem

Relevant Vite Plugins