/dev-toolbar-review

name: dev-toolbar-review
description: Safety rules for the dev toolbar, PostHog client, and feature flags. Use
  when writing or reviewing any change to packages/dev-tools/, packages/common/posthog-client.ts,
  or packages/common/feature-flags.tsx. Covers environment guards, flag override cookies,
  telemetry event subscription, and SSE stream safety.

Dev Toolbar Review Guide

Review checklist for PRs touching the dev toolbar (`packages/dev-tools/`) and its integration points in `packages/common/`. The toolbar surfaces telemetry events and allows feature flag overrides during local development (expanding to staging/preview).

When This Applies

PRs modifying any of these paths need growth eng review:

• `packages/dev-tools/**` (owned by `@supabase/growth-eng` in CODEOWNERS)
• `packages/common/posthog-client.ts` (flag override reads, event subscription)
• `packages/common/feature-flags.tsx` (flag override merge logic)
• App-level mounting: `DevToolbarProvider`/`DevToolbar`/`DevToolbarTrigger` in `apps/studio/`, `apps/www/`, `apps/docs/`

Note: `posthog-client.ts` and `feature-flags.tsx` are NOT in CODEOWNERS for growth-eng, so PRs touching only those files won't auto-request review. Watch for these in the PR feed.

Review Checklist

1. Environment Guards

**Files:** `packages/dev-tools/index.ts`, `DevToolbar.tsx`, `DevToolbarTrigger.tsx`, `DevToolbarContext.tsx`

The toolbar uses two layers of protection:

• **Build-time tree-shaking** in `index.ts`: `process.env.NODE_ENV !== 'development'` ternaries that replace components with noops/stubs so the implementation is eliminated from production bundles.
• **Runtime guards** in components: `IS_LOCAL_DEV` checks — `DevToolbar` and `DevToolbarTrigger` return `null` to hide themselves, while `DevToolbarProvider` passes children through (`<>{children}</>`) to preserve the component tree.

**Check for:**

• Guards being removed or broadened. The toolbar is expanding to staging and preview deploys but must remain invisible in production.
• Tree-shaking ternaries in `index.ts` staying intact — these are the primary production safety mechanism.
• New components or exports that bypass the existing guard pattern.

2. Flag Override Cookies

**Files:** `packages/dev-tools/DevToolbar.tsx`, `packages/common/posthog-client.ts`, `packages/common/feature-flags.tsx`

The toolbar writes two cookies that override feature flags locally:

• `x-ph-flag-overrides` — PostHog flag overrides
• `x-cc-flag-overrides` — ConfigCat flag overrides

These are read by:

• `posthog-client.ts:getFeatureFlag()` — checks the PostHog override cookie before querying the SDK
• `feature-flags.tsx` — merges both override cookies into the flag store during initialization

**Check for:**

• Cookie name changes (must stay in sync across writer and all readers)
• Changes to the merge/precedence logic in `feature-flags.tsx` (currently: `vercel-flag-overrides` first, then `x-cc-flag-overrides` takes precedence in local dev)
• Override cookies being read outside the `IS_LOCAL_DEV` / `isLocalDev` guard — overrides must never affect production flag evaluation
• Changes to `parseOverrideValue` or `valuesAreEqual` in `packages/dev-tools/utils.ts` that could cause type coercion bugs

3. Telemetry Event Subscription

**Files:** `packages/common/posthog-client.ts`, `packages/dev-tools/DevToolbarContext.tsx`

The toolbar subscribes to client-side PostHog events via `posthogClient.subscribeToEvents()`. The PostHog client calls `emitToDevListeners()` after `capturePageView`, `capturePageLeave`, and `identify`. Note: `captureExperimentExposure` calls `posthog.capture()` directly without emitting to dev listeners — experiment exposure events are invisible in the toolbar.

**Check for:**

• Changes to `emitToDevListeners` or `subscribeToEvents` that could introduce side effects on the actual capture path (e.g., throwing errors, blocking, mutating event data)
• The listener set (`devListeners`) being iterated synchronously in a way that could delay event dispatch
• New PostHog client methods that capture events but don't call `emitToDevListeners` (gap in toolbar visibility)

4. SSE Server Telemetry Stream

**Files:** `packages/dev-tools/DevToolbarContext.tsx`

The toolbar connects to `${apiUrl}/telemetry/stream` via Server-Sent Events to display server-side telemetry. Uses exponential backoff on connection errors.

**Check for:**

• Changes to the SSE endpoint URL or `session_id` cookie handling
• Reconnection logic changes that could cause excessive retries or connection leaks
• Note: the stream endpoint lives in the platform repo — cross-repo changes need coordinated review

5. App-Level Mounting

**Provider + toolbar panel** (`DevToolbarProvider`, `DevToolbar`):

• `apps/studio/pages/_app.tsx`
• `apps/www/pages/_app.tsx`, `apps/www/app/providers.tsx`
• `apps/docs/features/app.providers.tsx`

**Trigger button** (`DevToolbarTrigger`) — rendered separately in nav/header components:

• `apps/studio/components/layouts/Navigation/LayoutHeader/LayoutHeader.tsx`
• `apps/www/components/Nav/index.tsx`
• `apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx`

**Check for:**

• Provider being added or removed from an app
• `apiUrl` prop changes (must point to the correct platform API)
• Rendering order changes that could affect the toolbar's access to PostHog context

What Doesn't Need Growth Review

Changes that are purely UI/UX within the toolbar panel itself — styling, layout, copy changes, drag behavior, popover positioning — don't need growth eng review unless they also touch the integration points above.