Nuxt/docs/content/3.docs/2.directory-structure/15.nuxt.config.md

icon	title	head.title
IconFile	nuxt.config.js	Nuxt configuration file

Nuxt configuration file

Nuxt can be configured easily with one single file, called nuxt.config, it supports both .js and .ts extension.

export default {
  // My Nuxt config
}

Learn more about all the different config properties

alias

• Type: object
• Version: 2, 3
• Default

{
  "~~": "/project",
  "@@": "/project",
  "~": "/project",
  "@": "/project",
  "assets": "/project/assets",
  "public": "/project"
}

You can improve your DX by defining additional aliases to access custom directories within your JavaScript and CSS.

::alert{type="info"} Note: Within a webpack context (image sources, CSS - but not JavaScript) you must access your alias by prefixing it with ~. ::

::alert{type="info"} Note: If you are using TypeScript and want to use the alias you define within your TypeScript files, you will need to add the aliases to your paths object within tsconfig.json . ::

Example:

import { resolve } from 'pathe'
export default {
  alias: {
    'images': resolve(__dirname, './assets/images'),
    'style': resolve(__dirname, './assets/style'),
    'data': resolve(__dirname, './assets/other/data')
  }
}

buildDir

• Type: string
• Version: 2, 3
• Default

"/project/.nuxt"

Define the directory where your built Nuxt files will be placed.

Many tools assume that .nuxt is a hidden directory (because it starts with a .). If that is a problem, you can use this option to prevent that.

Example:

export default {
  buildDir: 'nuxt-build'
}

buildModules

• Type: array
• Version: 2, 3
• Default

[]

Modules that are only required during development and build time.

Modules are Nuxt extensions which can extend its core functionality and add endless integrations Each module is either a string (which can refer to a package, or be a path to a file), a tuple with the module as first string and the options as a second object, or an inline module function. Nuxt tries to resolve each item in the modules array using node require path (in node_modules) and then will be resolved from project srcDir if ~ alias is used.

::alert{type="info"} Note: Modules are executed sequentially so the order is important. ::

Example:

modules: [
  // Using package name
  '@nuxtjs/axios',
  // Relative to your project srcDir
  '~/modules/awesome.js',
  // Providing options
  ['@nuxtjs/google-analytics', { ua: 'X1234567' }],
  // Inline definition
  function () {}
]

::alert{type="info"} Note: Using buildModules helps to make production startup faster and also significantly decreases the size of node_modules in production deployments. Please refer to each module's documentation to see if it is recommended to use modules or buildModules. ::

dev

• Type: boolean
• Version: 2, 3
• Default

true

Whether Nuxt is running in development mode.

Normally you should not need to set this.

dir

Customize default directory structure used by nuxt.

It is better to stick with defaults unless needed.

layouts

• Type: string
• Version: 2, 3
• Default

"layouts"

The layouts directory, each file of which will be auto-registered as a Nuxt layout.

pages

• Type: string
• Version: 2, 3
• Default

"pages"

The directory which will be processed to auto-generate your application page routes.

public

• Type: string
• Version: 3
• Default

"public"

The directory containing your static files, which will be directly accessible via the Nuxt server and copied across into your dist folder when your app is generated.

extensions

• Type: array
• Version: 2, 3
• Default

[
  ".js",
  ".mjs",
  ".ts",
  ".tsx",
  ".vue"
]

The extensions that should be resolved by the Nuxt resolver.

globalName

• Type: string
• Version: 2, 3
• Default

"nuxt"

Allows customizing the global ID used in the main HTML template as well as the main Vue instance name and other options.

hooks

• Type: any
• Version: 2, 3
• Default

null

Hooks are listeners to Nuxt events that are typically used in modules, but are also available in nuxt.config.

Internally, hooks follow a naming pattern using colons (e.g., build:done). For ease of configuration, you can also structure them as an hierarchical object in nuxt.config (as below).

Example:

import fs from 'fs'
import path from 'path'
export default {
  hooks: {
    build: {
      done(builder) {
        const extraFilePath = path.join(
          builder.nuxt.options.buildDir,
          'extra-file'
        )
        fs.writeFileSync(extraFilePath, 'Something extra')
      }
    }
  }
}

modules

• Type: array
• Version: 2, 3
• Default

[]

Modules are Nuxt extensions which can extend its core functionality and add endless integrations

Each module is either a string (which can refer to a package, or be a path to a file), a tuple with the module as first string and the options as a second object, or an inline module function. Nuxt tries to resolve each item in the modules array using node require path (in node_modules) and then will be resolved from project srcDir if ~ alias is used.

::alert{type="info"} Note: Modules are executed sequentially so the order is important. ::

Example:

modules: [
  // Using package name
  '@nuxtjs/axios',
  // Relative to your project srcDir
  '~/modules/awesome.js',
  // Providing options
  ['@nuxtjs/google-analytics', { ua: 'X1234567' }],
  // Inline definition
  function () {}
]

privateRuntimeConfig

• Type: any
• Version: 2, 3
• Default

{}

Runtime config allows passing dynamic config and environment variables to the Nuxt app context.

It is added to the Nuxt payload so there is no need to rebuild to update your configuration in development or if your application is served by the Nuxt server. (For static sites you will still need to regenerate your site to see changes.) The value of this object is accessible from server only using $config. It will override publicRuntimeConfig on the server-side. It should hold private environment variables (that should not be exposed on the frontend). This could include a reference to your API secret tokens.

Example:

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

publicRuntimeConfig

Runtime config allows passing dynamic config and environment variables to the Nuxt app context.

It is added to the Nuxt payload so there is no need to rebuild to update your configuration in development or if your application is served by the Nuxt server. (For static sites you will still need to regenerate your site to see changes.) The value of this object is accessible from both client and server using $config. It should hold env variables that are public as they will be accessible on the frontend. This could include a reference to your public URL.

Example:

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

app

• Type: object
• Version: 2, 3
• Default

{
  "basePath": "/",
  "assetsPath": "/_nuxt/",
  "cdnURL": null
}

rootDir

• Type: string
• Version: 2, 3
• Default

"/project"

Define the workspace directory of your application.

This property can be overwritten (for example, running nuxt ./my-app/ will set the rootDir to the absolute path of ./my-app/ from the current/working directory. It is normally not needed to configure this option.

serverMiddleware

• Type: array
• Version: 2, 3
• Default

[]

Server middleware are connect/express/h3-shaped functions that handle server-side requests. They run on the server and before the Vue renderer.

By adding entries to serverMiddleware you can register additional routes or modify req/res objects without the need for an external server. You can pass a string, which can be the name of a node dependency or a path to a file. You can also pass an object with path and handler keys. (handler can be a path or a function.)

Example:

serverMiddleware: [
  // Will register redirect-ssl npm package
  'redirect-ssl',
  // Will register file from project server-middleware directory to handle /server-middleware/* requires
  { path: '/server-middleware', handler: '~/server-middleware/index.js' },
  // We can create custom instances too
  { path: '/static2', handler: serveStatic(__dirname + '/static2') }
]

::alert{type="info"} Note: If you don't want middleware to run on all routes you should use the object form with a specific path. ::

Example:

export default function (req, res, next) {
  // req is the Node.js http request object
  console.log(req.url)
  // res is the Node.js http response object
  // next is a function to call to invoke the next middleware
  // Don't forget to call next at the end if your middleware is not an endpoint!
  next()
}

Example:

const bodyParser = require('body-parser')
const app = require('express')()
app.use(bodyParser.json())
app.all('/getJSON', (req, res) => {
  res.json({ data: 'data' })
})
module.exports = app

Example:

export default {
  serverMiddleware: {
    '/a': '~/server-middleware/a.js',
    '/b': '~/server-middleware/b.js',
    '/c': '~/server-middleware/c.js'
  }
}

srcDir

• Type: string
• Version: 2, 3
• Default

"/project"

Define the source directory of your Nuxt application.

If a relative path is specified it will be relative to the rootDir.

Example:

export default {
  srcDir: 'client/'
}

This would work with the following folder structure:

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

ssr

• Type: boolean
• Version: 2, 3
• Default

true

Whether to enable rendering of HTML - either dynamically (in server mode) or at generate time. If set to false and combined with static target, generated pages will simply display a loading screen with no content.

watchers

The watchers property lets you overwrite watchers configuration in your nuxt.config.

chokidar

Options to pass directly to chokidar.

See: chokidar

ignoreInitial

• Type: boolean
• Version: 2, 3
• Default

true

rewatchOnRawEvents

• Type: any
• Version: 2, 3
• Default

{}

An array of event types, which, when received, will cause the watcher to restart.

webpack

watchOptions to pass directly to webpack.

See: webpack@4 watch options.

aggregateTimeout

• Type: number
• Version: 2, 3
• Default

1000