docs: filenameHashing

yyx990803 · yyx990803 · commit 77f7f9ac77ce · 2018-07-30T16:01:15.000-04:00
diff --git a/docs/config/README.md b/docs/config/README.md
@@ -83,6 +83,13 @@ module.exports = {
 
   Specify the output path for the generated `index.html` (relative to `outputDir`). Can also be an absolute path.
 
+### filenameHashing
+
+- Type: `boolean`
+- Default: `true`
+
+  By default, generated static assets contains hashes in their filenames for better caching control. However, this requires the index HTML to be auto-generated by Vue CLI. If you cannot make use of the index HTML generated by Vue CLI, you can disable filename hashing by setting this option to `false`.
+
 ### pages
 
 - Type: `Object`
@@ -365,56 +372,3 @@ See [@vue/cli-plugin-e2e-cypress](https://github.com/vuejs/vue-cli/tree/dev/pack
 ### Nightwatch
 
 See [@vue/cli-plugin-e2e-nightwatch](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-nightwatch) for more details.
-
-## Example Configurations
-
-### Disable Hashed Filenames
-
-While generated static asset filenames contain a hash to [ensure the browser picks up changed files](https://webpack.js.org/guides/caching/#output-filenames) this can be disabled. One common scenario for this is when integrating Vue with a backend that dictates a code structure other than what Vue CLI generates, such as with WordPress or Laravel. To disable the hashed filenames, the following can be added to [`vue.config.js`](#vue-config-js):
-
-``` js
-// vue.config.js
-module.exports = {
-    chainWebpack: (config) => {
-    config.module
-      .rule('images')
-      .use('url-loader')
-      .tap(options => Object.assign({}, options, { name: 'img/[name].[ext]' }));
-  },
-  css: {
-    extract: {
-      filename: '/css/[name].css',
-      chunkFilename: '/css/[name].css',
-    },
-  },
-  configureWebpack: {
-    output: {
-      filename: 'js/[name].js',
-      chunkFilename: 'js/[name].js',
-    },
-  },
-};
-```
-
-::: tip
-When manually overwriting `filename` or `chunkFilename`, `assetsDir` does not need to be included in their path values.
-:::
-
-### Disable Generating index.html
-
-When using Vue CLI with an existing backend, you may need to disable the generation of `index.html` so that they generated assets can be used with another default document. To do so, the following can be added to [`vue.config.js`](#vue-config-js):
-
-``` js
-// vue.config.js
-module.exports = {
-  chainWebpack: config => {
-    config.plugins.delete('html')
-    config.plugins.delete('preload')
-    config.plugins.delete('prefetch')
-  }
-}
-```
-
-::: warning
-[Modern Mode](../guide/browser-compatibility.md#modern-mode) will not work when the `html-webpack-plugin` is disabled.
-:::
diff --git a/docs/guide/html-and-static-assets.md b/docs/guide/html-and-static-assets.md
@@ -70,6 +70,32 @@ webpack's runtime will inject prefetch links when the parent chunk is loaded.
 Prefetch links will consume bandwidth. If you have a large app with many async chunks and your user are primarily mobile and thus bandwidth-aware, you may want to disable prefetch links and manually select chunks to prefetch.
 :::
 
+### Disable Index Generation
+
+When using Vue CLI with an existing backend, you may need to disable the generation of `index.html` so that the generated assets can be used in a server-rendered page. To do so, the following can be added to [`vue.config.js`](#vue-config-js):
+
+``` js
+// vue.config.js
+module.exports = {
+  // disable hashes in filenames
+  filenameHashing: false,
+  // delete HTML related webpack plugins
+  chainWebpack: config => {
+    config.plugins.delete('html')
+    config.plugins.delete('preload')
+    config.plugins.delete('prefetch')
+  }
+}
+```
+
+However, this is not really recommended because:
+
+- Hard-coded file names makes it more difficult to implement efficient cache control.
+- Hard-coded file names also do not play well with code-splitting, which generates additional JavaScript files with varying filenames.
+- Hard-coded file names do not work with [Modern Mode](../guide/browser-compatibility.md#modern-mode).
+
+Instead, you should consider using the [indexPath](../config/#indexpath) option to use the generated HTML as a view template in your server-side framework.
+
 ### Building a Multi-Page App
 
 Not every app has to be an SPA. Vue CLI supports building a multi-paged app using the [`pages` option in `vue.config.js`](../config/#pages). The built app will efficiently share common chunks between multiple entries for optimal loading performance.
