resources/lib/vue/README.md

   1 # vue
   2
   3 ## Which dist file to use?
   4
   5 ### From CDN or without a Bundler
   6
   7 - **`vue(.runtime).global(.prod).js`**:
   8   - For direct use via `<script src="...">` in the browser. Exposes the `Vue` global.
   9   - Note that global builds are not [UMD](https://github.com/umdjs/umd) builds.  They are built as [IIFEs](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) and is only meant for direct use via `<script src="...">`.
  10   - In-browser template compilation:
  11     - **`vue.global.js`** is the "full" build that includes both the compiler and the runtime so it supports compiling templates on the fly.
  12     - **`vue.runtime.global.js`** contains only the runtime and requires templates to be pre-compiled during a build step.
  13   - Inlines all Vue core internal packages - i.e. it's a single file with no dependencies on 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.
  14   - Contains hard-coded prod/dev branches, and the prod build is pre-minified. Use the `*.prod.js` files for production.
  15
  16 - **`vue(.runtime).esm-browser(.prod).js`**:
  17   - For usage via native ES modules imports (in browser via `<script type="module">`.
  18   - Shares the same runtime compilation, dependency inlining and hard-coded prod/dev behavior with the global build.
  19
  20 ### With a Bundler
  21
  22 - **`vue(.runtime).esm-bundler.js`**:
  23
  24   - For use with bundlers like `webpack`, `rollup` and `parcel`.
  25   - Leaves prod/dev branches with `process.env.NODE_ENV` guards (must be replaced by bundler)
  26   - Does not ship minified builds (to be done together with the rest of the code after bundling)
  27   - Imports dependencies (e.g. `@vue/runtime-core`, `@vue/runtime-compiler`)
  28     - Imported dependencies are also `esm-bundler` builds and will in turn import their dependencies (e.g. `@vue/runtime-core` imports `@vue/reactivity`)
  29     - This means you **can** install/import these deps individually without ending up with different instances of these dependencies, but you must make sure they all resolve to the same version.
  30   - In-browser template compilation:
  31     - **`vue.runtime.esm-bundler.js` (default)** is runtime only, and requires all templates to be pre-compiled. 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).
  32     - **`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). You will need to configure your bundler to alias `vue` to this file.
  33
  34 #### Bundler Build Feature Flags
  35
  36 [Detailed Reference on vuejs.org](https://vuejs.org/api/compile-time-flags.html)
  37
  38 `esm-bundler` builds of Vue expose global feature flags that can be overwritten at compile time:
  39
  40 - `__VUE_OPTIONS_API__`
  41   - Default: `true`
  42   - Enable / disable Options API support
  43
  44 - `__VUE_PROD_DEVTOOLS__`
  45   - Default: `false`
  46   - Enable / disable devtools support in production
  47
  48 - `__VUE_PROD_HYDRATION_MISMATCH_DETAILS__`
  49   - Default: `false`
  50   - Enable / disable detailed warnings for hydration mismatches in production
  51
  52 The build will work without configuring these flags, however it is **strongly recommended** to properly configure them in order to get proper tree-shaking in the final bundle.
  53
  54 ### For Server-Side Rendering
  55
  56 - **`vue.cjs(.prod).js`**:
  57   - For use in Node.js server-side rendering via `require()`.
  58   - If you bundle your app with webpack with `target: 'node'` and properly externalize `vue`, this is the build that will be loaded.
  59   - The dev/prod files are pre-built, but the appropriate file is automatically required based on `process.env.NODE_ENV`.