Restore ability to override the build directory (from ".next" default) in static export mode

[GrantASL19]

Goals

Configure the directory Next.js writes build files to during static export builds (e.g. from .next to .next-test) to allow completely independent simultaneous builds with dynamic configurations without conflicts caused by all static build files writing to .next.

This was possible Next.js 13 and lower using a combination of the distDir configuration and next export -o <directory>

Non-Goals

No response

Background

In Next.js 13 with this next.config.js:

// All test scripts begin with "test-"
const isTestBuild = (process.env.npm_lifecycle_event ?? "").startsWith("test-");

module.exports = {
  // Build test builds into ".next-test" to keep test builds separate from
  // regular builds, and to allow E2E tests to run while regular server is
  // running.
  distDir: isTestBuild ? ".next-test" : ".next",
};

We could simultaneously:

1. Run the site in development mode with the default configuration in one shell with next dev; or build and run with the default configuration with next build && next export && ws
2. Build and run with the test configuration (using mocked API requests) using dotenv -oe .env.test -- next build && dotenv -oe .env.test -- next export -o out-test && PORT=3001 dotenv -oe .env.test -- ws

(ws is local-web-server).

---

In Next.js 14 the next export -o option was removed and merged into distDir, but the use case was only partially addressed because crucially production build files are now always written into .next, with AFAIK no way to override in configuration.

This means that the closest we can get to our Next.js 13 setup our Next.js 14 next.config.js is this:

// All scripts with `next dev` end with "-dev"; all test scripts begin with "test-"
const isDevBuild = (process.env.npm_lifecycle_event ?? "").endsWith("-dev");
const isTestBuild = (process.env.npm_lifecycle_event ?? "").startsWith("test-");

module.exports = {
  // (This uses ts-pattern)
  distDir: match({ isDevBuild, isTestBuild })
    // Writes to .next
    .with({ isDevBuild: true, isTestBuild: false }, () => ".next")
    // Writes to .next-test
    .with({ isDevBuild: true, isTestBuild: true }, () => ".next-test")
    // Writes to .next and out
    .with({ isDevBuild: false, isTestBuild: false }, () => "out")
    // Writes to .next and out-test
    .with({ isDevBuild: false, isTestBuild: true }, () => "out-test")
    .exhaustive(),
  output: "export",
};

This allows us to simultaneously run with isDevBuild: true, isTestBuild: false (writes to .next) and isDevBuild: true, isTestBuild: true (written to .next-test) as we could with Next.js 13.

But it does’t work with isDevBuild: true/false, isTestBuild: false (writes to .next and out for prod builds) and isDevBuild: false, isTestBuild: true (writes to .next and out-test) because the production files are always written into .next, conflicting with the dev build.

I understand the rationale for the changed behaviour in Next.js 14, but this is a regression for our (admittedly uncommon) use case, and IMO it’s potentially confusing that distDir usually overrides .next, but overrides out when used with output: "export".

Proposal

I’m not sure if this is a use case you want to support, but if so I can think of two possible options:

1. Add a new buildDir config option that allows configuring the build directory separately from distDir
2. Add a new --build-dir flag to next build

[Sly36]

I also have this use case.

Currently migrating our application from Pages router to App router for web performance improvement.

With Next.js 13.5.6 and Pages router I managed to parallelize the build and the export of our 7k pages to reduce the build time on our CI from around 50 minutes to 10 minutes. Big improvement for us to reduce all the pipelines (MR, realease, etc).

I was using the combination of :

distDir: "nextOutput/builds/build-" + ciNodeIndex,

to build different sets of pages for each parallel job

and

- npm run build
- EXPORT_PATH=$(echo "nextOutput/outs/out-${CI_NODE_INDEX}")
- npm run export -- -o $EXPORT_PATH

to export them

Then I merged the different output directories into one and deployed it in a bucket.

But now, with the App router not supporting npm run export and the fact that distDir: "nextOutput/builds/build-" + ciNodeIndex, does not apply to build directory when output: "export" is set, I can't find a way to make "parallel building" work on our application and CI (getting errors and conflicts on files that are created and or moved during the builds in the unique .next directory).

Going back to 50 minutes of build time is a no go for us, so we are excluding ourselves from the potential App router benefits and web performance optimisation (with RSC for exemple). We also can't upgrade to Next.js v14 for the same reason.

So I would really like to know if someone here managed to parallelize the next.js build with App router or really want to bring back the buildDir config option !

PS : this issue about the build being non-deterministic #63201 worries me too

[r3fresh]

Same problem here, I need this feature back :/ please !

[CLMSMG]

Hi, i have the same problem...