IndexXuanUse Vite Today
out-of-the-box for vue-cli projects without any codebase modifications.
Table of Contents
- Usage
- Motivation
- Options
- Underlying principle
- Milestones
- Examples
- Troubleshooting
- Benefits
- 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,
}
},
}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#viteand one file atbin/vite
- injected one devDependency
- 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}_XXXfor 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
- ✅ preprocessorOptions:
- ✅ 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
- ✅ host - resolved from
- ✅ 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
- ✅ outDir - resolved from vue.config.js#
- ✅ Alias - resolved from configureWebpack or chainWebpack
- ✅ also resolved from
vue.config.js#runtimeCompiler
- ✅ also resolved from
- ✅ vite#base - resolved from
- ✅ 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
- 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
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 notmodule.xxx
- use import('xxx') not
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.