bitvid/docs/logging.md

Logging and Dev-Mode Guidance

This document explains how bitvid routes browser logs, how inline scripts can re-use the shared logger, and what operators must do with the dev-mode flag when promoting builds.

Picking the right channel

bitvid ships a frozen logger at js/utils/logger.js with two channels:

• logger.dev: Emits only when IS_DEV_MODE is truthy. Use this channel for verbose traces, performance probes, and feature flag experimentation that should disappear from production consoles.
• logger.user: Always available and automatically prefixes output with [bitvid]. Use this channel for operator-facing warnings and errors that help diagnose issues in production.

When adding new messages, classify them by the audience:

Scenario	Recommended channel	Notes
Debugging a new feature locally	logger.dev.info/logger.dev.log	Remove or downgrade before launching if they no longer serve a purpose.
Non-fatal recoverable issues users should investigate	logger.user.warn	Provide actionable context so operators know what failed.
Fatal errors that block playback or payments	logger.user.error	Escalate with a clear message and include relevant IDs or URLs.
Metrics or noisy traces that only help during QA	logger.dev.*	Wrap expensive logging in conditional checks when possible.

Avoid direct console.* calls—routing everything through the logger keeps the production console clean and guarantees dev-mode gates behave consistently.

Using the logger from inline scripts

The logger is exposed as a frozen global so inline scripts can share the same API without additional bundling:

const { dev, user } = window.bitvidLogger;

dev.log("rendering upload modal preview");
user.warn("Playback manifest missing expected resolution tag");

If you need to guard logic by environment, rely on the companion global set in js/config.js:

if (window.__BITVID_DEV_MODE__) {
  window.bitvidLogger.dev.info("Hydrating admin widgets in dev mode");
}

The globals are populated as soon as js/config.js loads. Check for their existence before using them in third-party contexts that may execute earlier.

Adjusting the dev-mode flag for deployments

The source of truth lives in config/instance-config.js:

• Set IS_DEV_MODE = true while developing locally so the dev logger and other diagnostics are available.
• Flip IS_DEV_MODE = false before shipping a production build. This change propagates to isDevMode (the module export), window.__BITVID_DEV_MODE__, and logger.dev, silencing development-only messages.

Always commit the flag change alongside deployment-ready configuration tweaks. Forgetting to update the flag leaves verbose traces in user consoles and can expose experimental behavior intended only for QA environments.