Assets

By default, Nuxt uses vue-loader, file-loader and url-loader webpack loaders for strong assets serving. You can also use the static directory for static assets.

Webpack

vue-loader automatically processes your style and template files with css-loader and the Vue template compiler out of the box.In this compilation process, all asset URLs such as <img src="…">, background: url(…) and CSS @import are resolved as module dependencies.

For example, we have this file tree:

  1. -| assets/
  2. ----| image.png
  3. -| pages/
  4. ----| index.vue

If you use url('~assets/image.png') in your CSS, it will be translated into require('~/assets/image.png').

Warning: Starting from Nuxt 2.0 the ~/ alias won't be resolved correctly in your CSS files.You must use ~assets (without a slash) or the @ alias in url CSS references, i.e. background: url("~assets/banner.svg")

Or if you reference that image in your pages/index.vue:

  1. <template>
  2.   <img src="~/assets/image.png">
  3. </template>

It will be compiled into:

  1. createElement('img', { attrs: { src: require('~/assets/image.png') } })

Because .png is not a JavaScript file, Nuxt.js configures webpack to use file-loader and url-loader to handle them for you.

The benefits of these loaders are:

  • file-loader lets you designate where to copy and place the asset file, and how to name it using version hashes for better caching. In production, you will benefit from long-term caching by default!
  • url-loader allows you to conditionally inline a file as base-64 data URL if they are smaller than a given threshold. This can reduce a number of HTTP requests for trivial files. If the file is larger than the threshold, it automatically falls back to file-loader.

For those two loaders, the default configuration is:

  1. // https://github.com/nuxt/nuxt.js/blob/dev/packages/webpack/src/config/base.js#L297-L316
  2. [
  3.   {
  4.     test: /\.(png|jpe?g|gif|svg|webp)$/,
  5.     loader: 'url-loader',
  6.     query: {
  7.       limit: 1000, // 1kB
  8.       name: 'img/[name].[hash:7].[ext]'
  9.     }
  10.   },
  11.   {
  12.     test: /\.(woff2?|eot|ttf|otf)(\?.*)?$/,
  13.     loader: 'url-loader',
  14.     query: {
  15.       limit: 1000, // 1kB
  16.       name: 'fonts/[name].[hash:7].[ext]'
  17.     }
  18.   }
  19. ]

Which means that every file below 1 KB will be inlined as base-64 data URL.Otherwise, the image/font will be copied in its corresponding folder (under the .nuxt directory)with a name containing a version hash for better caching.

When launching our application with nuxt, our template in pages/index.vue:

  1. <template>
  2.   <img src="~/assets/image.png">
  3. </template>

Will be transformed into:

  1. <img src="/_nuxt/img/image.0c61159.png">

If you want to change the loader configurations, please use build.extend.

Static

If you don't want to use Webpack assets from the assets directory, you can create and use the static directory (in your project root folder).

All included files will be automatically served by Nuxt and are accessible through your project root URL. (static/favicon.ico will be available at localhost:3000/favicon.ico)

This option is helpful for files like robots.txt, sitemap.xml or CNAME (which is important for GitHub Pages deployment).

In your code, you can then reference these files relative to the root (/):

  1. <!-- Static image from static directory -->
  2. <img src="/my-image.png"/>
  4. <!-- webpacked image from assets directory -->
  5. <img src="~/assets/my-image-2.png"/>