docs: update readme for 0.17 [ci skip]

README.md

@@ -72,58 +72,58 @@ Note that `vue` has special treatment - if it isn't installed in the project loc
 
 - The `vue`, `react` and `preact` templates of `create-vite-app` all come with HMR out of the box.
 
-- For manual HMR, a dedicated API is provided:
+- 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, using `import.meta.hot.acceptDeps`:
 
   ```js
   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) => {
+  if (import.meta.hot) {
+    import.meta.hot.acceptDeps('./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]) => {
+    import.meta.hot.acceptDeps(['./foo.js', './bar.js'], ([newFooModule, newBarModule]) => {
       // the callback receives the updated mdoules in an Array
     })
   }
   ```
 
-  Modules can also be self-accepting:
-
-  ```js
-  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:
 
   ```js
-  import { hot } from 'vite/hmr'
-
   function setupSideEffect() {}
-  function cleanupSideEffect() {}
 
   setupSideEffect()
 
-  if (__DEV__) {
-    hot.dispose(cleanupSideEffect)
+  if (import.meta.hot) {
+    import.meta.hot.dispose((data) => {
+      // cleanup side effect
+    })
   }
   ```
 
+  For the full API, consult [hmr.d.ts](https://github.com/vitejs/vite/blob/master/hmr.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.
@@ -154,15 +154,25 @@ You can reference static assets in your `*.vue` templates, styles and plain `.cs
 
 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 **static** path references, including absolute paths, should be based on your working directory structure.
+
+#### The `public` Directory
+
+The `public` directory under project root can be used as an escape hatch to provide static assets that either are never referenced in source code (e.g. `robots.txt`), or must retain the exact same file name (without hashing).
+
+Assets placed in `public` will be copied to the root of the dist directory as-is.
 
-All **static** 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.
+Note that you should reference files placed in `public` using root absolute path - for example, `public/icon.png` should always be referenced in source code as `/icon.png`.
+
+#### Public Base Path
+
+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.
 
 For dynamic path references, there are two options:
 
 - You can get the resolved public path of a static asset file by importing it from JavaScript. e.g. `import path from './foo.png'` will give you its resolved public path as a string.
 
-- If you need to concatenate paths on the fly, you can use the globally injected `__BASE__` variable with will be the public base path.
+- If you need to concatenate paths on the fly, you can use the globally injected `process.env.BASE_URL` variable with will be the public base path. Note this variable is statically replaced during build so it must appear exactly as-is (i.e. `process.env['BASE_URL']` won't work).
 
 ### PostCSS
 
@@ -367,17 +377,15 @@ Finally, because compilation is still done in Node, it can technically support a
 
 ### How is This Different from [Snowpack](https://www.snowpack.dev/)?
 
-Both Snowpack v2 and Vite offer native ES module import based dev servers. Vite's dependency pre-optimization is also heavily inspired by Snowpack v1. Some notable differences are:
-
-- Vite was created with HMR as a first-class concern. Vite provides out-of-the-box HMR integration in `create-vite-app` templates for Vue, React and Preact.
+Both Snowpack v2 and Vite offer native ES module import based dev servers. Vite's dependency pre-optimization is also heavily inspired by Snowpack v1. Both projects share similar performance characteristics when it comes to development feedback speed. Some notable differences are:
 
-  Full page reload speed of native ES import based dev servers suffer from the network waterfall when the project gets big, and HMR allows you to avoid reloading the page for a decent part of your development time.
+- Vite was created to tackle native ESM-based HMR. When Vite was first released with working ESM-based HMR, there was no other project actively trying to bring native ESM based HMR to production.
 
-  Snowpack as of now doesn't support HMR but there is work being done in this area.
+  Snowpack v2 initially did not offer HMR support but added it in a later release, making the scope of two projects much closer. Vite and Snowpack has collaborated on a common API spec for ESM HMR, but due to the constraints of different implementation strategies, the two projects still ship slightly different APIs.
 
 - Vite is more opinionated and supports more opt-in features by default - for example, features listed above like TypeScript transpilation, CSS import, CSS modules and PostCSS support all work out of the box without the need for configuration.
 
-- Both solutions can also bundle the app for production, but Vite uses Rollup with custom config while Snowpack delegate it to Parcel. This isn't a significant difference, but worth being aware of if you intend to customize the build.
+- Both solutions can also bundle the app for production, but Vite uses Rollup while Snowpack delegates it to Parcel/webpack. This isn't a significant difference, but worth being aware of if you intend to customize the build.
 
 ## Trivia