From bd0d20cd85a760af1a9674011086a2279b00bec9 Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Thu, 26 Mar 2026 08:16:00 +0100 Subject: [PATCH 1/2] docs: add PostHog analytics migration guide --- MIGRATIONS.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/MIGRATIONS.md b/MIGRATIONS.md index 36fa35959..39dd483a7 100644 --- a/MIGRATIONS.md +++ b/MIGRATIONS.md @@ -4,6 +4,47 @@ Breaking changes and upgrade notes for downstream projects. --- +## PostHog Analytics (2026-03-26) + +Server-side analytics, user/org identification, API auto-capture, and feature flags via PostHog. + +### New module + +`modules/analytics/` — auto-discovered, no manual registration needed. + +### Configuration + +Uncomment and set in your env-specific config (e.g. `modules/analytics/config/analytics.development.config.js`): + +```js +posthog: { + apiKey: process.env.DEVKIT_NODE_posthog_apiKey ?? '', + host: process.env.DEVKIT_NODE_posthog_host ?? 'https://us.i.posthog.com', + personalApiKey: process.env.DEVKIT_NODE_posthog_personalApiKey ?? '', +} +``` + +All features are no-op when `apiKey` is empty — safe to deploy without PostHog. + +### What's included + +| Feature | File | Notes | +|---------|------|-------| +| Analytics service | `analytics.service.js` | `track()`, `identify()`, `groupIdentify()` | +| Auto-capture middleware | `analytics.middleware.js` | Captures `api_request` on all routes (except health/public) | +| Feature flags service | `analytics.featureFlags.service.js` | `isEnabled()`, `getVariant()` — fails open when not configured | +| `requireFeatureFlag` middleware | `analytics.requireFeatureFlag.js` | 403 when flag disabled, allows when analytics not configured | +| Billing integration | `analytics.init.js` | Listens to `plan.changed` event → `groupIdentify` | + +### Action for downstream + +1. Run `/update-stack` to pull the new module +2. Set env vars: `DEVKIT_NODE_posthog_apiKey`, `DEVKIT_NODE_posthog_host` +3. Optionally set `DEVKIT_NODE_posthog_personalApiKey` for local feature flag evaluation +4. No DB migration needed — all data stored in PostHog + +--- + ## Organizations & CASL v2 (2026-03-13) This guide is for downstream projects (e.g. lou-node, pierreb-node) migrating to the new organizations + CASL document-level authorization system introduced on the `feature/signup-org-flow` branch. From 896ca9d088d9e4d050cf3e0d45536d200b3d8e8d Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Thu, 26 Mar 2026 08:24:10 +0100 Subject: [PATCH 2/2] fix(docs): address review comments on analytics migration guide - Correct feature flags service description: isEnabled() returns false (not fails-open) - Document requireFeatureFlag 401 for unauthenticated users - Remove undocumented personalApiKey references (not wired into PostHog client) --- MIGRATIONS.md | 8 +++----- modules/analytics/config/analytics.development.config.js | 1 - 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/MIGRATIONS.md b/MIGRATIONS.md index 39dd483a7..2c5e83dc9 100644 --- a/MIGRATIONS.md +++ b/MIGRATIONS.md @@ -20,7 +20,6 @@ Uncomment and set in your env-specific config (e.g. `modules/analytics/config/an posthog: { apiKey: process.env.DEVKIT_NODE_posthog_apiKey ?? '', host: process.env.DEVKIT_NODE_posthog_host ?? 'https://us.i.posthog.com', - personalApiKey: process.env.DEVKIT_NODE_posthog_personalApiKey ?? '', } ``` @@ -32,16 +31,15 @@ All features are no-op when `apiKey` is empty — safe to deploy without PostHog |---------|------|-------| | Analytics service | `analytics.service.js` | `track()`, `identify()`, `groupIdentify()` | | Auto-capture middleware | `analytics.middleware.js` | Captures `api_request` on all routes (except health/public) | -| Feature flags service | `analytics.featureFlags.service.js` | `isEnabled()`, `getVariant()` — fails open when not configured | -| `requireFeatureFlag` middleware | `analytics.requireFeatureFlag.js` | 403 when flag disabled, allows when analytics not configured | +| Feature flags service | `analytics.featureFlags.service.js` | `isEnabled()` (safe default `false` when not configured), `getVariant()` (`undefined` when not configured) | +| `requireFeatureFlag` middleware | `analytics.requireFeatureFlag.js` | 401 when unauthenticated, 403 when flag disabled, fail-open when analytics not configured | | Billing integration | `analytics.init.js` | Listens to `plan.changed` event → `groupIdentify` | ### Action for downstream 1. Run `/update-stack` to pull the new module 2. Set env vars: `DEVKIT_NODE_posthog_apiKey`, `DEVKIT_NODE_posthog_host` -3. Optionally set `DEVKIT_NODE_posthog_personalApiKey` for local feature flag evaluation -4. No DB migration needed — all data stored in PostHog +3. No DB migration needed — all data stored in PostHog --- diff --git a/modules/analytics/config/analytics.development.config.js b/modules/analytics/config/analytics.development.config.js index e24df3e92..7e569f51f 100644 --- a/modules/analytics/config/analytics.development.config.js +++ b/modules/analytics/config/analytics.development.config.js @@ -2,7 +2,6 @@ const config = { posthog: { // apiKey: process.env.DEVKIT_NODE_posthog_apiKey ?? '', // host: process.env.DEVKIT_NODE_posthog_host ?? 'https://us.i.posthog.com', - // personalApiKey: process.env.DEVKIT_NODE_posthog_personalApiKey ?? '', }, };