Skip to content

Passing configuration options as the conf property to the next() function in a custom server is ignored #87429

@woodman231

Description

@woodman231

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:


Metadata

Metadata

Assignees

No one assigned

    Labels

    RuntimeRelated to Node.js or Edge Runtime with Next.js.

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions