bitvid/dist/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. The logger.dev.debug helper is available for especially noisy traces that you want to keep isolated to local development sessions.
• 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.debug/logger.dev.info	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.