# Next.js session replay installation - Docs 1. 1 ## Install the package Required Install the PostHog JavaScript library using your package manager: PostHog AI ### npm ```bash npm install posthog-js ``` ### yarn ```bash yarn add posthog-js ``` ### pnpm ```bash pnpm add posthog-js ``` 2. 2 ## Add environment variables Required 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. .env.local PostHog AI ```bash NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN= NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com ``` 3. 3 ## Initialize PostHog Required Choose the integration method based on your Next.js version and router type. ## Next.js 15.3+ If you're using Next.js 15.3+, you can use `instrumentation-client.ts` for a lightweight, fast integration: instrumentation-client.ts PostHog AI ```typescript import posthog from 'posthog-js' posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN!, { api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST, defaults: '2026-01-30' }) ``` ## App router 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: app/providers.tsx PostHog AI ```typescript 'use client' import { usePathname, useSearchParams } from "next/navigation" import { useEffect } from "react" import posthog from 'posthog-js' import { PostHogProvider as PHProvider } from 'posthog-js/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: '2026-01-30' }) }, []) return ( {children} ) } ``` Then import the `PostHogProvider` component in your `app/layout.tsx` and wrap your app with it: app/layout.tsx PostHog AI ```typescript import './globals.css' import { PostHogProvider } from './providers' export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` ## Pages router For the Pages router, integrate PostHog at the root of your app in `pages/_app.tsx`: pages/\_app.tsx PostHog AI ```typescript import { useEffect } from 'react' import { Router } from 'next/router' import posthog from 'posthog-js' import { PostHogProvider } from 'posthog-js/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: '2026-01-30', loaded: (posthog) => { if (process.env.NODE_ENV === 'development') posthog.debug() } }) }, []) return ( ) } ``` **Defaults option** The `defaults` option automatically configures PostHog with recommended settings for new projects. See [SDK defaults](/docs/libraries/js.md#sdk-defaults) for details. 4. 4 ## Accessing PostHog on the client Recommended ## Next.js 15.3+ Once initialized in `instrumentation-client.ts`, import `posthog` from `posthog-js` anywhere and call the methods you need: app/checkout/page.tsx PostHog AI ```typescript 'use client' import posthog from 'posthog-js' export default function CheckoutPage() { function handlePurchase() { posthog.capture('purchase_completed', { amount: 99 }) } return } ``` ## App/Pages router Use the `usePostHog` hook to access PostHog in client components: app/checkout/page.tsx PostHog AI ```typescript 'use client' import { usePostHog } from 'posthog-js/react' export default function CheckoutPage() { const posthog = usePostHog() function handlePurchase() { posthog.capture('purchase_completed', { amount: 99 }) } return } ``` 5. 5 ## Watch session recordings Recommended Visit your site or app and interact with it for at least 10 seconds to generate a recording. Navigate between pages, click buttons, and fill out forms to capture meaningful interactions. [Watch your first recording →](/replay/home.md) 6. 6 ## Next steps Recommended Now that you're recording sessions, continue with the resources below to learn what else Session Replay enables within the PostHog platform. | Resource | Description | | --- | --- | | [Watching recordings](/docs/session-replay/how-to-watch-recordings.md) | How to find and watch session recordings | | [Privacy controls](/docs/session-replay/privacy.md) | How to mask sensitive data in recordings | | [Network recording](/docs/session-replay/network-recording.md) | How to capture network requests in recordings | | [Console log recording](/docs/session-replay/console-log-recording.md) | How to capture console logs in recordings | | [More tutorials](/docs/session-replay/tutorials.md) | Other real-world examples and use cases | ### Community questions Ask a question ### Was this page useful? HelpfulCould be better