mirror of
https://github.com/PR0M3TH3AN/bitvid.git
synced 2026-10-27 16:02:26 +00:00
82 lines
3.3 KiB
Markdown
82 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
```js
|
|
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`:
|
|
|
|
```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.
|
|
- Keep `IS_DEV_MODE = false` for production builds. This value 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.
|
|
|
|
If you need to enable dev logging without editing `config/instance-config.js`,
|
|
inject a runtime override before `js/config.js` loads:
|
|
|
|
```html
|
|
<script>
|
|
window.__BITVID_DEV_MODE_OVERRIDE__ = true;
|
|
window.__BITVID_VERBOSE_DEV_MODE_OVERRIDE__ = true;
|
|
</script>
|
|
```
|
|
|
|
Overrides accept boolean values or the strings `"true"` / `"false"` so they can
|
|
be injected by a build pipeline.
|