docs(libraries): add Convex integration page#16978
Conversation
…g tutorial Walks through wiring the @posthog/convex component into a Convex backend, covering event capture from mutations and actions, identifying users against Convex auth, local and remote feature flag evaluation, and exception capture. Links out to the existing LLM analytics installation guide and Convex data warehouse source for adjacent surfaces. Adds matt-brooker author entry.
MattBro
requested review from
a team,
fercgomes and
rafaeelaudibert
and removed request for
a team
Deploy preview
|
|
Vale prose linter → found 0 errors, 12 warnings, 1 suggestions in your markdown Full report → Copy the linter results into an LLM to batch-fix issues. Linter being weird? Update the rules!
|
| Line | Severity | Message | Rule |
|---|---|---|---|
| 16:31 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 19:67 | warning | Capitalize 'Data Warehouse' for PostHog's product. Use 'data warehouse' for the general industry concept. | PostHogBase.ProductNames |
| 20:18 | warning | Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. | PostHogBase.ProductNames |
| 42:98 | warning | Use 'project token' instead of 'project API key'. The project token (phc_) is not an API key. | PostHogBase.ProjectToken |
| 49:132 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 93:68 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 150:17 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 152:180 | warning | 'reactively' is a possible misspelling. | PostHogBase.Spelling |
| 154:205 | warning | 'reactively' is a possible misspelling. | PostHogBase.Spelling |
| 329:203 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
| 331:238 | warning | Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. | PostHogBase.ProductNames |
| 333:4 | warning | 'Trace LLM calls and Convex Agent' heading should be in sentence case, and product names should be capitalized. | PostHogBase.SentenceCase |
| 341:72 | warning | Capitalize 'Data Warehouse' for PostHog's product. Use 'data warehouse' for the general industry concept. | PostHogBase.ProductNames |
…ctivity copy - /docs/llm-analytics/... was renamed to /docs/ai-observability/... on master - Clarify that the React re-render happens on the next cron refresh, not the moment the upstream flag changes
Renames convex-analytics.mdx to convex.mdx and restructures from a narrow product-analytics walkthrough into the single landing page for using PostHog with Convex. Per stakeholder feedback (Richard Solomou), the Convex-dashboard Logs and Error Tracking destinations are not duplicated here — they're surfaced in the decision matrix with direct links to docs.convex.dev. The principle: posthog.com docs cover things that require PostHog; Convex's docs cover things configured in Convex. New sections beyond the original tutorial: - Decision matrix at the top so a reader can route in 15 seconds - Frontend + backend identity stitching (posthog-js + @posthog/react) - AI observability summary + link - Warehouse source summary + link React example uses the canonical posthog.init() + @posthog/react pattern documented at contents/docs/libraries/react/index.mdx.
MattBro
changed the title
- Fix broken anchor on labs.convex.dev (use-authentication-data-in-functions was renamed to use-authentication-state-in-backend-functions) - Tighten 6 sentences flagged by tone review: marketing words removed, filler clauses dropped, sentence rhythm shortened to match recent tutorials - Add two screenshot placeholders (Convex Integrations tab; PostHog AI observability trace view) as JSX comments, so the structure is ready when images land
The Convex page is shaped like a platform-partner hub, not a single-task tutorial. Move it alongside lovable, replit, v0, and vercel-marketplace where it belongs. - git mv contents/tutorials/convex.mdx -> contents/docs/integrations/convex.mdx - Frontmatter switched from tutorial schema (title, date, author, tags, showTitle) to integration schema (title, sidebarTitle) - Add a Convex entry under Platforms in src/navs/index.js, alongside Lovable / Replit / v0 - Add vercel.json redirects from /tutorials/convex and /tutorials/convex-analytics to the new path No content changes other than frontmatter; the body is unchanged from the prior commit.
MattBro
changed the title
|
For some reason this shows up under the MCP dropdown instead of having a dedicated Integrations dropdown |
…holder comments Generated-By: PostHog Code Task-Id: 844d28da-21d9-441e-b7bd-8bb56745e775
@richardsolomou flagged that /docs/integrations/convex was surfacing under "AI Engineering > MCP > Platforms" in the sidebar, alongside Lovable / Replit / v0. Those are MCP host platforms; Convex is a backend framework. Wrong nav neighborhood, bad discoverability. Move to /docs/libraries/convex.mdx, the slot where Vercel, Cloudflare Workers, Hono, etc. live. Convex is now listed under "Frameworks" alphabetically between Cloudflare Workers and Django. - git mv contents/docs/integrations/convex.mdx -> contents/docs/libraries/convex.mdx - Frontmatter changed to match library page convention: title: Convex, platformLogo: convex (drops sidebarTitle, which the libraries template doesn't use) - src/navs/index.js: remove the MCP/Platforms entry, add to Frameworks - vercel.json: add /docs/integrations/convex -> /docs/libraries/convex redirect; update existing /tutorials/convex(-analytics) redirects to point to the new path
MattBro
changed the title
moved to 
|
| { | ||
| "handle": "matt-brooker", | ||
| "name": "Matt Brooker", | ||
| "role": "Growth Engineer" | ||
| } |
There was a problem hiding this comment.
Can you fill your profile_id too? That will make it link properly
There was a problem hiding this comment.
On it, looking it up.
| - **Local** (`getFeatureFlag`, `isFeatureEnabled`) runs against flag definitions cached on your Convex deployment. Works in queries, mutations, and actions, with no per-call network round-trip. Queries that read a flag re-run reactively when the cached definitions refresh. | ||
| - **Remote** (`evaluateFlag`, `evaluateAllFlags`) hits PostHog's `/flags` endpoint on every call. Action-only, handles every flag (including experience continuity flags and static cohorts that local eval can't reach). | ||
|
|
||
| To enable local eval, add a cron that refreshes flag definitions on whatever interval suits you: |
There was a problem hiding this comment.
@richardsolomou can't we do this automatically for our users, please? I'm sure the other convex components I've used in the past declared such things automatically. Maybe make it optional somehow?
There was a problem hiding this comment.
Looked into it. Convex components do support auto-registering crons (action-retrier and persistent-text-streaming both ship a src/component/crons.ts). It's a library change in @posthog/convex rather than a docs fix. @richardsolomou, want to take a look? Happy to update the page once the library auto-registers.
There was a problem hiding this comment.
Partly right. Components can have crons, but components have never had access to environment variables directly (as per their sandboxing rules) to be able to set them up with specific parameters, which is something we'd need since the cron would use your PAK to update the flags. You needed to instantiate components with the environment variables, and then that would need to go and do its magic (but then you would need crons that instantiate dynamically instead of statically, which AFAIK is not possible). So, if you wanted a component with a cron that utilized something with an env var (in this case, POSTHOG_PERSONAL_API_KEY), components have always had to ask users to do this on the app-level.
Buuuut, Convex just shipped the ability to do this in-component late last week. Relevant Slack thread. They made it so that with v1.39, components can inherit env vars from the application-level so you don't have to set them up manually, which makes this use-case (and so many more) possible (though it's still not an implicit inheritance, it's still explicit, just at a higher level). It's super important to note though that they did, however, specifically warn us against it, as, and I quote, "free-tier users may complain if they have a bunch of idle dev deployments with crons using resources every minute".
So, this does make sense, but:
- We'd need to change how the component works to make it so that the user can define
featureFlagsPollingIntervalsimilar toposthog-node - This is so that we can reference their
POSTHOG_PERSONAL_API_KEYincrons.tsin the component-level - This means that we should throw errors if the user tries to use the local eval methods without having set up a PAK or a polling interval
- And all of this would essentially be a major version update to the component to avoid confusion with making the existing env vars optional.
- There is a world where we can support both approaches, and that might be the way forward, but like Ian said in the thread, we're early enough in the component's lifetime that it might just be a better idea to just switch over to the new way of doing things and just make a new major version.
So I'll take that as feedback for our Convex component and will investigate how we can do this properly, without unintended side-effects for users, and while keeping it close to how posthog-node does things, but it's not quite as simple as it sounds, so for the purposes of this PR, I think we can ship the docs as is.
Sorry for the long wall of text, it's a bit hard to explain otherwise. Happy to hear your thoughts and pushback, otherwise I'll start working on a v2 with all this in mind!
There was a problem hiding this comment.
Awesome! Let's merge that, and then work on this PR after we've merged v2
There was a problem hiding this comment.
This looks very different from most other library files.
- Remove accidentally-committed .claude/settings.local.json (came in via
Richard's screenshots commit, empty {})
- Remove the three convex redirects from vercel.json per editorial team
preference
- Wrap install commands in <MultiLanguage> blocks (npm / Yarn / pnpm /
Bun) for both @posthog/convex and the posthog-js + @posthog/react
pair
- Add a one-line "default to local, fall back to remote when..." rule
above the local-vs-remote bullets so the choice is obvious at first
read
- Move the local-eval-can't-resolve fallback into a CalloutBox so it
reads as an addendum rather than a top-level paragraph
- Frontend stitching: clarify that the React example is illustrative
and the same identity-stitching technique works with any JS framework
- Drop the "Use captureException here" wording per Rafa's suggestion
- Remove the trailing "file an issue" sentence
|
|
||
| Every integration on this page needs the same two values: | ||
|
|
||
| - **Project token**, starts with `phc_`. Found in PostHog under **Settings → Project → General → Project API Key**. |
There was a problem hiding this comment.
Pretty sure it's just "Project token" now, not "Project API Key"
rafaeelaudibert
left a comment
rafaeelaudibert
left a comment
There was a problem hiding this comment.
Let's wait until PostHog/posthog-js#3662 is merged, and we can then document it properly with the new usage
3 participants
Changes
Adds
contents/docs/libraries/convex.mdx, a single landing page covering every PostHog + Convex integration surface. The page sits under Frameworks alongsidevercel.mdx,cloudflare-workers.mdx,hono.mdx, and the other backend platform/framework pages.Also adds:
Convexentry under Frameworks insrc/navs/index.js, alphabetically between Cloudflare Workers and Djangovercel.jsonredirects from/tutorials/convex,/tutorials/convex-analytics, and/docs/integrations/convexto the new pathWhy this lives under libraries, not tutorials or integrations
tags:and don't get individual sidebar entries. The Convex hub is too broad and too high-stakes to live in tag-based discovery./docs/integrations/folder is currently a mix of MCP host platforms (Lovable, Replit, v0) and marketplace flows (Vercel Marketplace). Convex isn't an MCP host, so placing it there put the nav entry underAI Engineering → MCP → Platforms, which was misleading./docs/libraries/is the actual catch-all for "integrate PostHog with X" pages, including platforms (Cloudflare Workers, Vercel) that are shaped the same as our Convex hub. The Vercel page in particular covers multiple surfaces (Vercel Functions, AI SDK, Flags SDK) the same way ours does.Sections
@posthog/convexv1.0.5 (install, capture, identify against Convex Auth, local + remote feature flags,captureException)posthog-js+@posthog/reactplus anAuthSynccomponent/docs/ai-observability/installation/convex/docs/cdp/sources/convexWhat's intentionally not on this page
Convex-dashboard Logs and Error Tracking setup steps are not duplicated. The decision matrix links out to
docs.convex.devfor those flows. Principle: posthog.com covers what requires PostHog; Convex's docs cover what's configured in Convex. Avoids drift if Convex changes their UI.Code accuracy
@posthog/convexexamples verified against the v1.0.5 source (constructor, capture, identify, getFeatureFlag, refreshFlagDefinitions, captureException withadditionalProperties).posthog.init()+<PostHogProvider client={posthog}>from@posthog/react, matchingcontents/docs/libraries/react/index.mdx.labs.convex.devanchor fixed.Screenshots
@richardsolomou contributed screenshots of both Convex dashboard PostHog configuration forms (Logs and Error Tracking) directly to the PR.
Checklist
vercel.json