common

Cross-cutting client-side infrastructure shared between apps: authentication, telemetry, feature flags, consent, marketplace data, and small helpers. Imported via the 'common' alias.

Purpose

Anything that more than one app needs and that is too app-specific for ui but too generic for any single app. Think "platform glue."

Directory layout

packages/common/
├── auth.tsx                    # Auth context provider; wraps GoTrue
├── gotrue.ts                   # GoTrue client setup
├── telemetry.tsx               # Telemetry provider
├── telemetry-constants.ts      # All product event names (≈ 85 KB)
├── telemetry-utils.ts          # Helper utilities for events
├── telemetry-first-touch-store.ts
├── posthog-client.ts           # PostHog wrapper
├── configcat.ts                # ConfigCat feature-flag client
├── consent-state.ts            # User consent for cookies / analytics
├── feature-flags.tsx           # React surface for flags
├── enabled-features/           # Statically-listed enabled features
├── first-referrer-cookie.ts    # Marketing attribution
├── marketplace-client.ts       # Vercel / AWS marketplace data
├── marketplace.types.ts
├── database-types.ts           # Shared local Supabase database types
├── fetchWrappers.tsx
├── hooks/                      # Cross-app hooks
├── helpers.ts
├── index.tsx                   # Barrel
├── MetaFavicons/, assets/, constants/
├── tailwind.config.js          # Stub for IntelliSense
├── postcss.config.js
└── package.json

Key abstractions

Module	Responsibility
auth.tsx	React context that owns the current GoTrue session and exposes a hook used by Studio and the marketing site.
telemetry.tsx + telemetry-constants.ts	A single registry of every product event name. Adding an event = adding a constant + a typed helper call.
posthog-client.ts	Thin wrapper that respects consent and only initializes after opt-in.
configcat.ts	Reads remote feature flags; values feed the React surface.
feature-flags.tsx + enabled-features/	Hooks like useFlag('foo') and a static enum of locally-enabled features.
consent-state.ts	GDPR-style consent state machine, persisted to local storage.
first-referrer-cookie.ts	First-touch attribution cookie used by www.
marketplace-client.ts, marketplace.types.ts	Data and types for partner marketplaces.
database-types.ts	Local Supabase database types used by package code.

telemetry-constants.ts is the largest single file in the workspace (~85 KB) — every event name in every Supabase frontend lives there. Treat it as canonical.

How it works

Apps wrap their tree with a small set of providers from this package:

<Providers>
  <AuthProvider>
    <ConsentProvider>
      <TelemetryProvider>{/* app */}</TelemetryProvider>
    </ConsentProvider>
  </AuthProvider>
</Providers>

Providers.tsx composes the providers; individual apps may add their own on top.

Tests

Unit tests live next to the source (*.test.ts(x)):

• configcat.test.ts
• consent-state.test.ts
• first-referrer-cookie.test.ts
• telemetry-first-touch-store.test.ts

Integration points

• Consumed by every Next.js app under apps/.
• Talks to GoTrue via @supabase/auth-js, ConfigCat via the ConfigCat SDK, PostHog via the PostHog browser SDK.

Entry points for modification

• New product event → add a constant in telemetry-constants.ts and a typed helper invocation site (telemetry.tsx).
• New feature flag → add to enabled-features/ and gate via useFlag('your-flag') in feature-flags.tsx.
• New auth method → extend gotrue.ts and auth.tsx.
• New consent control → update consent-state.ts and the surfacing UI (typically in the host app).