Skip to content

Conversation

@edwinyjlim
Copy link
Member

@edwinyjlim edwinyjlim commented Dec 7, 2025

Resources manifest
{
  "version": "1.0",
  "buildVersion": "dev",
  "buildTimestamp": "2025-12-07T21:20:06.738Z",
  "resources": {
    "workflows": [
      {
        "id": "basic-integration-begin",
        "name": "PostHog Setup - Begin",
        "description": "Start the event tracking setup process by analyzing the project and creating an event tracking plan",
        "file": "prompts/basic-integration/1.0-begin.md",
        "order": 1,
        "uri": "posthog://workflows/basic-integration/begin",
        "nextStepId": "basic-integration-edit",
        "nextStepUri": "posthog://workflows/basic-integration/edit"
      },
      {
        "id": "basic-integration-edit",
        "name": "PostHog Setup - Edit",
        "description": "Implement PostHog event tracking in the identified files, following best practices and the example project",
        "file": "prompts/basic-integration/1.1-edit.md",
        "order": 1.1,
        "uri": "posthog://workflows/basic-integration/edit",
        "nextStepId": "basic-integration-revise",
        "nextStepUri": "posthog://workflows/basic-integration/revise"
      },
      {
        "id": "basic-integration-revise",
        "name": "PostHog Setup - Revise",
        "description": "Review and fix any errors in the PostHog integration implementation",
        "file": "prompts/basic-integration/1.2-revise.md",
        "order": 1.2,
        "uri": "posthog://workflows/basic-integration/revise"
      },
      {
        "id": "legacy-setup-begin",
        "name": "Event Setup - Begin (Legacy URI)",
        "description": "Start the event tracking setup process (legacy URI for backward compatibility)",
        "file": "prompts/basic-integration/1.0-begin.md",
        "order": 1,
        "uri": "posthog://integration/workflow/setup/begin",
        "nextStepId": "basic-integration-edit",
        "nextStepUri": "posthog://workflows/basic-integration/edit"
      }
    ],
    "docs": [
      {
        "id": "identify",
        "name": "Identify Users docs",
        "description": "PostHog documentation on identifying users",
        "uri": "posthog://docs/identify",
        "url": "https://posthog.com/docs/getting-started/identify-users.md"
      }
    ],
    "prompts": [
      {
        "id": "posthog-setup",
        "name": "posthog-setup",
        "title": "Setup a deep PostHog integration",
        "description": "Automatically instrument your project with PostHog event tracking, user identification, and error tracking. Available frameworks: nextjs-app-router, nextjs-pages-router, react-react-router",
        "messages": [
          {
            "role": "user",
            "content": {
              "type": "text",
              "text": "Setup automatic PostHog event tracking in this project.\n\nUse these MCP resources:\n- posthog://workflows/basic-integration/begin - The event setup workflow guide (start here)\n- posthog://docs/frameworks/{framework} - Integration documentation per framework\n- posthog://examples/{framework} - Example projects with known-good PostHog integrations\n\nFollow the workflow guide to implement a deep PostHog integration."
            }
          },
          {
            "role": "assistant",
            "content": {
              "type": "text",
              "text": "I'll set up PostHog event tracking in your project using the provided workflow guide and documentation."
            }
          }
        ]
      }
    ]
  },
  "templates": [
    {
      "name": "PostHog example projects",
      "uriPattern": "posthog://examples/{framework}",
      "description": "Example project code showing PostHog integration for various frameworks",
      "parameterName": "framework",
      "items": [
        {
          "id": "nextjs-app-router",
          "file": "nextjs-app-router.md"
        },
        {
          "id": "nextjs-pages-router",
          "file": "nextjs-pages-router.md"
        },
        {
          "id": "react-react-router",
          "file": "react-react-router.md"
        }
      ]
    },
    {
      "name": "PostHog framework integration documentation",
      "uriPattern": "posthog://docs/frameworks/{framework}",
      "description": "PostHog integration documentation for various frameworks",
      "parameterName": "framework",
      "items": [
        {
          "id": "nextjs-app-router",
          "url": "https://posthog.com/docs/libraries/next-js.md"
        },
        {
          "id": "nextjs-pages-router",
          "url": "https://posthog.com/docs/libraries/next-js.md"
        },
        {
          "id": "react-react-router",
          "url": "https://posthog.com/docs/libraries/react.md"
        }
      ]
    }
  ]
}

@edwinyjlim
Copy link
Member Author

Now I have all the information needed to evaluate this PR. Let me produce the comprehensive review:


PR Evaluation Report

Summary

This PR adds PostHog analytics integration to a Next.js 15 Pages Router todo application. It includes client-side initialization via instrumentation-client.ts, server-side tracking with posthog-node, reverse proxy configuration, and comprehensive event tracking across todo CRUD operations and API routes.

Files changed Lines added Lines removed
8 +258 -0

Confidence score: 2/5 ❌

  • PostHog SDK packages not installed: posthog-js and posthog-node are not listed in package.json dependencies. The app will fail to build. [CRITICAL]
  • Client-side PostHog initialization not loaded: instrumentation-client.ts is created but never imported in _app.tsx. PostHog client won't initialize and all posthog.capture() calls will fail silently. [CRITICAL]
  • Invalid PostHog config option: defaults: '2025-05-24' is not a valid PostHog configuration option. This will cause initialization warnings/errors. [MEDIUM]

File changes

Filename Score Description
.posthog-events.json 4/5 Well-documented event catalog with 14 events covering CRUD operations and errors
components/todos/todo-list.tsx 3/5 Adds PostHog tracking for all todo operations with exception capture, but relies on uninitialized client
instrumentation-client.ts 2/5 PostHog client init created but uses invalid defaults option and file is never loaded
lib/posthog-server.ts 4/5 Proper singleton pattern for server-side PostHog client with shutdown handling
next.config.ts 5/5 Correctly configured reverse proxy rewrites for PostHog to bypass ad blockers
pages/about.tsx 3/5 Adds page view tracking but relies on uninitialized client
pages/api/todos/[id].ts 3/5 Server-side tracking for update/delete errors with good properties, uses hardcoded 'anonymous' distinctId
pages/api/todos/index.ts 3/5 Server-side tracking for create/validation errors, uses hardcoded 'anonymous' distinctId

App sanity check: 2/5 ❌

Criteria Result Description
App builds and runs No Missing posthog-js and posthog-node dependencies in package.json will cause build failure
Preserves existing env vars & configs Yes Environment variables present in .env, no existing configs broken
No syntax or type errors No Invalid defaults option in PostHog init; missing package imports will cause TypeScript errors
Correct imports/exports No instrumentation-client.ts is never imported; PostHog imports will fail without packages
Minimal, focused changes Yes Changes are focused on PostHog integration only

Issues

  • Missing PostHog packages: posthog-js and posthog-node must be added to package.json dependencies. Run npm install posthog-js posthog-node. [CRITICAL]
  • Client not initialized on app load: instrumentation-client.ts must be imported in pages/_app.tsx to initialize PostHog client. Without this, all client-side tracking will fail silently. [CRITICAL]
  • Invalid config option: defaults: '2025-05-24' is not a valid PostHog JS configuration option. Remove this line. [MEDIUM]

Other completed criteria

  • Existing app code structure preserved
  • TypeScript types maintained
  • Comments added explaining PostHog tracking purpose
  • No PII exposed in tracked events

PostHog implementation: 3/5 ⚠️

Criteria Result Description
PostHog SDKs installed No posthog-js and posthog-node not in package.json dependencies
PostHog client initialized Partial instrumentation-client.ts has init code but file is never imported in _app.tsx
capture() Yes 14 custom events tracked across client and server
identify() No No user identification implemented
Error tracking Yes captureException() calls in client code; capture_exceptions: true in config
Reverse proxy Yes Correctly configured in next.config.ts with /ingest rewrites to PostHog

Issues

  • SDK packages missing from package.json: Application will not build without posthog-js and posthog-node installed. [CRITICAL]
  • Client initialization not loaded: instrumentation-client.ts exists but is never imported. Add import '@/instrumentation-client' to pages/_app.tsx. [CRITICAL]
  • Invalid defaults option: Remove defaults: '2025-05-24' from PostHog init - this is not a valid option. [MEDIUM]
  • No user identification: All server-side events use hardcoded distinctId: 'anonymous'. Consider implementing proper user identification for meaningful analytics. [MEDIUM]
  • Server-side host config mismatch: posthog-server.ts uses NEXT_PUBLIC_POSTHOG_HOST but should bypass the reverse proxy for server-to-server calls. Currently set to https://us.i.posthog.com which is correct. [LOW]

Other completed criteria

  • Correct API host configuration (/ingest for client, direct host for server)
  • Debug mode enabled in development
  • Exception capture enabled
  • Proper singleton pattern for server-side client
  • Shutdown handler provided for server client
  • skipTrailingSlashRedirect set for PostHog compatibility
  • Static asset rewrites included for reverse proxy

PostHog insights and events: 4/5 ✅

Filename PostHog events Description
todo-list.tsx todo_created, todo_completed, todo_uncompleted, todo_deleted, todo_create_failed, todo_update_failed, todo_delete_failed, todos_fetch_failed, captureException Comprehensive client-side tracking of all todo operations and errors. Events include relevant properties like todo_id, has_description, title_length
about.tsx about_page_viewed Page view tracking for funnel analysis
api/todos/index.ts api_todo_validation_error, api_todo_create_error Server-side error tracking with validation details
api/todos/[id].ts api_todo_not_found, api_todo_validation_error, api_todo_update_error, api_todo_delete_error Server-side error tracking with operation context and todo_id

Issues

  • No success tracking on server-side: Only errors are tracked server-side. Consider adding api_todo_created, api_todo_updated, api_todo_deleted success events for complete picture. [LOW]
  • Missing homepage pageview: No $pageview or custom page view event for the main todo list page. [LOW]

Other completed criteria

  • Events capture real user actions (create, complete, delete todos)
  • Error events capture exception messages for debugging
  • Events enriched with relevant properties (todo_id, operation type, error messages)
  • Event naming follows consistent snake_case convention
  • Events documented in .posthog-events.json with descriptions
  • Both success and failure paths covered for client-side operations
  • Validation errors tracked separately from server errors

Reviewed by wizard workbench PR evaluator

@edwinyjlim
Copy link
Member Author

The output from /services/pr-evaluator. I just copy pasted it here. It's not integrated to GitHub yet.

It's a little overkill and verbose rn, but I think AI reviews are gonna help us stay sane and spare us from looking at millions of Wizard runs

@PostHog/team-docs-wizard

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants