@djangocfg/monitor 2.1.228 → 2.1.230

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/monitor",
-  "version": "2.1.228",
+  "version": "2.1.230",
   "description": "Browser error and event monitoring SDK for django-cfg backends. Captures JS errors, network failures, console logs, and performance metrics.",
   "keywords": [
     "django",
@@ -83,7 +83,7 @@
     }
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.228",
+    "@djangocfg/typescript-config": "^2.1.230",
     "p-retry": "^6.2.0",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",

package/src/client/hooks/useDebugMode.ts

@@ -0,0 +1,70 @@
+'use client'
+
+/**
+ * useDebugMode — shared debug mode detection hook.
+ *
+ * Logic:
+ * - development: always true (no localStorage needed)
+ * - production:
+ *   - ?debug=1 in URL → persist to localStorage, remove param from URL
+ *   - localStorage.__debug_mode__ === '1' → true
+ *   - otherwise → false
+ *
+ * @example
+ * const isDebug = useDebugMode()
+ */
+
+import { useEffect, useState } from 'react'
+import { isDevelopment } from '../utils/env'
+
+const LS_KEY = '__debug_mode__'
+
+function readFromStorage(): boolean {
+  try {
+    return localStorage.getItem(LS_KEY) === '1'
+  } catch {
+    return false
+  }
+}
+
+function persistToStorage(): void {
+  try {
+    localStorage.setItem(LS_KEY, '1')
+  } catch {
+    // ignore — private browsing or quota exceeded
+  }
+}
+
+function consumeDebugParam(): boolean {
+  if (typeof window === 'undefined') return false
+  const params = new URLSearchParams(window.location.search)
+  const value = params.get('debug')
+  if (!value) return false
+
+  persistToStorage()
+
+  params.delete('debug')
+  const newUrl = `${window.location.pathname}${params.toString() ? `?${params.toString()}` : ''}${window.location.hash}`
+  window.history.replaceState(null, '', newUrl)
+  return true
+}
+
+export function useDebugMode(): boolean {
+  // In development, always true — no side effects needed
+  if (isDevelopment) return true
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const [isDebug, setIsDebug] = useState(false)
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  useEffect(() => {
+    const fromUrl = consumeDebugParam()
+    if (fromUrl) {
+      setIsDebug(true)
+      return
+    }
+    setIsDebug(readFromStorage())
+  }, [])
+
+  return isDebug
+}

package/src/client/index.ts

@@ -36,6 +36,8 @@ export type { MonitorProviderProps } from './MonitorProvider'
 export { initWindowMonitor } from './window'
 export type { WindowMonitorAPI } from './window'
 export { monitorStore } from './store'
+export { useDebugMode } from './hooks/useDebugMode'
+export { isDevelopment, isProduction } from './utils/env'
 
 let flushInterval: ReturnType<typeof setInterval> | null = null
 const cleanupFns: Array<() => void> = []

package/src/client/utils/env.ts

@@ -0,0 +1,13 @@
+/**
+ * Environment utilities.
+ *
+ * Use these constants instead of inline process.env.NODE_ENV checks.
+ * Webpack/esbuild replaces process.env.NODE_ENV statically at build time,
+ * so these are zero-cost — they tree-shake correctly in both client and server bundles.
+ */
+
+/** True only in `next dev` / jest / vitest */
+export const isDevelopment = process.env.NODE_ENV === 'development'
+
+/** True in production builds and test environments */
+export const isProduction = process.env.NODE_ENV !== 'development'