Browser dev logging (devLog / devWarn)

Purpose

Use devLog and devWarn from @goosehead-innovation/ui-utils instead of scattering raw console.log / console.warn calls in feature code. Logs stay silent by default and only appear when a developer explicitly enables them with a URL query flag, in non-production builds.

Source: libs/ui/utils/src/lib/dev-logger.ts (re-exported from libs/ui/utils/src/index.ts).

When logs appear

Condition	Behavior
Vite import.meta.env.MODE === 'production'	Never logs, regardless of URL (no PII or noise in prod consoles).
Any other mode (e.g. local development)	Logs only if the current page URL includes logging=true as a query parameter.

The flag is read once and cached on first use. The value must be the literal string true (e.g. logging=yes does not enable logging).

How to enable in the browser

Append the query parameter to the URL (combine with existing params using &):

https://localhost:4200/your-path?sessionId=...&logging=true

If the app already has a query string, add:

&logging=true

Then open DevTools → Console. You will see lines prefixed with the label you pass as the first argument (see examples below).

API

Export	Behavior
devLog(label, ...args)	Calls console.log(label, ...args) when enabled.
devWarn(label, ...args)	Calls console.warn(label, ...args) when enabled.
resetLoggingCache()	Clears the internal cache so the next check re-reads window.location.search. Use if you change the query string without a full page reload (e.g. custom history handling). Not currently wired in the app shell.

label: Use a short, grep-friendly tag (e.g. '[AboutYou]', '[parseSessionField]') so console output is easy to filter.

Import

import { devLog, devWarn } from '@goosehead-innovation/ui-utils';

Works in components, hooks, services, and plain TS modules bundled for the browser (the implementation uses window.location).

Current consumers (examples)

These are Progressive Home (Fastlane Portal) call sites as of the last repo audit; the same pattern applies anywhere the package is used in a Vite client bundle.

Area	File	API	What gets logged
About You step	apps/fastlane-portal/.../about-you/index.tsx	devLog	Session data when loaded (debug flow).
Checkout submit	apps/fastlane-portal/.../checkout/use-checkout-submit.ts	devLog	Successful save / stub navigation; submit error message.
Session API	apps/fastlane-portal/.../progressive-session-api.ts	devWarn	Zod parse failures, quote/form preservation validation issues.
Hooks	use-start-quote.ts, use-update-price.ts, use-coverage-defaults.ts	devWarn	API / quote failures (wrapped errors).
UI	home-structures-card/index.tsx	devWarn	Auto-complete trigger failures.
Shared hook	use-external-validation.ts	devWarn	External validation callback rejection.

Unit tests that execute this code typically vi.mock('@goosehead-innovation/ui-utils') and stub devLog / devWarn so the console stays clean and assertions stay focused.

Rules and restrictions

1. Do not log secrets or PII — Even though production never prints these calls, treat payloads as if they could leak (code paths change, misconfiguration happens). Prefer opaque flags, lengths, or field names over full session objects in shared code unless strictly necessary for local debugging.
2. Prefer devWarn for recoverable / diagnostic issues (parse mismatches, optional failures); use devLog for neutral flow tracing (e.g. “step completed”).
3. Do not replace product UX or error reporting — This is developer diagnostics only, not user-visible error handling.
4. Avoid high-frequency logs in hot paths (render loops, per-keystroke handlers) when logging=true; they can still slow dev machines.
5. Browser-only — Do not import this module from Node-only contexts that have no window (e.g. API gateway). Progressive Home usage is all client-side portal code.
6. SPA caveat — Toggling logging without a full reload may not take effect until resetLoggingCache() is called (or the page is refreshed).