Analytics

StartStack uses PostHog for analytics by default. PostHog is an open-source analytics platform that allows you to track events, funnels, and more. It's awesome, and I highly recommend it!

Setting up PostHog

1. Sign up for a PostHog account.
2. Create a new project and click on Settings.
3. You will see a code snippet that looks like this:

<script>
    ... omitted ...
    posthog.init('<YOUR-POSTHOG-KEY>',{api_host:'<YOUR-POSTHOG-HOST>', person_profiles: 'identified_only')
</script>

4. Update the NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST in your .env file.

NEXT_PUBLIC_POSTHOG_KEY="<YOUR-POSTHOG-KEY>"
NEXT_PUBLIC_POSTHOG_HOST="<YOUR-POSTHOG-HOST>"

Capturing events server side

StartStack comes with a captureEvent function that you can use to capture events server side. This function is a wrapper around PostHog's capture function. It takes an event name and a properties object.

captureEvent({
  event: "my_event",
  properties: {
    my_property: "my_value",
  },
})

Note: I recommend wrapping your captureEvent calls in an after when possible. See the docs on next.js after for more information.

The captureEvent function will automatically set the distinctId based on the user's posthog cookie. If the user has not been identified yet by the posthog client side sdk, it will generate a new one using nanoid(). What's nice about this is you will maintain the same distinctId across client and server side events.

Capturing events client side

Posthog will capture events using the client side sdk by default. This is great for tracking page views, clicks, and more. Once you add the above env vars to your project, Posthog will be enabled and start capturing events. You can customize posthog.init by editing the PostHogProvider component in components/post-hog-provider.tsx. To capture a custom event client side, you can use the posthog.capture function.

posthog.capture("my_event", {
  my_property: "my_value",
})

Identifying users

StartStack will identify users by default when they are logged in. This will set the distinctId in posthog.

You can also identify users manually by calling the posthog.identify function. This function takes a userId and a properties object.

posthog.identify("user_id", {
  email: "user@example.com",
})

See the PostHogPageView component in components/post-hog-page-view.tsx to see how StartStack tracks page views and identify users once they have logged in.

See the PostHog docs to learn more.

Proxy configuration

StartStack comes with Posthog configured to use the proxy pattern. Events are sent to the app and then forwarded to Posthog. This allows you to bypass certain browser restrictions.

You can view / edit the proxy configuration in the next.config.mjs file.

  async rewrites() {
    return [
      // next15 dropped the .xml extension from the sitemap
      {
        source: "/sitemap.xml",
        destination: "/sitemap",
      },
      // posthog proxy: https://posthog.com/docs/advanced/proxy/nextjs
      {
        source: "/ingest/static/:path*",
        destination: "https://us-assets.i.posthog.com/static/:path*",
      },
      {
        source: "/ingest/:path*",
        destination: "https://us.i.posthog.com/:path*",
      },
      {
        source: "/ingest/decide",
        destination: "https://us.i.posthog.com/decide",
      },
    ]
  },
  // This is required to support PostHog trailing slash API requests
  skipTrailingSlashRedirect: true,

Note: If you are using the EU cloud then use eu instead of us in all domains (e.g. us.i.posthog.com -> eu.i.posthog.com)

Read the PostHog docs to learn more.