API: The build Property

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

analyze

Nuxt.js 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.

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

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:
  • Object: { isServer: true | false }
  • 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, {
              buildTarget: isServer ? 'server' : 'client',
              ...options
            }],
          [
            // Other presets
          ]
        ]
      }
    }
  }
}

cache

• Type: Boolean
• Default: false
• ⚠️ Experimental

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

crossorigin

• Type: String

• Default: undefined

Configure the crossorigin attribute on <link rel="stylesheet"> and <script> tags in generated HTML.

More Info: CORS settings attributes

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.

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

Example (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
• 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.

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 extracting 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 }) => isDev ? '[name].js' : '[contenthash].js',
  chunk: ({ isDev }) => isDev ? '[name].js' : '[contenthash].js',
  css: ({ isDev }) => isDev ? '[name].css' : '[contenthash].css',
  img: ({ isDev }) => isDev ? '[path][name].[ext]' : 'img/[contenthash:7].[ext]',
  font: ({ isDev }) => isDev ? '[path][name].[ext]' : 'fonts/[contenthash:7].[ext]',
  video: ({ isDev }) => isDev ? '[path][name].[ext]' : 'videos/[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.

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 minifyHTML 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.js 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 Node 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: []

Example (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.js has applied PostCSS Preset Env. By default it enables Stage 2 features and Autoprefixer, you can use build.postcss.preset to configure it.

• Default:

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

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

Example (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 & nuxt-tailwindcss

If you want to apply postcss plugin (eg. postcss-pxtorem) on the nuxt-tailwindcss configuration, you have to change order and load first tailwindcss.

This setup have no impact on the nuxt-purgecss.

Example (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.js lets you upload your dist files to your CDN for maximum performances, simply set the publicPath to your CDN.

• Type: String
• Default: '/_nuxt/'

Example (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à!

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:

{
  layouts: false,
  pages: true,
  commons: true
}

If split codes for layout, pages and commons (common libs: vue|vue-loader|vue-router|vuex…).

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.

styleResources

• Type: Object
• Default: {}

Warning: 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.js uses https://github.com/yenshih/style-resources-loader to achieve this behaviour.

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

Example (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:

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

sourceMap will be enabled when webpack config.devtool matches 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 conditionnaly transpile, the function will receive a object ({ isDev, isServer, isClient, isModern, isLegacy }):

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

vueLoader

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

• Type: Object

• Default:

{
  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>

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

export default {
  build: {
    followSymlinks: false
  }
}