JACoB PR for Issue Integrate PostHog Analytics into Next.js Application

Summary:

Description We need to integrate PostHog analytics into our Next.js application to track user interactions and gather valuable insights. This integration will help us understand user behavior, improve user experience, and make data-driven decisions for future development. We currently have PostHog on the server side (node) but we need to add it to the client.

Expected Outcome PostHog is successfully integrated into the Next.js application. User interactions and events are accurately tracked and sent to our PostHog analytics dashboard. The integration is optimized for performance and does not negatively impact the application's load times or responsiveness. User privacy is maintained, with appropriate measures in place to anonymize data and gain necessary consents. The analytics tracking can be easily enabled or disabled through a configuration setting to accommodate different deployment environments (e.g., development, staging, production). The docs are here: https://posthog.com/docs/libraries/next-js @jacob-ai-bot --skip-build

Plan:

Step 1: Edit `/.env.example`

Task: Add client-side PostHog environment variables to .env.example

Instructions: In the /.env.example file, add the following environment variables for client-side PostHog integration:

NEXT_PUBLIC_POSTHOG_KEY="your-posthog-api-key" (provide a sample value or leave it empty)
NEXT_PUBLIC_POSTHOG_HOST="https://app.posthog.com" (optional, include if using a custom PostHog host)
NEXT_PUBLIC_ENABLE_ANALYTICS="false" (set to 'false' by default to allow easy enabling or disabling of analytics)

Ensure these variables are clearly documented, indicating their purpose and usage.

Exit Criteria: The .env.example file includes NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST, and NEXT_PUBLIC_ENABLE_ANALYTICS with appropriate sample values or placeholders.

Step 2: Edit `/src/env.js`

Task: Validate PostHog environment variables in env.js

Instructions: In the /src/env.js file, add the following environment variables to the client-side schema under the client section:

NEXT_PUBLIC_POSTHOG_KEY: z.string().optional()
NEXT_PUBLIC_POSTHOG_HOST: z.string().optional().default('https://app.posthog.com')
NEXT_PUBLIC_ENABLE_ANALYTICS: z.enum(['true', 'false']).default('false')

This will ensure that these environment variables are validated and have default values where appropriate. Update the runtimeEnv section to include these variables, mapping them from process.env. Ensure that these variables are accessible in the client-side code.

Exit Criteria: The environment variables NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST, and NEXT_PUBLIC_ENABLE_ANALYTICS are validated and accessible in the client-side environment variables.

Step 3: Create `/src/lib/posthog.ts`

Task: Create PostHog client initialization in /src/lib/posthog.ts

Instructions: Create a new file at /src/lib/posthog.ts. In this file, perform the following steps:

Import posthog-js by adding import posthog from 'posthog-js' at the top of the file.
Import the necessary environment variables from /src/env.js.
Check if analytics are enabled by evaluating if NEXT_PUBLIC_ENABLE_ANALYTICS is set to 'true' and NEXT_PUBLIC_POSTHOG_KEY is provided.
If analytics are enabled, initialize PostHog using posthog.init() with the following options:
- apiKey: Use the NEXT_PUBLIC_POSTHOG_KEY environment variable.
- api_host: Use the NEXT_PUBLIC_POSTHOG_HOST environment variable.
- Ensure that you set appropriate configuration options to respect user privacy, such as anonymizing IP addresses and respecting Do Not Track settings.
If analytics are not enabled, ensure that PostHog is not initialized.
Export the PostHog instance for use in other parts of the application.

This setup ensures that PostHog is conditionally initialized based on configuration settings and that user privacy is considered.

Exit Criteria: A new file /src/lib/posthog.ts is created with PostHog client initialized conditionally based on configuration, respecting user privacy, and exporting the posthog instance.

Step 4: Edit `/src/app/layout.tsx`

Task: Integrate PostHogProvider into RootLayout in layout.tsx

Instructions: In the /src/app/layout.tsx file, perform the following modifications:

Import PostHogProvider from posthog-js/react by adding import { PostHogProvider } from 'posthog-js/react' at the top of the file.
Import the PostHog instance from /src/lib/posthog.ts using import { posthog } from '~/lib/posthog'.
Wrap the existing content inside the <ThemeProvider> component with the <PostHogProvider> component, passing the posthog instance as a prop.
- The structure should look like:
```
<ThemeProvider ...>
<PostHogProvider client={posthog}>
 {/* existing children */}
</PostHogProvider>
<ToastContainer />
</ThemeProvider>
```
Ensure that the application continues to function correctly even if analytics are disabled (i.e., when posthog is not initialized). The PostHogProvider should handle cases where the posthog instance is undefined or not initialized.

This integration will enable client-side analytics throughout the application without impacting existing functionality.

Exit Criteria: The RootLayout component uses PostHogProvider to wrap the application, and PostHog is integrated into the Next.js application without impacting functionality.

jacob-ai-bot / jacob