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).

Configuration - 图1

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

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

nuxt.config.js

  1. export default {
  2.   css: [
  3.     // Load a Node.js module directly (here it's a Sass file)
  4.     'bulma',
  5.     // CSS file in the project
  6.     '~/assets/css/main.css',
  7.     // SCSS file in the project
  8.     '~/assets/css/main.scss'
  9.   ]
  10. }

Configuration - 图2

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.

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.

nuxt.config.js

  1. export default {
  2.   css: ['~/assets/css/main', '~/assets/css/animations']
  3. }

Configuration - 图3

If you have two files with the same name, e.g. main.scss and main.css, and don’t specify an extension in the css array entry, e.g. css: ['~/assets/css/main'], then only one file will be loaded depending on the order of styleExtensions. In this case only the css file will be loaded and the scss file will be ignored because css comes first in the default styleExtension array.

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:

pages/index.vue

  1. <template lang="pug">
  2.   h1.red Hello {{ name }}!
  3. </template>
  5. <style lang="scss">
  6.   .red {
  7.     color: red;
  8.   }
  9. </style>

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

Yarn

  1. yarn add --dev pug pug-plain-loader
  2. yarn add --dev sass sass-loader@10

NPM

  1. npm install --save-dev pug pug-plain-loader
  2. 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):

  1. export default {
  2.   head: {
  3.     script: [
  4.       {
  5.         src: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js'
  6.       }
  7.     ],
  8.     link: [
  9.       {
  10.         rel: 'stylesheet',
  11.         href: 'https://fonts.googleapis.com/css?family=Roboto&display=swap'
  12.       }
  13.     ]
  14.   }
  15. }

Local Settings

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

  1. <template>
  2.   <h1>About page with jQuery and Roboto font</h1>
  3. </template>
  5. <script>
  6.   export default {
  7.     head() {
  8.       return {
  9.         script: [
  10.           {
  11.             src: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js'
  12.           }
  13.         ],
  14.         link: [
  15.           {
  16.             rel: 'stylesheet',
  17.             href: 'https://fonts.googleapis.com/css?family=Roboto&display=swap'
  18.           }
  19.         ]
  20.       }
  21.     }
  22.   }
  23. </script>
  25. <style scoped>
  26.   h1 {
  27.     font-family: Roboto, sans-serif;
  28.   }
  29. </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:

nuxt.config.js

  1. export default {
  2.   build: {
  3.     postcss: {
  4.       // Add plugin names as key and arguments as value
  5.       // Install them before as dependencies with npm or yarn
  6.       plugins: {
  7.         // Disable a plugin by passing false as value
  8.         'postcss-url': false,
  9.         'postcss-nested': {},
  10.         'postcss-responsive-type': {},
  11.         'postcss-hexrgba': {}
  12.       },
  13.       preset: {
  14.         // Change the postcss-preset-env settings
  15.         autoprefixer: {
  16.           grid: true
  17.         }
  18.       }
  19.     }
  20.   }
  21. }

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:

  1. export default {
  2.   data () {
  3.     return { name: 'World' }
  4.   },
  5.   render (h) {
  6.     return <h1 class="red">{this.name}</h1>
  7.   }
  8. }

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.

.nuxtignore

  1. # ignore layout foo.vue
  3. layouts/foo.vue
  5. # ignore layout files whose name ends with -ignore.vue
  7. layouts/*-ignore.vue
  9. # ignore page bar.vue
  11. pages/bar.vue
  13. # ignore page inside ignore folder
  15. pages/ignore/*.vue
  17. # ignore store baz.js
  19. store/baz.js
  21. # ignore store files match _.test._
  23. store/ignore/_.test._
  25. # ignore middleware files under foo folder except foo/bar.js
  27. 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.

nuxt.config.js

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

ignoreOptions

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

nuxt.config.js

  1. export default {
  2.   ignoreOptions: {
  3.     ignorecase: false
  4.   }
  5. }

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 }.

nuxt.config.js

  1. export default {
  2.   build: {
  3.     extend(config, { isDev, isClient }) {
  4.       // ..
  5.       config.module.rules.push({
  6.         test: /\.(ttf|eot|svg|woff(2)?)(\?[a-z0-9=&.]+)?$/,
  7.         loader: 'file-loader'
  8.       })
  9.       // Sets webpack's mode to development if `isDev` is true.
  10.       if (isDev) {
  11.         config.mode = 'development'
  12.       }
  13.     }
  14.   }
  15. }

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.

nuxt.config.js

  1. export default {
  2.   build: {
  3.     extend(config, { isClient }) {
  4.       if (isClient) {
  5.         config.optimization.splitChunks.maxSize = 200000
  6.       }
  7.     }
  8.   }
  9. }

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.

nuxt.config.js

  1. import webpack from 'webpack'
  3. export default {
  4.   build: {
  5.     plugins: [
  6.       new webpack.ProvidePlugin({
  7.         // global modules
  8.         $: 'jquery',
  9.         _: 'lodash'
  10.       })
  11.     ]
  12.   }
  13. }

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:

nuxt.config.js

  1. export default {
  2.   build: {
  3.     extend(config, ctx) {
  4.       config.module.rules.push({
  5.         test: /\.(ogg|mp3|wav|mpe?g)$/i,
  6.         loader: 'file-loader',
  7.         options: {
  8.           name: '[path][name].[ext]'
  9.         }
  10.       })
  11.     }
  12.   }
  13. }

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:

nuxt.config.js

  1. export default {
  2.   build: {
  3.     loaders: {
  4.       vue: {
  5.         transformAssetUrls: {
  6.           audio: 'src'
  7.         }
  8.       }
  9.     },
  11.     extend(config, ctx) {
  12.       config.module.rules.push({
  13.         test: /\.(ogg|mp3|wav|mpe?g)$/i,
  14.         loader: 'file-loader',
  15.         options: {
  16.           name: '[path][name].[ext]'
  17.         }
  18.       })
  19.     }
  20.   }
  21. }

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.

nuxt.config.js

  1. export default {
  2.   server: {
  3.     host: '0' // default: localhost
  4.   }
  5. }

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

nuxt.config.js

  1. export default {
  2.   server: {
  3.     port: 8000 // default: 3000
  4.   }
  5. }

Configuration - 图4

If the port is assigned the string value of '0' (not 0, which is falsy) a random port number will be assigned to your Nuxt application.

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.

  1. HOST=0 PORT=8000 npm run dev

or create a script in your package.json

  1. "scripts": {
  2.   "dev:host": "nuxt --hostname '0' --port 8000"
  3. }

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.

nuxt.config.js

  1. import axios from 'axios'
  3. export default async () => {
  4.   const data = await axios.get('https://api.nuxtjs.dev/posts')
  5.   return {
  6.     head: {
  7.       title: data.title
  8.       //... rest of config
  9.     }
  10.   }
  11. }

Configuration - 图5

The axios-module cannot be used in nuxt.config.js. You will need to import axios and configure it again.

Further configuration

Configuration - 图6

The nuxt.config.js has way more customization and configuration options! Check out all its keys in the configuration glossary.