@hotfyllc/debug-console-rn

Console de debug flutuante in-app pra React Native. Captura saída de console.*, intercepta fetch/XHR pra inspeção de rede, expõe botões de ação customizados pelo app e segue a paleta visual do design system da Hotfy.

Status: 1.x — estável e em produção.

O que você ganha

• Botão flutuante arrastável — abre/fecha o painel, posição persistida em AsyncStorage. Mostra badge vermelho com contagem de erros não-vistos. Ícone: o "mark" da Hotfy em verde.
• Aba Logs — captura automática de todo console.log/info/warn/ error do app. Busca por texto, filtro por nível (all / ad / log / info / warn / error), copy-all pra clipboard, scroll reverso pra ver os mais recentes.
• Aba Network — intercepta fetch e XMLHttpRequest (cobre Firebase, axios, qualquer lib HTTP que rode em RN). Mostra status, método, duração, URL. Toque numa request pra abrir o detalhe com headers, body cru, body parseado como JSON, timing, e botões pra copiar como cURL ou copiar só o response.
• Suporte a Blob nativo do RN — quando o response do XHR vem como Blob (caso default do fetch em RN), o painel chama FileReader / Blob.text() automaticamente pra mostrar o conteúdo desserializado em vez do shape {_data: {blobId: ...}} opaco.
• Actions customizáveis — o app passa DebugAction[] (label + callback), aparece como barra de botões no rodapé do painel. Útil pra "Clear Storage", "Refresh Wrapper Config", "Dump State", etc.
• Design system embutido — paleta canônica em 5 famílias × 10 tons, exportada como tokens e ui. Apps consumidores podem reaproveitar.

Impacto zero em produção: se você não renderizar <DebugConsole />, nenhum interceptor é instalado.

Instalação

npm install @hotfyllc/debug-console-rn

Peer dependencies

| Pacote | Versão mínima | |---|---| | react | * | | react-native | >=0.70.0 | | @react-native-async-storage/async-storage | >=1.17.0 | | expo-clipboard | >=6.0.0 | | lucide-react-native | >=0.300.0 | | react-native-safe-area-context | >=4.0.0 | | react-native-svg | >=15.0.0 |

Em projetos Expo, quase todas (exceto lucide-react-native) já vêm nos templates padrão. Pra bare RN, instale manualmente.

Uso

Monta uma vez

Renderize <DebugConsole /> no root do app (ou em qualquer lugar que fique sempre montado enquanto o app roda). Recomendado: logo antes da árvore de telas fechar no seu layout raiz.

import { DebugConsole, type DebugAction } from '@hotfyllc/debug-console-rn'
import AsyncStorage from '@react-native-async-storage/async-storage'

const debugActions: DebugAction[] = [
  {
    label: 'Clear Storage',
    onPress: async () => {
      await AsyncStorage.clear()
      console.warn('AsyncStorage limpo')
    },
  },
  {
    label: 'Wrapper Config',
    revealLogs: true,
    onPress: () => {
      console.info('[debug] HotfyWrapper.getConfig():', HotfyWrapper.getConfig())
    },
  },
]

export default function RootLayout() {
  return (
    <>
      {/* seu app */}
      {__DEV__ && <DebugConsole actions={debugActions} />}
    </>
  )
}

Habilitar condicionalmente em produção

Pra builds enviadas a testers/QA, dá pra liberar o console com base em qualquer flag (env, install referrer, deep link, override do remote config):

const debugEnabled =
  process.env.EXPO_PUBLIC_DEBUG_CONSOLE === 'true' ||
  installedViaDebugReferrer

return (
  <>
    {/* seu app */}
    {debugEnabled && <DebugConsole actions={debugActions} />}
  </>
)

Padrão usado nos apps Hotfy: ativar via parâmetro ?debug=1 no Install Referrer da Play Store, persistir flag em AsyncStorage, e ler aqui. Assim o time de QA consegue depurar prod sem precisar de novo build.

API

<DebugConsole>

interface DebugConsoleProps {
  actions?: DebugAction[]
}

Quando monta:

• Instala interceptor de console.* (logs viram entries na aba Logs; o console.* original continua funcionando)
• Instala interceptor de fetch e XHR (requests aparecem na aba Network; libs HTTP originais continuam funcionando)
• Renderiza o botão flutuante + painel sob demanda

DebugAction

interface DebugAction {
  /** Texto do botão (vira UPPERCASE no render). */
  label: string

  /** Callback do toque. Pode ser sync ou async. */
  onPress: () => void | Promise<void>

  /**
   * Se `true`, ao tocar:
   *   1. troca pra aba Logs automaticamente
   *   2. zera o filtro pra "all"
   *   3. faz scroll pro log mais recente
   *
   * Útil quando o `onPress` loga via `console.info` algo que o usuário
   * precisa ver na hora — ex.: "Wrapper Config", "Stored Attribution",
   * "Install Referrer", "CDP Anonymous ID".
   */
  revealLogs?: boolean

  /**
   * @deprecated Ignorado a partir de v1.2 — todos os botões usam a
   * cor padrão do design system pra consistência visual. Vai ser
   * removido em v2.
   */
  color?: string
}

NetworkRequest (tipo exportado)

Se seu app precisar inspecionar requests capturadas programaticamente, importe o tipo NetworkRequest. O store interno não é exposto como API pública — o painel lê via useSyncExternalStore.

import type { NetworkRequest } from '@hotfyllc/debug-console-rn'

interface NetworkRequest {
  id: number
  method: string
  url: string
  status: number          // -1 enquanto pendente, 0 em network error, código HTTP quando responde
  duration: number        // ms, -1 enquanto pendente
  startedAt: number       // timestamp absoluto
  endedAt: number
  requestHeaders: Record<string, string>   // Authorization etc. mascarados
  responseHeaders: Record<string, string>
  requestBody: string | null
  responseBody: string | null
  pending: boolean
  errored: boolean
  responseTruncated: boolean
}

Design tokens (tokens e ui)

A paleta visual do console é exportada pra que seu app possa reaproveitar:

import { tokens, ui } from '@hotfyllc/debug-console-rn'

// 5 famílias × 10 tons cada (50 → 900)
tokens.green[500]    // '#1da650' — primary
tokens.red[400]      // '#f87171' — erro
tokens.neutral[800]  // '#2a2926' — cinza-escuro

// Aliases semânticos do tema dark
ui.accent            // verde primary do design system
ui.textPrimary       // texto principal claro
ui.cardBg            // background de inputs/cards (slate-800)

Comportamento e limites

• Logs ficam só em memória (cap em 1000 entries). Limpa em reload do app ou via o botão Eraser do painel.
• Network requests cap em 200. Mais antigas são descartadas (FIFO).
• Headers sensíveis (Authorization, x-api-key, Cookie, Set-Cookie, x-auth-token, x-master-key) são automaticamente mascarados (xxxx***xxxx) tanto na visualização do painel quanto na opção "Copy as cURL". O console não vaza credenciais por copy/paste.
• Bodies grandes (> 50 KB) são truncados — flag responseTruncated marca isso no objeto e o título da seção mostra (truncated to 50KB).
• Sem logging remoto — o console só mostra localmente. Se você quer enviar logs pra um backend, use um SDK de analytics separado (Sentry, Crashlytics, Hotfy CDP, etc.) e deixe o console ser apenas a lente local.
• Performance: interceptors adicionam um wrapper fino sobre console, fetch e XHR. Overhead negligível, mas se você renderizar <DebugConsole> em build de produção, audite antes de enviar pra loja.

Layout visual

O console é renderizado em tema escuro consistente com ferramentas de DevTools:

| Camada | Cor | Notas | |---|---|---| | Background do painel | #0F172A (slate-900) | escuro profundo | | Cards / inputs / payload | #1E293B (slate-800) | um tom acima do panel | | Pressed state | #334155 (slate-700) | feedback de toque | | Texto principal | #e5e4e1 (neutral-200) | | | Texto secundário (timestamps, métodos) | #a8a7a4 (neutral-400) | | | Texto muted (counts, placeholders) | #6d6c6a (neutral-500) | | | Acento (tab/filter ativo, focus, HotfyMark) | #1da650 (green-500) | | | Estados de log (info/warn/error/success) | paleta DS | bg + texto contrastantes |

Convenção pra filtrar logs de ads

O filtro ad da aba Logs mostra apenas mensagens cujo texto começa com Ad [ (após trim). Use esse prefixo nos seus logs de monetização pra poder filtrar sem ruído:

console.log('Ad [INTERSTITIAL] LOADED unit=...')
console.warn('Ad [APPOPEN] SKIP reason=no_unit_configured')

O Wrapper SDK da Hotfy já segue essa convenção automaticamente.

Licença

UNLICENSED — proprietário. Copyright (c) 2026 Hotfy LLC. Todos os direitos reservados. Ver LICENSE pros termos.