Next.js boilerplate with PostHog

The catalogue is the only place an event name is born

src/lib/analytics/events.ts declares every event this repo sends. A capture call whose name is not in EventCatalogue does not compile, and that is the point: the alternative is a project that contains user_signed_up, userSignedUp, signup, Signup Completed and sign_up_success as five unrelated series, none of which has a full history.

• Never call posthog.capture() directly. Use capture() from @/lib/analytics/posthog-client in the browser and captureServer() from @/lib/analytics/posthog-server on the server. Both are typed against the catalogue and both strip personal data.
• Adding an event means editing events.ts first: the name, its property type, and its line in EVENT_QUESTIONS. The /add-event skill does all three.
• $pageview, $pageleave and autocapture events are PostHog's, not yours. Do not add them to the catalogue and do not fire them by hand; the provider in src/lib/analytics/provider.tsx owns page views.

Naming

object_verb, past tense, snake_case, checked by EVENT_NAME_PATTERN.

Write this	Not this	Why
subscription_started	startSubscription	Events are records of things that happened, not function calls
checkout_completed	checkout_complete	Past tense reads correctly in every funnel step label
project_created	create_project	Object first, so an alphabetical event list groups by object
onboarding_step_completed	onboarding_2_done	The step number is a property, never part of the name

Rules that follow from that table:

• Two words minimum: an object and a verb. clicked and error are not events.
• Never encode a value in the name. plan_pro_purchased and plan_team_purchased are one event with a plan property: otherwise every new plan silently breaks every chart.
• Never put an id, an email, a URL or a timestamp in a name.
• Pick the object's singular noun and stay with it. If the code calls it a project, the events say project_, not workspace_.

Properties

• Properties are dimensions you will group or filter by: plan, source, step, method, interval. Low cardinality, stable spelling, snake_case.
• Types come from the catalogue. Prefer a union of literals ("month" | "year") over string: it stops a typo becoming a permanent extra series in a breakdown.
• No PII. FORBIDDEN_PROPERTY_KEYS in events.ts is enforced at runtime by scrubProperties(); do not work around it by renaming email to user_contact.
• Never send a whole object. capture("project_created", { ...project }) ships every column the table gains in future, including ones added after this line was written.

Renaming an event is not free

A rename splits the history: charts built on the old name stop at the rename, charts built on the new one start there. If you must rename, fire both names for one full reporting period, migrate the insights, then delete the old one, and record the change in docs/solutions/posthog/, because the next person to see the seam in a graph will otherwise treat it as a product event.

The distinct id is your database id

• identifyViewer({ id }) from @/lib/analytics/identify takes the user's primary key from your database. Never the email, never a per-device uuid, never a session id. Emails change and sessions end; when they do, one person becomes two in every chart and the retention curve quietly lies.
• The same id is used on the server. captureServer({ distinctId: user.id }) and the browser's identify must agree, or a funnel that crosses the network boundary drops everyone at the crossing.

Timing

• Identify where the session is already loaded (the layout or provider that knows who the user is) not in the component that happens to need analytics.
• Identify before the first event you care about attributing. PostHog merges the current anonymous history into the person on identify, but only the current one: events captured in an earlier session, or after a full page load and before identify runs, stay on the anonymous profile forever.
• The order that works: session resolves → identifyViewer() → feature events. The order that loses data: page renders → signup_completed fires → an effect three levels down calls identify a tick later.
• Identify is idempotent here. identifyViewer() tracks the last id it saw, so re-rendering does not re-identify, and identifying a different id resets first rather than stitching two people together.

Sign-out

• Call resetViewer() in the sign-out path, always, before the redirect. Not calling it means the next person on that browser inherits the previous user's distinct id: a real problem on shared machines, demo laptops and support sessions, and one you cannot repair after the fact.
• Never call posthog.reset() on a route change, a token refresh or a failed request. Reset means "a different human is here now"; using it as a cache clear breaks every session that follows.

Person properties

• Set traits through identifyViewer({ traits }) or setViewerTraits() and keep them inside the ViewerTraits shape: plan, role, signup date, acquisition source, account id.
• Anything authoritative (plan, entitlement, role) is set from the server with identifyServer(), from the code that changed it. The browser is not a reliable narrator about a subscription.
• Do not put the email or the name on the profile in this repo. The join back to a human belongs in your database, where a deletion request is one statement.

Groups

• For a multi-tenant product, pass organisation to identifyViewer() and groups to captureServer(). Without it, "how many accounts activated" is unanswerable: you can only count users, and one account with forty seats looks like forty activations.

Which side fires it

A browser event is a claim. A server event is a record. Choose by asking what happens when the number is wrong.

Fire from the server (captureServer() in @/lib/analytics/posthog-server):

• anything involving money: subscription_started, subscription_cancelled, refunds, plan changes. These come from the payment webhook, which is the only place that knows a charge succeeded.
• anything about permissions, roles, quota or entitlement.
• anything whose absence is a bug you would investigate: account created, invite accepted, job completed, export delivered.
• anything that must be complete for a report someone else reads. Browser events are missing 10-30% of consumer traffic to ad blockers even with the /ingest proxy, plus everyone who closed the tab mid-request.

Fire from the browser (capture() in @/lib/analytics/posthog-client):

• intent and interface behaviour: pricing_viewed, checkout_started, signup_started, an empty state seen, a filter used.
• anything the server genuinely cannot see, which is most of what happens between two navigations.

Never fire the same event from both sides. Duplicated events double every count and there is no way to tell the copies apart afterwards. If a flow needs both, they are two events: checkout_started (browser, intent) and subscription_started (server, fact).

Never trust a value the client supplied

• captureServer() takes the distinct id and the properties from server state: the session, the database row, the webhook payload you verified. Never from a request body a client composed.
• A route handler that captures { plan: body.plan } is instrumenting what the browser claimed, not what was sold. Read the plan from the subscription you just wrote.
• An analytics call is never a reason to relax an authorisation check, and never runs before one.

No personal data in event properties

• Event properties are copied into every downstream tool, read by anyone with project access, and retained for years. FORBIDDEN_PROPERTY_KEYS in events.ts (email, name, phone, address, IP, tokens, card numbers) is stripped at runtime by scrubProperties(). Do not rename a field to sneak it past the list.
• No secrets, ever: no API keys, no session tokens, no signed URLs. An analytics payload is an exfiltration path with a nice dashboard on top.
• No free-text a user typed. A search query, a support message or a project description can contain anything, including someone else's personal data. Capture the length, the result count or a category instead.
• Ids are fine when they are your ids and mean nothing outside your database: account_id, project_id. A third-party id (Stripe customer, OAuth subject) is a join key to someone else's system: keep it out.

Analytics never breaks the product

• capture() and captureServer() do not throw and are never awaited in a request path. If PostHog is down, the checkout button still works.
• Do not put a capture call inside a database transaction, and do not let one block a redirect. captureServer() flushes with after() precisely so the response is already on its way.