next.config.js

For custom advanced configuration of Next.js, you can create a next.config.js or next.config.mjs file in the root of your project directory (next to package.json).

next.config.js is a regular Node.js module, not a JSON file. It gets used by the Next.js server and build phases, and it’s not included in the browser build.

Take a look at the following next.config.js example:

  1. /**
  2.  * @type {import('next').NextConfig}
  3.  */
  4. const nextConfig = {
  5.   /* config options here */
  6. }
  8. module.exports = nextConfig

If you need ECMAScript modules, you can use next.config.mjs:

  1. /**
  2.  * @type {import('next').NextConfig}
  3.  */
  4. const nextConfig = {
  5.   /* config options here */
  6. }
  8. export default nextConfig

You can also use a function:

  1. module.exports = (phase, { defaultConfig }) => {
  2.   /**
  3.    * @type {import('next').NextConfig}
  4.    */
  5.   const nextConfig = {
  6.     /* config options here */
  7.   }
  8.   return nextConfig
  9. }

Since Next.js 12.1.0, you can use an async function:

  1. module.exports = async (phase, { defaultConfig }) => {
  2.   /**
  3.    * @type {import('next').NextConfig}
  4.    */
  5.   const nextConfig = {
  6.     /* config options here */
  7.   }
  8.   return nextConfig
  9. }

phase is the current context in which the configuration is loaded. You can see the available phases. Phases can be imported from next/constants:

  1. const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')
  3. module.exports = (phase, { defaultConfig }) => {
  4.   if (phase === PHASE_DEVELOPMENT_SERVER) {
  5.     return {
  6.       /* development only config options here */
  7.     }
  8.   }
  10.   return {
  11.     /* config options for all phases except development here */
  12.   }
  13. }

The commented lines are the place where you can put the configs allowed by next.config.js, which are defined in this file.

However, none of the configs are required, and it’s not necessary to understand what each config does. Instead, search for the features you need to enable or modify in this section and they will show you what to do.

Avoid using new JavaScript features not available in your target Node.js version. next.config.js will not be parsed by Webpack, Babel or TypeScript.