@usequark/quark-create-app 1.27.0 → 1.27.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-create-app",
-  "version": "1.27.0",
+  "version": "1.27.2",
   "description": "CLI to scaffold new Quark projects with Next.js, Prisma, BullMQ, and Railway deployment",
   "keywords": [
     "quark",

package/templates/base-project/apps/web/.env.example

@@ -61,15 +61,21 @@ NEXTAUTH_SECRET=replace_with_a_long_random_secret
 # Staging and preview environments should leave this unset so they are not indexed.
 # ALLOW_INDEXING=true
 
-# --- Optional: Umami Analytics ---
+# --- Optional: Umami Analytics (first-party proxy) ---
 # Leave all three unset to disable analytics cleanly.
-# Set URL + website ID to load Umami script.js in the root layout head.
+# Set URL + website ID to load the tracker from the first-party proxy
+# (GET /s/script.js) in the root layout head. Beacons and replay batches
+# POST same-origin to /s/api/send, /s/api/collect, and /s/api/record, so
+# blocklists never see the upstream host and CSP stays 'self'-only.
 # Replay stays off unless NEXT_PUBLIC_UMAMI_REPLAY_ENABLED=true.
 # Umami Links and Pixels are dashboard-generated URLs, so the scaffold does not add extra env vars for them.
 # Use tracked links in campaigns/emails and pixel URLs only in HTML emails or external pages.
 # NEXT_PUBLIC_UMAMI_URL=https://stats.example.com
 # NEXT_PUBLIC_UMAMI_WEBSITE_ID=00000000-0000-0000-0000-000000000000
 # NEXT_PUBLIC_UMAMI_REPLAY_ENABLED=false
+# Optional server-only override for the proxy destination (takes precedence
+# over NEXT_PUBLIC_UMAMI_URL; never exposed to the browser):
+# UMAMI_UPSTREAM_URL=https://stats.example.com
 
 # --- Web App Configuration ---
 PORT=3005

package/templates/base-project/apps/web/next.config.js

@@ -1,5 +1,4 @@
 import { hostname, networkInterfaces } from "node:os";
-
 import { buildContentSecurityPolicy } from "./src/lib/analytics/umami-csp.js";
 
 function getLocalNetworkHosts() {
@@ -127,10 +126,16 @@ const nextConfig = {
 		},
 	},
 
-	// API route configuration
-	async rewrites() {
-		return [];
-	},
+	// First-party Umami proxy: GET /s/script.js and POST
+	// /s/api/send|collect|record are served by Route Handlers under
+	// src/app/s/*, not rewrites(). A handler is required in both cases:
+	// rewrites proxy incoming request headers unchanged, which would forward
+	// app session cookies to the analytics host (script) and cannot strip or
+	// append the ingest headers (cookie strip, X-Forwarded-For for geo,
+	// x-umami-cache for replay).
+	// NOTE: the tracker destination is resolved at request time from
+	// UMAMI_UPSTREAM_URL (preferred) or NEXT_PUBLIC_UMAMI_URL, so unlike
+	// rewrites() it needs no rebuild to take effect — only a restart.
 
 	// Compiler options for production optimization
 	compiler: {

package/templates/base-project/apps/web/src/app/_components/UmamiReplayRecorder.js

@@ -3,7 +3,7 @@
 import { usePathname } from "next/navigation";
 import { useEffect, useEffectEvent, useRef } from "react";
 import { isUmamiStaff } from "../../lib/analytics/umami.js";
-import { getUmamiConfig } from "../../lib/analytics/umami-config.js";
+import { getUmamiClientConfig } from "../../lib/analytics/umami-config.js";
 import {
 	buildReplayEndpoint,
 	createReplayBuffer,
@@ -65,7 +65,7 @@ export default function UmamiReplayRecorder() {
 	);
 
 	useEffect(() => {
-		const umamiConfig = getUmamiConfig();
+		const umamiConfig = getUmamiClientConfig();
 		if (!umamiConfig.replayEnabled || !shouldSampleReplay()) {
 			return undefined;
 		}
@@ -92,7 +92,7 @@ export default function UmamiReplayRecorder() {
 			if (cancelled) return;
 
 			cacheRef.current = cache;
-			endpointRef.current = buildReplayEndpoint(umamiConfig.url);
+			endpointRef.current = umamiConfig.proxyRecordUrl || buildReplayEndpoint();
 			websiteIdRef.current = umamiConfig.websiteId;
 			startedAtRef.current = Date.now();
 

package/templates/base-project/apps/web/src/app/_components/UmamiWebVitals.js

@@ -2,7 +2,7 @@
 
 import { useEffect } from "react";
 import { isUmamiStaff } from "../../lib/analytics/umami.js";
-import { getUmamiConfig } from "../../lib/analytics/umami-config.js";
+import { getUmamiClientConfig } from "../../lib/analytics/umami-config.js";
 import { observeWebVitals } from "../../lib/analytics/umami-web-vitals.js";
 
 /**
@@ -22,7 +22,7 @@ import { observeWebVitals } from "../../lib/analytics/umami-web-vitals.js";
  */
 export default function UmamiWebVitals() {
 	useEffect(() => {
-		const config = getUmamiConfig();
+		const config = getUmamiClientConfig();
 		if (!config.enabled) return;
 
 		// Skip web vitals dispatch for any staff user (identified by the

package/templates/base-project/apps/web/src/app/layout.js

@@ -21,6 +21,9 @@ const themeScript = `(function(){try{var t=localStorage.getItem("${THEME_STORAGE
 const umamiBeforeSendScript = buildUmamiBeforeSendScript();
 
 export default function RootLayout({ children }) {
+	// Server config deliberately: the gate stays upstream-aware so a missing
+	// upstream never emits a 404 script tag, while only websiteId + proxy
+	// paths reach the HTML. Browser code uses getUmamiClientConfig instead.
 	const umamiConfig = getUmamiConfig();
 
 	return (
@@ -31,21 +34,14 @@ export default function RootLayout({ children }) {
 				{/* biome-ignore lint/security/noDangerouslySetInnerHtml: static inline before-send handler */}
 				<script dangerouslySetInnerHTML={{ __html: umamiBeforeSendScript }} />
 				{umamiConfig.enabled ? (
-					<>
-						<link
-							crossOrigin="anonymous"
-							href={umamiConfig.origin}
-							rel="preconnect"
-						/>
-						<link href={umamiConfig.dnsPrefetchHref} rel="dns-prefetch" />
-						<script
-							defer
-							data-performance="true"
-							data-website-id={umamiConfig.websiteId}
-							src={umamiConfig.scriptUrl}
-							data-before-send="__umamiBeforeSend"
-						/>
-					</>
+					<script
+						defer
+						data-performance="true"
+						data-website-id={umamiConfig.websiteId}
+						data-host-url={umamiConfig.proxyHostUrl}
+						src={umamiConfig.proxyScriptUrl}
+						data-before-send="__umamiBeforeSend"
+					/>
 				) : null}
 			</head>
 			<body>

package/templates/base-project/apps/web/src/app/s/api/[endpoint]/route.js

@@ -0,0 +1,286 @@
+/**
+ * Umami First-Party Ingest Proxy
+ *
+ * POST /s/api/send|collect|record → upstream Umami /api/*.
+ *
+ * Why this exists: the tracker, web-vitals beacons, and replay batches would
+ * otherwise POST directly to the upstream analytics host, which blocklists
+ * (EasyPrivacy / uBlock / Brave) match as third-party. Same-origin ingest
+ * survives those lists while keeping geo, browser stats, and CSP tightness.
+ *
+ * Security shape (load-bearing, do not loosen without review):
+ * - Endpoint whitelist — never interpolate the raw route param into the
+ *   upstream URL, or this becomes an open proxy to the analytics host.
+ * - POST-only — every other method answers 405.
+ * - Header hygiene — `cookie`, `authorization`, and `x-metrics-token` are
+ *   never forwarded; only the analytics-relevant headers cross the boundary.
+ * - `X-Forwarded-For` / `X-Real-IP` are preserved so Umami geolocates the
+ *   visitor, not the Railway egress IP — unless TRUST_PROXY_HEADERS=false,
+ *   in which case "unknown" crosses instead (same rule as proxy.js).
+ * - 1 MB body cap enforced while streaming (a missing/lying Content-Length
+ *   cannot force full buffering) + 5s upstream timeout bound abuse cost.
+ * - `Cache-Control: no-store` on every response; upstream `Set-Cookie` is
+ *   stripped and never reaches the browser.
+ * - Fail-open 202 on upstream 5xx/timeout so analytics never fails the
+ *   product flow — and never retry-storms a struggling upstream. The body
+ *   is endpoint-aware: `record` answers `{ ok: false }` so replay batches
+ *   are retained and retried, while `send`/`collect` answer `{ ok: true }`
+ *   because those beacons have no retry path.
+ *
+ * Deliberately NOT rate-limited by proxy.js: that limiter keys on `/api/*`
+ * paths and analytics beacons must never 429. The body cap, content-type
+ * gate, and timeout are the abuse bounds here.
+ */
+
+import { createLogger } from "@usequark/quark-core/core";
+import { NextResponse } from "next/server";
+import { getUmamiUpstreamBase } from "@/lib/analytics/umami-config.js";
+import { shouldTrustProxyHeaders } from "@/lib/proxy-auth.js";
+
+const logger = createLogger("umami-proxy");
+
+const ALLOWED_ENDPOINTS = new Set(["send", "collect", "record"]);
+const MAX_BODY_BYTES = 1_000_000;
+const UPSTREAM_TIMEOUT_MS = 5000;
+
+function noStoreHeaders(extra = {}) {
+	return { "Cache-Control": "no-store", ...extra };
+}
+
+function methodNotAllowed() {
+	return NextResponse.json(
+		{ error: "Method not allowed" },
+		{ status: 405, headers: noStoreHeaders() },
+	);
+}
+
+// Fail-open without losing replay data. Tracker (`send`) and web-vitals
+// (`collect`) beacons are fire-and-forget with no retry path, so they keep
+// `{ ok: true }` to avoid any client-side retry storm against a struggling
+// upstream. Replay (`record`) has a restore/retry path keyed on
+// `body.ok === false` in postReplayBatch: answering `ok: true` there would
+// discard the batch, so record answers `ok: false` and the events are
+// retained and retried.
+function failOpenResponse(endpoint) {
+	const body =
+		endpoint === "record"
+			? { ok: false, proxied: false, reason: "upstream_unavailable" }
+			: { ok: true, proxied: false };
+	return NextResponse.json(body, {
+		status: 202,
+		headers: noStoreHeaders(),
+	});
+}
+
+function resolveClientIp(request) {
+	const forwardedFor = request.headers.get("x-forwarded-for");
+	if (forwardedFor) {
+		const client = forwardedFor
+			.split(",")
+			.map((value) => value.trim())
+			.filter(Boolean)[0];
+		if (client) return client;
+	}
+
+	return request.headers.get("x-real-ip")?.trim() || "unknown";
+}
+
+// Streams the request body under a running byte budget. The Content-Length
+// pre-check above is only an early exit: a missing or lying header must not
+// force full buffering of an unbounded body before the 413 fires.
+async function readCappedBody(request) {
+	if (!request.body) return { status: "empty" };
+
+	const reader = request.body.getReader();
+	const chunks = [];
+	let total = 0;
+
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			total += value.byteLength;
+			if (total > MAX_BODY_BYTES) {
+				await reader.cancel().catch(() => {});
+				return { status: "too-large" };
+			}
+			chunks.push(value);
+		}
+	} catch {
+		return { status: "unreadable" };
+	}
+
+	if (!total) return { status: "empty" };
+
+	const bytes = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+
+	return { status: "ok", bytes };
+}
+
+export async function POST(request, { params } = {}) {
+	const resolvedParams = params ? await params : {};
+	const endpoint = resolvedParams?.endpoint;
+
+	if (!ALLOWED_ENDPOINTS.has(endpoint)) {
+		return NextResponse.json(
+			{ error: "Not found" },
+			{ status: 404, headers: noStoreHeaders() },
+		);
+	}
+
+	const contentType =
+		request.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() ??
+		"";
+	if (contentType !== "application/json") {
+		return NextResponse.json(
+			{ error: "Unsupported media type" },
+			{ status: 415, headers: noStoreHeaders() },
+		);
+	}
+
+	const contentLength = request.headers.get("content-length");
+	if (contentLength && Number(contentLength) > MAX_BODY_BYTES) {
+		return NextResponse.json(
+			{ error: "Payload too large" },
+			{ status: 413, headers: noStoreHeaders() },
+		);
+	}
+
+	let body;
+	try {
+		body = await readCappedBody(request);
+	} catch {
+		return NextResponse.json(
+			{ error: "Unreadable request body" },
+			{ status: 400, headers: noStoreHeaders() },
+		);
+	}
+
+	if (body.status === "too-large") {
+		return NextResponse.json(
+			{ error: "Payload too large" },
+			{ status: 413, headers: noStoreHeaders() },
+		);
+	}
+
+	if (body.status !== "ok") {
+		return NextResponse.json(
+			{
+				error:
+					body.status === "empty" ? "Empty body" : "Unreadable request body",
+			},
+			{ status: 400, headers: noStoreHeaders() },
+		);
+	}
+
+	const upstreamBase = getUmamiUpstreamBase(process.env);
+	if (!upstreamBase) {
+		return failOpenResponse(endpoint);
+	}
+
+	// Honor the same proxy-header trust setting as proxy.js: with
+	// TRUST_PROXY_HEADERS=false the app is directly reachable, the headers
+	// are attacker-controlled, and forwarding them would poison Umami geo.
+	// "unknown" (never client bytes) crosses the boundary instead.
+	const trustProxyHeaders = shouldTrustProxyHeaders();
+	const incomingForwardedFor = trustProxyHeaders
+		? request.headers.get("x-forwarded-for")
+		: null;
+	const clientIp = trustProxyHeaders ? resolveClientIp(request) : "unknown";
+	const forwardedFor = incomingForwardedFor?.trim()
+		? incomingForwardedFor
+		: clientIp;
+
+	const forwardHeaders = {
+		"Content-Type": "application/json",
+		"X-Forwarded-For": forwardedFor,
+		"X-Real-IP": trustProxyHeaders
+			? request.headers.get("x-real-ip")?.trim() || clientIp
+			: clientIp,
+	};
+
+	const userAgent = request.headers.get("user-agent");
+	if (userAgent) forwardHeaders["User-Agent"] = userAgent;
+
+	const acceptLanguage = request.headers.get("accept-language");
+	if (acceptLanguage) forwardHeaders["Accept-Language"] = acceptLanguage;
+
+	const umamiCache = request.headers.get("x-umami-cache");
+	if (umamiCache) forwardHeaders["x-umami-cache"] = umamiCache;
+
+	let upstreamResponse;
+	try {
+		upstreamResponse = await fetch(`${upstreamBase}/api/${endpoint}`, {
+			method: "POST",
+			body: body.bytes,
+			headers: forwardHeaders,
+			signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+		});
+	} catch (error) {
+		logger.warn("Umami ingest proxy upstream unreachable", {
+			endpoint,
+			message: error?.message ?? String(error),
+		});
+		return failOpenResponse(endpoint);
+	}
+
+	if (upstreamResponse.status >= 500) {
+		logger.warn("Umami ingest proxy upstream error", {
+			endpoint,
+			status: upstreamResponse.status,
+		});
+		return failOpenResponse(endpoint);
+	}
+
+	let responseBody;
+	try {
+		responseBody = await upstreamResponse.arrayBuffer();
+	} catch (error) {
+		logger.warn("Umami ingest proxy upstream body unreadable", {
+			endpoint,
+			message: error?.message ?? String(error),
+		});
+		return failOpenResponse(endpoint);
+	}
+
+	const responseHeaders = noStoreHeaders();
+	const upstreamContentType = upstreamResponse.headers.get("content-type");
+	if (upstreamContentType) {
+		responseHeaders["Content-Type"] = upstreamContentType;
+	}
+
+	// Never pass upstream Set-Cookie through to the browser.
+	return new NextResponse(responseBody, {
+		status: upstreamResponse.status,
+		headers: responseHeaders,
+	});
+}
+
+export function GET() {
+	return methodNotAllowed();
+}
+
+export function PUT() {
+	return methodNotAllowed();
+}
+
+export function PATCH() {
+	return methodNotAllowed();
+}
+
+export function DELETE() {
+	return methodNotAllowed();
+}
+
+export function HEAD() {
+	return methodNotAllowed();
+}
+
+export function OPTIONS() {
+	return methodNotAllowed();
+}

package/templates/base-project/apps/web/src/app/s/script.js/route.js

@@ -0,0 +1,128 @@
+/**
+ * Umami First-Party Tracker Script
+ *
+ * GET /s/script.js → upstream Umami /script.js.
+ *
+ * Why a handler and not a `rewrites()` entry: a browser requesting a
+ * same-origin script URL sends this app's cookies with it, and Next.js
+ * external rewrites proxy incoming request headers unchanged — so a rewrite
+ * would forward session cookies to the analytics host. (The previous
+ * cross-origin `<script src>` never sent same-origin credentials.) This
+ * handler forwards NO client headers at all: the upstream sees an anonymous
+ * server-to-server fetch, and its `Set-Cookie` is stripped before the
+ * response reaches the browser.
+ *
+ * Caching: the tracker is static and versioned by the upstream, so the
+ * response is publicly cacheable (browser + CDN). The upstream fetch is
+ * revalidated hourly so most script loads never touch the analytics host.
+ */
+
+import { createLogger } from "@usequark/quark-core/core";
+import { NextResponse } from "next/server";
+import { getUmamiUpstreamBase } from "@/lib/analytics/umami-config.js";
+
+const logger = createLogger("umami-proxy");
+
+export const dynamic = "force-dynamic";
+
+const UPSTREAM_TIMEOUT_MS = 5000;
+const SCRIPT_CACHE_CONTROL =
+	"public, max-age=3600, stale-while-revalidate=86400";
+
+function noStoreHeaders(extra = {}) {
+	return { "Cache-Control": "no-store", ...extra };
+}
+
+function methodNotAllowed() {
+	return NextResponse.json(
+		{ error: "Method not allowed" },
+		{ status: 405, headers: noStoreHeaders() },
+	);
+}
+
+export async function GET() {
+	const upstreamBase = getUmamiUpstreamBase(process.env);
+	if (!upstreamBase) {
+		return NextResponse.json(
+			{ error: "Not found" },
+			{ status: 404, headers: noStoreHeaders() },
+		);
+	}
+
+	let upstreamResponse;
+	try {
+		// Deliberately no client headers: no Cookie, no Authorization, no
+		// X-Forwarded-For. The tracker script is identical for every visitor.
+		upstreamResponse = await fetch(`${upstreamBase}/script.js`, {
+			signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+			next: { revalidate: 3600 },
+		});
+	} catch (error) {
+		logger.warn("Umami script proxy upstream unreachable", {
+			message: error?.message ?? String(error),
+		});
+		return NextResponse.json(
+			{ error: "Bad gateway" },
+			{ status: 502, headers: noStoreHeaders() },
+		);
+	}
+
+	if (!upstreamResponse.ok) {
+		logger.warn("Umami script proxy upstream error", {
+			status: upstreamResponse.status,
+		});
+		return NextResponse.json(
+			{ error: "Bad gateway" },
+			{ status: 502, headers: noStoreHeaders() },
+		);
+	}
+
+	let body;
+	try {
+		body = await upstreamResponse.arrayBuffer();
+	} catch (error) {
+		logger.warn("Umami script proxy upstream body unreadable", {
+			message: error?.message ?? String(error),
+		});
+		return NextResponse.json(
+			{ error: "Bad gateway" },
+			{ status: 502, headers: noStoreHeaders() },
+		);
+	}
+
+	// Fresh headers: upstream Content-Type (or a JS default), public caching,
+	// and never an upstream Set-Cookie.
+	return new NextResponse(body, {
+		status: 200,
+		headers: {
+			"Content-Type":
+				upstreamResponse.headers.get("content-type") ??
+				"application/javascript",
+			"Cache-Control": SCRIPT_CACHE_CONTROL,
+		},
+	});
+}
+
+export function POST() {
+	return methodNotAllowed();
+}
+
+export function PUT() {
+	return methodNotAllowed();
+}
+
+export function PATCH() {
+	return methodNotAllowed();
+}
+
+export function DELETE() {
+	return methodNotAllowed();
+}
+
+export function HEAD() {
+	return methodNotAllowed();
+}
+
+export function OPTIONS() {
+	return methodNotAllowed();
+}

package/templates/base-project/apps/web/src/lib/analytics/umami-before-send.js

@@ -24,6 +24,11 @@ export function shouldBlockUmamiPayload({ url, roleCookie } = {}) {
  * @returns {string}
  */
 export function buildUmamiBeforeSendScript() {
-	// shouldBlockUmamiPayload.toString() already includes the "function name(){...}" form.
-	return `window.__umamiBeforeSend=function(t,p){var r=(document.cookie.match(/umami_user_role=([^;]+)/)||[])[1];if(shouldBlockUmamiPayload({url:p.url,roleCookie:r}))return false;return p};${shouldBlockUmamiPayload.toString()}`;
+	// Assigned via `var`: bundler minification may drop the function name from
+	// shouldBlockUmamiPayload.toString() (observed `function({...})` in the
+	// production bundle), and a bare anonymous `function(...){...}` statement
+	// is a SyntaxError that kills the whole inline tag — including
+	// window.__umamiBeforeSend. `var name=<any function form>;` is valid for
+	// named, anonymous, and arrow shapes alike.
+	return `window.__umamiBeforeSend=function(t,p){var r=(document.cookie.match(/umami_user_role=([^;]+)/)||[])[1];if(shouldBlockUmamiPayload({url:p.url,roleCookie:r}))return false;return p};var shouldBlockUmamiPayload=${shouldBlockUmamiPayload.toString()};`;
 }

package/templates/base-project/apps/web/src/lib/analytics/umami-config.js

@@ -48,6 +48,57 @@ export function getUmamiScriptUrl(value) {
 	return `${normalizedUrl}/script.js`;
 }
 
+// ─── First-party proxy ───────────────────────────────────────────────────────
+// The tracker, web-vitals beacons, and replay batches are served through
+// same-origin URLs so blocklists never see the upstream analytics host.
+// Base `/s` carries no `umami|analytics|track|stats|collect|send` token;
+// the `/api/*` suffix under it preserves the tracker's `data-host-url`
+// convention (`data-host-url="/s"` → POST `/s/api/send` with zero forks).
+export const UMAMI_PROXY_BASE = "/s";
+export const UMAMI_PROXY_SCRIPT_PATH = "/s/script.js";
+export const UMAMI_PROXY_HOST_URL = "/s";
+export const UMAMI_PROXY_SEND_PATH = "/s/api/send";
+export const UMAMI_PROXY_COLLECT_PATH = "/s/api/collect";
+export const UMAMI_PROXY_RECORD_PATH = "/s/api/record";
+
+// Server-side upstream preference: an operator that wants the analytics host
+// out of the client bundle entirely sets UMAMI_UPSTREAM_URL (or UMAMI_URL)
+// and the rewrite/handler destination follows it. NEXT_PUBLIC_UMAMI_URL
+// remains the default so existing deployments keep working with no new vars.
+export function getUmamiUpstreamBase(env = process.env) {
+	const candidates = [
+		env.UMAMI_UPSTREAM_URL,
+		env.UMAMI_URL,
+		env.NEXT_PUBLIC_UMAMI_URL,
+	];
+
+	for (const candidate of candidates) {
+		const normalized = normalizeUmamiUrl(candidate);
+		if (normalized) return normalized;
+	}
+
+	return "";
+}
+
+// Default env for browser-safe readers. Each NEXT_PUBLIC_* access MUST stay
+// a literal member expression: Next.js statically inlines those literals in
+// client bundles, where bare `process` does not exist — a whole-`process.env`
+// default throws ReferenceError in every browser, which previously killed
+// track(), web-vitals, and replay client-side. Do not refactor this into a
+// `process.env` passthrough. Exported for tests (the no-process fallback).
+export function readPublicEnv() {
+	try {
+		return {
+			NEXT_PUBLIC_UMAMI_URL: process.env.NEXT_PUBLIC_UMAMI_URL,
+			NEXT_PUBLIC_UMAMI_WEBSITE_ID: process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID,
+			NEXT_PUBLIC_UMAMI_REPLAY_ENABLED:
+				process.env.NEXT_PUBLIC_UMAMI_REPLAY_ENABLED,
+		};
+	} catch {
+		return {};
+	}
+}
+
 export function parseUmamiBooleanFlag(value) {
 	if (typeof value !== "string") return false;
 	return TRUE_VALUES.has(value.trim().toLowerCase());
@@ -59,7 +110,7 @@ export function isUmamiWebsiteId(value) {
 }
 
 export function getUmamiConfig(env = process.env) {
-	const url = normalizeUmamiUrl(env.NEXT_PUBLIC_UMAMI_URL);
+	const url = getUmamiUpstreamBase(env);
 	const rawWebsiteId =
 		typeof env.NEXT_PUBLIC_UMAMI_WEBSITE_ID === "string"
 			? env.NEXT_PUBLIC_UMAMI_WEBSITE_ID.trim()
@@ -76,20 +127,55 @@ export function getUmamiConfig(env = process.env) {
 		enabled,
 		replayEnabled:
 			enabled && parseUmamiBooleanFlag(env.NEXT_PUBLIC_UMAMI_REPLAY_ENABLED),
+		// First-party proxy URLs. Empty when analytics is disabled so
+		// callers can gate on `enabled` alone.
+		proxyBase: enabled ? UMAMI_PROXY_BASE : "",
+		proxyScriptUrl: enabled ? UMAMI_PROXY_SCRIPT_PATH : "",
+		proxyHostUrl: enabled ? UMAMI_PROXY_HOST_URL : "",
+		proxySendUrl: enabled ? UMAMI_PROXY_SEND_PATH : "",
+		proxyCollectUrl: enabled ? UMAMI_PROXY_COLLECT_PATH : "",
+		proxyRecordUrl: enabled ? UMAMI_PROXY_RECORD_PATH : "",
 	};
 }
 
-export function getUmamiCspOrigins(env = process.env) {
-	const config = getUmamiConfig(env);
-	if (!config.enabled || !config.origin) {
-		return {
-			scriptSrc: [],
-			connectSrc: [],
-		};
-	}
+// Client-safe config. Contains no upstream URL, origin, or script URL — only
+// the website ID, gates, and static first-party proxy paths. Browser code
+// must use this (never getUmamiConfig) so the analytics host cannot end up
+// in client bundles. `enabled` needs only a valid website ID because every
+// client surface is same-origin; the server layout keeps the upstream-aware
+// gate so a missing upstream never emits a 404 script tag.
+//
+// The default env is readPublicEnv(), not process.env: bare `process` does
+// not exist in browsers, so a process.env default throws on every no-arg
+// browser call.
+export function getUmamiClientConfig(env = readPublicEnv()) {
+	const rawWebsiteId =
+		typeof env.NEXT_PUBLIC_UMAMI_WEBSITE_ID === "string"
+			? env.NEXT_PUBLIC_UMAMI_WEBSITE_ID.trim()
+			: "";
+	const websiteId = isUmamiWebsiteId(rawWebsiteId) ? rawWebsiteId : "";
+	const enabled = Boolean(websiteId);
+
+	return {
+		websiteId,
+		enabled,
+		replayEnabled:
+			enabled && parseUmamiBooleanFlag(env.NEXT_PUBLIC_UMAMI_REPLAY_ENABLED),
+		proxyBase: enabled ? UMAMI_PROXY_BASE : "",
+		proxyScriptUrl: enabled ? UMAMI_PROXY_SCRIPT_PATH : "",
+		proxyHostUrl: enabled ? UMAMI_PROXY_HOST_URL : "",
+		proxySendUrl: enabled ? UMAMI_PROXY_SEND_PATH : "",
+		proxyCollectUrl: enabled ? UMAMI_PROXY_COLLECT_PATH : "",
+		proxyRecordUrl: enabled ? UMAMI_PROXY_RECORD_PATH : "",
+	};
+}
 
+export function getUmamiCspOrigins() {
+	// Proxy mode is the default path when analytics is enabled: tracker and
+	// beacons are same-origin, so CSP stays `'self'`-only and never names
+	// the upstream analytics host.
 	return {
-		scriptSrc: [config.origin],
-		connectSrc: [config.origin],
+		scriptSrc: [],
+		connectSrc: [],
 	};
 }

package/templates/base-project/apps/web/src/lib/analytics/umami-csp.js

@@ -2,8 +2,9 @@ import { getUmamiCspOrigins } from "./umami-config.js";
 
 export function buildContentSecurityPolicy(env = process.env) {
 	const isProduction = env.NODE_ENV === "production";
+	// Same-origin proxy: analytics needs no allowlist entries beyond 'self'.
 	const { connectSrc: umamiConnectSrc, scriptSrc: umamiScriptSrc } =
-		getUmamiCspOrigins(env);
+		getUmamiCspOrigins();
 
 	const scriptSrc = [
 		"script-src",

package/templates/base-project/apps/web/src/lib/analytics/umami-replay.js

@@ -1,5 +1,9 @@
 import { createLogger } from "@usequark/quark-core/logger";
-import { getUmamiConfig, normalizeUmamiUrl } from "./umami-config.js";
+import {
+	getUmamiClientConfig,
+	normalizeUmamiUrl,
+	readPublicEnv,
+} from "./umami-config.js";
 
 const log = createLogger("umami-replay");
 
@@ -18,6 +22,12 @@ export const UMAMI_REPLAY_DEFAULTS = Object.freeze({
 	blockSelector: "[data-umami-block]",
 });
 
+// Max serialized bytes per replay POST. Stays under the first-party proxy's
+// 1 MB cap with headroom for headers and JSON overhead, so a large DOM
+// snapshot cannot turn into a 413-restore-retry loop that grows the buffer
+// forever (each 413 restores the whole batch alongside new events).
+export const MAX_REPLAY_REQUEST_BYTES = 900_000;
+
 export function shouldSampleReplay(
 	randomValue = Math.random(),
 	sampleRate = UMAMI_REPLAY_DEFAULTS.sampleRate,
@@ -67,9 +77,17 @@ export function createReplayBuffer() {
 	};
 }
 
-export function buildReplayEndpoint(env = process.env) {
-	const url =
-		typeof env === "string" ? normalizeUmamiUrl(env) : getUmamiConfig(env).url;
+export function buildReplayEndpoint(env = readPublicEnv()) {
+	// First-party ingest is the default: replay batches POST same-origin so
+	// blocklists never see the upstream analytics host.
+	if (typeof env !== "string") {
+		const config = getUmamiClientConfig(env);
+		return config.enabled ? config.proxyRecordUrl : "";
+	}
+
+	// Explicit upstream URL string (legacy direct mode, e.g. server-side
+	// callers that already resolved the upstream base).
+	const url = normalizeUmamiUrl(env);
 
 	return url ? `${url}/api/record` : "";
 }
@@ -144,28 +162,22 @@ export function buildReplayBody({ websiteId, events, timestamp }) {
 	});
 }
 
-export async function postReplayBatch({
+function replayBodyBytes(body) {
+	if (typeof TextEncoder !== "undefined") {
+		return new TextEncoder().encode(body).length;
+	}
+	return body.length;
+}
+
+async function postReplayChunk({
 	endpoint,
-	cache,
+	sessionCache,
 	websiteId,
 	events,
-	timestamp = Math.floor(Date.now() / 1000),
-	useKeepalive = false,
-	getUmami = () => globalThis.window?.umami,
-	fetchImpl = globalThis.fetch?.bind(globalThis),
-} = {}) {
-	const sessionCache = resolveUmamiSessionCache({ cache, getUmami });
-
-	if (
-		!endpoint ||
-		!sessionCache ||
-		!websiteId ||
-		!events?.length ||
-		!fetchImpl
-	) {
-		return false;
-	}
-
+	timestamp,
+	useKeepalive,
+	fetchImpl,
+}) {
 	const body = buildReplayBody({ websiteId, events, timestamp });
 	const keepalive = useKeepalive && body.length < 60000;
 
@@ -181,11 +193,24 @@ export async function postReplayBatch({
 			credentials: "omit",
 		});
 
-		if (!response?.ok) return false;
+		if (!response) return "retry";
+
+		// A 413 means the bytes exceed the proxy's cap. Multi-event chunks
+		// split and retry halves; a single event that 413s can never be
+		// delivered, so drop it with a warning instead of restoring it into
+		// an infinite retry loop.
+		if (response.status === 413) {
+			if (events.length > 1) return "split";
+			log.warn("dropping replay event rejected as oversized (413)");
+			return "drop";
+		}
+
+		if (!response.ok) return "retry";
 
 		// Umami answers 200 with { ok: false, reason } when replay is disabled
-		// server-side. Treat that as a failure so events are restored instead
-		// of silently dropped.
+		// server-side — and the first-party proxy answers 202 with
+		// { ok: false } when the upstream is unavailable. Treat both as a
+		// failure so events are restored instead of silently dropped.
 		const responseBody =
 			typeof response.json === "function"
 				? await response.json().catch(() => null)
@@ -194,11 +219,130 @@ export async function postReplayBatch({
 			log.warn(
 				`batch rejected by server: ${responseBody.reason ?? "unknown reason"}`,
 			);
-			return false;
+			return "retry";
 		}
 
-		return true;
+		return "sent";
 	} catch {
+		return "retry";
+	}
+}
+
+async function postReplayChunks({
+	endpoint,
+	sessionCache,
+	websiteId,
+	events,
+	timestamp,
+	useKeepalive,
+	fetchImpl,
+}) {
+	if (!events.length) return true;
+
+	const probe = buildReplayBody({ websiteId, events, timestamp });
+	if (replayBodyBytes(probe) <= MAX_REPLAY_REQUEST_BYTES) {
+		const outcome = await postReplayChunk({
+			endpoint,
+			sessionCache,
+			websiteId,
+			events,
+			timestamp,
+			useKeepalive,
+			fetchImpl,
+		});
+		if (outcome === "sent" || outcome === "drop") return true;
+		if (outcome === "split") {
+			const mid = Math.max(1, Math.ceil(events.length / 2));
+			return (
+				(await postReplayChunks({
+					endpoint,
+					sessionCache,
+					websiteId,
+					events: events.slice(0, mid),
+					timestamp,
+					useKeepalive,
+					fetchImpl,
+				})) &&
+				(await postReplayChunks({
+					endpoint,
+					sessionCache,
+					websiteId,
+					events: events.slice(mid),
+					timestamp,
+					useKeepalive,
+					fetchImpl,
+				}))
+			);
+		}
+		return false;
+	}
+
+	// Oversized batch: split before sending. A single event that alone
+	// exceeds the cap can never be delivered, so drop it with a warning
+	// instead of restoring it into an infinite 413 loop.
+	if (events.length === 1) {
+		log.warn(
+			`dropping oversized replay event (${replayBodyBytes(probe)} bytes exceeds cap)`,
+		);
+		return true;
+	}
+
+	const mid = Math.max(1, Math.ceil(events.length / 2));
+	// Sequential halves: on partial failure the caller restores the whole
+	// batch, so an already-sent half may duplicate on retry. Accepted as
+	// rare best-effort duplication (upstream outage mid-oversized-batch);
+	// the alternative is silent loss.
+	return (
+		(await postReplayChunks({
+			endpoint,
+			sessionCache,
+			websiteId,
+			events: events.slice(0, mid),
+			timestamp,
+			useKeepalive,
+			fetchImpl,
+		})) &&
+		(await postReplayChunks({
+			endpoint,
+			sessionCache,
+			websiteId,
+			events: events.slice(mid),
+			timestamp,
+			useKeepalive,
+			fetchImpl,
+		}))
+	);
+}
+
+export async function postReplayBatch({
+	endpoint,
+	cache,
+	websiteId,
+	events,
+	timestamp = Math.floor(Date.now() / 1000),
+	useKeepalive = false,
+	getUmami = () => globalThis.window?.umami,
+	fetchImpl = globalThis.fetch?.bind(globalThis),
+} = {}) {
+	const sessionCache = resolveUmamiSessionCache({ cache, getUmami });
+
+	if (
+		!endpoint ||
+		!sessionCache ||
+		!websiteId ||
+		!events?.length ||
+		!fetchImpl
+	) {
 		return false;
 	}
+
+	return postReplayChunks({
+		endpoint,
+		sessionCache,
+		websiteId,
+		events,
+		timestamp,
+		useKeepalive,
+		fetchImpl,
+	});
 }

package/templates/base-project/apps/web/src/lib/analytics/umami-web-vitals.js

@@ -18,11 +18,12 @@
  *  (e.g. a "use client" wrapper in the root layout).
  *
  * Environment:
- *  Controlled by NEXT_PUBLIC_UMAMI_URL and NEXT_PUBLIC_UMAMI_WEBSITE_ID.
+ *  Controlled by NEXT_PUBLIC_UMAMI_WEBSITE_ID (first-party proxy paths are
+ *  static, so no upstream URL is needed in the browser).
  *  When Umami analytics is not configured, the observer is a no-op.
  */
 
-import { getUmamiConfig } from "./umami-config.js";
+import { getUmamiClientConfig } from "./umami-config.js";
 
 // ── Initialization guard ──────────────────────────────────────
 
@@ -62,7 +63,7 @@ function sanitiseUrl(url) {
  * @param {{ name: string, value: number, rating: string, navigationType?: string }} metric
  */
 function dispatchMetric(metric) {
-	const config = getUmamiConfig();
+	const config = getUmamiClientConfig();
 	if (!config.enabled) return;
 
 	const payload = {
@@ -83,13 +84,17 @@ function dispatchMetric(metric) {
 
 	const body = JSON.stringify(payload);
 
+	// First-party ingest: same-origin POSTs survive blocklists that match the
+	// upstream analytics host as third-party.
+	const endpoint = config.proxyCollectUrl || `${config.url}/api/collect`;
+
 	// Use sendBeacon for reliability during page lifecycle transitions.
 	if (navigator.sendBeacon) {
 		const blob = new Blob([body], { type: "application/json" });
-		navigator.sendBeacon(`${config.url}/api/collect`, blob);
+		navigator.sendBeacon(endpoint, blob);
 	} else {
 		// Fallback to fetch with keepalive.
-		fetch(`${config.url}/api/collect`, {
+		fetch(endpoint, {
 			method: "POST",
 			body,
 			keepalive: true,

package/templates/base-project/apps/web/src/lib/analytics/umami.js

@@ -1,4 +1,4 @@
-import { getUmamiConfig } from "./umami-config.js";
+import { getUmamiClientConfig, readPublicEnv } from "./umami-config.js";
 
 /**
  * Read the Umami user role cookie set by the admin layout.
@@ -18,12 +18,15 @@ export function isUmamiStaff() {
 
 function getUmamiClient() {
 	if (typeof window === "undefined") return null;
-	if (!getUmamiConfig().enabled) return null;
+	// Client config deliberately: the server-only upstream URL is invisible
+	// here, so gating on getUmamiConfig would wrongly disable track() and
+	// identify() in server-only-upstream deployments.
+	if (!getUmamiClientConfig().enabled) return null;
 	return window.umami ?? null;
 }
 
-export function isUmamiEnabled(env = process.env) {
-	return getUmamiConfig(env).enabled;
+export function isUmamiEnabled(env = readPublicEnv()) {
+	return getUmamiClientConfig(env).enabled;
 }
 
 export function track(name, data) {

package/templates/base-project/apps/web/src/lib/auth.js

@@ -237,6 +237,13 @@ async function validateSessionToken(token) {
 
 export function getAuthOptions() {
 	return createAuthConfig({
+		// The adapter is load-bearing even though sessions are JWT (see
+		// `session.strategy` below): it persists the `Account` rows that link
+		// OAuth identities to users — the adapter reads and writes them, and
+		// `account.findByUserIdAndProvider` is covered in `packages/db`. Do
+		// not remove it. The `Session` model queries (`session.*` in
+		// `packages/db/src/queries.js`) are the opposite: app-owned helpers the
+		// JWT strategy never populates.
 		adapter: PrismaAdapter(prisma),
 		providers: providers,
 		logger: {

package/templates/base-project/apps/web/src/lib/proxy-auth.js

@@ -107,3 +107,36 @@ export function getRateLimitBucket(pathname, method = "GET") {
 export function isRateLimitExempt(pathname) {
 	return RATE_LIMIT_EXEMPT_ROUTES.has(pathname);
 }
+
+/**
+ * Boolean-like values that disable trusting proxy headers. Mirrors the
+ * "explicit false wins" convention used by `AUTH_ALLOW_SIGNUP` and
+ * `DB_INSTRUMENTATION`, so operators don't have to learn a new dialect.
+ */
+const PROXY_HEADERS_FALSY_VALUES = new Set(["false", "0", "no", "off"]);
+
+/**
+ * Whether the client-supplied proxy headers (`x-forwarded-for`, `x-real-ip`)
+ * may be trusted to identify the client.
+ *
+ * Default `true`: the shipped behaviour. The app assumes it sits behind a
+ * reverse proxy (Railway, Docker, nginx) that overwrites these headers on
+ * every request, so the left-most `x-forwarded-for` entry is treated as the
+ * client IP.
+ *
+ * Set `TRUST_PROXY_HEADERS=false` when the app is reachable directly (no
+ * proxy rewriting the header on the way in). Callers must then ignore both
+ * headers: proxy.js keys every client on the literal "unknown", and the
+ * Umami ingest proxy forwards "unknown" instead of attacker bytes. A header
+ * a client can set is not an identity.
+ *
+ * Read lazily (per request) rather than at module load: tests flip it and a
+ * value set after import still takes effect. Only explicit false-like values
+ * disable trusting; unset, empty, "true", or a typo all keep the default.
+ *
+ * @returns {boolean}
+ */
+export function shouldTrustProxyHeaders() {
+	const raw = process.env.TRUST_PROXY_HEADERS?.trim().toLowerCase();
+	return !(raw && PROXY_HEADERS_FALSY_VALUES.has(raw));
+}

package/templates/base-project/apps/web/src/proxy.js

@@ -14,7 +14,16 @@ import { createLogger, createRateLimiter } from "@usequark/quark-core/core";
 import { NextResponse } from "next/server";
 
 import { buildContentSecurityPolicy } from "./lib/analytics/umami-csp.js";
-import { getRateLimitBucket, isRateLimitExempt } from "./lib/proxy-auth";
+import {
+	getRateLimitBucket,
+	isRateLimitExempt,
+	shouldTrustProxyHeaders,
+} from "./lib/proxy-auth";
+
+// Re-exported: proxy.test.js and external callers resolve it from here.
+// The definition lives in lib/proxy-auth.js, shared with the Umami ingest
+// proxy so both honor TRUST_PROXY_HEADERS identically.
+export { shouldTrustProxyHeaders };
 
 const logger = createLogger("proxy");
 
@@ -93,43 +102,6 @@ export async function getRateLimiter() {
 	return rateLimiterPromise;
 }
 
-/**
- * Boolean-like values that disable trusting proxy headers. Mirrors the
- * "explicit false wins" convention used by `AUTH_ALLOW_SIGNUP` and
- * `DB_INSTRUMENTATION`, so operators don't have to learn a new dialect.
- */
-const PROXY_HEADERS_FALSY_VALUES = new Set(["false", "0", "no", "off"]);
-
-/**
- * Whether the client-supplied proxy headers (`x-forwarded-for`, `x-real-ip`)
- * may be trusted to identify the client.
- *
- * Default `true`: the shipped behaviour. The app assumes it sits behind a
- * reverse proxy (Railway, Docker, nginx) that overwrites these headers on
- * every request, so the left-most `x-forwarded-for` entry is treated as the
- * client IP.
- *
- * Set `TRUST_PROXY_HEADERS=false` when the app is reachable directly (no
- * proxy rewriting the header on the way in). The headers are then ignored and
- * every client keys on the literal "unknown". Because the bucket key is
- * `${ip}:${path}`, that means one bucket shared by every client of a route —
- * not one bucket across all routes. A header a client can set is not an
- * identity, so this is what stops a spoofed `x-forwarded-for` from buying a
- * fresh bucket per request. The trade-off is the reverse of the default: one
- * client can now exhaust the shared bucket for the route it floods, which is
- * why the default keeps trusting the headers.
- *
- * Read lazily (per request) rather than at module load: tests flip it and a
- * value set after import still takes effect. Only explicit false-like values
- * disable trusting; unset, empty, "true", or a typo all keep the default.
- *
- * @returns {boolean}
- */
-export function shouldTrustProxyHeaders() {
-	const raw = process.env.TRUST_PROXY_HEADERS?.trim().toLowerCase();
-	return !(raw && PROXY_HEADERS_FALSY_VALUES.has(raw));
-}
-
 /**
  * Resolve the client IP for rate-limit keying.
  *

package/templates/base-project/packages/db/src/queries.js

@@ -139,6 +139,12 @@ export const account = {
 };
 
 // Session queries (NextAuth)
+//
+// App-owned helpers, not Auth.js storage: the scaffold pins
+// `session.strategy: "jwt"` (see `apps/web/src/lib/auth.js`), under which
+// Auth.js neither reads nor writes session rows — revocation is enforced by
+// `validateSessionToken` re-reading the user row instead. Kept for apps that
+// need server-side session bookkeeping of their own.
 export const session = {
 	findByToken: (sessionToken) => {
 		return prisma.session.findUnique({

package/templates/config/src/validate-env.js

@@ -101,6 +101,10 @@ const ENV_DESCRIPTIONS = {
 	APP_URL: "Canonical application URL - derives NEXTAUTH_URL and CORS origins",
 	NEXT_PUBLIC_UMAMI_URL:
 		"Public Umami base URL for script.js and replay uploads",
+	UMAMI_UPSTREAM_URL:
+		"Server-only Umami base URL for the first-party proxy (rewrites + /s/api/* destination). Takes precedence over NEXT_PUBLIC_UMAMI_URL and keeps the analytics host out of the client bundle",
+	UMAMI_URL:
+		"Server-only Umami base URL alias for the first-party proxy (same as UMAMI_UPSTREAM_URL)",
 	NEXT_PUBLIC_UMAMI_WEBSITE_ID: "Public Umami website UUID",
 	NEXT_PUBLIC_UMAMI_REPLAY_ENABLED:
 		"Enable local rrweb session replay uploads to Umami",
@@ -246,6 +250,10 @@ function createEnvSchema(service) {
 			NEXT_PUBLIC_UMAMI_URL: absoluteHttpUrl(
 				"NEXT_PUBLIC_UMAMI_URL must be an absolute http(s) URL",
 			),
+			UMAMI_UPSTREAM_URL: absoluteHttpUrl(
+				"UMAMI_UPSTREAM_URL must be an absolute http(s) URL",
+			),
+			UMAMI_URL: absoluteHttpUrl("UMAMI_URL must be an absolute http(s) URL"),
 			NEXT_PUBLIC_UMAMI_WEBSITE_ID: z
 				.string()
 				.refine((value) => isUuid(value), {
@@ -370,8 +378,13 @@ function createEnvSchema(service) {
 				}
 			}
 
-			// Umami replay requires full analytics contract
-			const umamiUrl = data.NEXT_PUBLIC_UMAMI_URL?.trim();
+			// Umami replay requires full analytics contract. A server-only
+			// upstream (UMAMI_UPSTREAM_URL / UMAMI_URL) counts as URL-present:
+			// the proxy rewrite/handler destination follows it.
+			const umamiUrl =
+				data.UMAMI_UPSTREAM_URL?.trim() ||
+				data.UMAMI_URL?.trim() ||
+				data.NEXT_PUBLIC_UMAMI_URL?.trim();
 			const umamiWebsiteId = data.NEXT_PUBLIC_UMAMI_WEBSITE_ID?.trim();
 			const umamiReplayEnabled = data.NEXT_PUBLIC_UMAMI_REPLAY_ENABLED?.trim();
 			const hasUmamiUrl = Boolean(umamiUrl);
@@ -385,7 +398,7 @@ function createEnvSchema(service) {
 				ctx.addIssue({
 					code: "custom",
 					message:
-						"NEXT_PUBLIC_UMAMI_REPLAY_ENABLED requires NEXT_PUBLIC_UMAMI_URL and NEXT_PUBLIC_UMAMI_WEBSITE_ID.",
+						"NEXT_PUBLIC_UMAMI_REPLAY_ENABLED requires an Umami URL (UMAMI_UPSTREAM_URL, UMAMI_URL, or NEXT_PUBLIC_UMAMI_URL) and NEXT_PUBLIC_UMAMI_WEBSITE_ID.",
 				});
 			}
 		});
@@ -455,14 +468,20 @@ function collectWarnings() {
 		}
 	}
 
-	// Umami pair completeness
-	const umamiUrl = process.env.NEXT_PUBLIC_UMAMI_URL?.trim();
+	// Umami pair completeness. Server-only upstream vars count as
+	// URL-present, matching the proxy destination preference.
+	const umamiUrl = (
+		process.env.UMAMI_UPSTREAM_URL ||
+		process.env.UMAMI_URL ||
+		process.env.NEXT_PUBLIC_UMAMI_URL ||
+		""
+	).trim();
 	const umamiWebsiteId = process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID?.trim();
 	const hasUmamiUrl = Boolean(umamiUrl);
 	const hasUmamiWebsiteId = Boolean(umamiWebsiteId);
 	if (hasUmamiUrl !== hasUmamiWebsiteId) {
 		warnings.push(
-			"Umami analytics is incomplete: set both NEXT_PUBLIC_UMAMI_URL and NEXT_PUBLIC_UMAMI_WEBSITE_ID to enable tracking.",
+			"Umami analytics is incomplete: set an Umami URL (UMAMI_UPSTREAM_URL, UMAMI_URL, or NEXT_PUBLIC_UMAMI_URL) and NEXT_PUBLIC_UMAMI_WEBSITE_ID to enable tracking.",
 		);
 	}