vite

What is vite?

Vite is a modern frontend build tool that provides a faster and leaner development experience for modern web projects. It leverages native ES modules and is designed to serve your code via HTTP in development, enabling hot module replacement (HMR) for a fast development cycle, and bundles it for production using Rollup.

What are vite's main functionalities?

Instant Server Start

With Vite, you can start a development server instantly due to its use of native ES modules. Here's a simple command to start the server:

npx vite

Hot Module Replacement (HMR)

Vite provides out-of-the-box support for HMR, which enables you to update code and see changes in real-time without a full page reload. The code sample shows how to use HMR with a Vue application.

import { createApp } from 'vue';
const app = createApp(App);
if (import.meta.hot) {
  import.meta.hot.accept();
}

Optimized Build

For production, Vite uses Rollup to bundle your code. This results in an optimized build that's ready for deployment. The command to create a production build is straightforward.

npx vite build

Plugin System

Vite supports a rich plugin system that allows you to extend its functionality. This code sample demonstrates how to include the official Vue plugin in your Vite configuration.

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [vue()]
});

TypeScript Support

Vite comes with built-in TypeScript support, allowing you to develop your application using TypeScript without additional setup. The command to start a server with TypeScript support is the same as for JavaScript.

npx vite --host

Other packages similar to vite

webpack

Webpack is a powerful module bundler that can transform and bundle various types of assets. It is highly configurable and has a large ecosystem of loaders and plugins. Compared to Vite, webpack has a steeper learning curve and can be slower in development due to its build process.

parcel

Parcel is a zero-configuration web application bundler. It offers a fast development experience and supports a wide range of file types out of the box. Parcel is similar to Vite in terms of ease of use, but Vite's development server is generally faster due to its use of native ES modules.

rollup

Rollup is a module bundler for JavaScript that compiles small pieces of code into something larger and more complex, such as a library or application. It is the same bundler that Vite uses for production builds. Rollup focuses on bundling for production and is not optimized for development speed like Vite.

snowpack

Snowpack is a build tool that uses JavaScript's native module system (ESM) for unbundled development. It provides a fast development experience by only rebuilding individual files as they change. Snowpack and Vite share similar philosophies, but Vite offers a more integrated experience with features like HMR and pre-configured plugins.

README

vite ⚡

Make Web Dev Fast Again

• Lightning fast cold server start
• Instant hot module replacement (HMR)
• True on-demand compilation
• More details in How and Why

Status

Still experimental, but we intend to make it suitable for production.

Getting Started

$ 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

Browser Support

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.

Features

• Bare Module Resolving
• Hot Module Replacement
• TypeScript
• CSS / JSON Importing
• Asset URL Handling
• PostCSS
• CSS Modules
• CSS Pre-processors
• JSX
• 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.

Bare Module Resolving

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 rewrites 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 since Vite will serve it by default. But if you want to use a specific version of vue (only supports Vue 3.x), you can install vue locally into node_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's module entry if available.

Hot Module Replacement

• *.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 'vite/hmr'
  
  foo()
  
  // this code will be stripped out when building
  if (__DEV__) {
    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 'vite/hmr'
  
  export const count = 1
  
  // this code will be stripped out when building
  if (__DEV__) {
    hot.accept((newModule) => {
      console.log('updated: count is now ', newModule.count)
    })
  }
  

  A self-accepting module, or a module that expects to be accepted by others can use hot.dispose to cleanup any persistent side effects created by its updated copy:

  import { hot } from 'vite/hmr'
  
  function setupSideEffect() {}
  function cleanupSideEffect() {}
  
  setupSideEffect()
  
  if (__DEV__) {
    hot.dispose(cleanupSideEffect)
  }
  

  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 using let). 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.

TypeScript

Starting with v0.11, Vite supports <script lang="ts"> in *.vue files, and importing .ts files out of the box. Note that Vite does NOT perform type checking - it assumes type checking is taken care of by your IDE and build process (you can run tsc --noEmit in the build script). With that in mind, Vite uses esbuild to transpile TypeScript into JavaScript which is about 20~30x faster than vanilla tsc, and HMR updates can reflect in the browser in under 50ms.

Note that because esbuild only performs transpilation without type information, it doesn't support certain features like const enum and implicit type-only imports. You must set "isolatedModules": true in your tsconfig.json under compilerOptions so that TS will warn you against the features that do not work with isolated transpilation.

CSS / JSON Importing

You can directly import .css and .json files from JavaScript (including <script> tags of *.vue files, of course).

• .json files export their content as an object that is the default export.

• .css files do not export anything unless it ends with .module.css (See CSS Modules below). Importing them leads to the side effect of them being injected to the page during dev, and being included in the final style.css of the production build.

Both CSS and JSON imports also support Hot Module Replacement.

Asset URL Handling

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.

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.

The exception is the public directory - assets placed in this directory will be copied to the dist directory as-is. It can be used to provide assets that are never referenced in your code - e.g. robots.txt.

All path references, including absolute paths and those starting with /public, should be based on your working directory structure. If you are deploying your project under a nested public path, simply specify --base=/your/public/path/ and all asset paths will be rewritten accordingly. You never need to think about the public path during development.

PostCSS

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.

CSS Modules

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 to name CSS modules files as *.module.css which allows you to import the naming hash from it.

CSS Pre-Processors

Because Vite targets modern browsers only, it is recommended to use native CSS variables with PostCSS plugins that implement 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.

JSX

.jsx and .tsx files are also supported out of the box. JSX transpilation is also handled via esbuild.

Because React doesn't ship ES module builds, you either need to use es-react, or pre-bundle React into a ES module with Snowpack. Easiest way to get it running is:

import { React, ReactDOM } from 'https://unpkg.com/es-react'

ReactDOM.render(<h1>Hello, what!</h1>, document.getElementById('app'))

JSX can also be customized via --jsx-factory and --jsx-fragment flags from the CLI or jsx: { factory, fragment } fro the API. For example, to use Preact with Vite:

{
  "scripts": {
    "dev": "vite --jsx-factory=h"
  }
}

import { h, render } from 'preact'
render(<h1>Hello, what!</h1>, document.getElementById('app'))

Notes on JSX Support

• Vue 3's JSX transform is still WIP, so Vite's JSX support currently only targets React/Preact.

• There is no out-of-the-box HMR when using non-Vue frameworks, but userland HMR support is technically possible via the server API.

Production Build

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.

Internally, we use a highly opinionated Rollup config to generate the build. The build is configurable by passing on most options to Rollup - and most non-rollup string/boolean options have mapping flags in the CLI (see build/index.ts for full details).

API

Dev Server

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)

Build

Check out the full options interface in build/index.ts.

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
    }
    // ...
  })
})()

How and Why

How is This Different from vue-cli or Other Bundler-based Solutions?

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:

• One of Vite's primary goal was to support Hot Module Replacement, but 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 use Vite 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 to vue-cli for obvious reasons.

How is This Different from Snowpack?

Snowpack 2 is closer to Vite in scope - both offer bundle-free dev servers and can bundle the app for production. Some notable differences are:

• Vite has HMR, while Snowpack simply reloads the page on any file edit. This is a fundamental difference in terms of development experience:

  • Since both solutions rely on native ES imports, the network waterfall of full page reloads can actually become the bottleneck in edit-to-feedback speed. HMR allows you to avoid reloading the page for the majority of your development time. The difference is already obvious in a hello world app, and will be more significant as the app size grows.

  • When working on apps with complex state, HMR precisely reflects the minimum changes made while preserving unaffected application state, saving the time needed to reproduce the state you were in.

• Vite is a bit more opinionated and aims to minimize the amount of configuration required. All the features listed above like TypeScript transpilation, CSS import, and PostCSS support just work out of the box.

• While Vite can technically be used to develop apps with any framework, its main focus is to provide the best Vue development experience possible. 3rd party framework support is currently not a priority in the roadmap. On the other hand, Snowpack aims to be more flexible and support multiple frameworks at the same time.

That said, because Vite supports resolving web_modules, you can use Snowpack to pre-bundle dependencies (which reduces network requests during dev) in your Vite project to speed up full page reloads.

TODOs

• Config file support
  • Define config options
  • Define plugin format

Trivia

vite is the french word for "fast" and is pronounced /vit/.

License

MIT