PostHog

Product analytics, feature flags and session replay.

adds it to an existing project · no account needed
Currentas published in v1.5.1

The rule

This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.

Event naming

object_action, past tense, snake_case:

ts
posthog.capture('subscription_started', { plan: 'annual', source: 'paywall' });
  • Never put a value in the name. plan_selected with a plan property, not plan_selected_annual.
  • Never invent a second convention. Renaming events later does not backfill history, so inconsistency is permanent.

What to track

  • Track decisions and outcomes, not every tap. If you cannot name the question an event answers, do not add it.
  • Analytics calls go through src/services/analytics/, never directly from a component.

Privacy

  • No personal data in properties: no email, name, phone number, address, or message content.
  • Identify by internal user id only.
  • posthog.reset() on sign-out — without it the next user on a shared device inherits the previous person's identity.

Feature flags

  • Never block first render on a flag. Render the default and update when the flag arrives.
  • Always handle the "flag unavailable" case explicitly; the fetch can fail.
  • Remove a flag from the code once it has fully rolled out. Stale flags become permanent dead branches.

Never

  • Never let an analytics failure break a user flow. Wrap it, and let it fail silently.
  • Never send an event containing a token, key or session id.
  • Never point a development build at the production project.

6 formats, one per tool

Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.

.cursor/rules/posthog.mdchand-written
---
description: PostHog analytics conventions
globs: ["src/**/*.ts", "src/**/*.tsx"]
alwaysApply: false
---

# PostHog

## Event naming

`object_action`, past tense, snake_case:

```ts
posthog.capture('subscription_started', { plan: 'annual', source: 'paywall' });
```

- Never put a value in the name. `plan_selected` with a `plan` property, not
  `plan_selected_annual`.
- Never invent a second convention. Renaming events later does not backfill
  history, so inconsistency is permanent.

## What to track

- Track decisions and outcomes, not every tap. If you cannot name the question
  an event answers, do not add it.
- Analytics calls go through `src/services/analytics/`, never directly from a
  component.

## Privacy

- No personal data in properties: no email, name, phone number, address, or
  message content.
- Identify by internal user id only.
- `posthog.reset()` on sign-out — without it the next user on a shared device
  inherits the previous person's identity.

## Feature flags

- Never block first render on a flag. Render the default and update when the
  flag arrives.
- Always handle the "flag unavailable" case explicitly; the fetch can fail.
- Remove a flag from the code once it has fully rolled out. Stale flags become
  permanent dead branches.

## Never

- Never let an analytics failure break a user flow. Wrap it, and let it fail
  silently.
- Never send an event containing a token, key or session id.
- Never point a development build at the production project.

Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.

What else this module writes

The rule is one file of several. Selecting PostHog contributes all of this too — merged with every other module you pick, with conflicts resolved rather than duplicated.

Environment
{{envPrefix}}POSTHOG_KEYrequiredProject API key. Write-only, safe in the client.
{{envPrefix}}POSTHOG_HOSTrequiredIngestion host. Replace `<region>` with `eu` or `us` — this decides where your data is stored, so choose deliberately.
POSTHOG_PERSONAL_API_KEYoptionalServer-side API access. Never ship in the app.
Dependencies
Depends on the rest of the stack — this module installs different packages depending on what else you select, so there is no single list to show.
Folders
src/services/analytics/

Advisory history

Every time this rule turned out to be wrong, and what we did about it.

No corrections yet

This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.

Pro tells you the day a correction lands that affects a repo you actually have.

See what Pro adds →
Put this rule in a real project

The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.