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.

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

import { getNextJSClientSteps } from '../product-analytics/nextjs'
import { StepDefinition } from '../steps'

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

    const clientSteps = getNextJSClientSteps(ctx)

    const captureClientExceptionsStep: StepDefinition = {
        title: 'Capture client-side exceptions',
        badge: 'required',
        content: (
            <>
                <Markdown>
                    {dedent`
                        PostHog can automatically capture unhandled exceptions in your Next.js app using the JavaScript Web SDK. Turn it on with \`capture_exceptions: true\` in your \`posthog.init\` call:
                    `}
                </Markdown>
                <CodeBlock
                    blocks={[
                        {
                            language: 'javascript',
                            file: 'instrumentation-client.js',
                            code: dedent`
                                posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN, {
                                  api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
                                  capture_exceptions: true,
                                })
                            `,
                        },
                    ]}
                />
                <Markdown>
                    {dedent`
                        It is also possible to manually capture exceptions using the \`captureException\` method:
                    `}
                </Markdown>
                <CodeBlock
                    blocks={[
                        {
                            language: 'javascript',
                            file: 'JavaScript',
                            code: dedent`
                                posthog.captureException(error, additionalProperties)
                            `,
                        },
                    ]}
                />
                Manual capture is very useful if you already use error boundaries to handle errors in your app:
                <Tab.Group tabs={['App router', 'Pages router']}>
                    <Tab.List>
                        <Tab>App router</Tab>
                        <Tab>Pages router</Tab>
                    </Tab.List>
                    <Tab.Panels>
                        <Tab.Panel>
                            <Markdown>
                                {dedent`
                                    Next.js uses [error boundaries](https://nextjs.org/docs/app/building-your-application/routing/error-handling#using-error-boundaries) to handle uncaught exceptions by rendering a fallback UI instead of the crashing components. To set one up, create a \`error.tsx\` file in any of your route directories. This triggers when there is an error rendering your component. An error boundary catches the error before autocapture sees it, so add the capture to **every** \`error.tsx\` your app has. It should look like this:
                                `}
                            </Markdown>
                            <CodeBlock
                                blocks={[
                                    {
                                        language: 'typescript',
                                        file: 'error.tsx',
                                        code: dedent`
                                            "use client"
                                            import posthog from "posthog-js"
                                            import { useEffect } from "react"

                                            export default function Error({
                                              error,
                                              reset,
                                            }: {
                                              error: Error & { digest?: string }
                                              reset: () => void
                                            }) {
                                              useEffect(() => {
                                                posthog.captureException(error)
                                              }, [error])
                                              return (
                                                ...
                                              )
                                            }
                                        `,
                                    },
                                ]}
                            />
                            <Markdown>
                                {dedent`
                                    Also add the capture to a [Global Error component](https://nextjs.org/docs/app/building-your-application/routing/error-handling#handling-global-errors) at \`app/global-error.tsx\`, and create one if your app has none: it catches errors in the root layout and in the first render, before autocapture loads.
                                `}
                            </Markdown>
                            <CodeBlock
                                blocks={[
                                    {
                                        language: 'typescript',
                                        file: 'app/global-error.tsx',
                                        code: dedent`
                                            'use client'
                                            import posthog from "posthog-js"
                                            import NextError from "next/error"
                                            import { useEffect } from "react"

                                            export default function GlobalError({
                                              error,
                                              reset,
                                            }: {
                                              error: Error & { digest?: string }
                                              reset: () => void
                                            }) {
                                              useEffect(() => {
                                                posthog.captureException(error)
                                              }, [error])
                                              return (
                                                // global-error must include html and body tags
                                                <html>
                                                  <body>
                                                    {/* \`NextError\` is the default Next.js error page component */}
                                                    <NextError statusCode={0} />
                                                  </body>
                                                </html>
                                              )
                                            }
                                        `,
                                    },
                                ]}
                            />
                        </Tab.Panel>
                        <Tab.Panel>
                            <Markdown>
                                {dedent`
                                    For Pages Router, you can use React's [Error Boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) to catch JavaScript errors anywhere in the component tree. Create a custom error boundary component and report errors to PostHog in the \`componentDidCatch\` method:
                                `}
                            </Markdown>
                            <CodeBlock
                                blocks={[
                                    {
                                        language: 'typescript',
                                        file: 'components/ErrorBoundary.tsx',
                                        code: dedent`
                                            componentDidCatch(error, errorInfo) {
                                              posthog.captureException(error)
                                            }
                                        `,
                                    },
                                ]}
                            />
                            <Markdown>
                                {dedent`
                                    Then wrap your app or specific components with the error boundary:
                                `}
                            </Markdown>
                            <CodeBlock
                                blocks={[
                                    {
                                        language: 'typescript',
                                        file: 'pages/_app.tsx',
                                        code: dedent`
                                            import type { AppProps } from 'next/app'
                                            import ErrorBoundary from '../components/ErrorBoundary'

                                            export default function App({ Component, pageProps }: AppProps) {
                                              return (
                                                <ErrorBoundary>
                                                  <Component {...pageProps} />
                                                </ErrorBoundary>
                                              )
                                            }
                                        `,
                                    },
                                ]}
                            />
                        </Tab.Panel>
                    </Tab.Panels>
                </Tab.Group>
            </>
        ),
    }

    const verifyClientStep: StepDefinition = {
        title: 'Verify error tracking',
        badge: 'recommended',
        checkpoint: true,
        content: (
            <Markdown>
                {dedent`
                    Check that exception events appear in the [activity feed](https://app.posthog.com/activity/events).
                `}
            </Markdown>
        ),
    }

    const installServerStep: StepDefinition = {
        title: 'Installing PostHog SDK for server-side',
        badge: 'required',
        content: (
            <>
                <Markdown>
                    {dedent`
                        Next.js enables you to both server-side render pages and add server-side functionality. To capture server-side exceptions, use [\`@posthog/next\`](https://posthog.com/docs/libraries/next-js/posthog-next) for the errors Next.js reports and the [Node SDK](https://posthog.com/docs/libraries/node) for everything else.

                        First, install \`@posthog/next\` 0.11.0+ and \`posthog-node\` 5.61.1+, and upgrade \`posthog-js\` to 1.445.1+ if yours is older:
                    `}
                </Markdown>
                <CodeBlock
                    blocks={[
                        { language: 'bash', file: 'npm', code: dedent`npm install @posthog/next posthog-node` },
                        { language: 'bash', file: 'yarn', code: dedent`yarn add @posthog/next posthog-node` },
                        { language: 'bash', file: 'pnpm', code: dedent`pnpm add @posthog/next posthog-node` },
                        { language: 'bash', file: 'bun', code: dedent`bun add @posthog/next posthog-node` },
                    ]}
                />
                <Markdown>
                    {dedent`
                        Then create a \`lib/posthog-server.js\` file that initializes PostHog from \`posthog-node\`. With \`enableExceptionAutocapture\`, it captures uncaught exceptions and unhandled promise rejections. Turn it on for the Node.js runtime only: the edge runtime cannot register process listeners, so the client would fail to start there.

                        This looks like this:
                    `}
                </Markdown>
                <CodeBlock
                    blocks={[
                        {
                            language: 'javascript',
                            file: 'lib/posthog-server.js',
                            code: dedent`
                                import { PostHog } from 'posthog-node'

                                let posthogServer = null

                                export function getPostHogServer() {
                                  posthogServer ??= new PostHog(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN, {
                                    host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
                                    flushAt: 1,
                                    flushInterval: 0,
                                    // Uncaught exceptions and unhandled promise rejections, on the Node.js runtime only
                                    enableExceptionAutocapture: process.env.NEXT_RUNTIME === 'nodejs',
                                  })
                                  return posthogServer
                                }
                            `,
                        },
                    ]}
                />
                <Markdown>
                    {dedent`
                        You can now use the \`getPostHogServer\` function to capture exceptions your server-side code handles itself. Pass the user's distinct ID when you know it:
                    `}
                </Markdown>
                <CodeBlock
                    blocks={[
                        {
                            language: 'javascript',
                            file: 'JavaScript',
                            code: dedent`
                                const posthog = getPostHogServer()
                                try {
                                  throw new Error('This is a test exception for error tracking')
                                } catch (error) {
                                  posthog.captureException(error, 'user_distinct_id', { source: 'test' })
                                }
                            `,
                        },
                    ]}
                />
            </>
        ),
    }

    const verifyServerStep: StepDefinition = {
        title: 'Verify server-side exceptions',
        badge: 'recommended',
        checkpoint: true,
        content: (
            <Markdown>
                {dedent`
                    You should also see events and exceptions in PostHog coming from your server-side code in the activity feed.

                    [Check for server events in PostHog](https://app.posthog.com/activity/events)
                `}
            </Markdown>
        ),
    }

    const captureServerExceptionsStep: StepDefinition = {
        title: 'Capturing server-side exceptions',
        badge: 'required',
        content: (
            <>
                <Markdown>
                    {dedent`
                        To capture errors that occur in your server-side code, set up an [\`instrumentation.ts\`](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) file at the root of your project (or in \`src/\`). Next.js calls its \`onRequestError\` hook when a Server Component, Route Handler, or Server Action throws. [\`createOnRequestError\`](https://posthog.com/docs/libraries/next-js/posthog-next) returns that hook, and links each error to the user and session. \`register()\` starts the \`posthog-node\` client when the server starts.

                        This looks like this:
                    `}
                </Markdown>
                <CodeBlock
                    blocks={[
                        {
                            language: 'javascript',
                            file: 'instrumentation.js',
                            code: dedent`
                                import { createOnRequestError } from '@posthog/next'
                                import { getPostHogServer } from './lib/posthog-server'

                                export function register() {
                                  if (process.env.NEXT_RUNTIME === 'nodejs') {
                                    getPostHogServer()
                                  }
                                }

                                export const onRequestError = createOnRequestError({
                                  apiKey: process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN,
                                  host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
                                })
                            `,
                        },
                    ]}
                />
                <Markdown>
                    {dedent`
                        \`onRequestError\` misses errors thrown in \`proxy.ts\` and in Node.js middleware. If your app has either, wrap it with \`withPostHogProxy\`:
                    `}
                </Markdown>
                <CodeBlock
                    blocks={[
                        {
                            language: 'typescript',
                            file: 'proxy.ts',
                            code: dedent`
                                import { NextResponse } from 'next/server'
                                import type { NextRequest } from 'next/server'
                                import { withPostHogProxy } from '@posthog/next'

                                // On Next.js 15 and earlier, this is middleware.ts with \`export const middleware\`
                                export const proxy = withPostHogProxy(
                                  async (request: NextRequest) => {
                                    // Your existing proxy code
                                    return NextResponse.next()
                                  },
                                  {
                                    apiKey: process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN,
                                    host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
                                  }
                                )
                            `,
                        },
                    ]}
                />
                <Markdown>
                    {dedent`
                        Errors thrown in \`after()\` callbacks do not reach \`onRequestError\` either. If your app imports \`after\` from \`next/server\`, capture inside each callback:
                    `}
                </Markdown>
                <CodeBlock
                    blocks={[
                        {
                            language: 'typescript',
                            file: 'app/api/orders/route.ts',
                            code: dedent`
                                import { after } from 'next/server'
                                import { getPostHogServer } from '@/lib/posthog-server'

                                after(async () => {
                                  try {
                                    await sendReceipt(order)
                                  } catch (error) {
                                    await getPostHogServer().captureExceptionImmediate(error)
                                    throw error
                                  }
                                })
                            `,
                        },
                    ]}
                />
                <Markdown>
                    {dedent`
                        **Next.js 14 and earlier** run \`instrumentation.js\` only with the \`instrumentationHook\` flag. They never call \`onRequestError\`, so leave it out, and upgrade to capture Server Component, Route Handler and Server Action errors:
                    `}
                </Markdown>
                <CodeBlock
                    blocks={[
                        {
                            language: 'javascript',
                            file: 'next.config.js',
                            code: dedent`
                                module.exports = {
                                  // Only on Next.js 14 and earlier: later versions run instrumentation.js without it
                                  experimental: { instrumentationHook: true },
                                }
                            `,
                        },
                    ]}
                />
                <Markdown>
                    {dedent`
                        You can find a full example of both this and client-side error tracking in our [Next.js error monitoring tutorial](https://posthog.com/tutorials/nextjs-error-monitoring).
                    `}
                </Markdown>
            </>
        ),
    }

    return [
        ...clientSteps,
        captureClientExceptionsStep,
        verifyClientStep,
        installServerStep,
        verifyServerStep,
        captureServerExceptionsStep,
    ]
}

export const NextJSInstallation = createInstallation(getNextJSSteps)