distDir
Sets the directory next build writes to, instead of the default .next folder.
distDir?: stringParameters
| Parameter | Type | Description |
|---|---|---|
$distDiroptional | string= '.next' | Directory name, resolved relative to the project root, that next build and next start use for build output. It must not escape the project directory; '../build' is invalid. |
Errors
A distDir that resolves outside the project directory, such as '../build', is rejected as an invalid directory.
Renames the build directory. next build, next start and the dev server all follow the setting, so nothing else needs telling — but everything outside Next.js does.
When to reach for it
- A host or CI system that expects output in
buildordist. - Keeping parallel builds for different environments in separate folders.
- Avoiding a collision with another tool that already owns
.next.
What trips people up
The default .next starts with a dot, and most project .gitignore files list it by that exact name. Rename it to build and you will commit a few hundred megabytes of build output unless you update the ignore file first. Docker COPY lines, CI cache keys, and cleanup scripts hardcode the path too. The directory must stay inside the project — '../build' is rejected. Two other paths move with it: standalone output lands at <distDir>/standalone, and the optimized image cache at <distDir>/cache/images, which is the directory to delete when you need to invalidate cached images. With output: 'export' this renames the export directory, so out becomes whatever you set.
Example
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
distDir: 'build',
}
export default nextConfigWhen to use it
- Match a deployment platform that expects the build in dist
- Keep staging and production builds in separate directories on one machine
- Rename the static export folder from out to something the host expects
Frequently asked questions
Can distDir point outside the project?
No. It must not leave the project directory — '../build' is explicitly invalid. Use a path inside the project and move or symlink the result afterwards if your deployment needs it elsewhere.
Do I need to change my start command after setting distDir?
No. next build, next start and next dev all read the setting from next.config. What does need updating is anything outside Next.js: .gitignore, Dockerfile COPY paths, CI cache keys and cleanup scripts.
Where is the image cache after changing distDir?
At <distDir>/cache/images. Since next/image has no cache invalidation API, deleting that directory is the manual way to clear optimized images, and its path follows whatever you set here.
More examples
Everything that moves with it
Every path Next.js documents relative to .next follows distDir, including the standalone server, the file traces and the optimized image cache. That last one matters in practice: since there is no cache invalidation API for next/image, deleting <distDir>/cache/images is the manual escape hatch, and the path changes when you rename the directory.
# .gitignore — update this first
build/
# next build now writes here
build/
build/standalone/server.js # with output: 'standalone'
build/cache/images # optimized image cache
build/next-server.js.nft.json # server file trace
# invalidating the image cache
rm -rf build/cache/imagesRenaming the static export directory
A static export normally writes to out. With distDir set, the HTML, CSS and JS land in dist instead, which is the folder you point the static host or GitHub Pages action at. This is the documented way to rename the export output; there is no separate export directory option.
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
output: 'export',
// out -> dist
distDir: 'dist',
}
export default nextConfig
Discussion