No-bundle Dev Server for Vue 3 Single-File Components.
- Super fast cold server start
- Super fast hot module replacement (HMR)
- True on-demand compilation
- More details in How and Why
Still experimental, but we intend to make it suitable for production.
$ npx create-vite-app <project-name>
$ cd <project-name>
$ npm install
$ npm run dev
If using Yarn:
$ yarn create vite-app <project-name>
$ cd <project-name>
$ yarn
$ yarn dev
vite
requires native ES module imports during development. The production build also relies on dynamic imports for code-splitting (which can be polyfilled).
vite
assumes you are targeting modern browsers and therefore does not perform any compatibility-oriented code transforms by default. Technically, you can add autoprefixer
yourself using a PostCSS config file, or add necessary polyfills and post-processing steps to make your code work in legacy browsers - however that is not vite
's concern by design.
- Bare Module Resolving
- Hot Module Replacement
- CSS / JSON Importing
- Asset URL Handling
- PostCSS
- CSS Modules
- CSS Pre-processors
- Production Build
vite
tries to mirror the default configuration in vue-cli as much as possible. If you've used vue-cli
or other webpack-based boilerplates before, you should feel right at home. That said, do expect things to be different here and there.
Native ES imports doesn't support bare module imports like
import { createApp } from 'vue'
The above will throw an error by default. vite
detects such bare module imports in all served .js
files and rewrite them with special paths like /@modules/vue
. Under these special paths, vite
performs module resolution to locate the correct files on disk:
-
vue
has special handling: you don't need to install it sincevite
will serve it by default. But if you want to use a specific version ofvue
(only supports Vue 3.x), you can installvue
locally intonode_modules
and it will be preferred (@vue/compiler-sfc
of the same version will also need to be installed). -
If a
web_modules
directory (generated by Snowpack) is present, we will try to locate it. -
Finally we will try resolving the module from
node_modules
, using the package'smodule
entry if available.
-
*.vue
files come with HMR out of the box. -
For
*.js
files, a simple HMR API is provided:import { foo } from './foo.js' import { hot } from '@hmr' foo() hot.accept('./foo.js', (newFoo) => { // the callback receives the updated './foo.js' module newFoo.foo() }) // Can also accept an array of dep modules: hot.accept(['./foo.js', './bar.js'], ([newFooModule, newBarModule]) => { // the callback receives the updated mdoules in an Array })
Modules can also be self-accepting:
import { hot } from '@hmr' export const count = 1 hot.accept(newModule => { console.log('updated: count is now ', newModule.count) })
Note that
vite
's HMR does not actually swap the originally imported module: if an accepting module re-exports imports from a dep, then it is responsible for updating those re-exports (and these exports must be usinglet
). In addition, importers up the chain from the accepting module will not be notified of the change.This simplified HMR implementation is sufficient for most dev use cases, while allowing us to skip the expensive work of generating proxy modules.
You can directly import .css
and .json
files from JavaScript (including <script>
tags of *.vue
files, of course).
-
.json
files exports its content as an object as the default export. -
.css
files do not export anything. Importing them leads to the side effect of them being injected to the page during dev, or being included in the finalstyle.css
of the production build.
Both CSS and JSON imports also support Hot Module Replacement.
You can reference static assets in your *.vue
templates, styles and plain .css
files either using absolute public paths (based on project root) or relative paths (based on your file system). The latter is similar to the behavior you are used to if you have used vue-cli
or webpack's file-loader
.
There is no conventional public
directory. All referenced assets, including those using absolute paths, will be copied to the dist folder with a hashed file name in the production build. Never-referenced assets will not be copied.
Similar to vue-cli
, image assets smaller than 4kb will be base64 inlined.
vite
automatically applies your PostCSS config to all styles in *.vue
files and imported plain .css
files. Just install necessary plugins and add a postcss.config.js
in your project root.
Note that you do not need to configure PostCSS if you want to use CSS Modules: it works out of the box. Inside *.vue
components you can use <style module>
, and for plain .css
files, you need name CSS modules files as *.module.css
which allows you to import the naming hash from it.
Because vite
targets modern browsers only, it is recommended to use native CSS variables with PostCSS plugins that implements CSSWG drafts (e.g. postcss-nesting) and author plain, future-standards-compliant CSS. That said, if you insist on using a CSS pre-processor, you can install the corresponding pre-processor and just use it:
yarn add -D sass
<style lang="scss">
/* use scss */
</style>
Note importing CSS / preprocessor files from .js
files, and HMR from imported pre-processor files are currently not supported, but can be in the future.
vite
does utilize bundling for production builds, because native ES module imports result in waterfall network requests that are simply too punishing for page load time in production.
You can run vite build
to bundle the app.
-
vite build --root dir
: build files in the target directory instead of current working directory. -
vite build --cdn
: importvue
from a CDN link in the built js. This will make the build faster, but overall the page payload will be larger because therer will be no tree-shaking for Vue APIs.
Internally, we use a highly opinionated Rollup config to generate the build. There's not much you can configure from the command line, but if you use the API, then the build is configurable by passing on most options to Rollup (see below).
You can customize the server using the API. The server can accept plugins which have access to the internal Koa app instance. You can then add custom Koa middlewares to add pre-processor support:
const { createServer } = require('vite')
const myPlugin = ({
root, // project root directory, absolute path
app, // Koa app instance
server, // raw http server instance
watcher // chokidar file watcher instance
}) => {
app.use(async (ctx, next) => {
// You can do pre-processing here - this will be the raw incoming requests
// before vite touches it.
if (ctx.path.endsWith('.scss')) {
// Note vue <style lang="xxx"> are supported by
// default as long as the corresponding pre-processor is installed, so this
// only applies to <link ref="stylesheet" href="*.scss"> or js imports like
// `import '*.scss'`.
console.log('pre processing: ', ctx.url)
ctx.type = 'css'
ctx.body = 'body { border: 1px solid red }'
}
// ...wait for vite to do built-in transforms
await next()
// Post processing before the content is served. Note this includes parts
// compiled from `*.vue` files, where <template> and <script> are served as
// `application/javascript` and <style> are served as `text/css`.
if (ctx.response.is('js')) {
console.log('post processing: ', ctx.url)
console.log(ctx.body) // can be string or Readable stream
}
})
}
createServer({
plugins: [
myPlugin
]
}).listen(3000)
const { build } = require('vite')
;(async () => {
// All options are optional.
// check out `src/node/build.ts` for full options interface.
const result = await build({
rollupInputOptions: {
// https://rollupjs.org/guide/en/#big-list-of-options
},
rollupOutputOptions: {
// https://rollupjs.org/guide/en/#big-list-of-options
},
rollupPluginVueOptions: {
// https://github.com/vuejs/rollup-plugin-vue/tree/next#options
},
root: process.cwd(),
cdn: false,
write: true,
minify: true,
silent: false
})
})()
The primary difference is that for vite
there is no bundling during development. The ES Import syntax in your source code is served directly to the browser, and the browser parses them via native <script module>
support, making HTTP requests for each import. The dev server intercepts the requests and performs code transforms if necessary. For example, an import to a *.vue
file is compiled on the fly right before it's sent back to the browser.
There are a few advantages of this approach:
-
Since there is no bundling work to be done, the server cold start is extremely fast.
-
Code is compiled on demand, so only code actually imported on the current screen is compiled. You don't have to wait until your entire app to be bundled to start developing. This can be a huge difference in apps with dozens of screens.
-
Hot module replacement (HMR) performance is decoupled from the total number of modules. This makes HMR consistently fast no matter how big your app is.
Full page reload could be slightly slower than a bundler-based setup, since native ES imports result in network waterfalls with deep import chains. However since this is local development, the difference should be trivial compared to actual compilation time. (There is no compile cost on page reload since already compiled files are cached in memory.)
Finally, because compilation is still done in Node, it can technically support any code transforms a bundler can, and nothing prevents you from eventually bundling the code for production. In fact, vite
provides a vite build
command to do exactly that so the app doesn't suffer from network waterfall in production.
How is This Different from es-dev-server?
es-dev-server
is a great project and we did take some inspiration from it when refactoring vite
in the early stages. That said, here is why vite
is different from es-dev-server
and why we didn't just implement vite
as a middleware for es-dev-server
:
-
vite
supports Hot Module Replacement, which surgically updates the updated module without reloading the page. This is a fundamental difference in terms of development experience.es-dev-server
internals is a bit too opaque to get this working nicely via a middleware. -
vite
aims to be a single tool that integrates both the dev and the build process. You can usevite
to both serve and bundle the same source code, with zero configuration. -
vite
is more opinionated on how certain types of imports are handled, e.g..css
and static assets. The handling is similar tovue-cli
for obvious reasons.
- Public base path support
- Config file support (custom import maps and plugins)
- Support TypeScript / Flow /(P)React JSX via Sucrase or esbuild
vite is the french word for "fast" and is pronounced /vit/
.
MIT