Files
supabase/packages/dev-tools/DevToolbarContext.tsx
T
Sean OliverandCharis Lam 6bbe2c3297 feat(telemetry): add dev telemetry toolbar (#42259)
## Problem
We need a local-only UI to inspect client and server telemetry events
and override flags during development without touching non-local env
behavior. This work is intended to be shared across Studio, Docs, and
WWW.

## Changes
- Introduced a shared `dev-tools` package with the Dev Telemetry Toolbar
UI, trigger, and provider.
- Wired the toolbar into Studio, Docs, and WWW app shells (local-only
gating).
- Added a local-only `devTelemetry()` opt-in with storage gating and SSE
subscription.
- Wired client PostHog events into a local listener and re-exported
types.
- Added local flag override cookie support in the UI and CODEOWNERS for
the new package.
- Added unit tests covering local/non-local behavior and flag utilities.

## Testing
Manual (local only):
- Start each app locally: `pnpm dev:studio`, `pnpm dev:docs`, `pnpm
dev:www`
- Open the app, run `devTelemetry()` in the browser console
- Click around and confirm both client and server events appear (client
will be page views only)
- Verify feature flag overrides (PostHog + ConfigCat) persist and
restore correctly
- Confirm dismissing the toolbar clears local storage and hides the
trigger

Unblocked by https://github.com/supabase/platform/pull/29172

Resolves GROWTH-591

Demo:

[github.com/user-attachments/assets/60b376db-7440-4ada-82f5-d1bd4af4db3b](https://github.com/user-attachments/assets/60b376db-7440-4ada-82f5-d1bd4af4db3b)

Screenshots:

<img width="1368" height="972" alt="1"
src="https://github.com/user-attachments/assets/d2f20a0c-191f-4118-bb5e-15b25f5a54a9"
/>

<img width="1423" height="790" alt="2"
src="https://github.com/user-attachments/assets/115598e2-7287-49bf-9ed7-71ecc679dee3"
/>

<img width="1433" height="882" alt="3"
src="https://github.com/user-attachments/assets/51f666f2-9efc-410f-baec-378bdee9dbfe"
/>

<img width="608" height="483" alt="4"
src="https://github.com/user-attachments/assets/584d6cf5-1b2f-4cee-9e6a-d55ce2e3bae5"
/>

<img width="628" height="305" alt="5"
src="https://github.com/user-attachments/assets/991a9b39-578a-4565-b110-537a02040a53"
/>

<img width="659" height="447" alt="6"
src="https://github.com/user-attachments/assets/95ef405c-fffa-44af-bf6a-f974b780e3fc"
/>

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Developer Toolbar (local only): view client/server telemetry, inspect
events, and manage/override feature flags with persistent overrides,
filtering, and clear/reload.
* Client-side telemetry hooks: surface structured events to dev tooling
for realtime inspection.

* **Bug Fixes**
  * Fixed end-of-file newline in shared code.

* **Chores**
* Added dev-tools package, integrated provider and trigger across
Studio, Docs, and marketing sites, and added CODEOWNERS entry.

* **Tests**
  * Added comprehensive tests and test setup for the DevToolbar.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Charis Lam <26616127+charislam@users.noreply.github.com>
2026-02-06 11:46:53 -08:00

213 lines
5.1 KiB
TypeScript

'use client'
import { type ClientTelemetryEvent, ensurePlatformSuffix, posthogClient } from 'common'
import {
type ReactNode,
createContext,
useCallback,
useContext,
useEffect,
useRef,
useState,
} from 'react'
import type {
DevTelemetryEvent,
DevTelemetryToolbarContextType,
ServerTelemetryEvent,
} from './types'
import { getCookie } from './utils'
const IS_LOCAL_DEV = process.env.NODE_ENV === 'development'
const MAX_EVENTS = 200
const STORAGE_KEY = 'dev-telemetry-toolbar-enabled'
const SSE_INITIAL_RETRY_MS = 1000
const SSE_MAX_RETRY_MS = 30000
const SSE_BACKOFF_MULTIPLIER = 2
declare global {
interface Window {
devTelemetry?: () => void
}
}
const DevToolbarContext = createContext<DevTelemetryToolbarContextType | null>(null)
interface DevToolbarProviderProps {
children: ReactNode
apiUrl: string
}
export function DevToolbarProvider({ children, apiUrl }: DevToolbarProviderProps) {
const [isEnabled, setIsEnabled] = useState(false)
const [isOpen, setIsOpen] = useState(false)
const [events, setEvents] = useState<DevTelemetryEvent[]>([])
const sseRetryDelayRef = useRef(SSE_INITIAL_RETRY_MS)
const sseRetryTimeoutRef = useRef<NodeJS.Timeout | null>(null)
const dismissToolbar = useCallback(() => {
try {
localStorage.removeItem(STORAGE_KEY)
} catch {}
setIsEnabled(false)
setIsOpen(false)
}, [])
useEffect(() => {
if (!IS_LOCAL_DEV) return
let stored: string | null = null
try {
stored = localStorage.getItem(STORAGE_KEY)
} catch {}
if (stored === 'true') {
setIsEnabled(true)
}
window.devTelemetry = () => {
try {
localStorage.setItem(STORAGE_KEY, 'true')
} catch {}
setIsEnabled(true)
}
return () => {
delete window.devTelemetry
}
}, [])
const appendEvent = useCallback((event: DevTelemetryEvent) => {
setEvents((prev) => {
const key = `${event.source}-${event.id}`
if (prev.some((e) => `${e.source}-${e.id}` === key)) return prev
return [...prev.slice(-(MAX_EVENTS - 1)), event]
})
}, [])
useEffect(() => {
if (!isEnabled) return
const unsubscribe = posthogClient.subscribeToEvents((clientEvent: ClientTelemetryEvent) => {
appendEvent({
id: clientEvent.id,
timestamp: clientEvent.timestamp,
source: 'client',
eventType: clientEvent.eventType,
eventName: clientEvent.eventName,
distinctId: clientEvent.distinctId,
properties: clientEvent.properties,
})
})
return unsubscribe
}, [appendEvent, isEnabled])
useEffect(() => {
if (!isEnabled || typeof EventSource === 'undefined') return
let eventSource: EventSource | null = null
let isMounted = true
const connect = () => {
if (!isMounted) return
const sessionId = getCookie('session_id')
const streamUrl = `${ensurePlatformSuffix(apiUrl)}/telemetry/stream${
sessionId ? `?session_id=${encodeURIComponent(sessionId)}` : ''
}`
eventSource = new EventSource(streamUrl, { withCredentials: true })
eventSource.onopen = () => {
sseRetryDelayRef.current = SSE_INITIAL_RETRY_MS
}
eventSource.onmessage = (event) => {
try {
const data = JSON.parse(event.data) as ServerTelemetryEvent
appendEvent({
id: data.id,
timestamp: data.timestamp,
source: 'server',
eventType: data.eventType,
eventName: data.eventName,
distinctId: data.distinctId,
properties: data.properties,
})
} catch (e) {
console.error('[DevToolbar] Failed to parse SSE event:', e)
}
}
eventSource.onerror = () => {
if (!isMounted) return
eventSource?.close()
eventSource = null
const delay = sseRetryDelayRef.current
console.warn(`[DevToolbar] SSE connection error, reconnecting in ${delay}ms...`)
if (sseRetryTimeoutRef.current) {
clearTimeout(sseRetryTimeoutRef.current)
sseRetryTimeoutRef.current = null
}
sseRetryTimeoutRef.current = setTimeout(() => {
if (isMounted) {
connect()
}
}, delay)
sseRetryDelayRef.current = Math.min(delay * SSE_BACKOFF_MULTIPLIER, SSE_MAX_RETRY_MS)
}
}
connect()
return () => {
isMounted = false
eventSource?.close()
if (sseRetryTimeoutRef.current) {
clearTimeout(sseRetryTimeoutRef.current)
sseRetryTimeoutRef.current = null
}
}
}, [apiUrl, appendEvent, isEnabled])
if (!IS_LOCAL_DEV) {
return <>{children}</>
}
return (
<DevToolbarContext.Provider
value={{
isEnabled,
isOpen,
setIsOpen,
events,
setEvents,
dismissToolbar,
}}
>
{children}
</DevToolbarContext.Provider>
)
}
export function useDevToolbar() {
const context = useContext(DevToolbarContext)
if (!context) {
return {
isEnabled: false,
isOpen: false,
setIsOpen: () => {},
events: [],
setEvents: () => {},
dismissToolbar: () => {},
}
}
return context
}