Assets directory

The assets directory contains your un-compiled assets such as Stylus or Sass files, images, or fonts.

Images

Inside your vue templates, if you need to link to your assets directory use ~/assets/your_image.png with a slash before assets.

<template>
  <img src="~/assets/your_image.png" />
</template>

Inside your css files, if you need to reference your assets directory, use ~assets/your_image.png(without a slash)

background: url('~assets/banner.svg');

When working with dynamic images you will need to use require

<img :src="require(`~/assets/img/${image}.jpg`)" />

Learn more about webpack Assets

Styles

Nuxt lets you define the CSS files/modules/libraries you want to set globally (included in every page). In the nuxt.config you can easily add your styles using the CSS Property.

nuxt.config.js

export default {
  css: [
    // Load a Node.js module directly (here it's a Sass file)
    'bulma',
    // CSS file in the project
    '~/assets/css/main.css',
    // SCSS file in the project
    '~/assets/css/main.scss'
  ]
}

Sass

In case you want to use sass make sure that you have installed sass and sass-loader packages.

Yarn

yarn add --dev sass sass-loader@10

NPM

npm install --save-dev sass sass-loader@10

Nuxt will automatically guess the file type by its extension and use the appropriate pre-processor loader for webpack. You will still need to install the required loader if you need to use them.

Fonts

You can use local fonts by adding them to your assets folder. Once they have been added you can then access them through your css using the @font-face.

-| assets
----| fonts
------| DMSans-Regular.ttf
------| DMSans-Bold.ttf

assets/main.css

@font-face {
  font-family: 'DM Sans';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url('~assets/fonts/DMSans-Regular.ttf') format('truetype');
}
@font-face {
  font-family: 'DM Sans';
  font-style: normal;
  font-weight: 700;
  font-display: swap;
  src: url('~assets/fonts/DMSans-Bold.ttf') format('truetype');
}

CSS files are not automatically loaded. Add them using the CSS config property.

To add external fonts such as google fonts check out the Meta Tags and SEO chapter

Webpack Assets

By default, Nuxt uses webpack’s vue-loader, file-loader and url-loader to serve your assets. You can also use the static directory for assets that should not run through webpack

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:

-| assets/
----| image.png
-| pages/
----| index.vue

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

The ~/ alias won’t be resolved correctly in your CSS files. You must use ~assets (without a slash) in url CSS references, i.e. background: url("~assets/banner.svg")

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

pages/index.vue

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

It will be compiled into:

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

Because .png is not a JavaScript file, Nuxt 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 files as base64 data URLs if they are smaller than a given threshold. This can reduce the number of HTTP requests for trivial files. If a file is larger than the threshold, it automatically falls back to file-loader.

For these two loaders, the default configuration is:

// https://github.com/nuxt/nuxt.js/blob/dev/packages/webpack/src/config/base.js#L382-L411
{
  test: /\.(png|jpe?g|gif|svg|webp|avif)$/i,
  use: [{
    loader: 'url-loader',
    options: {
      esModule: false,
      limit: 1000, // 1kB
      name: 'img/[name].[contenthash:7].[ext]'
    }
  }]
},
{
  test: /\.(woff2?|eot|ttf|otf)(\?.*)?$/i,
  use: [{
    loader: 'url-loader',
    options: {
       esModule: false,
       limit: 1000, // 1kB
       name: 'fonts/[name].[contenthash:7].[ext]'
    }
  }]
},
{
  test: /\.(webm|mp4|ogv)$/i,
  use: [{
    loader: 'file-loader',
    options: {
      esModule: false,
      name: 'videos/[name].[contenthash:7].[ext]'
    }
  }]
}

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

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

pages/index.vue

<template>
  <img src="~/assets/your_image.png" />
</template>

Will be transformed into:

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

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

Aliases

By default the source directory (srcDir) and the root directory (rootDir) are the same. You can use the alias of ~ for the source directory. Instead of writing relative paths like ../assets/your_image.png you can use ~/assets/your_image.png.

Both will achieve the same results.

components/Avatar.vue

<template>
  <div>
    <img src="../assets/your_image.png" />
    <img src="~/assets/your_image.png" />
  </div>
</template>

We recommend using the ~ as an alias. @ is still supported but will not work in all cases such as with background images in your css.

You can use the alias of ~~ or @@ for the root directory.

Tip: On Spanish keyboard you can access ~ with (Option + ñ) on Mac OS, or (Alt gr + 4) on Windows