HTML and Static Assets
HTML
The Index File
The file public/index.html
is a template that will be processed with html-webpack-plugin. During build, asset links will be injected automatically. In addition, Vue CLI also automatically injects resource hints (preload/prefetch
), manifest/icon links (when PWA plugin is used), and the asset links for the JavaScript and CSS files produced during the build.
Interpolation
Since the index file is used as a template, you can use the lodash template syntax to interpolate values in it:
<%= VALUE %>
for unescaped interpolation;<%- VALUE %>
for HTML-escaped interpolation;<% expression %>
for JavaScript control flows.
In addition to the default values exposed by html-webpack-plugin
, all client-side env variables are also available directly. For example, to use the BASE_URL
value:
<link rel="icon" href="<%= BASE_URL %>favicon.ico">
See also:
Preload
<link rel="preload">
is a type of resource hint that is used to specify resources that your pages will need very soon after loading, which you therefore want to start preloading early in the lifecycle of a page load, before the browser's main rendering machinery kicks in.
By default, a Vue CLI app will automatically generate preload hints for all files that are needed for the initial rendering of your app.
The hints are injected using @vue/preload-webpack-plugin and can be modified / deleted via chainWebpack
as config.plugin('preload')
.
Prefetch
<link rel="prefetch">
is a type of resource hint that tells the browser to prefetch content that the user may visit in the near future in the browser's idle time, after the page finishes loading.
By default, a Vue CLI app will automatically generate prefetch hints for all JavaScript files generated for async chunks (as a result of on-demand code splitting via dynamic import()
).
The hints are injected using @vue/preload-webpack-plugin and can be modified / deleted via chainWebpack
as config.plugin('prefetch')
.
Note for multi page setups
When using a multipage setup, the plugin name above should be changed to match the structure 'prefetch-{pagename}', for example 'prefetch-app'.
Example:
// vue.config.js
module.exports = {
chainWebpack: config => {
// remove the prefetch plugin
config.plugins.delete('prefetch')
// or:
// modify its options:
config.plugin('prefetch').tap(options => {
options[0].fileBlacklist = options[0].fileBlacklist || []
options[0].fileBlacklist.push(/myasyncRoute(.)+?\.js$/)
return options
})
}
}
When the prefetch plugin is disabled, you can manually select specific chunks to prefetch using webpack's inline comments:
import(/* webpackPrefetch: true */ './someAsyncComponent.vue')
webpack's runtime will inject prefetch links when the parent chunk is loaded.
TIP
Prefetch links will consume bandwidth. If you have a large app with many async chunks and your users 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
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.
Instead, you should consider using the 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
. The built app will efficiently share common chunks between multiple entries for optimal loading performance.
Static Assets Handling
Static assets can be handled in two different ways:
Imported in JavaScript or referenced in templates/CSS via relative paths. Such references will be handled by webpack.
Placed in the
public
directory and referenced via absolute paths. These assets will simply be copied and not go through webpack.
Relative Path Imports
When you reference a static asset using relative path (must start with .
) inside JavaScript, CSS or *.vue
files, the asset will be included into webpack's dependency graph. During this compilation process, all asset URLs such as <img src="...">
, background: url(...)
and CSS @import
are resolved as module dependencies.
For example, url(./image.png)
will be translated into require('./image.png')
, and
<img src="./image.png">
will be compiled into:
h('img', { attrs: { src: require('./image.png') }})
Internally, we configured webpack Assets Modules to determine the final file location with version hashes and correct public base paths, and conditionally inline assets that are smaller than 8KiB, reducing the amount of HTTP requests.
You can adjust the inline file size limit via chainWebpack. For example, to set the limit of inline images to 4KiB instead:
// vue.config.js
module.exports = {
chainWebpack: config => {
config.module
.rule('images')
.set('parser', {
dataUrlCondition: {
maxSize: 4 * 1024 // 4KiB
}
})
}
}
URL Transform Rules
If the URL is an absolute path (e.g.
/images/foo.png
), it will be preserved as-is.If the URL starts with
.
, it's interpreted as a relative module request and resolved based on the folder structure on your file system.If the URL starts with
~
, anything after it is interpreted as a module request. This means you can even reference assets inside node modules:<img src="~some-npm-package/foo.png">
If the URL starts with
@
, it's also interpreted as a module request. This is useful because Vue CLI by default aliases@
to<projectRoot>/src
. (templates only)
The public
Folder
Any static assets placed in the public
folder will simply be copied and not go through webpack. You need to reference them using absolute paths.
Note we recommend importing assets as part of your module dependency graph so that they will go through webpack with the following benefits:
- Scripts and stylesheets get minified and bundled together to avoid extra network requests.
- Missing files cause compilation errors instead of 404 errors for your users.
- Result filenames include content hashes so you don’t need to worry about browsers caching their old versions.
The public
directory is provided as an escape hatch, and when you reference it via absolute path, you need to take into account where your app will be deployed. If your app is not deployed at the root of a domain, you will need to prefix your URLs with the publicPath:
In
public/index.html
or other HTML files used as templates byhtml-webpack-plugin
, you need to prefix the link with<%= BASE_URL %>
:<link rel="icon" href="<%= BASE_URL %>favicon.ico">
In templates, you will need to first pass the base URL to your component:
data () { return { publicPath: process.env.BASE_URL } }
Then:
<img :src="`${publicPath}my-image.png`">
When to use the public
folder
- You need a file with a specific name in the build output.
- You have thousands of images and need to dynamically reference their paths.
- Some library may be incompatible with Webpack and you have no other option but to include it as a
<script>
tag.