HiveGrid-Wireframes/hivegrid-cloud/docs/ops/production-build-warnings.md

Production Build Warnings

pnpm run build is allowed to finish with known Vite/Rollup warning classes. Treat this file as the operator reference before opening a deploy blocker for build output that still exits with status 0.

Last observed: 2026-05-28 via pnpm run build.

Known Warning Classes

Warning	Current interpretation	Escalate when
Source maps are enabled in production	Expected only when TOOLCTRL_BUILD_SOURCEMAPS=1 is set for the Sentry release lane. Default web and bundle-budget builds should not emit this warning. Do not put secrets in source code; environment values must stay in @toolctrl/config and server-only boundaries.	Source maps expose hard-coded credentials, a default build emits maps unexpectedly, or a deploy target starts publishing server-only artifacts outside the intended build output.
Generated an empty chunk	Expected for React Router resource/API routes that have no client runtime. Empty route chunks are checked by pnpm run verify:bundle-size; unexpected names should be added only with an explicit rationale.	A new empty chunk is not covered by the bundle-size gate or appears for a user-facing UI route that should ship client code.
AWS/Smithy circular chunk warnings	Mitigated in the web Vite build by grouping @aws-sdk/* and @smithy/* into vendor-aws-sdk. The 2026-05-28 build emits build/server/assets/vendor-aws-sdk-*.js and no longer prints the circular Smithy/AWS reexport warning.	The circular warning returns, runtime AWS/S3 paths fail after build, the warning points to first-party modules, or the SDK versions/change set introduce a new broken execution order.
dynamically imported ... but also statically imported	Known Vite server-build warning where a lazy import cannot move a shared server module into a separate chunk because another route imports it statically. Current examples include DB, config, admin SSO audit, subscription entitlements, admin fallback helpers, and password reset helpers.	The warning starts involving a large client-only dependency, moves code into the default client shell, or a new performance slice claims a lazy split that this warning proves ineffective.

Recheck Commands

pnpm run build
pnpm run verify:bundle-size
pnpm run verify:docs-links

To inspect only warning lines from a local build log:

pnpm run build > /tmp/toolctrl-build.log 2>&1
rg -n 'Source maps are enabled|Generated an empty chunk|@smithy|@aws-sdk|vendor-aws-sdk|dynamically imported|dynamic import will not move' /tmp/toolctrl-build.log

Triage Notes

• Do not change runtime build configuration just to silence one of the known warnings above.
• Prefer one warning class per follow-up PR.
• Keep unknown warning classes visible. If a warning is suppressed or accepted, add or update a regression gate next to the owner.
• For bundle concerns, use pnpm run verify:bundle-size as the first hard signal. The raw pnpm run build chunk list is diagnostic, not the budget gate.