Add PostHog to a new app: Here's how to set up and configure PostHog and Clerk

Projects

Add services, generate credentials, and manage billing from the CLI – or let your agent do it.

Learn more 
  1. Introduction
  2. Key takeaways
  3. What are PostHog and Clerk?
  4. Why should you combine PostHog analytics with Clerk auth?
  5. How do you configure PostHog and Clerk manually?
    1. 1. Create a PostHog project
    2. 2. Create a Clerk application
    3. 3. Install the SDKs
    4. 4. Set environment variables
    5. 5. Test the setup
  6. How can you browse analytics providers with Stripe Projects?
  7. How do you add PostHog and Clerk with Stripe Projects?
  8. What are the best practices for PostHog and Clerk?
  9. How Stripe Projects can help

Adding PostHog and Clerk to a new app involves setting up two separate systems that solve different problems. Clerk handles user sign-in to your app, while PostHog tracks what users do once they're inside. You can configure them manually through their dashboards and software development kits (SDKs), or provision them with Stripe Projects, which pulls credentials for both providers directly into your project's .env file without you having to dashboard hop.

PostHog is used by more than 500,000 teams and nearly 250,000 engineers. Many teams will eventually pair PostHog with an authentication provider, such as Clerk. Stripe Projects simplifies that setup by provisioning both services in a single workflow.

Below, we'll discuss what each provider does, why connecting authenticated identity to analytics events helps you understand more than traffic alone, and how to add PostHog and Clerk quickly using Stripe Projects.

Key takeaways

  • Connecting Clerk's authenticated user identifiers (IDs) to PostHog's identify() method turns anonymous session data into identified user profiles without losing pre-login event history.

  • Stripe Projects can provision PostHog and Clerk through command-line interface (CLI) commands that handle account authorisation and write credentials directly into your project's .env file.

  • Best practices for PostHog and Clerk include separating environments cleanly and minimising personal data in event properties.

What are PostHog and Clerk?

PostHog is a product analytics platform. It tracks events, pageviews, and user behaviour inside an app, then turns that data into funnels, session recordings, feature flags, and cohort analysis. Clerk is an authentication and user management provider. It handles sign-up, sign-in, session tokens, multifactor authentication, and user profile data.

Why should you combine PostHog analytics with Clerk auth?

Combining PostHog with Clerk gives you analytics about top-of-funnel traffic, such as churn prediction, onboarding analysis, or feature adoption, broken out by account tier. PostHog tracks users through a distinct ID, which starts as an anonymous, randomly generated identifier tied to a browser or device. When a user signs in through Clerk, you can call PostHog's identify() method and pass Clerk's user ID as the new distinct ID. PostHog then merges the anonymous session history with the identified profile, linking tracked events before sign-in – such as page views, button clicks, and feature interactions – to that user.

Pay close attention to these specifics:

  • Event-naming consistency: Decide early whether events are snake case (e.g., without spaces) or title case, and whether they describe actions such as signed\_up or objects such as signup\_completed. Mixing conventions makes your PostHog dashboards unreadable.

  • Anonymous versus identified users: If you call identify() on every page load, you'll rack up duplicate merge events in PostHog's activity log. Call it once, right after Clerk confirms a session. You can also gate the call behind a check for whether the user was already identified in the current session.

  • Privacy and consent: In jurisdictions with consent requirements for tracking, such as under GDPR in the EU, capture consent before identifying a user or attaching personal data to event properties. An email or name on every analytics event is rarely necessary and widens your compliance surface.

  • When to connect the two: If your app is mainly pre-signup marketing pages, then anonymous tracking covers you. Connect Clerk and PostHog events once you have authenticated flows worth measuring, such as trial-to-paid conversion.

How do you configure PostHog and Clerk manually?

You'll manually configure both providers across four systems: two dashboards and two SDKs.

Here's how it works:

1. Create a PostHog project

Sign up at PostHog and create a project. This gives you a project application programming interface (API) key and host URL. You'll need both values for the SDK.

2. Create a Clerk application

In the Clerk dashboard, create an application and choose your sign-in methods, such as email, Google OAuth, or passkeys.

3. Install the SDKs

Run npm install posthog-js and npm install @clerk/nextjs for a Next.js app. PostHog initialises client-side through posthog.init(), while Clerk wraps your app in a \<ClerkProvider\> and requires middleware to handle route protection.

4. Set environment variables

Add four to six values to your .env.local file.

5. Test the setup

Confirm that Clerk's sign-in flow produces a session, then check PostHog's live events view to confirm events are coming through. Verify that identify() fires exactly once per session, right after authentication resolves.

How can you browse analytics providers with Stripe Projects?

Stripe Projects is a Stripe CLI feature for provisioning third-party infrastructure services, including databases, analytics, and AI providers, directly from the command line. Instead of opening separate dashboards for each service, you browse and provision them from one interface tied to your project.

Use Stripe Projects to browse provider options for analytics by running it from your project directory to list available providers, organised by category and service tier. You can narrow it with stripe projects catalog \<provider\> or stripe projects catalog \<category\>, or search directly with stripe projects search \<keyword\>. If you're looking for analytics specifically, you'll see PostHog alongside other supported providers, eliminating the need to leave your terminal or switch into a browser.

How do you add PostHog and Clerk with Stripe Projects?

Once you've chosen PostHog and Clerk, it takes two commands to provision both from a project already initialised with the Stripe CLI. To add PostHog, run stripe projects add posthog/analytics to start the provisioning flow. Stripe Projects handles the account authorisation step that would normally require you to log into PostHog directly and copy keys manually. It then writes the resulting API key and host URL into your project's .env file. Running stripe projects add clerk/auth does the same for Clerk: it manages the authorisation flow and retrieves the publishable and secret keys. Those are written into .env alongside whatever PostHog just added.

The practical difference between setup with Stripe Projects and manual setup is where the credentials come from. Instead of copying keys out of two dashboards and pasting them into .env.local, Stripe Projects retrieves and writes them directly, though you (or your coding agent) still write the SDK initialisation code and wire up your app logic yourself.

You'll also want to keep your keys in sync. If you're setting up the project on a new machine for the first time, stripe projects pull \<projectID\> clones the existing project into an empty directory and writes your .env file, which connects to the project's existing services rather than provisioning new ones. If you're already in the project directory and need to refresh your local .env after a teammate adds or rotates a provider, run stripe projects pull env \--pull instead.

What are the best practices for PostHog and Clerk?

A few things are worth getting right before you ship this integration.

Here's what to keep in mind:

  • Separate environments cleanly: Use different PostHog projects and Clerk applications for development and production. Mixing test sign-ups with real user data makes your analytics unreliable and clutters your Clerk user list with throwaway accounts.

  • Never expose the Clerk secret key client-side: It belongs in server-side environment variables only. The publishable key is safe for the browser; the secret key is not.

  • Minimise personal data in event properties: Send a user ID rather than an email address, since the ID alone lets you join data back to Clerk's user table later if you need it.

  • Respect consent before identifying users: If your jurisdiction requires tracking consent, gate the identify() call behind that consent.

  • Test the merge behaviour explicitly: Sign up as an anonymous user, generate a few events, then sign in and confirm PostHog merges that history under the identified profile instead of starting a disconnected new one.

  • Document your event schema: A shared reference for event names and properties keeps different parts of your team from tracking the same action under three different names.

How Stripe Projects can help

Stripe Projects lets developers and their AI agents add services, generate credentials, and manage billing from the command line interface (CLI).

Stripe Projects helps you:

  • Provision third-party services from the command line: Use one workflow to add services, manage credentials, and upgrade plans, instead of different tools and workflows for every provider. Manage hosting, databases, auth, AI, and more without needing dashboards, config files, or infrastructure code.

  • Sync credentials automatically: Keep environment variables portable across local setups, machines, teammates, and agents – no copy-pasting application programming interface (API) keys.

  • Manage billing from the CLI or your coding agent: Set up billing details once and securely share them with third-party services. Upgrade and downgrade tiers, monitor usage, and manage subscriptions from the CLI.

Learn more about how Stripe Projects helps simplify app provisioning, or copy and paste this command into your terminal to get started today:

The content in this article is for general information and education purposes only and should not be construed as legal or tax advice. Stripe does not warrant or guarantee the accuracy, completeness, adequacy, or currency of the information in the article. You should seek the advice of a competent lawyer or accountant licensed to practise in your jurisdiction for advice on your particular situation.

More articles

  • Something went wrong. Please try again or contact support.

Ready to get started?

Create an account and start accepting payments – no contracts or banking details required. Or, contact us to design a custom package for your business.
Payments

Payments

Accept payments online, in person, and around the world with a payments solution built for any business.

Payments docs

Find a guide to integrate Stripe's payments APIs.