The build property

The build property

Nuxt lets you customize the webpack configuration for building your web application as you want.

analyze

Nuxt use webpack-bundle-analyzer to let you visualize your bundles and how to optimize them.

Type: Boolean or Object
Default: false

If an object, see available properties here.

nuxt.config.js

export default {
  build: {
    analyze: true,
    // or
    analyze: {
      analyzerMode: 'static'
    }
  }
}

Info: you can use the command yarn nuxt build --analyze or yarn nuxt build -a to build your application and launch the bundle analyzer on http://localhost:8888. If you are not using yarn you can run the command with npx.

corejs

As of Nuxt@2.14 Nuxt automatically detects the current version of core-js in your project, also you can specify which version you want to use.

Type: number | string (Valid values are 'auto', 2 and 3)
Default: 'auto'

babel

Customize Babel configuration for JavaScript and Vue files. .babelrc is ignored by default.

Type: Object
See babel-loader options and babel options

Default:

{
  babelrc: false,
  cacheDirectory: undefined,
  presets: ['@nuxt/babel-preset-app']
}

The default targets of @nuxt/babel-preset-app are ie: '9' in the client build, and node: 'current' in the server build.

presets

Type: Function
Argument:
1. Object: { isServer: true | false }
2. Array:
  - preset name @nuxt/babel-preset-app
  - options of @nuxt/babel-preset-app

Note: The presets configured in build.babel.presets will be applied to both, the client and the server build. The target will be set by Nuxt accordingly (client/server). If you want configure the preset differently for the client or the server build, please use presets as a function:

We highly recommend to use the default preset instead of below customization

export default {
  build: {
    babel: {
      presets({ isServer }, [ preset, options ]) {
        // change options directly
        options.targets = isServer ? ... :  ...
        options.corejs = ...
        // return nothing
      }
    }
  }
}

Or override default value by returning whole presets list:

export default {
  build: {
    babel: {
      presets({ isServer }, [preset, options]) {
        return [
          [
            preset,
            {
              targets: isServer ? ... :  ...,
              ...options
            }
          ],
          [
            // Other presets
          ]
        ]
      }
    }
  }
}

cache

Type: Boolean
Default: false
⚠️ Experimental

Enable cache of terser-webpack-plugin and cache-loader

cssSourceMap

Type: boolean
Default: true for dev and false for production.

Enables CSS Source Map support

devMiddleware

Type: Object

See webpack-dev-middleware for available options.

devtools

Type: boolean
Default: false

Configure whether to allow vue-devtools inspection.

If you already activated through nuxt.config.js or otherwise, devtools enable regardless of the flag.

extend

Extend the webpack configuration manually for the client & server bundles.

Type: Function

The extend is called twice, one time for the server bundle, and one time for the client bundle. The arguments of the method are:

The Webpack config object,
An object with the following keys (all boolean except loaders): isDev, isClient, isServer, loaders.

Warning: The isClient and isServer keys provided in are separate from the keys available in context. They are not deprecated. Do not use process.client and process.server here as they are undefined at this point.

nuxt.config.js

export default {
  build: {
    extend(config, { isClient }) {
      // Extend only webpack config for client-bundle
      if (isClient) {
        config.devtool = 'source-map'
      }
    }
  }
}

If you want to see more about our default webpack configuration, take a look at our webpack directory.

loaders in extend

loaders has the same object structure as build.loaders, so you can change the options of loaders inside extend.

nuxt.config.js

export default {
  build: {
    extend(config, { isClient, loaders: { vue } }) {
      // Extend only webpack config for client-bundle
      if (isClient) {
        vue.transformAssetUrls.video = ['src', 'poster']
      }
    }
  }
}

extractCSS

Enables Common CSS Extraction using Vue Server Renderer guidelines.

Type: Boolean or Object
Default: false

Using extract-css-chunks-webpack-plugin under the hood, all your CSS will be extracted into separate files, usually one per component. This allows caching your CSS and JavaScript separately and is worth a try in case you have a lot of global or shared CSS.

Example (nuxt.config.js):

export default {
  build: {
    extractCSS: true,
    // or
    extractCSS: {
      ignoreOrder: true
    }
  }
}

Note: There was a bug prior to Vue 2.5.18 that removed critical CSS imports when using this options.

You may want to extract all your CSS to a single file. There is a workaround for this:

It is not recommended to extract everything into a single file. Extracting into multiple CSS files is better for caching and preload isolation. It can also improve page performance by downloading and resolving only those resources that are needed.

export default {
  build: {
    extractCSS: true,
    optimization: {
      splitChunks: {
        cacheGroups: {
          styles: {
            name: 'styles',
            test: /\.(css|vue)$/,
            chunks: 'all',
            enforce: true
          }
        }
      }
    }
  }
}

filenames

Customize bundle filenames.

Type: Object

Default:

{
  app: ({ isDev, isModern }) => isDev ? `[name]${isModern ? '.modern' : ''}.js` : `[contenthash:7]${isModern ? '.modern' : ''}.js`,
  chunk: ({ isDev, isModern }) => isDev ? `[name]${isModern ? '.modern' : ''}.js` : `[contenthash:7]${isModern ? '.modern' : ''}.js`,
  css: ({ isDev }) => isDev ? '[name].css' : 'css/[contenthash:7].css',
  img: ({ isDev }) => isDev ? '[path][name].[ext]' : 'img/[name].[contenthash:7].[ext]',
  font: ({ isDev }) => isDev ? '[path][name].[ext]' : 'fonts/[name].[contenthash:7].[ext]',
  video: ({ isDev }) => isDev ? '[path][name].[ext]' : 'videos/[name].[contenthash:7].[ext]'
}

This example changes fancy chunk names to numerical ids:

nuxt.config.js

export default {
  build: {
    filenames: {
      chunk: ({ isDev }) => (isDev ? '[name].js' : '[id].[contenthash].js')
    }
  }
}

To understand a bit more about the use of manifests, take a look at this webpack documentation.

Be careful when using non-hashed based filenames in production as most browsers will cache the asset and not detect the changes on first load.

friendlyErrors

Type: Boolean
Default: true (Overlay enabled)

Enables or disables the overlay provided by FriendlyErrorsWebpackPlugin

hardSource

Type: Boolean
Default: false
⚠️ Experimental

Enables the HardSourceWebpackPlugin for improved caching

hotMiddleware

Type: Object

See webpack-hot-middleware for available options.

html.minify

Type: Object
Default:

{
  collapseBooleanAttributes: true,
  decodeEntities: true,
  minifyCSS: true,
  minifyJS: true,
  processConditionalComments: true,
  removeEmptyAttributes: true,
  removeRedundantAttributes: true,
  trimCustomFragments: true,
  useShortDoctype: true
}

Attention: If you make changes to html.minify, they won’t be merged with the defaults!

Configuration for the html-minifier plugin used to minify HTML files created during the build process (will be applied for all modes).

indicator

Display build indicator for hot module replacement in development (available in v2.8.0+)

Type: Boolean
Default: true

loaders

Customize options of Nuxt integrated webpack loaders.

Type: Object
Default:

{
  file: {},
  fontUrl: { limit: 1000 },
  imgUrl: { limit: 1000 },
  pugPlain: {},
  vue: {
    transformAssetUrls: {
      video: 'src',
      source: 'src',
      object: 'src',
      embed: 'src'
    }
  },
  css: {},
  cssModules: {
    localIdentName: '[local]_[hash:base64:5]'
  },
  less: {},
  sass: {
    indentedSyntax: true
  },
  scss: {},
  stylus: {},
  vueStyle: {}
}

Note: In addition to specifying the configurations in nuxt.config.js, it can also be modified by build.extend

loaders.file

More details are in file-loader options.

loaders.fontUrl and loaders.imgUrl

More details are in url-loader options.

loaders.pugPlain

More details are in pug-plain-loader or Pug compiler options.

loaders.vue

More details are in vue-loader options.

loaders.css and loaders.cssModules

More details are in css-loader options. Note: cssModules is loader options for usage of CSS Modules

loaders.less

You can pass any Less specific options to the less-loader via loaders.less. See the Less documentation for all available options in dash-case.

loaders.sass and loaders.scss

See the Sass documentation for all available Sass options. Note: loaders.sass is for Sass Indented Syntax

loaders.vueStyle

More details are in vue-style-loader options.

optimization

Type: Object

Default:

{
  minimize: true,
  minimizer: [
    // terser-webpack-plugin
    // optimize-css-assets-webpack-plugin
  ],
  splitChunks: {
    chunks: 'all',
    automaticNameDelimiter: '.',
    name: undefined,
    cacheGroups: {}
  }
}

The default value of splitChunks.name is true in dev or analyze mode.

You can set minimizer to a customized Array of plugins or set minimize to false to disable all minimizers. (minimize is being disabled for development by default)

See Webpack Optimization.

optimizeCSS

Type: Object or Boolean
Default:
- false
- {} when extractCSS is enabled

OptimizeCSSAssets plugin options.

See NMFR/optimize-css-assets-webpack-plugin.

parallel

Type: Boolean
Default: false
⚠️ Experimental

Enable thread-loader in webpack building

plugins

Add webpack plugins

Type: Array
Default: []

nuxt.config.js

import webpack from 'webpack'
import { version } from './package.json'
export default {
  build: {
    plugins: [
      new webpack.DefinePlugin({
        'process.VERSION': version
      })
    ]
  }
}

postcss

Customize PostCSS Loader plugins.

Type: Array (legacy, will override defaults), Object (recommended), Function or Boolean
Note: Nuxt has applied PostCSS Preset Env. By default it enables Stage 2 features and Autoprefixer, you can use build.postcss.preset to configure it.

Default:

nuxt.config.js

{
  plugins: {
    'postcss-import': {},
    'postcss-url': {},
    'postcss-preset-env': this.preset,
    'cssnano': { preset: 'default' } // disabled in dev mode
  },
  order: 'presetEnvAndCssnanoLast',
  preset: {
    stage: 2
  }
}

Your custom plugin settings will be merged with the default plugins (unless you are using an Array instead of an Object).

nuxt.config.js

export default {
  build: {
    postcss: {
      plugins: {
        // Disable `postcss-url`
        'postcss-url': false,
        // Add some plugins
        'postcss-nested': {},
        'postcss-responsive-type': {},
        'postcss-hexrgba': {}
      },
      preset: {
        autoprefixer: {
          grid: true
        }
      }
    }
  }
}

If the postcss configuration is an Object, order can be used for defining the plugin order:

Type: Array (ordered plugin names), String (order preset name), Function
Default: cssnanoLast (put cssnano in last)

nuxt.config.js

export default {
  build: {
    postcss: {
      // preset name
      order: 'cssnanoLast',
      // ordered plugin names
      order: ['postcss-import', 'postcss-preset-env', 'cssnano']
      // Function to calculate plugin order
      order: (names, presets) => presets.cssnanoLast(names)
    }
  }
}

postcss plugins & @nuxtjs/tailwindcss

If you want to apply a postcss plugin (e.g. postcss-pxtorem) on the @nuxtjs/tailwindcss configuration, you have to change order and load tailwindcss first.

This setup has no impact on nuxt-purgecss.

nuxt.config.js

import { join } from 'path'
export default {
  // ...
  build: {
    postcss: {
      plugins: {
        tailwindcss: join(__dirname, 'tailwind.config.js'),
        'postcss-pxtorem': {
          propList: ['*', '!border*']
        }
      }
    }
  }
}

profile

Type: Boolean
Default: enabled by command line argument --profile

Enable the profiler in WebpackBar

publicPath

Nuxt lets you upload your dist files to your CDN for maximum performances, simply set the publicPath to your CDN.

Type: String
Default: '/_nuxt/'

nuxt.config.js

export default {
  build: {
    publicPath: 'https://cdn.nuxtjs.org'
  }
}

Then, when launching nuxt build, upload the content of .nuxt/dist/client directory to your CDN and voilà!

In Nuxt 2.15+, changing the value of this property at runtime will override the configuration of an app that has already been built.

quiet

Suppresses most of the build output log

Type: Boolean
Default: Enabled when a CI or test environment is detected by std-env

splitChunks

Type: Object

Default:

nuxt.config.js

export default {
  build: {
    splitChunks: {
      layouts: false,
      pages: true,
      commons: true
    }
  }
}

Whether or not to create separate chunks for layout, pages and commons (common libs: vue|vue-loader|vue-router|vuex…). For more information, see webpack docs.

ssr

Creates special webpack bundle for SSR renderer.

Type: Boolean
Default: true for universal mode and false for spa mode

This option is automatically set based on mode value if not provided.

standalone

Inline server bundle dependencies (advanced)

Type: Boolean
Default: false

This mode bundles node_modules that are normally preserved as externals in the server build (more information).

Runtime dependencies (modules, nuxt.config, server middleware and static directory) are not bundled. This feature only disables use of webpack-externals for server-bundle.

you can use the command yarn nuxt build --standalone to enable this mode on the command line. (If you are not using yarn you can run the command with npx.)

styleResources

Type: Object
Default: {}

This property is deprecated. Please use the style-resources-module instead for improved performance and better DX!

This is useful when you need to inject some variables and mixins in your pages without having to import them every time.

Nuxt uses https://github.com/yenshih/style-resources-loader to achieve this behavior.

You need to specify the patterns/path you want to include for the given pre-processors: less, sass, scss or stylus

You cannot use path aliases here (~ and @), you need to use relative or absolute paths.

nuxt.config.js

{
  build: {
    styleResources: {
      scss: './assets/variables.scss',
      less: './assets/*.less',
      // sass: ...,
      // scss: ...
      options: {
        // See https://github.com/yenshih/style-resources-loader#options
        // Except `patterns` property
      }
    }
  }
}

templates

Nuxt allows you provide your own templates which will be rendered based on Nuxt configuration. This feature is specially useful for using with modules.

Type: Array

nuxt.config.js

export default {
  build: {
    templates: [
      {
        src: '~/modules/support/plugin.js', // `src` can be absolute or relative
        dst: 'support.js', // `dst` is relative to project `.nuxt` dir
        options: {
          // Options are provided to template as `options` key
          live_chat: false
        }
      }
    ]
  }
}

Templates are rendered using lodash.template you can learn more about using them here.

terser

Type: Object or Boolean
Default:

nuxt.config.js

{
  parallel: true,
  cache: false,
  sourceMap: false,
  extractComments: {
    filename: 'LICENSES'
  },
  terserOptions: {
    output: {
      comments: /^\**!|@preserve|@license|@cc_on/
    }
  }
}

Terser plugin options. Set to false to disable this plugin.

Enabling sourceMap will leave //# sourceMappingURL linking comment at the end of each output file if webpack config.devtool is set to source-map.

See webpack-contrib/terser-webpack-plugin.

transpile

Type: Array<String | RegExp | Function>
Default: []

If you want to transpile specific dependencies with Babel, you can add them in build.transpile. Each item in transpile can be a package name, a string or regex object matching the dependency’s file name.

Starting with v2.9.0, you can also use a function to conditionally transpile. The function will receive an object ({ isDev, isServer, isClient, isModern, isLegacy }):

nuxt.config.js

{
  build: {
    transpile: [({ isLegacy }) => isLegacy && 'ky']
  }
}

In this example, ky will be transpiled by Babel if Nuxt is not in modern mode.

vueLoader

Note: This config has been removed since Nuxt 2.0, please use build.loaders.vueinstead.

Type: Object

Default:

nuxt.config.js

{
  productionMode: !this.options.dev,
  transformAssetUrls: {
    video: 'src',
    source: 'src',
    object: 'src',
    embed: 'src'
  }
}

Specify the Vue Loader Options.

watch

You can provide your custom files to watch and regenerate after changes. This feature is specially useful for using with modules.

Type: Array<String>

nuxt.config.js

export default {
  build: {
    watch: ['~/.nuxt/support.js']
  }
}

followSymlinks

By default, the build process does not scan files inside symlinks. This boolean includes them, thus allowing usage of symlinks inside folders such as the “pages” folder, for example.

Type: Boolean

nuxt.config.js

export default {
  build: {
    followSymlinks: true
  }
}

The build Property

The build property