Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

23.9 KB
Raw Blame
import { OnboardingComponentsContext, createInstallation } from 'scenes/onboarding/shared/OnboardingDocsContentWrapper'

import { StepDefinition } from '../steps'
import { SDK_DEFAULTS_DATE } from './_snippets/sdkDefaults'

export const getNextJSSetupSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => {
    const { CodeBlock, Markdown, CalloutBox, Tab, dedent } = ctx

    return [
        {
            title: 'Install the package',
            badge: 'required',
            content: (
                <>
                    <Markdown>Install the PostHog JavaScript library using your package manager:</Markdown>
                    <CodeBlock
                        blocks={[
                            {
                                language: 'bash',
                                file: 'npm',
                                code: dedent`
                                    npm install posthog-js
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'yarn',
                                code: dedent`
                                    yarn add posthog-js
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'pnpm',
                                code: dedent`
                                    pnpm add posthog-js
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'bun',
                                code: dedent`
                                    bun add posthog-js
                                `,
                            },
                        ]}
                    />
                </>
            ),
        },
        {
            title: 'Add environment variables',
            badge: 'required',
            content: (
                <>
                    <Markdown>
                        Add your PostHog project token and host to your `.env.local` file and to your hosting provider
                        (e.g. Vercel, Netlify). These values need to start with `NEXT_PUBLIC_` to be accessible on the
                        client-side.
                    </Markdown>
                    <CodeBlock
                        blocks={[
                            {
                                language: 'bash',
                                file: '.env.local',
                                code: dedent`
                                    NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=<ph_project_token>
                                    NEXT_PUBLIC_POSTHOG_HOST=<ph_client_api_host>
                                `,
                            },
                        ]}
                    />
                </>
            ),
        },
        {
            title: 'Initialize PostHog',
            badge: 'required',
            content: (
                <>
                    <Markdown>Choose the integration method based on your Next.js version and router type.</Markdown>

                    <Tab.Group tabs={['Next.js 15.3+', 'App router', 'Pages router']}>
                        <Tab.List>
                            <Tab>Next.js 15.3+</Tab>
                            <Tab>App router</Tab>
                            <Tab>Pages router</Tab>
                        </Tab.List>
                        <Tab.Panels>
                            <Tab.Panel>
                                <Markdown>
                                    If you're using Next.js 15.3+, you can use `instrumentation-client.ts` for a
                                    lightweight, fast integration:
                                </Markdown>
                                <CodeBlock
                                    blocks={[
                                        {
                                            language: 'typescript',
                                            file: 'instrumentation-client.ts',
                                            code: dedent`
                                                import posthog from 'posthog-js'

                                                posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN!, {
                                                    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
                                                    defaults: '${SDK_DEFAULTS_DATE}'
                                                })
                                            `,
                                        },
                                    ]}
                                />
                            </Tab.Panel>
                            <Tab.Panel>
                                <Markdown>
                                    For the App router, create a `providers.tsx` file in your `app` folder. The
                                    `posthog-js` library needs to be initialized on the client-side using the `'use
                                    client'` directive:
                                </Markdown>
                                <CodeBlock
                                    blocks={[
                                        {
                                            language: 'typescript',
                                            file: 'app/providers.tsx',
                                            code: dedent`
                                                'use client'

                                                import { usePathname, useSearchParams } from "next/navigation"
                                                import { useEffect } from "react"

                                                import posthog from 'posthog-js'
                                                import { PostHogProvider as PHProvider } from '@posthog/react'

                                                export function PostHogProvider({ children }: { children: React.ReactNode }) {
                                                  useEffect(() => {
                                                    posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN as string, {
                                                      api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
                                                      defaults: '${SDK_DEFAULTS_DATE}'
                                                    })
                                                  }, [])

                                                  return (
                                                    <PHProvider client={posthog}>
                                                      {children}
                                                    </PHProvider>
                                                  )
                                                }
                                            `,
                                        },
                                    ]}
                                />
                                <Markdown>
                                    Then import the `PostHogProvider` component in your `app/layout.tsx` and wrap your
                                    app with it:
                                </Markdown>
                                <CodeBlock
                                    blocks={[
                                        {
                                            language: 'typescript',
                                            file: 'app/layout.tsx',
                                            code: dedent`
                                                import './globals.css'
                                                import { PostHogProvider } from './providers'

                                                export default function RootLayout({ children }: { children: React.ReactNode }) {
                                                  return (
                                                    <html lang="en">
                                                      <body>
                                                        <PostHogProvider>
                                                          {children}
                                                        </PostHogProvider>
                                                      </body>
                                                    </html>
                                                  )
                                                }
                                            `,
                                        },
                                    ]}
                                />
                            </Tab.Panel>
                            <Tab.Panel>
                                <Markdown>
                                    For the Pages router, integrate PostHog at the root of your app in `pages/_app.tsx`:
                                </Markdown>
                                <CodeBlock
                                    blocks={[
                                        {
                                            language: 'typescript',
                                            file: 'pages/_app.tsx',
                                            code: dedent`
                                                import { useEffect } from 'react'
                                                import { Router } from 'next/router'
                                                import posthog from 'posthog-js'
                                                import { PostHogProvider } from '@posthog/react'
                                                import type { AppProps } from 'next/app'

                                                export default function App({ Component, pageProps }: AppProps) {

                                                  useEffect(() => {
                                                    posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN as string, {
                                                      api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
                                                      defaults: '${SDK_DEFAULTS_DATE}',
                                                      loaded: (posthog) => {
                                                        if (process.env.NODE_ENV === 'development') posthog.debug()
                                                      }
                                                    })
                                                  }, [])

                                                  return (
                                                    <PostHogProvider client={posthog}>
                                                      <Component {...pageProps} />
                                                    </PostHogProvider>
                                                  )
                                                }
                                            `,
                                        },
                                    ]}
                                />
                            </Tab.Panel>
                        </Tab.Panels>
                    </Tab.Group>

                    <CalloutBox type="fyi" title="Defaults option">
                        <Markdown>
                            The `defaults` option automatically configures PostHog with recommended settings for new
                            projects. See [SDK defaults](https://posthog.com/docs/libraries/js#sdk-defaults) for
                            details.
                        </Markdown>
                    </CalloutBox>
                </>
            ),
        },
    ]
}

export const getNextJSClientAccessStep = (ctx: OnboardingComponentsContext): StepDefinition => {
    const { CodeBlock, Markdown, Tab, dedent } = ctx

    return {
        title: 'Accessing PostHog on the client',
        badge: 'recommended',
        content: (
            <>
                <Tab.Group tabs={['Next.js 15.3+', 'App/Pages router']}>
                    <Tab.List>
                        <Tab>Next.js 15.3+</Tab>
                        <Tab>App/Pages router</Tab>
                    </Tab.List>
                    <Tab.Panels>
                        <Tab.Panel>
                            <Markdown>
                                Once initialized in `instrumentation-client.ts`, import `posthog` from `posthog-js`
                                anywhere and call the methods you need:
                            </Markdown>
                            <CodeBlock
                                blocks={[
                                    {
                                        language: 'typescript',
                                        file: 'app/checkout/page.tsx',
                                        code: dedent`
                                                'use client'

                                                import posthog from 'posthog-js'

                                                export default function CheckoutPage() {
                                                    function handlePurchase() {
                                                        posthog.capture('purchase_completed', { amount: 99 })
                                                    }

                                                    return <button onClick={handlePurchase}>Complete purchase</button>
                                                }
                                            `,
                                    },
                                ]}
                            />
                        </Tab.Panel>
                        <Tab.Panel>
                            <Markdown>Use the `usePostHog` hook to access PostHog in client components:</Markdown>
                            <CodeBlock
                                blocks={[
                                    {
                                        language: 'typescript',
                                        file: 'app/checkout/page.tsx',
                                        code: dedent`
                                                'use client'

                                                import { usePostHog } from '@posthog/react'

                                                export default function CheckoutPage() {
                                                    const posthog = usePostHog()

                                                    function handlePurchase() {
                                                        posthog.capture('purchase_completed', { amount: 99 })
                                                    }

                                                    return <button onClick={handlePurchase}>Complete purchase</button>
                                                }
                                            `,
                                    },
                                ]}
                            />
                        </Tab.Panel>
                    </Tab.Panels>
                </Tab.Group>
            </>
        ),
    }
}

export const getNextJSClientSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => [
    ...getNextJSSetupSteps(ctx),
    getNextJSClientAccessStep(ctx),
]

export const getNextJSServerSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => {
    const { CodeBlock, Markdown, CalloutBox, Tab, dedent } = ctx

    return [
        {
            title: 'Server-side setup',
            badge: 'optional',
            content: (
                <>
                    <Markdown>To capture events from API routes or server actions, install `posthog-node`:</Markdown>
                    <CodeBlock
                        blocks={[
                            {
                                language: 'bash',
                                file: 'npm',
                                code: dedent`
                                    npm install posthog-node
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'yarn',
                                code: dedent`
                                    yarn add posthog-node
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'pnpm',
                                code: dedent`
                                    pnpm add posthog-node
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'bun',
                                code: dedent`
                                    bun add posthog-node
                                `,
                            },
                        ]}
                    />
                    <Markdown>
                        Then, initialize PostHog in your API route or server action. Choose the method based on your
                        router type:
                    </Markdown>

                    <Tab.Group tabs={['App router', 'Pages router']}>
                        <Tab.List>
                            <Tab>App router</Tab>
                            <Tab>Pages router</Tab>
                        </Tab.List>
                        <Tab.Panels>
                            <Tab.Panel>
                                <Markdown>
                                    For the App router, you can use PostHog in API routes or server actions. Create a
                                    new PostHog client instance for each request, or reuse a singleton instance across
                                    requests:
                                </Markdown>
                                <CodeBlock
                                    blocks={[
                                        {
                                            language: 'typescript',
                                            file: 'app/api/example/route.ts',
                                            code: dedent`
                                                import { PostHog } from 'posthog-node'

                                                export async function POST(request: Request) {
                                                    const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN!, {
                                                        host: process.env.NEXT_PUBLIC_POSTHOG_HOST
                                                    })

                                                    posthog.capture({
                                                        distinctId: 'distinct_id_of_the_user',
                                                        event: 'event_name'
                                                    })

                                                    await posthog.shutdown()
                                                }
                                            `,
                                        },
                                    ]}
                                />
                                <Markdown>You can also use PostHog in server actions:</Markdown>
                                <CodeBlock
                                    blocks={[
                                        {
                                            language: 'typescript',
                                            file: 'app/actions.ts',
                                            code: dedent`
                                                'use server'

                                                import { PostHog } from 'posthog-node'

                                                export async function myServerAction() {
                                                    const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN!, {
                                                        host: process.env.NEXT_PUBLIC_POSTHOG_HOST
                                                    })

                                                    posthog.capture({
                                                        distinctId: 'distinct_id_of_the_user',
                                                        event: 'server_action_completed'
                                                    })

                                                    await posthog.shutdown()
                                                }
                                            `,
                                        },
                                    ]}
                                />
                            </Tab.Panel>
                            <Tab.Panel>
                                <Markdown>For the Pages router, use PostHog in your API routes:</Markdown>
                                <CodeBlock
                                    blocks={[
                                        {
                                            language: 'typescript',
                                            file: 'pages/api/example.ts',
                                            code: dedent`
                                                import { PostHog } from 'posthog-node'
                                                import type { NextApiRequest, NextApiResponse } from 'next'

                                                export default async function handler(
                                                    req: NextApiRequest,
                                                    res: NextApiResponse
                                                ) {
                                                    const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN!, {
                                                        host: process.env.NEXT_PUBLIC_POSTHOG_HOST
                                                    })

                                                    posthog.capture({
                                                        distinctId: 'distinct_id_of_the_user',
                                                        event: 'event_name'
                                                    })

                                                    await posthog.shutdown()

                                                    res.status(200).json({ success: true })
                                                }
                                            `,
                                        },
                                    ]}
                                />
                            </Tab.Panel>
                        </Tab.Panels>
                    </Tab.Group>

                    <CalloutBox type="fyi" title="Important">
                        <Markdown>
                            Always call `await posthog.shutdown()` when you're done with the client to ensure all events
                            are flushed before the request completes. For better performance, consider creating a
                            singleton PostHog instance that you reuse across requests.
                        </Markdown>
                    </CalloutBox>
                </>
            ),
        },
    ]
}

export const getNextJSInstallSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => [
    ...getNextJSClientSteps(ctx),
    ...getNextJSServerSteps(ctx),
]

export const getNextJSEventStep = (ctx: OnboardingComponentsContext): StepDefinition => {
    const JSEventCapture = ctx.snippets?.JSEventCapture

    return {
        title: 'Send events',
        badge: 'recommended',
        content: <>{JSEventCapture && <JSEventCapture />}</>,
    }
}

export const getNextJSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => [
    ...getNextJSInstallSteps(ctx),
    getNextJSEventStep(ctx),
]

export const NextJSInstallation = createInstallation(getNextJSSteps)