next.config.js

Next.js can be configured through anext.config.js file in the root of your project directory (for example, bypackage.json) with a default export.

// @ts-check/**@type{import('next').NextConfig} */constnextConfig= {/* config options here */}module.exports= nextConfig

ECMAScript Modules

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.

If you needECMAScript modules, you can usenext.config.mjs:

// @ts-check/** *@type{import('next').NextConfig} */constnextConfig= {/* config options here */}exportdefault nextConfig

Good to know:next.config with the.cjs or.cts extensions are currentlynot supported.

Configuration as a Function

You can also use a function:

// @ts-checkexportdefault (phase, { defaultConfig })=> {/**   *@type{import('next').NextConfig}   */constnextConfig= {/* config options here */  }return nextConfig}

Async Configuration

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

// @ts-checkmodule.exports=async (phase, { defaultConfig })=> {/**   *@type{import('next').NextConfig}   */constnextConfig= {/* config options here */  }return nextConfig}

Phase

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

// @ts-checkconst {PHASE_DEVELOPMENT_SERVER }=require('next/constants')module.exports= (phase, { defaultConfig })=> {if (phase===PHASE_DEVELOPMENT_SERVER) {return {/* development only config options here */    }  }return {/* config options for all phases except development here */  }}

TypeScript

If you are using TypeScript in your project, you can usenext.config.ts to use TypeScript in your configuration:

importtype { NextConfig }from'next'constnextConfig:NextConfig= {/* config options here */}exportdefault nextConfig

The commented lines are the place where you can put the configs allowed bynext.config.js, which aredefined 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 or Babel.

This page documents all the available configuration options:

Unit Testing (experimental)

Starting in Next.js 15.1, thenext/experimental/testing/server package contains utilities to help unit testnext.config.js files.

Theunstable_getResponseFromNextConfig function runs theheaders,redirects, andrewrites functions fromnext.config.js with the provided request information and returnsNextResponse with the results of the routing.

The response fromunstable_getResponseFromNextConfig only considersnext.config.js fields and does not consider proxy or filesystem routes, so the result in production may be different than the unit test.

import {  getRedirectUrl,  unstable_getResponseFromNextConfig,}from'next/experimental/testing/server'constresponse=awaitunstable_getResponseFromNextConfig({  url:'https://nextjs.org/test',  nextConfig: {asyncredirects() {return [{ source:'/test', destination:'/test2', permanent:false }]    },  },})expect(response.status).toEqual(307)expect(getRedirectUrl(response)).toEqual('https://nextjs.org/test2')