Configuration

By default, Nuxt is configured to cover most use cases. This default configuration can be overwritten with the nuxt.config.js file.

The css Property

Nuxt lets you define the CSS files/modules/libraries you want to set globally (included in every page).

In nuxt.config.js, add the CSS resources:

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'
  ]
}

Style Extensions

You can omit the file extension for CSS/SCSS/Postcss/Less/Stylus/... files listed in the css array in your nuxt config file.

export default {
  css: ['~/assets/css/main', '~/assets/css/animations']
}

Default order: ['css', 'pcss', 'postcss', 'styl', 'stylus', 'scss', 'sass', 'less']

Pre-processors

Thanks to Vue Loader , you can use any kind of pre-processor for your  <template> or <style>: use the lang attribute.

Example of our pages/index.vue using Pug and Sass :

<template lang="pug">
  h1.red Hello {{ name }}!
</template>

<style lang="scss">
  .red {
    color: red;
  }
</style>

To use these pre-processors, we need to install their webpack loaders:

yarn add --dev pug pug-plain-loader
yarn add --dev sass sass-loader@10

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

External Resources

Global Settings

You can include your external resources in the head object or function. As described in the head API docs , the following examples shows the use of head as an object and as a function. If you want to use values from your Vue component like computed properties or data, you can use the head() function, returning the final head object. You can also pass each resource an optional body: true to include the resource before the closing </body> tag.

Include your resources in nuxt.config.js (here in the head object):

export default {
  head: {
    script: [
      {
        src: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js'
      }
    ],
    link: [
      {
        rel: 'stylesheet',
        href: 'https://fonts.googleapis.com/css?family=Roboto&display=swap'
      }
    ]
  }
}

Local Settings

Include your resources in your .vue file inside the pages/ directory (here in the head function):

<template>
  <h1>About page with jQuery and Roboto font</h1>
</template>

<script>
  export default {
    head() {
      return {
        script: [
          {
            src: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js'
          }
        ],
        link: [
          {
            rel: 'stylesheet',
            href: 'https://fonts.googleapis.com/css?family=Roboto&display=swap'
          }
        ]
      }
    }
  }
</script>

<style scoped>
  h1 {
    font-family: Roboto, sans-serif;
  }
</style>

PostCSS plugins

If present, rename or delete the postcss.config.js in your project directory. Then, in your nuxt.config.js file add the following:

export default {
  build: {
    postcss: {
      // Add plugin names as key and arguments as value
      // Install them before as dependencies with npm or yarn
      plugins: {
        // Disable a plugin by passing false as value
        'postcss-url': false,
        'postcss-nested': {},
        'postcss-responsive-type': {},
        'postcss-hexrgba': {}
      },
      preset: {
        // Change the postcss-preset-env settings
        autoprefixer: {
          grid: true
        }
      }
    }
  }
}

JSX

Nuxt uses @nuxt/babel-preset-app , which is based on the official @vue/babel-preset-app  for babel default configuration, so you can use JSX in your components.

You can also use JSX in the render method of your components:

export default {
  data () {
    return { name: 'World' }
  },
  render (h) {
    return <h1 class="red">{this.name}</h1>
  }
}

Aliasing createElement to h is a common convention you’ll see in the Vue ecosystem but is actually optional for JSX since it automatically injects  const h = this.$createElement in any method and getter (not functions or arrow functions) declared in ES2015 syntax that has JSX so you can drop the (h) parameter.

You can learn more about how to use it in the JSX section  of the Vue.js documentation.

Ignoring files

.nuxtignore

You can use a .nuxtignore file to let Nuxt ignore  layout, page, store and middleware  files in your project’s root directory (rootDir) during the build phase. The .nuxtignore file is subject to the same specification as  .gitignore  and  .eslintignore files, in which each line is a glob pattern indicating which files should be ignored.

# ignore layout foo.vue

layouts/foo.vue

# ignore layout files whose name ends with -ignore.vue

layouts/*-ignore.vue

# ignore page bar.vue

pages/bar.vue

# ignore page inside ignore folder

pages/ignore/*.vue

# ignore store baz.js

store/baz.js

# ignore store files match _.test._

store/ignore/_.test._

# ignore middleware files under foo folder except foo/bar.js

middleware/foo/*.js !middleware/foo/bar.js

The ignorePrefix Property

Any file in pages/, layout/, middleware/ or store/ will be ignored during the build if its filename starts with the prefix specified by ignorePrefix.

By default all files which start with - will be ignored, such as store/-foo.js and pages/-bar.vue. This allows for co-locating tests, utilities, and components with their callers without themselves being converted into routes, stores, etc.

The ignore Property

More customizable than ignorePrefix: all files matching glob patterns specified inside ignore will be ignored in building.

export default {
  ignore: 'pages/bar.vue'
}

ignoreOptions

nuxtignore is using node-ignore under the hood, ignoreOptions can be configured as options of node-ignore.

export default {
  ignoreOptions: {
    ignorecase: false
  }
}

Extend webpack config

You can extend nuxt's webpack configuration via the extend option in your nuxt.config.js. The extend option of the build property is a method that accepts two arguments. The first argument is the webpack config object exported from nuxt's webpack config. The second parameter is a context object with the following boolean properties: { isDev, isClient, isServer, loaders }.

export default {
  build: {
    extend(config, { isDev, isClient }) {
      // ..
      config.module.rules.push({
        test: /\.(ttf|eot|svg|woff(2)?)(\?[a-z0-9=&.]+)?$/,
        loader: 'file-loader'
      })
      // Sets webpack's mode to development if `isDev` is true.
      if (isDev) {
        config.mode = 'development'
      }
    }
  }
}

The extend method gets called twice - Once for the client bundle and the other for the server bundle.

Customize chunks configuration

You may want to tweak the optimization configuration a bit, avoiding a rewrite of the default object.

export default {
  build: {
    extend(config, { isClient }) {
      if (isClient) {
        config.optimization.splitChunks.maxSize = 200000
      }
    }
  }
}

Inspect webpack configuration

For complex projects and debugging it's sometimes useful to check what the final webpack configuration will look like. Luckily you can run nuxt webpack command from withing your project to output the configuration. Checkout this PR #7029 for more details.

Add webpack plugins

In your nuxt.config.js file, under the build option, you can pass webpack plugins, the same way you would do it in a webpack.config.js file .

In this example we add the webpack built-in ProvidePlugin for automatically loading JavaScript modules (lodash and jQuery) instead of having to import or require them everywhere.

import webpack from 'webpack'

export default {
  build: {
    plugins: [
      new webpack.ProvidePlugin({
        // global modules
        $: 'jquery',
        _: 'lodash'
      })
    ]
  }
}

Note: You might not need jQuery in a Vue-based app.

With Nuxt, you can also control plugins execution context: if they are meant to be run on the client or in the server builds (or differentiating dev and prod builds) within build.extend , where you can manually pass webpack plugins too.

Extend Webpack to load audio files

Audio files should be processed by file-loader. This loader is already included in the default Webpack configuration, but it is not set up to handle audio files. You need to extend its default configuration in nuxt.config.js:

export default {
  build: {
    extend(config, ctx) {
      config.module.rules.push({
        test: /\.(ogg|mp3|wav|mpe?g)$/i,
        loader: 'file-loader',
        options: {
          name: '[path][name].[ext]'
        }
      })
    }
  }
}

You can now import audio files like this <audio :src="require('@/assets/water.mp3')" controls></audio>.

If you only want to write: <audio src="@/assets/water.mp3" controls></audio>, you need to tell vue-loader to automatically require your audio files when you reference them with the src attribute:

export default {
  build: {
    loaders: {
      vue: {
        transformAssetUrls: {
          audio: 'src'
        }
      }
    },

    extend(config, ctx) {
      config.module.rules.push({
        test: /\.(ogg|mp3|wav|mpe?g)$/i,
        loader: 'file-loader',
        options: {
          name: '[path][name].[ext]'
        }
      })
    }
  }
}

Edit host and port

By default, the Nuxt development server host is localhost  which is only accessible from within the host machine. In order to view your app on another device you need to modify the host. You can modify the host in your nuxt.config.js file.

Host '0.0.0.0'  is designated to tell Nuxt to resolve a host address, which is accessible to connections outside of the host machine (e.g. LAN). If the host is assigned the string value of '0' (not 0, which is falsy), or '0.0.0.0' your local IP address will be assigned to your Nuxt application.

export default {
  server: {
    host: '0' // default: localhost
  }
}

You can also change the port number from the default port of 3000.

export default {
  server: {
    port: 8000 // default: 3000
  }
}

Although you can modify this in the nuxt.config.js file it is not advised to as it might cause you issues when hosting your site. It is much better to modify the host and port direct in the dev command.

HOST=0 PORT=8000 npm run dev

or create a script in your package.json

"scripts": {
  "dev:host": "nuxt --hostname '0' --port 8000"
}

Asynchronous Configuration

Although it is better to use the normal configuration export default {} you can have an async configuration by exporting an async function that return the config object.

import axios from 'axios'

export default async () => {
  const data = await axios.get('https://api.nuxtjs.dev/posts')
  return {
    head: {
      title: data.title
      //... rest of config
    }
  }
}

Further configuration