next.config.js Options
Next.js can be configured through a next.config.js
file in the root of your project directory (for example, by package.json
) with a default export.
// @ts-check
/** @type {import('next').NextConfig} */
const nextConfig = {
/* 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 need ECMAScript modules, you can use next.config.mjs
:
// @ts-check
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
/* config options here */
}
export default nextConfig
Good to know:
next.config
with the.cjs
,.cts
, or.mts
extensions are currently not supported.
Configuration as a Function
You can also use a function:
// @ts-check
export default (phase, { defaultConfig }) => {
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
/* config options here */
}
return nextConfig
}
Async Configuration
Since Next.js 12.1.0, you can use an async function:
// @ts-check
module.exports = async (phase, { defaultConfig }) => {
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
/* config options here */
}
return nextConfig
}
Phase
phase
is the current context in which the configuration is loaded. You can see the available phases. Phases can be imported from next/constants
:
// @ts-check
const { 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
This feature is available from Next.js canary.
If you are using TypeScript in your project, you can use next.config.ts
to use TypeScript in your configuration:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
/* config options here */
}
export default nextConfig
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 or Babel.
This page documents all the available configuration options:
assetPrefix
basePath
bundlePagesRouterDependencies
compress
crossOrigin
devIndicators
distDir
env
eslint
exportPathMap
generateBuildId
generateEtags
headers
httpAgentOptions
images
instrumentationHook
onDemandEntries
optimizePackageImports
output
pageExtensions
poweredByHeader
productionBrowserSourceMaps
reactStrictMode
redirects
rewrites
Runtime Config
serverExternalPackages
trailingSlash
transpilePackages
turbo
typescript
urlImports
useLightningcss
webpack
webVitalsAttribution
Was this helpful?