nextjs - 💡(How to fix) Fix Passing configuration options as the `conf` property to the `next()` function in a custom server is ignored [1 participants]

Link to the code that reproduces this issue

https://github.com/woodman231/next-custom1

To Reproduce

1. Clone the examples/custom-server example from the Next.js repository.
2. Modify the server file to the following:

import { createServer } from "http";
import { parse } from "url";
import next from "next";

const port = 3000;
const dev = false;
const app = next({ dev, conf: { basePath: "/config-test", devIndicators: false } });
const handle = app.getRequestHandler();

app.prepare().then(() => {
  createServer((req, res) => {
    const parsedUrl = parse(req.url!, true);
    handle(req, res, parsedUrl);
  }).listen(port);

  console.log(`> Server listening at http://localhost:${port}`);
});

1. Do not include any next.config.mjs or next.config.js file.
2. Start the server and attempt to visit http://localhost:3000/config-test.
3. It fails with a 404 and ignores the basePath.
4. If you now add a next.config.mjs with the same options (e.g. basePath: '/config-test', devIndicators: false), the settings are respected and it works as expected.

Current vs. Expected behavior

Expected behavior

• Passing config options in the conf property to the next() function should have the same effect as specifying them in next.config.js/next.config.mjs.
• Routing, basePath, devIndicators, and all other documented config settings should apply at startup, both in dev and production modes.

Actual behavior

• The config options provided via the conf property are ignored for many settings (such as basePath).
• Only file-based config is respected for these options.
• This makes it impossible to control these behaviors dynamically in a custom server environment as documented.

Provide environment information

Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 11 Enterprise
  Available memory (MB): 65144
  Available CPU cores: 20
Binaries:
  Node: 22.16.0
  npm: 10.9.2
  Yarn: N/A
  pnpm: 10.12.1
Relevant Packages:
  next: 16.1.1-canary.0 // Latest available version is detected (16.1.1-canary.0).
  eslint-config-next: N/A
  react: 19.2.3
  react-dom: 19.2.3
  typescript: 5.9.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Runtime

Which stage(s) are affected? (Select all that apply)

next dev (local), next build (local)

Additional context

Notes

• This happens in both development and production modes (dev: true and dev: false).
• Bug is present in all recent versions of Next.js.
• The issue is confirmed by source code review which appears to process the conf, but its effects do not apply for routing-level and other core settings.
• You can easily verify this with the official custom-server example.

Impact

• Users following the documentation have a false sense of control over config via conf.
• There is an acute need to either fix this or to update the documentation to clarify that only file-based config works for routing/basePath and related settings.

What should happen?

• Either respect the conf property for all settings, or update documentation to warn users of this critical limitation.

References:

• Next.js custom server options documentation
• loadConfig implementation
• custom server example