Quark's recommended default is a dormant Umami baseline in every scaffolded Next.js app. Analytics stays off until the public Umami URL and website ID are both present, and replay stays off until it is explicitly enabled.
script.js from NEXT_PUBLIC_UMAMI_URL in the root layout head.apps/web/src/lib/analytics/* and sync them into the scaffold templates. Do not move vendor-specific code into @usequark/quark-core.rrweb client component for replay uploads instead of Umami's hosted recorder.js.NEXT_PUBLIC_UMAMI_REPLAY_ENABLED.Scaffolded apps should expose only these three public variables by default:
NEXT_PUBLIC_UMAMI_URL - absolute Umami base URL, for example https://stats.example.comNEXT_PUBLIC_UMAMI_WEBSITE_ID - public website UUID used by script.js and replay uploadsNEXT_PUBLIC_UMAMI_REPLAY_ENABLED - boolean-like flag that enables the local rrweb recorderBehavior rules:
data-performance="true" on the main tracker.NEXT_PUBLIC_UMAMI_REPLAY_ENABLED=true.The generated web app should include these surfaces:
| Surface | Purpose |
|---|---|
apps/web/src/lib/analytics/umami-config.js | Normalize URL, derive origin and dns-prefetch hint, build script.js URL, expose enabled and replayEnabled |
apps/web/src/lib/analytics/umami.js | Thin client wrapper for track(), identify(), and optional revenue helpers |
apps/web/src/lib/analytics/umami-marketing.js | Dormant helpers for campaign URLs, dashboard-generated Umami Links, Pixels, and marketing-email snippets |
apps/web/src/lib/analytics/umami-replay.js | Replay defaults, buffering, session-cache waiting, and /api/record payload helpers |
apps/web/src/app/_components/UmamiReplayRecorder.js | Local rrweb recorder that waits for window.umami.getSession().cache, batches events, flushes on hidden/pagehide, and checkpoints across App Router transitions |
apps/web/src/app/layout.js | Adds preconnect, dns-prefetch, a deferred script.js tag with data-performance="true", and conditionally mounts the replay recorder |
apps/web/src/proxy.js and apps/web/next.config.js | Derive Umami CSP allowlists from shared config instead of hardcoded hosts |
packages/config/src/validate-env.js | Validates the three-variable contract and replay preconditions |
apps/web/.env.example | Documents the public Umami setup without adding extra env sprawl |
Replay remains app-local and uses code defaults that mirror Umami's recorder behavior closely enough for App Router apps:
1 (validate end-to-end at 100% before lowering)10000 ms100300000 msmoderate by default with maskAllInputs: truewindow.umami.getSession().cache appears (abortable); a fixed timeout silently dropped every session on slow networkskeepalive only when the payload stays under the browser body limit200 with { ok: false, reason } (e.g. replay disabled server-side) is treated as a failure — events are restored and retried instead of silently droppedThese defaults belong in code, not in additional public environment variables.
Umami Links and Pixels are generated in the Umami dashboard, not derived from runtime env vars. Quark still includes dormant helper surfaces so projects can use those assets later without adding framework complexity:
buildCampaignUrl() appends standard UTM params to relative or absolute campaign URLs.resolveUmamiLinkHref() prefers a dashboard-generated Umami Link when one exists and falls back to the canonical destination.getUmamiPixelProps() returns a hidden image payload for external pages that cannot load the main tracker.getUmamiEmailPixelHtml() returns a dormant HTML snippet for custom email templates when a project decides to track opens.These helpers are intentionally dormant:
Use them only for external campaigns, HTML emails, or other surfaces where the main tracker cannot run. Do not replace normal internal app navigation with marketing redirects.
Quark does not recommend these as scaffold defaults:
recorder.jsThose can be added later by projects that need them, but they should not widen the default contract.
script tag in the layout head for script.js so the tracker can bootstrap in parallel before replay polling begins.data-performance="true" to the main tracker when a site is already opted into Umami analytics.script-src and connect-src from the normalized Umami origin.unsafe-eval where Turbopack still requires it.window.umami.getSession().cache before starting rrweb capture; the main tracker owns the session token.data-umami-block to any subtree that should be excluded from replay capture, such as payment, secrets, or support-case content.After changing the monorepo source, sync the scaffold templates:
pnpm --filter @usequark/quark-create-app sync-templates