fix(build,docs): document expected build warnings + quiet build-phase JWT FATAL (#16320) (#16324)

fix(build,docs): document the expected production-build warnings and suppress the JWT_SECRET FATAL log only during `next build`. POST /api/auth/login still fail-closes when the secret is missing.

Closes #16320

Boarded with #16346, #16342, and #16323 on detached `62049e9cb8`. Focused tests: tests/unit/16320-build-warnings.test.ts 4 pass, tests/unit/build/known-build-warnings.test.ts 7 pass (23/23 across the batch). File-size, changelog integrity, eslint, typecheck:core, complexity (3038/3218), cognitive complexity (1400/1437), and docs-counts (retry) passed. CI Lint is the inherited `executeTargetAttempt.ts` ceiling, a file this PR does not touch, and Build was cancelled. Thanks @opensource-elearning.

⚠️ base-red inherited: #15306
This commit is contained in:
opensource-elearning
2026-10-16 00:49:28 +05:30
committed by GitHub
parent a49bfc81a6
commit 29f9ade3bc
8 changed files with 341 additions and 40 deletions

View File

@@ -0,0 +1 @@
- Build: documented the expected production-build warnings in `docs/ops/BUILD_WARNINGS.md`, stopped the login route from logging `[SECURITY] FATAL: JWT_SECRET is not set` during `next build`, and widened the Fumadocs MDX build-cache warning filter to cover the `dist/eval-*.js` bundle ([#16320](https://github.com/diegosouzapw/OmniRoute/issues/16320)).

View File

@@ -0,0 +1,99 @@
---
title: "Build Warnings Reference"
version: 3.8.52
lastUpdated: 2026-10-11
---
# Build Warnings Reference
`npm run build` and `npm run build:release` print a handful of warnings that are
**expected** and do not mean the artifact is broken. This page catalogs them, says
whether each one is actionable, and points at the code that owns it — so an operator can
tell known build-time noise from a real regression.
If a message you see is not listed here, treat it as new and investigate it.
## Webpack "Critical dependency" for `open-sse/executors/codex.ts`
```
./open-sse/executors/codex.ts
Critical dependency: require function is used in a way in which dependencies cannot be statically extracted
```
**Expected — intentional.** `open-sse/executors/codex/wreqLoader.ts` loads the optional
`wreq-js` native helper through a `createRequire()`-returned function whose specifier is
kept as a **variable** on purpose (`Reflect.apply(requireFn, undefined, [moduleName])`). A
literal specifier is statically rewritten by Turbopack into a hashed `.next`-relative
require that does not exist in the standalone Docker runtime, so the dynamic form is
required (#12491). The warning is the price of that pattern; the module still resolves at
runtime and is not a missing dependency.
Because the loader is imported by the Codex quota service, instrumentation, and the
internal Codex WebSocket route, webpack reports the same warning once per import path.
## Fumadocs MDX "build dependencies" cache warning
```
[webpack.cache.PackFileCacheStrategy/webpack.FileSystemInfo] Parsing of
.../fumadocs-mdx/dist/eval-*.js for build dependencies failed at 'import(pathToFileURL(outfile).href)'.
Build dependencies behind this expression are ignored and might cause incorrect cache invalidation.
```
**Upstream `fumadocs-mdx`, not actionable.** The package emits a dynamic `import()` of a
generated module that webpack's `FileSystemInfo` pass cannot statically follow. The only
consequence is that webpack may invalidate its build cache more often for that dependency;
the **emitted output is unaffected**. OmniRoute suppresses the known benign form in
`next.config.mjs` via `scripts/build/knownBuildWarnings.mjs`, which allow-lists the whole
`node_modules/fumadocs-mdx/dist/` directory (both the `load-from-file-*.js` and
`eval-*.js` bundles).
## Runtime configuration messages during static generation
`next build` imports application modules while collecting page data, so a few
runtime-oriented log lines appear during the build as well. They are **not** build errors.
| Message | Owner | Meaning |
| --------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `[DB] Build phase detected — using no-op SQLite stub (never queried)` | `src/lib/db/core.ts` | The build never opens the real database. Expected. |
| `[REDIS] REDIS_URL is not set in production. Using in-memory rate limiting.` | `src/shared/utils/rateLimiter.ts` | Redis is optional; without it rate limiting falls back to memory. Set it only if you run Redis in production — see `REDIS_PRODUCTION_CONFIG.md`. |
| `[CREDENTIALS] No external credentials file found, using defaults.` | `open-sse/config/credentialLoader.ts` | Expected unless you ship an external credentials file. |
| `[INFO] [PLUGIN_SCANNER] scanner.dir_resolved` / `[INFO] [MEMORY_MANAGER] Registered backend` | plugin + memory registries | Informational. |
### `[SECURITY] FATAL: JWT_SECRET is not set`
`JWT_SECRET` is **required at runtime** — without it, login fails closed and the dashboard
is unreachable. Set it in your environment before starting the server (see
`../reference/ENVIRONMENT.md`).
During `next build` the login route module used to be imported while collecting page data
with no `JWT_SECRET`, and printed the same `FATAL` line, which reads like a live security
failure. That message is now skipped during the build phase: the module-level warning in
`src/app/api/auth/login/route.ts` is gated on `isNextBuildPhase()`
(`src/lib/buildPhase.ts`), which matches `NEXT_PHASE=phase-production-build`,
`OMNIROUTE_BUILDING=1`, and `npm_lifecycle_event=build`. The request handler still returns
`500` when the secret is missing at runtime, so runtime behavior is unchanged.
## Bun and dependency installation
OmniRoute is built and run with **Node.js** (`engines.node` in `package.json`). Install
dependencies with `npm ci` (or `npm install`):
```bash
npm ci
npm run build:release
```
**`bun install` is not a supported way to install OmniRoute's dependencies** for this
branch. Bun `1.4.2` is pinned as a devDependency and is used only to run a small,
allow-listed set of gate/generator scripts. If you install with Bun you may see:
- `warn: Bun currently only supports one level of nested "overrides"` — Bun's support for
`package.json` `overrides` is shallower than npm's; npm applies the full tree.
- **Blocked lifecycle scripts** for native packages (ONNX Runtime, Playwright Chromium,
SWC, protobufjs, Parcel Watcher, unrs-resolver). Bun blocks install scripts by default;
the supported `npm ci` path runs them, and `npm run check:native-deps` verifies that
every externalized package resolves afterward.
If a Bun-invoked gate script fails with `bun: not found`, the tree is stale — re-run
`npm install`. If `node_modules/bun/bin/bun.exe` is a tiny shell-script placeholder instead
of the real binary, its `postinstall` was skipped; run `cd node_modules/bun && node install.js`.

View File

@@ -3,6 +3,7 @@
"pages": [
"RELEASE_CHECKLIST",
"RELEASE_GREEN",
"BUILD_WARNINGS",
"BRANCHING_MODEL",
"RELEASE_STRATEGY",
"BRANCH_PROTECTION_MAIN",

View File

@@ -11,6 +11,10 @@ import {
resolveDashboardEmbedMode,
} from "./scripts/build/dashboardEmbed.mjs";
import { shouldBuildStandalone } from "./scripts/build/backendOnlyPages.mjs";
import {
filterKnownInfrastructureWarnings,
isNextIntlExtractorDynamicImportWarning,
} from "./scripts/build/knownBuildWarnings.mjs";
const withNextIntl = createNextIntlPlugin("./src/i18n/request.ts");
const distDir = process.env.NEXT_DIST_DIR || ".build/next";
@@ -65,45 +69,6 @@ const securityHeaders = [
},
];
function isNextIntlExtractorDynamicImportWarning(warning) {
const message = typeof warning === "string" ? warning : warning?.message || "";
const resource = warning?.module?.resource || warning?.file || "";
const target = "next-intl/dist/esm/production/extractor/format/index.js";
return (
resource.includes(target) &&
(message.includes("import(t)") || message.includes("dependency is an expression"))
);
}
const IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES = [
"/node_modules/fumadocs-mdx/dist/load-from-file-",
"/node_modules/next-intl/dist/esm/production/extractor/format/index.js",
];
function isKnownInfrastructureBuildDependencyWarning(args) {
const message = args
.filter((value) => typeof value === "string")
.join(" ")
.replaceAll("\\", "/");
return (
message.includes("webpack.FileSystemInfo") &&
message.includes("for build dependencies failed at 'import(") &&
message.includes("incorrect cache invalidation") &&
IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES.some((modulePath) =>
message.includes(modulePath)
)
);
}
function filterKnownInfrastructureWarnings(baseConsole) {
const filteredConsole = Object.create(baseConsole);
filteredConsole.warn = (...args) => {
if (isKnownInfrastructureBuildDependencyWarning(args)) return;
Reflect.apply(baseConsole.warn, baseConsole, args);
};
return filteredConsole;
}
// OMNIROUTE_BUILD_PROFILE=minimal physically removes four optional privileged
// modules (MITM cert install, Zed keychain import, Cloud Sync, 9router
// installer) from the built bundle by aliasing them to feature-disabled stubs.

View File

@@ -0,0 +1,69 @@
/**
* Known, non-actionable Next.js/webpack build warnings.
*
* Kept in a standalone module (rather than inlined in `next.config.mjs`) so the
* matching logic is unit-testable. The #16320 report showed the Fumadocs MDX
* "build dependencies" warning escaping the allowlist because the entry only
* matched the `dist/load-from-file-*.js` bundle, never the `dist/eval-*.js` one
* that webpack actually parsed in production.
*/
/**
* Bundled third-party files whose `import(<expression>)` a webpack
* `FileSystemInfo` pass cannot statically resolve. The warning never indicates
* broken output — only coarser build-cache invalidation for that dependency.
*/
export const IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES = [
// `fumadocs-mdx` emits both `dist/load-from-file-*.js` and `dist/eval-*.js`;
// match the whole `dist/` directory so a renamed bundle cannot re-open #16320.
"/node_modules/fumadocs-mdx/dist/",
"/node_modules/next-intl/dist/esm/production/extractor/format/index.js",
];
/**
* True for the `webpack.FileSystemInfo` "build dependencies failed" warning
* raised for one of the allow-listed third-party modules above.
*/
export function isKnownInfrastructureBuildDependencyWarning(args) {
const values = Array.isArray(args) ? args : [args];
const message = values
.filter((value) => typeof value === "string")
.join(" ")
.replaceAll("\\", "/");
return (
message.includes("webpack.FileSystemInfo") &&
message.includes("for build dependencies failed at 'import(") &&
message.includes("incorrect cache invalidation") &&
IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES.some((modulePath) =>
message.includes(modulePath)
)
);
}
/**
* True for the `next-intl` production extractor's dynamic-import webpack warning
* (matched by module resource, since the message text is generic).
*/
export function isNextIntlExtractorDynamicImportWarning(warning) {
const message = typeof warning === "string" ? warning : warning?.message || "";
const resource = warning?.module?.resource || warning?.file || "";
const target = "next-intl/dist/esm/production/extractor/format/index.js";
return (
resource.includes(target) &&
(message.includes("import(t)") || message.includes("dependency is an expression"))
);
}
/**
* Wrap a webpack infrastructure-logging console so the known-benign build
* dependency warnings above are dropped while every other message passes
* through untouched.
*/
export function filterKnownInfrastructureWarnings(baseConsole) {
const filteredConsole = Object.create(baseConsole);
filteredConsole.warn = (...args) => {
if (isKnownInfrastructureBuildDependencyWarning(args)) return;
Reflect.apply(baseConsole.warn, baseConsole, args);
};
return filteredConsole;
}

View File

@@ -10,6 +10,7 @@ import {
verifyManagementPassword,
} from "@/lib/auth/managementPassword";
import { isFeatureFlagEnabled } from "@/shared/utils/featureFlags";
import { isNextBuildPhase } from "@/lib/buildPhase";
import { loginSchema } from "@/shared/validation/schemas";
import { isValidationFailure, validateBody } from "@/shared/validation/helpers";
import {
@@ -30,14 +31,27 @@ import {
} from "@/server/auth/loginPeer";
import { getRequestPeerLocality } from "@/shared/utils/apiAuth";
/**
* Whether the module-level missing-JWT_SECRET warning should fire. It is
* suppressed while `next build` imports this route to collect page data, where
* the secret is legitimately absent (the operator supplies it at container
* start) and the FATAL wording is misleading rather than actionable (#16320).
* The POST handler still fails closed when the secret is missing at runtime.
*/
function shouldWarnMissingJwtSecret(): boolean {
return !process.env.JWT_SECRET && !isNextBuildPhase();
}
// SECURITY: No hardcoded fallback — JWT_SECRET must be configured.
if (!process.env.JWT_SECRET) {
if (shouldWarnMissingJwtSecret()) {
console.error("[SECURITY] FATAL: JWT_SECRET is not set. Login authentication is disabled.");
}
// Test seam for cookie store injection without affecting runtime behavior.
export const authRouteInternals = {
getCookieStore: cookies,
/** True when the module-level missing-JWT_SECRET warning should fire (#16320). */
shouldWarnMissingJwtSecret,
};
export async function POST(request: NextRequest) {

View File

@@ -0,0 +1,67 @@
/**
* #16320 — during `next build` (page-data collection) the login route module is
* imported with no JWT_SECRET, and its module-level `console.error` printed
* `[SECURITY] FATAL: JWT_SECRET is not set. Login authentication is disabled.`
* That reads like a runtime security failure. The warning must stay for the
* runtime, and be suppressed for the build phase.
*/
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-16320-"));
process.env.DATA_DIR = TEST_DATA_DIR;
process.env.JWT_SECRET = "test-jwt-secret-16320";
const loginRoute = await import("../../src/app/api/auth/login/route.ts");
const shouldWarn = loginRoute.authRouteInternals.shouldWarnMissingJwtSecret;
const BUILD_SIGNAL_KEYS = ["NEXT_PHASE", "OMNIROUTE_BUILDING", "npm_lifecycle_event"] as const;
const saved = {
JWT_SECRET: process.env.JWT_SECRET,
...Object.fromEntries(BUILD_SIGNAL_KEYS.map((key) => [key, process.env[key]])),
} as Record<string, string | undefined>;
function clearBuildSignals() {
for (const key of BUILD_SIGNAL_KEYS) delete process.env[key];
}
test.after(() => {
for (const [key, value] of Object.entries(saved)) {
if (value === undefined) delete process.env[key];
else process.env[key] = value;
}
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
});
test("no FATAL during the Next.js build phase when JWT_SECRET is absent (#16320)", () => {
clearBuildSignals();
delete process.env.JWT_SECRET;
process.env.NEXT_PHASE = "phase-production-build";
assert.equal(shouldWarn(), false);
});
test("OMNIROUTE_BUILDING=1 also suppresses the warning (build-worker signal)", () => {
clearBuildSignals();
delete process.env.JWT_SECRET;
process.env.OMNIROUTE_BUILDING = "1";
assert.equal(shouldWarn(), false);
});
test("the runtime warning is preserved when JWT_SECRET is missing", () => {
clearBuildSignals();
delete process.env.JWT_SECRET;
assert.equal(shouldWarn(), true);
});
test("no warning when JWT_SECRET is configured at runtime", () => {
clearBuildSignals();
process.env.JWT_SECRET = "configured-secret";
assert.equal(shouldWarn(), false);
});

View File

@@ -0,0 +1,85 @@
/**
* #16320 — the production build reported the Fumadocs MDX build-dependency
* warning for `fumadocs-mdx/dist/eval-*.js`, but the infrastructure-log filter
* only allow-listed `dist/load-from-file-*.js`, so the warning leaked through.
*
* These cases pin the match to the whole `dist/` directory and guard the
* passthrough behavior of the console wrapper.
*/
import { test } from "node:test";
import assert from "node:assert/strict";
import {
IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES,
filterKnownInfrastructureWarnings,
isKnownInfrastructureBuildDependencyWarning,
isNextIntlExtractorDynamicImportWarning,
} from "../../../scripts/build/knownBuildWarnings.mjs";
const ISSUE_WARNING = [
"[webpack.cache.PackFileCacheStrategy/webpack.FileSystemInfo] Parsing of",
"/home/temp/OmniRoute/node_modules/fumadocs-mdx/dist/eval-Cldqy98u.js",
"for build dependencies failed at 'import(pathToFileURL(outfile).href)'.",
"Build dependencies behind this expression are ignored and might cause incorrect cache invalidation.",
].join(" ");
test("the reported fumadocs-mdx eval-*.js warning is recognized (#16320)", () => {
assert.equal(isKnownInfrastructureBuildDependencyWarning([ISSUE_WARNING]), true);
});
test("the load-from-file-* fumadocs-mdx bundle shape stays recognized", () => {
const warning = ISSUE_WARNING.replace("eval-Cldqy98u.js", "load-from-file-abc123.js");
assert.equal(isKnownInfrastructureBuildDependencyWarning([warning]), true);
});
test("Windows-style backslash paths are normalized before matching", () => {
const warning = ISSUE_WARNING.replaceAll("/", "\\");
assert.equal(isKnownInfrastructureBuildDependencyWarning([warning]), true);
});
test("an unrelated FileSystemInfo warning is not swallowed", () => {
const warning = [
"[webpack.cache.PackFileCacheStrategy/webpack.FileSystemInfo] Parsing of",
"/repo/node_modules/some-other-lib/dist/index.js",
"for build dependencies failed at 'import(expr)'.",
"Build dependencies behind this expression are ignored and might cause incorrect cache invalidation.",
].join(" ");
assert.equal(isKnownInfrastructureBuildDependencyWarning([warning]), false);
});
test("the fumadocs allowlist matches the dist directory, not a single bundle name", () => {
assert.ok(
IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES.some((entry) =>
entry.includes("/node_modules/fumadocs-mdx/dist/")
)
);
});
test("filterKnownInfrastructureWarnings drops known noise and forwards everything else", () => {
const seen = [];
const baseConsole = { warn: (...args) => seen.push(args) };
const filtered = filterKnownInfrastructureWarnings(baseConsole);
filtered.warn(ISSUE_WARNING);
filtered.warn("a genuine warning");
assert.deepEqual(seen, [["a genuine warning"]]);
});
test("isNextIntlExtractorDynamicImportWarning matches only the extractor resource", () => {
const resource = "node_modules/next-intl/dist/esm/production/extractor/format/index.js";
assert.equal(
isNextIntlExtractorDynamicImportWarning({
module: { resource },
message: "the request of a dependency is an expression",
}),
true
);
assert.equal(
isNextIntlExtractorDynamicImportWarning({
module: { resource: "node_modules/other/index.js" },
message: "the request of a dependency is an expression",
}),
false
);
});