## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
- Noticing our code we have many patterns of calling localstorage and
handling those errors
- We should add those in a single well tested file
- Handle those errors in the singleton which makes it easier for us to
debug customer issues. Logger is outputing local storage warnings for
feature we expose
- Side effect of this is random crashes on studio when local storage
isn't available or handled correctly
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Refactor**
* Improved browser storage handling across the app for more reliable
persistence and graceful behavior in restricted or non-browser
environments (settings, previews, charts, tabs, sign-in/session flows,
integrations, and UI state).
* **New Features**
* Introduced a safe storage layer to standardize and harden
local/session persistence.
* **Tests**
* Added comprehensive tests covering the new safe storage behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
Re-lands the first-referrer cookie feature from #42768 (reverted in
#43129) with middleware matcher fixes that prevent Studio traffic
interference.
**Tracks:** [GROWTH-651](https://linear.app/supabase/issue/GROWTH-651)
## What changed
New shared module in `packages/common/first-referrer-cookie.ts` that
handles stamping and parsing a first-referrer cookie (referrer, UTMs,
click IDs, landing URL). Each app's middleware calls
`stampFirstReferrerCookie` on the edge response — www and docs are the
primary entry points, Studio is a fallback for direct visits with UTMs.
On the telemetry side, `handlePageTelemetry` now takes an options object
instead of positional args, reads the cookie on initial pageview, and
overrides the referrer if the cookie captured an external source but the
current referrer is internal (i.e., the user navigated cross-app). Also
sends `first_referrer_cookie_present`/`consumed` properties so we can
observe the handoff in PostHog.
The docs middleware matcher was broadened from `/reference/:path*` to
all docs pages so we stamp cookies site-wide, not just on reference
paths.
## Root cause of original revert
Two layers:
1. **Matcher gap**: www middleware ran on `/dashboard/*` traffic in prod
due to Vercel Multi-Zone architecture (www is the gateway for
`supabase.com`, proxying `/dashboard` → Studio, `/docs` → Docs).
Middleware runs *before* rewrites, so www middleware executed on all
proxied traffic.
2. **`_next/data` interception**: The matcher didn't exclude
`_next/data` paths. Client-side navigation in Next.js fetches JSON via
`/_next/data/...` — middleware intercepted these, returned
`NextResponse.next()` with cookie mutations (which processes through the
middleware response pipeline), and this interfered with the JSON
responses, causing full page reloads in the SQL editor.
## How this PR fixes it
| Fix | Detail |
|---|---|
| Exclude `_next/data` | All three matchers (`www`, `docs`, `studio`)
exclude `_next/data` via negative lookahead |
| Exclude `dashboard` + `docs` from www | www middleware no longer runs
on proxied app traffic |
| `/api/` path guard in Studio | Broadened matcher requires explicit
path check for API route filtering |
| `NextResponse.next()` semantics | Cookie stamping only happens on
matched paths; unmatched paths never enter middleware |
### `NextResponse.next()` vs `undefined` nuance
Returning an explicit `NextResponse.next()` with cookie mutations
processes through Next.js's middleware response pipeline (headers are
merged, cookies are set). Returning `undefined` (i.e. the request never
matches the matcher) lets Next.js handle the request completely
untouched. The matcher exclusions ensure `_next/data` and proxied app
paths never enter middleware at all.
## Testing
- ✅ 22 unit tests for shared cookie utilities (all pass)
- ✅ Studio prod build succeeds, middleware recognized as `ƒ Proxy
(Middleware)`
- ✅ Playwright validation: client-side navigation works across 3 page
transitions, `_next/data` requests return 200 OK without middleware
interception, no full-page reloads
- ❌ www/docs SSG builds require platform backend services (expected —
same as master)
## Summary
Fixes GROWTH-625.
Preserves first-touch attribution across app boundaries by persisting
external referrer context at the edge and consuming it on Studio's
initial pageview.
When users come from an external source to www/docs and then navigate to
Studio, Studio often only sees the internal `supabase.com` hop. This
change preserves the original external context so first-touch
attribution is retained.
## What changed
- **Shared first-referrer cookie utilities**
(`packages/common/first-referrer-cookie.ts`):
- `isExternalReferrer`, `buildFirstReferrerData`,
`serializeFirstReferrerCookie`, `parseFirstReferrerCookie`
- `hasPaidSignals` — detects click IDs (gclid, fbclid, etc.) and paid
utm_medium values
- `shouldRefreshCookie` — centralizes stamp-or-skip decision for all
apps
- `stampFirstReferrerCookie` — shared middleware helper used by all apps
(extracted from duplicated inline logic)
- **Edge middleware on all apps** — stamps cookie for external visitors,
refreshes on paid signals:
- `apps/www/middleware.ts` (simplified to use shared helper)
- `apps/docs/middleware.ts` (simplified to use shared helper)
- `apps/studio/proxy.ts` (integrated into existing proxy file)
- **Docs middleware matcher** — broadened from `/reference/:path*` to
all non-static paths so the first-referrer cookie is stamped on all docs
pages, not just reference paths
- **Telemetry** — Studio consumes cookie on initial pageview
(`packages/common/telemetry.tsx`). `handlePageTelemetry` refactored from
7 positional params to an options object for readability.
- **Tests** — 22 unit tests covering all utilities and edge cases
(including direct-navigation scenario)
## Behavior
- Writes `_sb_first_referrer` cookie when:
- cookie is not already set and request has an external referrer, OR
- cookie exists but incoming URL has paid traffic signals (click IDs or
paid utm_medium)
- Cookie: 365-day TTL, `domain=supabase.com`, `sameSite=lax`,
`secure=true` in production
- On first Studio pageview, if current referrer is internal and cookie
has external context:
- use persisted external referrer
- apply persisted UTM/click-id/landing-url attribution props
- Measurement properties: `first_referrer_cookie_present`,
`first_referrer_cookie_consumed`
## Manual testing
1. Visit `supabase.com/pricing?utm_source=google&utm_medium=cpc` from an
external referrer (or use DevTools to set a `Referer` header)
2. Check `_sb_first_referrer` cookie is set in Application > Cookies
3. Navigate to Studio (`supabase.com/dashboard`)
4. In PostHog (or browser network tab), verify the first `$pageview`
event has:
- `first_referrer_cookie_present: true`
- `first_referrer_cookie_consumed: true`
- `$utm_source: "google"`, `$utm_medium: "cpc"`
- `$referrer` points to the external source, not `supabase.com`
5. Verify subsequent route changes do NOT include
`first_referrer_cookie_*` properties
## Review feedback addressed
- Added `secure: true` flag on production cookies (Pam's first comment)
- Fixed inaccurate JSDoc on `utms` field — keys retain `utm_` prefix
(Pam's fourth comment)
- Added test coverage for edge cases: malformed URLs, multi-cookie
headers, http:// referrers (Pam's sixth comment)
- Docs matcher broadening: fast-path exit on cookie-exists check keeps
overhead minimal, exclusion list is correct
- Extracted shared middleware helper to eliminate duplication across 3
apps
- Refactored `handlePageTelemetry` from positional params to options
object
- Removed redundant null check in `hasPaidSignals`
- Added direct-navigation test case
- Deleted dead `apps/learn/middleware.ts`
- Fixed studio build: integrated cookie stamping into existing
`proxy.ts` (Next.js 16 rejects both middleware.ts and proxy.ts)
---------
Co-authored-by: pamelachia <26612111+pamelachia@users.noreply.github.com>
Co-authored-by: Pamela Chia <pamelachiamayyee@gmail.com>
* feat: enable/disable dashboard features
* use the set directly
* move enabled features to common
* remove sneaky any
---------
Co-authored-by: Joshen Lim <joshenlimek@gmail.com>
* chore: add usercentrics for consent management
* client component to make next.js happy
* address feedback
* move consent state to common
* fix import
* ensure page events are sent correctly
* add feature flag provider to ui library site
* fix ui lib 500 error
* skip in test env
---------
Co-authored-by: Joshen Lim <joshenlimek@gmail.com>
Co-authored-by: Jordi Enric <jordi.err@gmail.com>
There were two bugs when trying to run the integrations page locally
with NEXT_PUBLIC_IS_PLATFORM=false:
1. The IS_PLATFORM check imported from common was not evaluating
correctly to a boolean. This is because I slapped a 'use client' on the
entire common package last year -_-""" which caused all its imports to
be evaluated to functions when used in server components. I have now
moved the 'use client's down to the submodules that actually need it.
2. When the integrations submenu is empty, the navigation menu errors
out because it expects all navigation items to either have children or
have links. Have updated this to gracefully hide empty headers.
* update deps + image codemod (studio)
* update next links (studio)
* update deps
* update links (ui)
* remove next-transpile-modules
* move next-themes dependency
* chore: update ConfirmDialog
* chore: remove old ConfirmModal js file. migrated to TS
* dependency wrangling
* remove empty page
* update next links (www)
* First run bump react-data-grid-v7 beta 4
* fix package-lock.json
* more deps wrangling
* update recharts
* update sentry options
* fix some broken things in www
* studio fixes
* fix graphiql
* fix studio build
* fix menu hydration
* small build error
* update turbo
* fix www typescript errors
* docs image codemod
* links codemod docs
* fix docs typescript errors
* move useConsent to ui to prevent circular deps
* Fix links
* Fix homepage
* Fix links
* move studio/ to apps/
* Revert "move studio/ to apps/"
This reverts commit 1b0a985fcb.
* disable outputFileTracingRoot
* remove outputFileTracingRoot
* fix homepage product cards
* fix PrivacySettings links
* Fix links
* Fix the build for www.
* Minor fixes for JWTGenerator.
* Fix the docs and ui tests.
* Revert codehike back to 0.8.3
* remove ConfirmAlert()
* reenable babel because mobx hates me
* fix blog image and comparison page avatar
* Fix svg errors
* update image synthax
* Fix code hike
* Move the button in a div so that it doesn't inherit its parent height and make the button look weird.
* When components are defined in a component, they get recreated on each render. This makes them unstable in certain cases and causes infinite rerenders.
* Replace the next/head usage with next/script.
* Chore/upgrade next 13 fix table editor (#18431)
* fix table editor styling and fix row deletion logic
* Fix deleting selected rows from header, and fix checkboxes not clearing up
* Fix deleting all rows when filter applied, and fix deleting all rows
* Fix grid size styling issue
* Fix TS error
* Hydration errors
* studio org pages fixes
* fix more studio links
* audit logs fixes
* dropdown icon styling fixes
* fix some images in www
* upgrade to next 14
* try new sentry wrapper for api
* see if this is even invoked
* Revert "see if this is even invoked"
This reverts commit 86c3973ffa.
* Revert "try new sentry wrapper for api"
This reverts commit f67623ebad.
* Revert "upgrade to next 14"
This reverts commit a24dd6131e.
* chore: allow node version 19/20
* Try to fix the LogTable so that it renders with the newer "react-data-grid" version.
* Fix type errors in the log renderer code.
* Fix the replication screen.
* Add the CSS for the GraphiQL.
* Fix SQL editor results rendering
* Lint
* Fix SQL editor results height issue
* Fix auth RLS not invalidating RQ when toggling RLS
* Fix database tables new/edit column regressed
* Fix migrations page empty state if migrations schema not yet created
* Fix API side panel docs temp remove postgrest text for column description PK and FK
* Fix + improve timeout handling in SQL editor
---------
Co-authored-by: Jonathan Summers-Muir <MildTomato@users.noreply.github.com>
Co-authored-by: Joshen Lim <joshenlimek@gmail.com>
Co-authored-by: Francesco Sansalvadore <f.sansalvadore@gmail.com>
Co-authored-by: Terry Sutton <saltcod@gmail.com>
Co-authored-by: Ivan Vasilov <vasilov.ivan@gmail.com>
Co-authored-by: Kevin Grüneberg <k.grueneberg1994@gmail.com>
Ali Waseem