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.

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

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

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

    return [
        {
            title: 'Install the package',
            badge: 'required',
            content: (
                <>
                    <Markdown>
                        Install [`posthog-js`](https://github.com/posthog/posthog-js) and `@posthog/react` using your
                        package manager:
                    </Markdown>
                    <CodeBlock
                        blocks={[
                            {
                                language: 'bash',
                                file: 'npm',
                                code: dedent`
                                    npm install posthog-js @posthog/react
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'yarn',
                                code: dedent`
                                    yarn add posthog-js @posthog/react
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'pnpm',
                                code: dedent`
                                    pnpm add posthog-js @posthog/react
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'bun',
                                code: dedent`
                                    bun add posthog-js @posthog/react
                                `,
                            },
                        ]}
                    />
                </>
            ),
        },
        {
            title: 'Add environment variables',
            badge: 'required',
            content: (
                <>
                    <Markdown>
                        Add your PostHog project token and host to your environment variables. For Vite-based React
                        apps, use the `VITE_` prefix to expose them to the client:
                    </Markdown>
                    <CodeBlock
                        blocks={[
                            {
                                language: 'bash',
                                file: '.env',
                                code: dedent`
                                    VITE_POSTHOG_PROJECT_TOKEN=<ph_project_token>
                                    VITE_POSTHOG_HOST=<ph_client_api_host>
                                `,
                            },
                        ]}
                    />
                </>
            ),
        },
        {
            title: 'Initialize PostHog',
            badge: 'required',
            content: (
                <>
                    <Markdown>
                        Wrap your app with the `PostHogProvider` component at the root of your application (such as
                        `main.tsx` if you're using Vite):
                    </Markdown>
                    <CodeBlock
                        blocks={[
                            {
                                language: 'tsx',
                                file: 'main.tsx',
                                code: dedent`
                                    import { StrictMode } from 'react'
                                    import { createRoot } from 'react-dom/client'
                                    import './index.css'
                                    import App from './App.jsx'
                                    import { PostHogProvider } from '@posthog/react'

                                    const options = {
                                      api_host: import.meta.env.VITE_POSTHOG_HOST,
                                      defaults: '${SDK_DEFAULTS_DATE}',
                                    } as const

                                    createRoot(document.getElementById('root')).render(
                                      <StrictMode>
                                        <PostHogProvider apiKey={import.meta.env.VITE_POSTHOG_PROJECT_TOKEN} options={options}>
                                          <App />
                                        </PostHogProvider>
                                      </StrictMode>
                                    )
                                `,
                            },
                        ]}
                    />
                    <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>
                </>
            ),
        },
        {
            title: 'Accessing PostHog in your code',
            badge: 'recommended',
            content: (
                <>
                    <Markdown>
                        Use the `usePostHog` hook to access the PostHog instance in any component wrapped by
                        `PostHogProvider`:
                    </Markdown>
                    <CodeBlock
                        blocks={[
                            {
                                language: 'tsx',
                                file: 'MyComponent.tsx',
                                code: dedent`
                                    import { usePostHog } from '@posthog/react'

                                    function MyComponent() {
                                        const posthog = usePostHog()

                                        function handleClick() {
                                            posthog.capture('button_clicked', { button_name: 'signup' })
                                        }

                                        return <button onClick={handleClick}>Sign up</button>
                                    }
                                `,
                            },
                        ]}
                    />
                    <Markdown>You can also import `posthog` directly for non-React code or utility functions:</Markdown>
                    <CodeBlock
                        blocks={[
                            {
                                language: 'tsx',
                                file: 'utils/analytics.ts',
                                code: dedent`
                                    import posthog from 'posthog-js'

                                    export function trackPurchase(amount: number) {
                                        posthog.capture('purchase_completed', { amount })
                                    }
                                `,
                            },
                        ]}
                    />
                </>
            ),
        },
    ]
}

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

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

export const getReactSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => [
    ...getReactInstallSteps(ctx),
    getReactEventStep(ctx),
]

export const ReactInstallation = createInstallation(getReactSteps)