From d4160726501779417ef19f05cc621bf1a0302097 Mon Sep 17 00:00:00 2001 From: Evan You Date: Fri, 1 Jan 2021 22:55:58 -0500 Subject: [PATCH] chore: update branch links [ci skip] --- .github/contributing.md | 46 +- .github/maintenance.md | 36 -- README.md | 566 +-------------------- docs/guide/features.md | 2 +- docs/guide/index.md | 2 +- docs/guide/migration.md | 6 +- packages/plugin-react-refresh/package.json | 2 +- packages/plugin-vue/package.json | 2 +- packages/vite/package.json | 2 +- 9 files changed, 64 insertions(+), 600 deletions(-) delete mode 100644 .github/maintenance.md diff --git a/.github/contributing.md b/.github/contributing.md index 0a84d1a1f587b5..6caa68f03288ac 100644 --- a/.github/contributing.md +++ b/.github/contributing.md @@ -1,12 +1,9 @@ # Vite Contributing Guide -Hi! I'm really excited that you are interested in contributing to Vite.js. Before submitting your contribution, please make sure to take a moment and read through the following guidelines: - -- [Pull Request Guidelines](#pull-request-guidelines) - +Hi! We are really excited that you are interested in contributing to Vite. Before submitting your contribution, please make sure to take a moment and read through the following guidelines: ## Pull Request Guidelines -- Checkout a topic branch from a base branch, e.g. `master`, and merge back against that branch. +- Checkout a topic branch from a base branch, e.g. `main`, and merge back against that branch. - If adding a new feature: @@ -26,3 +23,42 @@ Hi! I'm really excited that you are interested in contributing to Vite.js. Befor - Commit messages must follow the [commit message convention](./commit-convention.md) so that changelogs can be automatically generated. Commit messages are automatically validated before commit (by invoking [Git Hooks](https://git-scm.com/docs/githooks) via [yorkie](https://github.com/yyx990803/yorkie)). - No need to worry about code style as long as you have installed the dev dependencies - modified files are automatically formatted with Prettier on commit (by invoking [Git Hooks](https://git-scm.com/docs/githooks) via [yorkie](https://github.com/yyx990803/yorkie)). + +## Maintenance Guidelines + +> The following section is mostly for maintainers who have commit access, but it's helpful to go through if you intend to make non-trivial contributions to the codebase. + +Vite aims to be lightweight, and this includes being aware of the number of npm dependencies and their size. + +We use rollup to pre-bundle most dependencies before publishing! Therefore most dependencies, even used in src code, should be added under `devDependencies` by default. This also creates a number of constraints that we need to be aware of in the codebase: + +### Usage of `require()` + +In some cases we intentionally lazy-require some dependencies to improve startup performance. However, note that we cannot use simple `require('somedep')` calls since these are ignored in ESM files so the dependency won't be included in the bundle, and the actual dependency won't even be there when published since they are in `devDependencies`. + +Instead, use `(await import('somedep')).default`. + +### Think before adding a dependency + +Most deps should be added to `devDependencies` even if they are needed at runtime. Some exceptions are: + +- Type packages. Example: `@types/*`. +- Deps that cannot be properly bundled due to binary files. Example: `esbuild`. +- Deps that ships its own types and its type is used in vite's own public types. Example: `rollup`. + +Avoid deps that has large transitive dependencies that results in bloated size compared to the functionality it provides. For example, `http-proxy` itself plus `@types/http-proxy` is a little over 1MB in size, but `http-proxy-middleware` pulls in a ton of dependencies that makes it 7MB(!) when a minimal custom middleware on top of `http-proxy` only requires a couple lines of code. + +### Ensure type support + +Vite aims to be fully usable as a dependency in a TypeScript project (e.g. it should provide proper typings for VitePress), and also in `vite.config.ts`. This means technically a dependency whose types are exposed needs to be part of `dependencies` instead of `devDependencies`. However, these means we won't be able to bundle it. + +To get around this, we inline some of these dependencies' types in `packages/vite/types`. This way we can still expose the typing but bundle the dependency's source code. + +### Think before adding yet another option + +We already have many config options, and we should avoid fixing an issue by adding yet another one. Before adding an option, try to think about: + +- Whether the problem is really worth addressing +- Whether the problem can be fixed with a smarter default +- Whether the problem has workaround using existing options +- Whether the problem can be addressed with a plugin instead diff --git a/.github/maintenance.md b/.github/maintenance.md deleted file mode 100644 index 2d07916302529b..00000000000000 --- a/.github/maintenance.md +++ /dev/null @@ -1,36 +0,0 @@ -# Vite Maintenance Principles - -Vite aims to be lightweight, and this includes being aware of the number of npm dependencies and their size. - -We use rollup to pre-bundle most dependencies before publishing! Therefore most dependencies, even used in src code, should be added under `devDependencies` by default. This also creates a number of constraints that we need to be aware of in the codebase: - -## Usage of `require()` - -In some cases we intentionally lazy-require some dependencies to improve startup performance. However, note that we cannot use simple `require('somedep')` calls since these are ignored in ESM files so the dependency won't be included in the bundle, and the actual dependency won't even be there when published since they are in `devDependencies`. - -Instead, use `(await import('somedep')).default`. - -## Think before adding a dependency - -Most deps should be added to `devDependencies` even if they are needed at runtime. Some exceptions are: - -- Type packages. Example: `@types/*`. -- Deps that cannot be properly bundled due to binary files. Example: `esbuild`. -- Deps that ships its own types and its type is used in vite's own public types. Example: `rollup`. - -Avoid deps that has large transitive dependencies that results in bloated size compared to the functionality it provides. For example, `http-proxy` itself plus `@types/http-proxy` is a little over 1MB in size, but `http-proxy-middleware` pulls in a ton of dependencies that makes it 7MB(!) when a minimal custom middleware on top of `http-proxy` only requires a couple lines of code. - -## Ensure type support - -Vite aims to be fully usable as a dependency in a TypeScript project (e.g. it should provide proper typings for VitePress), and also in `vite.config.ts`. This means technically a dependency whose types are exposed needs to be part of `dependencies` instead of `devDependencies`. However, these means we won't be able to bundle it. - -To get around this, we inline some of these dependencies' types in `packages/vite/types`. This way we can still expose the typing but bundle the dependency's source code. - -## Think before adding yet another option - -We already have many config options, and we should avoid fixing an issue by adding yet another one. Before adding an option, try to think about: - -- Whether the problem is really worth addressing -- Whether the problem can be fixed with a smarter default -- Whether the problem has workaround using existing options -- Whether the problem can be addressed with a plugin instead diff --git a/README.md b/README.md index 22b9af810442f1..803b8a7a2971c1 100644 --- a/README.md +++ b/README.md @@ -1,568 +1,32 @@ # vite ⚡ - +[![npm][npm-img]][npm-url] +[![node][node-img]][node-url] [![unix CI status][unix-ci-img]][unix-ci-url] [![windows CI status][windows-ci-img]][windows-ci-url] -Vite is an opinionated web dev build tool that serves your code via native ES Module imports during dev and bundles it with [Rollup](https://rollupjs.org/) for production. +> Next Generation Frontend Tooling -- Lightning-fast cold server start -- Instant hot module replacement (HMR) regardless of app size -- True on-demand compilation -- More details in [How and Why](#how-and-why) +- 💡 Instant Server Start +- ⚡️ Lightning Fast HMR +- 🛠️ Rich Features +- 📦 Optimized Build +- 🔩 Universal Plugin Interface +- 🔑 Fully Typed APIs -## Getting Started +Vite (French word for "fast", pronounced `/vit/`) is a new breed of frontend build tool that significantly improves the frontend development experience. It consists of two major parts: -Make sure you have [node.js](https://nodejs.org/en/) installed on your machine before proceeding. +- A dev server that serves your source files over [native ES modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules), with [rich built-in features](./features) and astonishingly fast [Hot Module Replacement (HMR)](./features#hot-module-replacement). -```bash -$ npm init vite-app -$ cd -$ npm install -$ npm run dev -``` +- A [build command](./build) that bundles your code with [Rollup](https://rollupjs.org), pre-configured to output highly optimized static assets for production. -If using Yarn: +In addition, Vite is highly extensible via its [Plugin API](./api-plugin) and [JavaScript API](./api-javascript) with full typing support. -```bash -$ yarn create vite-app -$ cd -$ yarn -$ yarn dev -``` - -### Using master branch - -If you can't wait for a new release to test the latest features, clone the `vite` to your local machine and execute the following commands: - -``` -yarn -cd packages/vite -yarn build -yarn link -``` - -Then go to your vite based project and run `yarn link vite`. Now restart the development server (`yarn dev`) to ride on the bleeding edge! - -## Browser Support - -- Vite requires [native ES module imports](https://caniuse.com/#feat=es6-module) during development. - -- The production build assumes a baseline support for [Native ES modules dynamic imports](https://caniuse.com/es6-module-dynamic-import). By default, all code is minimally transpiled with target `es2020` (only for terser minification compatibility). You can specify the target range via the `esbuild.target` config option, where the lowest target available is `es2015`. - -- Legacy browsers can be supported via plugins that post-process the build output for compatibility. - -## Features - -- [NPM Dependency Resolving](#npm-dependency-resolving) -- [Hot Module Replacement](#hot-module-replacement) -- [TypeScript](#typescript) -- [CSS / JSON Importing](#css--json-importing) -- [Asset URL Handling](#asset-url-handling) -- [PostCSS](#postcss) -- [CSS Modules](#css-modules) -- [CSS Pre-processors](#css-pre-processors) -- [JSX](#jsx) -- [Web Assembly](#web-assembly) -- [Inline Web Workers](#inline-web-workers) -- [Custom Blocks](#custom-blocks) -- [Config File](#config-file) -- [HTTPS/2](#https2) -- [Dev Server Proxy](#dev-server-proxy) -- [Production Build](#production-build) -- [Modes and Environment Variables](#modes-and-environment-variables) -- [Using Vite with Traditional Backend](#using-vite-with-traditional-backend) - -Vite tries to mirror the default configuration in [vue-cli](http://cli.vuejs.org/) 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. - -### NPM Dependency Resolving - -Native ES imports don't support bare module imports like - -```js -import { someMethod } from 'my-dep' -``` - -The above will throw an error by default. Vite detects such bare module imports in all served `.js` files and rewrites them to resolved paths like `/node_modules/my-dep/dist/my-dep.js?v=1.0.0` (These paths are only present during development and your file system paths will never show up in the production build). - -### Hot Module Replacement - -- The `vue`, `react` and `preact` templates of `create-vite-app` all come with HMR out of the box. - -- For manual HMR, an API is provided via `import.meta.hot`. - - For a module to self-accept, use `import.meta.hot.accept`: - - ```js - export const count = 1 - - // the conditional check is required so that HMR related code can be - // dropped in production - if (import.meta.hot) { - import.meta.hot.accept((newModule) => { - console.log('updated: count is now ', newModule.count) - }) - } - ``` - - A module can also accept updates from direct dependencies without reloading itself: - - ```js - import { foo } from './foo.js' - - foo() - - if (import.meta.hot) { - import.meta.hot.accept('./foo.js', (newFoo) => { - // the callback receives the updated './foo.js' module - newFoo.foo() - }) - - // Can also accept an array of dep modules: - import.meta.hot.accept(['./foo.js', './bar.js'], ([newFooModule, newBarModule]) => { - // the callback receives the updated modules in an Array - }) - } - ``` - - A self-accepting module or a module that expects to be accepted by others can use `hot.dispose` to clean-up any persistent side effects created by its updated copy: - - ```js - function setupSideEffect() {} - - setupSideEffect() - - if (import.meta.hot) { - import.meta.hot.dispose((data) => { - // cleanup side effect - }) - } - ``` - - For the full API, consult [importMeta.d.ts](https://github.com/vitejs/vite/blob/master/importMeta.d.ts). - - 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 - -Vite supports importing `.ts` files out of the box. - -Vite only performs transpilation on `.ts` files and 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). - -Vite uses [esbuild](https://github.com/evanw/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 ` - - ``` - - Also make sure the server is configured to serve static assets in the Vite working directory, otherwise assets such as images won't be loaded properly. - -3. For production: after running `vite build`, a `manifest.json` file will be generated alongside other asset files. You can use this file to render links with hashed filenames (note: the syntax here is for explanation only, substitute with your server templating language): - - ```html - - - - ``` - -## 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: - -```js -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