@djangocfg/nextjs 2.1.483 → 2.1.484

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/nextjs",
-  "version": "2.1.483",
+  "version": "2.1.484",
   "description": "Next.js server utilities: sitemap, health, OG images, contact forms, navigation, config",
   "keywords": [
     "nextjs",
@@ -144,9 +144,9 @@
     "ai-docs": "tsx src/ai/cli.ts"
   },
   "peerDependencies": {
-    "@djangocfg/devtools": "^2.1.483",
-    "@djangocfg/i18n": "^2.1.483",
-    "@djangocfg/ui-core": "^2.1.483",
+    "@djangocfg/devtools": "^2.1.484",
+    "@djangocfg/i18n": "^2.1.484",
+    "@djangocfg/ui-core": "^2.1.484",
     "next": "^16.2.2"
   },
   "peerDependenciesMeta": {
@@ -168,11 +168,11 @@
     "serwist": "^9.5.11"
   },
   "devDependencies": {
-    "@djangocfg/devtools": "^2.1.483",
-    "@djangocfg/i18n": "^2.1.483",
-    "@djangocfg/layouts": "^2.1.483",
-    "@djangocfg/typescript-config": "^2.1.483",
-    "@djangocfg/ui-core": "^2.1.483",
+    "@djangocfg/devtools": "^2.1.484",
+    "@djangocfg/i18n": "^2.1.484",
+    "@djangocfg/layouts": "^2.1.484",
+    "@djangocfg/typescript-config": "^2.1.484",
+    "@djangocfg/ui-core": "^2.1.484",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",
     "@types/react-dom": "19.2.3",

package/src/config/createNextConfig.ts

@@ -31,7 +31,14 @@ import { CSP_BASELINE_VENDORS, type CspVendor, resolveCspVendors } from './csp';
 import { addCompressionPlugins } from './plugins/compression';
 import { DevStartupPlugin } from './plugins/devStartup';
 import { deepMerge } from './utils/deepMerge';
-import { getApiUrl, getBasePath, getSiteUrl, isDev, isStaticBuild } from './utils/env';
+import {
+  getApiUrl,
+  getBasePath,
+  getSiteUrl,
+  isDev,
+  isStaticBuild,
+  warnIfApiUrlMissing,
+} from './utils/env';
 
 // ─────────────────────────────────────────────────────────────────────────
 // Configuration Options
@@ -204,6 +211,7 @@ export function createBaseNextConfig(
 ): NextConfig {
 
   const basePath = getBasePath(options.isDefaultCfgAdmin);
+  warnIfApiUrlMissing();
   const apiUrl = getApiUrl();
   const siteUrl = getSiteUrl();
 

package/src/config/utils/env.ts

@@ -2,6 +2,8 @@
  * Environment Variable Utilities
  */
 
+import consola from 'consola';
+
 export const isStaticBuild = process.env.NEXT_PUBLIC_STATIC_BUILD === 'true';
 export const isDev = process.env.NODE_ENV === 'development';
 export const isProduction = !isDev;
@@ -12,10 +14,67 @@ export function getBasePath(isDefaultCfgAdmin?: boolean): string {
   return isDefaultCfgAdmin ? '/cfg/admin' : '/cfg/nextjs-admin';
 }
 
+/**
+ * Resolve the API origin that gets inlined into the client bundle.
+ *
+ * `NEXT_PUBLIC_*` is substituted at BUILD time, so a value supplied only at
+ * container runtime (a compose `environment:` entry, a `docker run -e`) arrives
+ * far too late — the bundle already shipped with whatever was present during
+ * `next build`.
+ *
+ * An empty result means "no API origin is configured". Callers MUST treat that
+ * as *do not send the request* rather than falling back to a relative path: the
+ * browser resolves a relative URL against the CURRENT page, so on an
+ * i18n-prefixed route `/cfg/accounts/profile` silently becomes
+ * `https://site.com/<locale>/cfg/accounts/profile` — a 404 that reproduces only
+ * in production. Use {@link hasApiUrl} to gate those call sites.
+ *
+ * The one case where empty legitimately means "relative": a static build served
+ * from the same origin as Django.
+ */
 export function getApiUrl(): string {
   return isStaticBuild ? '' : (process.env.NEXT_PUBLIC_API_URL || '');
 }
 
+/**
+ * Whether a usable API origin is configured for this build.
+ *
+ * Gate every network call that targets Django on this. An app with no backend
+ * (a pure marketing site) then needs no configuration at all — its optional
+ * transports simply stay dormant instead of firing requests at the page's own
+ * origin.
+ *
+ * A static build is same-origin by design, so relative paths ARE the intent
+ * there and this reports true despite the empty string.
+ */
+export function hasApiUrl(): boolean {
+  return isStaticBuild || Boolean(process.env.NEXT_PUBLIC_API_URL);
+}
+
+/**
+ * Warn once, at build time, when no API origin is configured.
+ *
+ * Not an error: an app with no backend is a legitimate configuration. But the
+ * same empty value also appears when a build *should* have had an API URL and
+ * lost it — a `.dockerignore` rule stripping `.env.production`, or a value
+ * supplied only through a runtime `environment:` entry. Both produce a bundle
+ * whose API-backed features are silently inert, so say so while the build log
+ * is still being read.
+ */
+export function warnIfApiUrlMissing(): void {
+  if (hasApiUrl() || isDev) return;
+
+  consola.warn(
+    'NEXT_PUBLIC_API_URL is not set — API-backed features are disabled in this build.\n' +
+      'Requests that need it are skipped rather than sent to a relative path.\n' +
+      'If this app DOES have a backend, the value must be present at BUILD time:\n' +
+      '  • commit it to the app\'s `.env.production`, and check no `.dockerignore`\n' +
+      '    rule (e.g. `**/.env*`) strips that file from the build context;\n' +
+      '  • or pass it as a Dockerfile ARG/ENV before the build step.\n' +
+      'A compose `environment:` entry is too late — it only exists at runtime.',
+  );
+}
+
 export function getSiteUrl(): string {
   return isStaticBuild ? '' : (process.env.NEXT_PUBLIC_SITE_URL || '');
 }

package/src/health/route.ts

@@ -3,7 +3,7 @@
  *
  * Usage:
  * ```tsx
- * // app/api/health/route.ts
+ * // app/healthz/route.ts
  * import { createHealthHandler } from '@djangocfg/nextjs/health';
  *
  * export const GET = createHealthHandler({
@@ -63,4 +63,3 @@ export function createHealthHandler(config: HealthConfig = {}) {
     return NextResponse.json(response, { status: statusCode });
   };
 }
-