Link to the code that reproduces this issue
https://github.com/woodman231/next-custom1
To Reproduce
- Clone the examples/custom-server example from the Next.js repository.
- 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}`);
});
- Do not include any
next.config.mjs or next.config.js file.
- Start the server and attempt to visit
http://localhost:3000/config-test.
- It fails with a 404 and ignores the basePath.
- 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:
Link to the code that reproduces this issue
https://github.com/woodman231/next-custom1
To Reproduce
next.config.mjsornext.config.jsfile.http://localhost:3000/config-test.next.config.mjswith 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
confproperty to thenext()function should have the same effect as specifying them innext.config.js/next.config.mjs.Actual behavior
confproperty are ignored for many settings (such asbasePath).Provide environment information
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
dev: trueanddev: false).Impact
conf.What should happen?
References: