Nuxt configuration file

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

nuxt.config.js

alias

This option lets you define aliases that will be available within your JavaScript and CSS.

nuxt.config.js

import { resolve } from 'path'
export default {
  alias: {
    'style': resolve(__dirname, './assets/style')
  }
}

See more on the alias property

build

This option lets you configure various settings for the build step, including loaders, filenames, the webpack config and transpilation.

nuxt.config.js

export default {
  build: {
    /*
     ** You can extend webpack config here
     */
    extend(config, ctx) {}
  }
}

See more on the build property

css

This option lets you define the CSS files, modules, and libraries you want to include globally (on every page).

nuxt.config.js

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

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

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

By omitting the extension, if you have a css file and decide to change to use sass for example, you won’t have to update your nuxt.config as it will use the new extension once the filename remains the same.

See more on the css property

dev

This option lets you define the development or production mode of Nuxt (important when you use Nuxt programmatically)

nuxt.config.js

export default {
  dev: process.env.NODE_ENV !== 'production'
}

See more on the dev property

env

This option lets you define environment variables that are required at build time (rather than runtime) such as NODE_ENV=staging or VERSION=1.2.3. However, for runtime environment variables runtimeConfig is required.

nuxt.config.js

export default {
  env: {
    baseURL: process.env.BASE_URL
  }
}

runtimeConfig

The runtime config has built-in dotenv support for better security and faster development. The runtime config is added to the Nuxt payload so there is no need to rebuild in order to update the runtime configuration when working in development or with server-side rendering or client-side only applications. (For static sites you will still need to regenerate your site to see changes.)

.env support

If you have a .env file in your project root directory, it will be automatically loaded into process.env and accessible within your nuxt.config/serverMiddleware and any other files they import.

You can customize the path by using --dotenv <file> or disable entirely with --dotenv false. For example, you might specify a different .env file in production, staging or development environments.

publicRuntimeConfig

• should hold all env variables that are public as these will be exposed on the frontend. This could include a reference to your public URL for example.
• is available using $config in both server and client.

nuxt.config.js

export default {
  publicRuntimeConfig: {
    baseURL: process.env.BASE_URL || 'https://nuxtjs.org'
  }
}

privateRuntimeConfig

• should hold all env variables that are private and that should not be exposed on the frontend. This could include a reference to your API secret tokens for example.
• is only available on server using same $config (it overrides publicRuntimeConfig)

nuxt.config.js

export default {
  privateRuntimeConfig: {
    apiSecret: process.env.API_SECRET
  }
}

Using your config values:

You can then access these values anywhere by using the context in your pages, store, components and plugins by using this.$config or context.$config.

pages/index.vue

<script>
  asyncData ({ $config: { baseURL } }) {
    const posts = await fetch(`${baseURL}/posts`)
      .then(res => res.json())
  }
</script>

Inside your templates you can access your runtimeConfigs directly using $config.*

pages/index.vue

<template>
  <p>Our Url is: {{ $config.baseURL}}</p>
</template>

Your private config could be exposed if you use $config outside of a server-only context (for example, if you use $config in fetch, asyncData or directly inside your template).

See more on the runtimeConfig

See our blog post on Moving from @nuxtjs/dotenv to runtime config

See more on the env property

generate

This option lets you set up parameter values for every dynamic route in your application that will be transformed into HTML files by Nuxt.

nuxt.config.js

export default {
  generate: {
    dir: 'gh_pages', // gh_pages/ instead of dist/
    subFolders: false // HTML files are generated according to the route path
  }
}

See more on the generate property

head

nuxt.config.js

export default {
    head: {
    title: 'my title',
    meta: [
      { charset: 'utf-8' },
            .....
        ]
    }
}

This option lets you define all default meta tags for your application.

See more on head integration

loading

This option lets you customize the loading component that Nuxt uses by default.

nuxt.config.js

export default {
  loading: {
    color: '#fff'
  }
}

See more on loading integration

modules

With this option you can add Nuxt modules to your project.

nuxt.config.js

export default {
  modules: ['@nuxtjs/axios']
}

See more on the modules property

modulesDir

The modulesDir property is used to set the modules directories for path resolving. For example: Webpack’s resolveLoading, nodeExternals and postcss. The configuration path is relative to options.rootDir (default: process.cwd()).

nuxt.config.js

export default {
  modulesDir: ['../../node_modules']
}

Setting this field may be necessary if your project is organized as a Yarn workspace-styled mono-repository.

See more on the modulesDir property

plugins

This option lets you define JavaScript plugins that should be run before instantiating the root Vue.js application.

nuxt.config.js

export default {
  plugins: ['~/plugins/url-helpers.js']
}

See more on the plugins property

router

With the router option you can overwrite the default Nuxt configuration of Vue Router.

nuxt.config.js

export default {
  router: {
    linkExactActiveClass: 'text-primary'
  }
}

See more on the router property

server

This option lets you configure the connection variables for the server instance of your Nuxt application.

nuxt.config.js

import path from 'path'
import fs from 'fs'
export default {
  server: {
    https: {
      key: fs.readFileSync(path.resolve(__dirname, 'server.key')),
      cert: fs.readFileSync(path.resolve(__dirname, 'server.crt'))
    }
  }
}

See more on the server property

srcDir

This option lets you define the source directory of your Nuxt application.

nuxt.config.js

export default {
  srcDir: 'client/'
}

Project structure example with your Nuxt application in the client directory.

**-| app/
---| node_modules/
---| nuxt.config.js
---| package.json
---| client/
------| assets/
------| components/
------| layouts/
------| middleware/
------| pages/
------| plugins/
------| static/
------| store/**

dir

This option lets you define custom names of your Nuxt directories.

nuxt.config.js

export default {
  dir: {
    pages: 'views' // Nuxt will look for the views/ instead of the pages/ folder
  }
}

See more on the dir property

pageTransition

This option lets you define the default properties of the page transitions.

nuxt.config.js

export default {
  pageTransition: 'page'
}

See more on the transition property

Other configuration files

Besides the nuxt.config.js there might be other config files in your project root, such as .eslintrc, prettier.config.json or .gitignore. These are used to configure other tools such as your linter, code formatter or your git repository and detached from the nuxt.config.js.

.gitignore

In your .gitignore file you will need to add the following so that they are ignored and not added to version control. node_modules which is where all your installed modules are. The nuxt folder which is what gets created when running the dev or build commands. The dist folder is the folder that gets created when running the generate command.

.gitignore

node_modules .nuxt dist

What’s next

Check out the configuration-glossary