@convex-internal/web-analytics 1.0.0

package/README.md

@@ -0,0 +1,197 @@
+# @convex-internal/web-analytics
+
+Shared consent state, consent banner, and analytics setup for Convex websites.
+Wrap the app in `WebAnalyticsProvider`. It renders the consent banner. Wrap
+other tracking, such as GA or an ad pixel, in `Consented` so it loads only
+after consent is confirmed. Use `useConsent` when you need the consent status
+itself.
+
+## Usage
+
+Install the package, then render `WebAnalyticsProvider` at the root of the
+app. It is a client component. `useConsent` throws if called outside that
+provider.
+
+The provider starts analytics in production, except on localhost, syncs
+consent to PostHog, and shows the consent banner when the visitor has not
+chosen yet. Pass `posthogConfig` for site-specific options, such as the
+website's `dub_id` campaign param:
+
+```tsx
+<WebAnalyticsProvider posthogConfig={{ custom_campaign_params: ["dub_id"] }}>
+  {children}
+</WebAnalyticsProvider>
+```
+
+### `capture`
+
+Record an event from client code. The optional third argument is
+[PostHog's capture options](https://posthog.com/docs/libraries/js/usage).
+
+```tsx
+import { capture } from "@convex-internal/web-analytics";
+
+capture("www-login", undefined, {
+  transport: "sendBeacon",
+  send_instantly: true,
+});
+```
+
+### Consent banner
+
+The provider shows the banner when `consent` is `"undecided"`. It records
+`cookie_consent_shown` when it appears and `cookie_consent_decided` with
+`{ decision: "accepted" | "declined" }` just before the choice is saved.
+
+The banner stays hidden while Global Privacy Control is on, because that
+resolves `consent` to `"declined"` rather than `"undecided"`. GPC does not
+write the cookie; see [Cookie behavior](#cookie-behavior).
+
+Theme with `--wa-banner-*` variables on `.wa-banner`:
+
+```css
+.wa-banner {
+  --wa-banner-background-color: var(--color-seashell);
+  --wa-banner-font-family: var(--font-primary);
+  --wa-banner-accept-background-color: var(--color-plum-p4);
+}
+```
+
+- Background, text, and border: `--wa-banner-background-color`,
+  `--wa-banner-text-color`, `--wa-banner-border-color`,
+  `--wa-banner-border-radius`, `--wa-banner-box-shadow`,
+  `--wa-banner-backdrop-filter`
+- Type and layout: `--wa-banner-font-family`, `--wa-banner-font-size`,
+  `--wa-banner-padding`, `--wa-banner-max-width`, `--wa-banner-action-gap`,
+  `--wa-banner-z-index`
+- Link and focus: `--wa-banner-link-color`, `--wa-banner-focus-color`
+- Buttons: `--wa-banner-button-border-radius`, `--wa-banner-button-padding`,
+  `--wa-banner-button-min-height`, `--wa-banner-button-font-size`,
+  `--wa-banner-button-font-weight`, `--wa-banner-button-line-height`
+- Accept button: `--wa-banner-accept-background-color`, `--wa-banner-accept-text-color`,
+  `--wa-banner-accept-hover-background-color`
+- Decline button: `--wa-banner-decline-background-color`,
+  `--wa-banner-decline-text-color`, `--wa-banner-decline-hover-background-color`
+
+### `Consented`
+
+Renders children only when `consent` is `"consented"`. It renders nothing during
+SSR, while consent is still `"unknown"` or `"undecided"`, if the visitor
+declined, or while Global Privacy Control is on.
+
+```tsx
+import { Consented } from "@convex-internal/web-analytics";
+
+<Consented>
+  <YourAnalyticsScripts />
+</Consented>;
+```
+
+### `useConsent`
+
+- `consent` (`ConsentStatus`)
+  - `"unknown"` until cookie has been read (SSR and first client render)
+  - `"undecided"` after that if there is no recognized choice yet
+  - `"consented"` if the cookie is `true` and GPC is not set
+  - `"declined"` if the cookie is `false` or GPC is set
+- `setConsent("consented" | "declined")`
+  - Saves the choice to the `allowsCookies` cookie and updates context
+  - Do not write the cookie yourself
+
+Use the hook when you need `consent` or `setConsent` directly. Enable tracking
+only when `consent === "consented"`.
+
+### Cookie behavior
+
+Once the cookie has been read, `consent` is resolved in this order:
+
+1. **Global Privacy Control.** If `navigator.globalPrivacyControl === true`,
+   `consent` is `"declined"`. GPC is not stored: the cookie is not written or
+   changed. Turn GPC off and the stored cookie (if set) applies again.
+2. **Cookie.** `true` is `"consented"`, `false` is `"declined"`, and a missing
+   or unrecognized value is `"undecided"`.
+
+The cookie is stored with `path=/` and a max-age of one year. On `convex.dev`
+and `*.convex.dev` it is also set with `domain=.convex.dev` so the website,
+Docs, Stack, and other subdomains share one choice. The cookie is marked
+`Secure` everywhere except localhost.
+
+Changes made through `setConsent` update immediately. Changes made
+elsewhere, such as in another tab or DevTools, are synchronized through cookie
+change events when available, and when the window regains focus or its
+visibility changes as a fallback.
+
+## Test in-development changes
+
+1. In the `web-analytics` repo, build and pack the package:
+
+```bash
+cd /path/to/web-analytics
+npm run build
+npm pack
+```
+
+This creates a tarball such as `convex-internal-web-analytics-1.0.0.tgz`.
+
+1. Install that tarball in the consuming app:
+
+```bash
+cd /path/to/consuming-app
+npm install /path/to/web-analytics/convex-internal-web-analytics-1.0.0.tgz --force
+```
+
+`--force` ensures npm refreshes the package when the filename and version have
+not changed.
+
+## Publish a version to npm
+
+1. Confirm that you are signed in to the npm account with access to the
+   `@convex-internal` organization:
+
+```bash
+npm whoami
+```
+
+Run `npm login` first if needed.
+
+1. Commit any README or code changes, then bump the version. `npm version`
+   requires a clean Git worktree and creates a version commit and tag.
+
+```bash
+npm version major   # breaking, or 0.x → 1.0.0
+npm version minor   # new backwards-compatible functionality
+npm version patch   # bug fixes
+```
+
+1. Run tests, inspect the package contents, then publish. `.npmrc` sets
+   `ignore-scripts=true`, so `prepack` will not run — build first:
+
+```bash
+npm test
+npm run build
+npm pack --dry-run
+npm publish --access public
+```
+
+If npm 2FA is enabled, add `--otp=<code>`.
+
+## Consume a published version
+
+Convex repos set `min-release-age=7` in `.npmrc`, so a version published in
+the last 7 days will fail to install (including `npm ci` in CI). Override
+the window for the install, then exclude this package so later installs
+succeed:
+
+```bash
+npm install @convex-internal/web-analytics@<version> --min-release-age=0
+```
+
+```
+# consuming-app/.npmrc
+min-release-age-exclude[]=@convex-internal/web-analytics
+```
+
+You can drop the exclude once this version has been on npm for 7 days.
+
+Use the local tarball workflow whenever you need to test changes that have
+not been published yet.

package/dist/ConsentBanner.d.ts

@@ -0,0 +1,2 @@
+import "./banner.css";
+export declare function ConsentBanner(): import("react").JSX.Element | null;

package/dist/ConsentBanner.js

@@ -0,0 +1,31 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { capture } from "./capture.js";
+import { useConsent } from "./useConsent.js";
+import "./banner.css";
+export function ConsentBanner() {
+    const { consent, setConsent } = useConsent();
+    const shouldShow = consent === "undecided";
+    const wasShowing = useRef(false);
+    useEffect(() => {
+        if (shouldShow && !wasShowing.current) {
+            // Captures once when the banner becomes visible, not on later renders.
+            capture("cookie_consent_shown");
+        }
+        wasShowing.current = shouldShow;
+    }, [shouldShow]);
+    if (!shouldShow) {
+        return null;
+    }
+    const decide = (decision) => {
+        try {
+            // Captures before the cookie write so decline is captured cookieless.
+            capture("cookie_consent_decided", { decision });
+        }
+        finally {
+            setConsent(decision === "accepted" ? "consented" : "declined");
+        }
+    };
+    return (_jsxs("aside", { "aria-label": "Privacy choices", className: "wa-banner", children: [_jsx("p", { className: "wa-banner-text", children: "We use cookies and similar technologies to understand how people interact with our site." }), _jsxs("p", { className: "wa-banner-text wa-banner-policy", children: ["See our", " ", _jsx("a", { className: "wa-banner-link", href: "https://www.convex.dev/legal/privacy", rel: "noopener noreferrer", target: "_blank", children: "Privacy Policy" }), " ", "to learn more."] }), _jsxs("div", { className: "wa-banner-actions", children: [_jsx("button", { className: "wa-banner-button wa-banner-decline", onClick: () => decide("declined"), type: "button", children: "Decline" }), _jsx("button", { className: "wa-banner-button wa-banner-accept", onClick: () => decide("accepted"), type: "button", children: "Accept" })] })] }));
+}

package/dist/Consented.d.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from "react";
+export interface ConsentedProps {
+    children: ReactNode;
+}
+export declare function Consented({ children }: ConsentedProps): ReactNode;

package/dist/Consented.js

@@ -0,0 +1,9 @@
+"use client";
+import { useConsent } from "./useConsent.js";
+export function Consented({ children }) {
+    const { consent } = useConsent();
+    if (consent !== "consented") {
+        return null;
+    }
+    return children;
+}

package/dist/WebAnalyticsProvider.d.ts

@@ -0,0 +1,22 @@
+import { type PostHogConfig } from "posthog-js";
+import { type ReactNode } from "react";
+export type { PostHogConfig };
+/**
+ * `"unknown"` until the cookie has been read on the client (SSR and first
+ * render). `"undecided"` when there is no recognized choice yet. `"consented"`
+ * when the cookie is `true` and Global Privacy Control (GPC) is not set.
+ * `"declined"` when the cookie is `false`, or while GPC is set.
+ *
+ * GPC does not write or change the cookie. If it is later turned off, the
+ * stored cookie (or the banner, if none) applies again.
+ */
+export type ConsentStatus = "unknown" | "undecided" | "consented" | "declined";
+export interface WebAnalyticsProviderProps {
+    children: ReactNode;
+    posthogConfig?: Partial<PostHogConfig>;
+}
+export declare const ConsentContext: import("react").Context<{
+    consent: ConsentStatus;
+    setConsent: (status: "consented" | "declined") => void;
+} | null>;
+export declare function WebAnalyticsProvider({ children, posthogConfig, }: WebAnalyticsProviderProps): import("react").JSX.Element;

package/dist/WebAnalyticsProvider.js

@@ -0,0 +1,88 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { posthog } from "posthog-js";
+import { PostHogProvider } from "posthog-js/react";
+import { createContext, useEffect } from "react";
+import { ConsentBanner } from "./ConsentBanner.js";
+import { useBooleanCookie } from "./useCookie.js";
+const COOKIE_NAME = "allowsCookies";
+const POSTHOG_KEY = "phc_JDNTRxeh2li2sQTRO0IcOYMJcp8fPs5nTK9TU751nQK";
+const POSTHOG_HOST = "https://ap.convex.dev";
+function resolveConsent(isReady, cookieValue, gpcOptOut) {
+    if (!isReady) {
+        return "unknown";
+    }
+    if (gpcOptOut) {
+        return "declined";
+    }
+    if (cookieValue === true) {
+        return "consented";
+    }
+    if (cookieValue === false) {
+        return "declined";
+    }
+    return "undecided";
+}
+export const ConsentContext = createContext(null);
+export function WebAnalyticsProvider({ children, posthogConfig, }) {
+    const { value, isReady, setValue } = useBooleanCookie(COOKIE_NAME);
+    const gpcOptOut = typeof navigator !== "undefined" && navigator.globalPrivacyControl === true;
+    const consent = resolveConsent(isReady, value, gpcOptOut);
+    useEffect(() => {
+        // Prevent PostHog from initializing in development or on localhost.
+        if (process.env.NODE_ENV !== "production" ||
+            window.location.hostname === "localhost" ||
+            window.location.hostname === "127.0.0.1" ||
+            window.location.hostname === "[::1]") {
+            return;
+        }
+        // If PostHog is already initialized, update its config.
+        if (posthog.__loaded) {
+            if (posthogConfig) {
+                posthog.set_config(posthogConfig);
+            }
+            return;
+        }
+        // Initialize PostHog.
+        posthog.init(POSTHOG_KEY, {
+            api_host: POSTHOG_HOST,
+            ui_host: "https://us.posthog.com/",
+            // Automatically capture navigations using the History API.
+            capture_pageview: "history_change",
+            // Together, these two settings capture cookieless events before the user
+            // chooses and continue doing so if they decline. Accepting enables persistent
+            // tracking. See more: https://posthog.com/tutorials/cookieless-tracking
+            opt_out_capturing_by_default: true,
+            cookieless_mode: "on_reject",
+            // Site-specific options to add or override the defaults.
+            ...posthogConfig,
+        });
+    }, [posthogConfig]);
+    // One-way sync: make PostHog match the resolved consent status.
+    useEffect(() => {
+        // No decision yet or PostHog is not initialized.
+        if (consent === "unknown" || consent === "undecided" || !posthog.__loaded) {
+            return;
+        }
+        const posthogConsent = posthog.get_explicit_consent_status();
+        const targetConsent = consent === "consented" ? "granted" : "denied";
+        if (posthogConsent === targetConsent) {
+            return;
+        }
+        if (consent === "consented") {
+            // Records an `$opt_in` event, which is distinct from ConsentBanner's
+            // `cookie_consent_decided` as it also fires when we sync an existing
+            // allowsCookies cookie for returning visitors.
+            posthog.opt_in_capturing();
+        }
+        else {
+            posthog.opt_out_capturing();
+        }
+    }, [consent]);
+    return (_jsxs(ConsentContext.Provider, { value: {
+            consent,
+            setConsent: (status) => {
+                setValue(status === "consented" ? "true" : "false");
+            },
+        }, children: [_jsx(PostHogProvider, { client: posthog, children: children }), _jsx(ConsentBanner, {})] }));
+}

package/dist/banner.css

@@ -0,0 +1,82 @@
+.wa-banner {
+  box-sizing: border-box;
+  position: fixed;
+  z-index: var(--wa-banner-z-index, 50);
+  inset-inline: 1rem;
+  bottom: 1rem;
+  padding: var(--wa-banner-padding, 1rem);
+  border: 1px solid var(--wa-banner-border-color, black);
+  border-radius: var(--wa-banner-border-radius, 0);
+  background-color: var(--wa-banner-background-color, white);
+  box-shadow: var(--wa-banner-box-shadow, none);
+  -webkit-backdrop-filter: var(--wa-banner-backdrop-filter, none);
+  backdrop-filter: var(--wa-banner-backdrop-filter, none);
+  color: var(--wa-banner-text-color, black);
+  font-family: var(--wa-banner-font-family, inherit);
+  font-size: var(--wa-banner-font-size, 1rem);
+
+  .wa-banner-text {
+    margin: 0 0 0.5rem;
+  }
+
+  .wa-banner-policy {
+    margin-bottom: 1rem;
+  }
+
+  .wa-banner-link {
+    color: var(--wa-banner-link-color, inherit);
+    text-decoration: underline;
+    text-underline-offset: 0.125rem;
+  }
+
+  .wa-banner-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: var(--wa-banner-action-gap, 0.5rem);
+  }
+
+  .wa-banner-button {
+    box-sizing: border-box;
+    min-height: var(--wa-banner-button-min-height, 2.75rem);
+    padding: var(--wa-banner-button-padding, 0.5rem 0.75rem);
+    border: 0;
+    border-radius: var(--wa-banner-button-border-radius, 0);
+    font-family: inherit;
+    font-size: var(--wa-banner-button-font-size, inherit);
+    font-weight: var(--wa-banner-button-font-weight, inherit);
+    line-height: var(--wa-banner-button-line-height, inherit);
+    cursor: pointer;
+    transition: background-color 0.15s;
+
+    &:focus-visible {
+      outline: 2px solid var(--wa-banner-focus-color, black);
+      outline-offset: 2px;
+    }
+
+    &.wa-banner-decline {
+      background-color: var(--wa-banner-decline-background-color, lightgray);
+      color: var(--wa-banner-decline-text-color, black);
+
+      &:hover {
+        background-color: var(
+          --wa-banner-decline-hover-background-color,
+          lightgray
+        );
+      }
+    }
+
+    &.wa-banner-accept {
+      background-color: var(--wa-banner-accept-background-color, black);
+      color: var(--wa-banner-accept-text-color, white);
+
+      &:hover {
+        background-color: var(--wa-banner-accept-hover-background-color, black);
+      }
+    }
+  }
+
+  @media (min-width: 40rem) {
+    inset-inline-start: auto;
+    max-width: var(--wa-banner-max-width, 24rem);
+  }
+}

package/dist/capture.d.ts

@@ -0,0 +1,3 @@
+import { type CaptureOptions } from "posthog-js";
+export type { CaptureOptions };
+export declare function capture(event: string, properties?: Record<string, unknown>, options?: CaptureOptions): void;

package/dist/capture.js

@@ -0,0 +1,5 @@
+"use client";
+import { posthog } from "posthog-js";
+export function capture(event, properties, options) {
+    posthog.capture(event, properties, options);
+}

package/dist/cookie.d.ts

@@ -0,0 +1,2 @@
+export declare function getCookie(name: string): string | undefined;
+export declare function setCookie(name: string, value: string): void;

package/dist/cookie.js

@@ -0,0 +1,23 @@
+const MAX_AGE = 365 * 24 * 60 * 60;
+export function getCookie(name) {
+    const row = document.cookie
+        .split("; ")
+        .find((part) => part.startsWith(`${name}=`));
+    if (!row) {
+        return undefined;
+    }
+    return row.slice(name.length + 1);
+}
+export function setCookie(name, value) {
+    const hostname = window.location.hostname;
+    const parts = [`${name}=${value}`, "path=/", `max-age=${MAX_AGE}`];
+    // Share cookies across the website, Docs, Stack, etc. When making changes
+    // to domain or cookie names, update those projects as well.
+    if (hostname === "convex.dev" || hostname.endsWith(".convex.dev")) {
+        parts.push("domain=.convex.dev");
+    }
+    if (hostname !== "localhost") {
+        parts.push("secure");
+    }
+    document.cookie = parts.join("; ");
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { WebAnalyticsProvider, type WebAnalyticsProviderProps, type PostHogConfig, type ConsentStatus, } from "./WebAnalyticsProvider.js";
+export { Consented, type ConsentedProps } from "./Consented.js";
+export { useConsent } from "./useConsent.js";
+export { capture, type CaptureOptions } from "./capture.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { WebAnalyticsProvider, } from "./WebAnalyticsProvider.js";
+export { Consented } from "./Consented.js";
+export { useConsent } from "./useConsent.js";
+export { capture } from "./capture.js";

package/dist/useConsent.d.ts

@@ -0,0 +1,4 @@
+export declare function useConsent(): {
+    consent: import("./WebAnalyticsProvider.js").ConsentStatus;
+    setConsent: (status: "consented" | "declined") => void;
+};

package/dist/useConsent.js

@@ -0,0 +1,10 @@
+"use client";
+import { useContext } from "react";
+import { ConsentContext } from "./WebAnalyticsProvider.js";
+export function useConsent() {
+    const context = useContext(ConsentContext);
+    if (context === null) {
+        throw new Error("useConsent must be used within WebAnalyticsProvider");
+    }
+    return context;
+}

package/dist/useCookie.d.ts

@@ -0,0 +1,10 @@
+export declare function useCookie<T extends string = string>(name: string): {
+    value: string | undefined;
+    setValue: (next: T) => void;
+    isReady: boolean;
+};
+export declare function useBooleanCookie(name: string): {
+    value: boolean | undefined;
+    isReady: boolean;
+    setValue: (next: "false" | "true") => void;
+};

package/dist/useCookie.js

@@ -0,0 +1,38 @@
+"use client";
+import { useCallback, useEffect, useState } from "react";
+import { getCookie, setCookie } from "./cookie.js";
+export function useCookie(name) {
+    const [value, setValueState] = useState(undefined);
+    const [isReady, setIsReady] = useState(false);
+    useEffect(() => {
+        const sync = () => {
+            setValueState(getCookie(name));
+            setIsReady(true);
+        };
+        const handleCookieChange = (event) => {
+            const changed = [...event.changed, ...event.deleted].some((cookie) => cookie.name === name);
+            if (changed) {
+                sync();
+            }
+        };
+        sync();
+        window.addEventListener("focus", sync);
+        document.addEventListener("visibilitychange", sync);
+        window.cookieStore?.addEventListener("change", handleCookieChange);
+        return () => {
+            window.removeEventListener("focus", sync);
+            document.removeEventListener("visibilitychange", sync);
+            window.cookieStore?.removeEventListener("change", handleCookieChange);
+        };
+    }, [name]);
+    const setValue = useCallback((next) => {
+        setCookie(name, next);
+        setValueState(next);
+    }, [name]);
+    return { value, setValue, isReady };
+}
+export function useBooleanCookie(name) {
+    const { value: raw, isReady, setValue } = useCookie(name);
+    const value = raw === "true" ? true : raw === "false" ? false : undefined;
+    return { value, isReady, setValue };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@convex-internal/web-analytics",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./banner.css": "./dist/banner.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && cp src/banner.css dist/banner.css",
+    "prepack": "npm run build",
+    "test": "vitest run"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "dependencies": {
+    "posthog-js": "^1.211.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "jsdom": "^30.0.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.8",
+    "typescript": "^5.9.2",
+    "vitest": "^4.1.10"
+  }
+}