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.

import { resolve } from 'path'

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

build

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

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

css

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

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.

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.

dev

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

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

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.

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.

export default {
  publicRuntimeConfig: {
    baseURL: process.env.BASE_URL || 'https://v2.nuxt.com'
  }
}

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)

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.

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

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

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.

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

head

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

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

loading

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

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

modules

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

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

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

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

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

plugins

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

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

router

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

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

server

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

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

srcDir

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

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.

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

pageTransition

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

export default {
  pageTransition: 'page'
}

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.

node_modules .nuxt dist

What's next