From: Evan You <yyx990803@gmail.com>
Date: Mon, 23 Dec 2019 15:28:40 +0000 (-0500)
Subject: chore: further edit formats and include it in vue package readme [ci skip]
X-Git-Tag: v3.0.0-alpha.1~22
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=6614f21bf41dd3fae07deeff7aac04c2d1c30592;p=thirdparty%2Fvuejs%2Fcore.git

chore: further edit formats and include it in vue package readme [ci skip]
---

diff --git a/.github/contributing.md b/.github/contributing.md
index d531b21093..71335b3b47 100644
--- a/.github/contributing.md
+++ b/.github/contributing.md
@@ -73,25 +73,26 @@ yarn build runtime --all
 By default, each package will be built in multiple distribution formats as specified in the `buildOptions.formats` field in its `package.json`. These can be overwritten via the `-f` flag. The following formats are supported:
 
 - **`global`**:
-  - for direct use via `<script>` in the browser. The global variable exposed is specified via the `buildOptions.name` field in a package's `package.json`.
+  - For direct use via `<script>` in the browser. The global variable exposed is specified via the `buildOptions.name` field in a package's `package.json`.
   - Note: global builds are not [UMD](https://github.com/umdjs/umd) builds. Instead they are built as [IIFEs](https://developer.mozilla.org/en-US/docs/Glossary/IIFE).
 
 - **`esm-bundler`**:
-  - for use with bundlers like `webpack`, `rollup` and `parcel`.
-  - imports dependencies (e.g. `@vue/runtime-core`, `@vue/runtime-compiler`)
-    - imported depdencies are also `esm-bundler` builds and will in turn import their dependencies (e.g. `@vue/runtime-core` imports `@vue/reactivity`)
-    - this means you **can** install/import these deps without ending up with different instances of these dependencies
   - Leaves prod/dev branches with `process.env.NODE_ENV` guards (to be replaced by bundler)
   - Does not ship a minified build (to be done together with the rest of the code after bundling)
+  - For use with bundlers like `webpack`, `rollup` and `parcel`.
+  - Imports dependencies (e.g. `@vue/runtime-core`, `@vue/runtime-compiler`)
+    - Imported depdencies are also `esm-bundler` builds and will in turn import their dependencies (e.g. `@vue/runtime-core` imports `@vue/reactivity`)
+    - This means you **can** install/import these deps without ending up with different instances of these dependencies
 
 - **`esm`**:
-  - for usage via native ES modules imports (in browser via `<script type="module">`, or via Node.js native ES modules support in the future)
-  - inlines all dependencies - i.e. it's a single ES module with no imports from other files
-    - this means you **must** import everything from `vue` and `vue` only to ensure you are getting the same instance of code.
-  - hard-coded prod/dev branches, and the prod build is pre-minified (you will have to use different paths/aliases for dev/prod)
+  - For usage via native ES modules imports (in browser via `<script type="module">`, or via Node.js native ES modules support in the future)
+  - Inlines all dependencies - i.e. it's a single ES module with no imports from other files
+    - This means you **must** import everything from this file and this file only to ensure you are getting the same instance of code.
+  - Hard-coded prod/dev branches, and the prod build is pre-minified (you will have to use different paths/aliases for dev/prod)
 
 - **`cjs`**:
-  - for use in Node.js server-side rendering via `require()`.
+  - For use in Node.js server-side rendering via `require()`.
+  - The dev/prod files are pre-built, but are dynamically required based on `process.env.NODE_ENV` in `index.js`, which is the default entry when you do `require('vue')`.
 
 For example, to build `runtime-core` with the global build only:
 
diff --git a/packages/vue/README.md b/packages/vue/README.md
index 9a0fc3e6cf..d82d9362cd 100644
--- a/packages/vue/README.md
+++ b/packages/vue/README.md
@@ -1 +1,27 @@
-# vue
\ No newline at end of file
+# vue
+
+## Which dist file to use?
+
+- **`vue.global(.prod).js`**:
+  - For direct use via `<script src="...">` in the browser. Exposes the `Vue` global.
+  - Note: global builds are not [UMD](https://github.com/umdjs/umd) builds. Instead they are built as [IIFEs](https://developer.mozilla.org/en-US/docs/Glossary/IIFE).
+
+- **`*vue(.runtime).esm-bundler.js`**:
+  - For use with bundlers like `webpack`, `rollup` and `parcel`.
+  - Leaves prod/dev branches with `process.env.NODE_ENV` guards (must be replaced by bundler)
+  - Does not ship minified builds (to be done together with the rest of the code after bundling)
+  - imports dependencies (e.g. `@vue/runtime-core`, `@vue/runtime-compiler`)
+    - imported depdencies are also `esm-bundler` builds and will in turn import their dependencies (e.g. `@vue/runtime-core` imports `@vue/reactivity`)
+    - this means you **can** install/import these deps individually without ending up with different instances of these dependencies.
+  - **`vue.runtime.esm-bundler.js`**: runtime only, does not include runtime template compilation support. **This is the default entry for bundlers (via `module` field in `package.json`)** because when using a bundler templates are typically pre-compiled (e.g. in `*.vue` files).
+  - **`vue.esm-bundler.js`**: includes the runtime compiler. Use this if you are using a bundler but still want runtime template compilation (e.g. in-DOM templates or templates via inline JavaScript strings).
+
+- **`vue.esm(.prod).js`**:
+  - For usage via native ES modules imports (in browser via `<script type="module">`, or via Node.js native ES modules support in the future)
+  - Inlines all dependencies - i.e. it's a single ES module with no imports from other files
+    - this means you **must** import everything from this file nad this file only to ensure you are getting the same instance of code.
+  - Hard-coded prod/dev branches, and the prod build is pre-minified (you will need to use different files for dev/prod)
+
+- **`vue.cjs(.prod).js`**:
+  - For use in Node.js server-side rendering via `require()`.
+  - The dev/prod files are pre-built, but are dynamically required based on `process.env.NODE_ENV` in `index.js`, which is the default entry when you do `require('vue')`.