references/EXAMPLE.md
PostHog Nuxt 4 Example Project
Repository: https://github.com/PostHog/context-mill Path: basics/nuxt-4
README.md
PostHog Nuxt 4 example
This is a Nuxt 4 example demonstrating PostHog integration with product analytics, session replay, feature flags, and error tracking.
Nuxt 4 supports the @posthog/nuxt package, which provides automatic PostHog integration with built-in error tracking, source map uploads, and simplified configuration. This is the recommended approach for Nuxt 4+.
For Nuxt 3.0 - 3.6, you must use the posthog-js and posthog-node packages directly instead. See the Nuxt 3.6 example for that approach.
Features
- Product Analytics: Track user events and behaviors
- Session Replay: Record and replay user sessions
- Error Tracking: Automatic error capture on both client and server
- Source Maps: Automatic source map uploads when building for production
- User Authentication: Demo login system with PostHog user identification
- Server-side & Client-side Tracking: Examples of both tracking methods
- SSR Support: Server-side rendering with Nuxt 4
Getting Started
1. Install Dependencies
npm install
# or
pnpm install
2. Configure Environment Variables
Create a .env file in the root directory:
NUXT_PUBLIC_POSTHOG_PROJECT_TOKEN=your_posthog_project_token
NUXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
# Optional: For source map uploads
PROJECT_ID=your_project_id
PERSONAL_API_KEY=your_personal_api_key
Get your PostHog project token from your PostHog project settings.
For source map uploads, get your project ID from PostHog environment variables and your personal API key from PostHog user API keys (requires organization:read and error_tracking:write scopes).
3. Run the Development Server
npm run dev
# or
pnpm dev
Open http://localhost:3000 with your browser to see the app.
Project Structure
├── app/
│ ├── components/
│ │ └── AppHeader.vue # Navigation header with auth state
│ ├── composables/
│ │ └── useAuth.ts # Authentication composable
│ ├── middleware/
│ │ └── auth.ts # Authentication middleware
│ ├── pages/
│ │ ├── index.vue # Home/Login page
│ │ ├── burrito.vue # Demo feature page with event tracking
│ │ └── profile.vue # User profile with error tracking demo
│ ├── utils/
│ │ └── formValidation.ts # Form validation utilities
│ └── app.vue # Root component
├── assets/
│ └── css/
│ └── main.css # Global styles
├── server/
│ ├── api/
│ │ ├── auth/
│ │ │ └── login.post.ts # Login API with server-side tracking
│ │ └── burrito/
│ │ └── consider.post.ts # Burrito consideration API with server-side tracking
│ └── utils/
│ ├── posthog.ts # Server-side PostHog utility
│ └── users.ts # In-memory user storage utilities
├── nuxt.config.ts # Nuxt configuration with PostHog module
└── package.json
Key Integration Points
Module Configuration (nuxt.config.ts)
Nuxt 4 uses the @posthog/nuxt module for automatic PostHog integration:
export default defineNuxtConfig({
modules: ['@posthog/nuxt'],
runtimeConfig: {
public: {
posthog: {
publicKey: process.env.NUXT_PUBLIC_POSTHOG_PROJECT_TOKEN || '',
host: process.env.NUXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com',
},
},
},
posthogConfig: {
publicKey: process.env.NUXT_PUBLIC_POSTHOG_PROJECT_TOKEN || '',
host: process.env.NUXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com',
clientConfig: {
capture_exceptions: true, // Enables automatic exception capture on the client side (Vue)
__add_tracing_headers: ['localhost', 'yourdomain.com'], // Add your domain here
},
serverConfig: {
enableExceptionAutocapture: true, // Enables automatic exception capture on the server side (Nitro)
},
sourcemaps: {
enabled: true,
envId: process.env.PROJECT_ID || '',
personalApiKey: process.env.PERSONAL_API_KEY || '',
project: 'my-application',
version: '1.0.0',
},
},
})
Key Points:
- The
@posthog/nuxtmodule handles PostHog initialization automatically - Client-side error tracking is enabled via
capture_exceptions: true - Server-side error tracking is enabled via
enableExceptionAutocapture: true - Source map uploads are configured for better error tracking
- The
__add_tracing_headersoption automatically addsX-POSTHOG-SESSION-IDandX-POSTHOG-DISTINCT-IDheaders to requests
Important: do not identify users on the server-side.
User identification (app/pages/index.vue)
The user is identified when the user logs in on the client-side.
const posthog = usePostHog()
const handleSubmit = async () => {
const success = await auth.login(formData.username, formData.password)
if (success) {
// Identifying the user once on login/sign up is enough.
posthog?.identify(formData.username)
// Capture login event
posthog?.capture('user_logged_in')
}
}
The session and distinct ID are automatically passed to the backend via the X-POSTHOG-SESSION-ID and X-POSTHOG-DISTINCT-ID headers because we set the __add_tracing_headers option in the PostHog configuration.
Important: do not identify users on the server-side.
Server-side API routes (server/api/auth/login.post.ts)
Server-side API routes use the useServerPostHog() utility to get a PostHog Node client and extract session and user context from request headers:
import { useServerPostHog } from '../../utils/posthog'
import { getOrCreateUser, users } from '../../utils/users'
export default defineEventHandler(async (event) => {
const body = await readBody<{ username: string; password: string }>(event)
const { username, password } = body || {}
if (!username || !password) {
throw createError({
statusCode: 400,
message: 'Username and password required',
})
}
const user = getOrCreateUser(username)
const isNewUser = !users.has(username)
const sessionId = getHeader(event, 'x-posthog-session-id')
const distinctId = getHeader(event, 'x-posthog-distinct-id')
// Capture server-side login event
const posthog = useServerPostHog()
posthog.capture({
distinctId: distinctId,
event: 'server_login',
properties: {
$session_id: sessionId,
username: username,
isNewUser: isNewUser,
source: 'api',
},
})
return {
success: true,
user,
}
})
Key Points:
- Uses
useServerPostHog()utility to get a shared PostHog Node client instance - Extracts
sessionIdanddistinctIdfrom request headers usinggetHeader()(auto-imported from h3) - The PostHog client is reused across requests (singleton pattern)
- h3 functions like
defineEventHandler,readBody,createError,getHeaderare auto-imported in server routes
Event tracking (app/pages/burrito.vue)
The burrito consideration page demonstrates both client-side and server-side event tracking:
const posthog = usePostHog()
const handleConsideration = async () => {
if (!user.value) return
try {
// Call server-side API route
const response = await $fetch('/api/burrito/consider', {
method: 'POST',
body: { username: user.value.username },
})
if (response.success && response.user) {
auth.setUser(response.user)
hasConsidered.value = true
// Client-side tracking (in addition to server-side tracking)
posthog?.capture('burrito_considered', {
total_considerations: response.user.burritoConsiderations,
username: response.user.username,
})
setTimeout(() => {
hasConsidered.value = false
}, 2000)
}
} catch (err) {
console.error('Error considering burrito:', err)
}
}
The server-side route (server/api/burrito/consider.post.ts) also captures the event, demonstrating dual tracking.
Error tracking
Errors are captured automatically in multiple ways:
-
Automatic client-side capture - The
@posthog/nuxtmodule automatically captures Vue errors whencapture_exceptions: trueis set inposthogConfig.clientConfig. -
Automatic server-side capture - The module automatically captures Nitro errors when
enableExceptionAutocapture: trueis set inposthogConfig.serverConfig. -
Manual error capture in components (app/pages/profile.vue):
const posthog = usePostHog()
const triggerTestError = () => {
try {
throw new Error('Test error for PostHog error tracking')
} catch (err) {
posthog?.captureException(err)
}
}
Server-side tracking (server/api/auth/login.post.ts)
Server-side events use the shared PostHog Node client. Note that h3 functions are auto-imported in Nuxt server routes:
import { useServerPostHog } from '../../utils/posthog'
import { getOrCreateUser, users } from '../../utils/users'
export default defineEventHandler(async (event) => {
const body = await readBody<{ username: string; password: string }>(event)
const { username, password } = body || {}
// ... validation logic ...
// Extract headers using getHeader (auto-imported from h3)
const sessionId = getHeader(event, 'x-posthog-session-id')
const distinctId = getHeader(event, 'x-posthog-distinct-id')
// Capture server-side event
const posthog = useServerPostHog()
posthog.capture({
distinctId: distinctId,
event: 'server_login',
properties: {
$session_id: sessionId,
username: username,
isNewUser: isNewUser,
source: 'api',
},
})
return { success: true, user }
})
Key Points:
- The PostHog Node client is shared across requests via
useServerPostHog()utility getHeader()is auto-imported from h3 in Nuxt server routes (no need to import from 'h3')- h3 functions like
defineEventHandler,readBody,createErrorare also auto-imported - The
distinctIdandsessionIdare extracted from request headers and used to maintain context between client and server - No need to manually shutdown the client (it's managed by the module)
Accessing PostHog in components
PostHog is accessed via the usePostHog() composable provided by @posthog/nuxt:
const posthog = usePostHog()
posthog?.capture('event_name', { property: 'value' })
The composable is automatically typed and available throughout your Nuxt application.
Server-side PostHog utility (server/utils/posthog.ts)
The server utility provides a shared PostHog Node client instance:
import { PostHog } from 'posthog-node'
let client: PostHog | null = null
export function useServerPostHog(): PostHog {
if (!client) {
const config = useRuntimeConfig()
const posthogConfig = config.public.posthog
client = new PostHog(posthogConfig.publicKey, {
host: posthogConfig.host,
})
}
return client
}
This ensures a single PostHog client instance is reused across all server requests, improving performance.
Differences from Nuxt 3.6
- Module-based: Uses
@posthog/nuxtmodule instead of manual plugin setup - Automatic error tracking: Built-in error capture on both client and server
- Source map uploads: Automatic source map uploads for better error tracking
- Simplified API: Uses
usePostHog()composable instead ofuseNuxtApp().$posthog - Shared server client: Reuses PostHog Node client across requests instead of creating per-request
- Automatic imports: In Nuxt 4 server routes, h3 functions (
defineEventHandler,readBody,createError,getHeader, etc.) are auto-imported - no need to import them explicitly
Learn More
.env.example
NUXT_PUBLIC_POSTHOG_PROJECT_TOKEN=
NUXT_PUBLIC_POSTHOG_HOST=
PROJECT_ID=
PERSONAL_API_KEY=
app/app.vue
<template>
<div style="min-height: 100vh; display: flex; flex-direction: column; background: #f5f5f5; width: 100%;">
<AppHeader />
<main style="flex: 1;">
<NuxtPage />
</main>
</div>
</template>
app/components/AppHeader.vue
<template>
<header class="header">
<div class="header-container">
<nav>
<NuxtLink to="/">Home</NuxtLink>
<template v-if="user">
<NuxtLink to="/burrito">Burrito Consideration</NuxtLink>
<NuxtLink to="/profile">Profile</NuxtLink>
</template>
</nav>
<div class="user-section">
<span v-if="user">Welcome, {{ user.username }}!</span>
<span v-else>Not logged in</span>
<button v-if="user" @click="handleLogout" class="btn-logout">Logout</button>
</div>
</div>
</header>
</template>
<script setup lang="ts">
const posthog = usePostHog()
const auth = useAuth()
const user = computed(() => auth.user.value)
const handleLogout = async () => {
auth.logout()
posthog?.capture('user_logged_out')
posthog?.reset()
await navigateTo('/')
}
</script>
app/composables/useAuth.ts
interface User {
username: string
burritoConsiderations: number
}
const users: Map<string, User> = new Map()
export function useAuth() {
const user = useState<User | null>('auth-user', () => {
if (process.client) {
const storedUsername = localStorage.getItem('currentUser')
if (storedUsername) {
const existingUser = users.get(storedUsername)
if (existingUser) {
return existingUser
}
}
}
return null
})
const login = async (username: string, password: string): Promise<boolean> => {
try {
const response = await $fetch<{ success: boolean; user: User }>('/api/auth/login', {
method: 'POST',
body: { username, password },
})
if (response.success) {
let localUser = users.get(username)
if (!localUser) {
localUser = response.user
users.set(username, localUser)
}
user.value = localUser
if (process.client) {
localStorage.setItem('currentUser', username)
}
return true
}
return false
} catch (error) {
console.error('Login error:', error)
return false
}
}
const logout = () => {
user.value = null
if (process.client) {
localStorage.removeItem('currentUser')
}
}
const incrementBurritoConsiderations = () => {
if (user.value) {
user.value.burritoConsiderations++
users.set(user.value.username, user.value)
// Trigger reactivity
user.value = { ...user.value }
}
}
const setUser = (newUser: User) => {
user.value = newUser
users.set(newUser.username, newUser)
}
return {
user,
login,
logout,
incrementBurritoConsiderations,
setUser,
}
}
app/middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
const auth = useAuth()
const user = auth.user.value
// If user is not logged in, redirect to home/login page
if (!user) {
return navigateTo('/')
}
})
app/pages/burrito.vue
<template>
<div class="container">
<h1>Burrito consideration zone</h1>
<p>Take a moment to truly consider the potential of burritos.</p>
<div style="text-align: center">
<button @click="handleConsideration" class="btn-burrito">
I have considered the burrito potential
</button>
<p v-if="hasConsidered" class="success">
Thank you for your consideration! Count: {{ user?.burritoConsiderations }}
</p>
</div>
<div class="stats">
<h3>Consideration stats</h3>
<p>Total considerations: {{ user?.burritoConsiderations }}</p>
</div>
</div>
</template>
<script setup lang="ts">
definePageMeta({
middleware: 'auth'
})
const auth = useAuth()
const user = computed(() => auth.user.value)
const posthog = usePostHog()
const hasConsidered = ref(false)
const handleConsideration = async () => {
if (!user.value) return
try {
const response = await $fetch('/api/burrito/consider', {
method: 'POST',
body: { username: user.value.username },
})
if (response.success && response.user) {
auth.setUser(response.user)
hasConsidered.value = true
// Client-side tracking (in addition to server-side tracking)
posthog?.capture('burrito_considered', {
total_considerations: response.user.burritoConsiderations,
username: response.user.username,
})
setTimeout(() => {
hasConsidered.value = false
}, 2000)
}
} catch (err) {
console.error('Error considering burrito:', err)
}
}
</script>
app/pages/index.vue
<template>
<div class="container">
<h1 v-if="user">Welcome back, {{ user.username }}!</h1>
<h1 v-else>Welcome to Burrito Consideration App</h1>
<div v-if="user">
<p>You are now logged in. Feel free to explore:</p>
<ul>
<li>Consider the potential of burritos</li>
<li>View your profile and statistics</li>
</ul>
</div>
<div v-else>
<p>Please sign in to begin your burrito journey</p>
<form @submit.prevent="handleSubmit" class="form" novalidate>
<div class="form-group">
<label for="username">Username:</label>
<input
id="username"
v-model="formData.username"
type="text"
placeholder="Enter any username"
:class="{ 'error-input': errors.username }"
@blur="validateField('username')"
@input="clearError('username')"
/>
<p v-if="errors.username" class="field-error">{{ errors.username }}</p>
</div>
<div class="form-group">
<label for="password">Password:</label>
<input
id="password"
v-model="formData.password"
type="password"
placeholder="Enter any password"
:class="{ 'error-input': errors.password }"
@blur="validateField('password')"
@input="clearError('password')"
/>
<p v-if="errors.password" class="field-error">{{ errors.password }}</p>
</div>
<p v-if="error" class="error">{{ error }}</p>
<button type="submit" class="btn-primary" :disabled="isSubmitting">
{{ isSubmitting ? 'Signing in...' : 'Sign In' }}
</button>
</form>
<p class="note">
Note: This is a demo app. Use any username and password to sign in.
</p>
</div>
</div>
</template>
<script setup lang="ts">
import { loginSchema, validateForm, type LoginFormData } from '../utils/formValidation'
const auth = useAuth()
const user = computed(() => auth.user.value)
const posthog = usePostHog()
const formData = reactive<LoginFormData>({
username: '',
password: '',
})
const errors = reactive<Partial<Record<keyof LoginFormData, string>>>({})
const error = ref('')
const isSubmitting = ref(false)
const validateField = (field: keyof LoginFormData) => {
const fieldSchema = loginSchema.shape[field]
if (!fieldSchema) return
const result = fieldSchema.safeParse(formData[field])
if (!result.success) {
errors[field] = result.error.errors[0]?.message || 'Invalid value'
} else {
delete errors[field]
}
}
const clearError = (field: keyof LoginFormData) => {
delete errors[field]
}
const handleSubmit = async () => {
// Clear previous errors
error.value = ''
Object.keys(errors).forEach((key) => {
delete errors[key as keyof LoginFormData]
})
// Validate entire form
const validation = validateForm(loginSchema, formData)
if (!validation.success) {
Object.assign(errors, validation.errors)
return
}
isSubmitting.value = true
try {
const success = await auth.login(formData.username, formData.password)
if (success) {
// Identifying the user once on login/sign up is enough.
posthog?.identify(formData.username)
// Capture login event
posthog?.capture('user_logged_in')
formData.username = ''
formData.password = ''
await navigateTo('/')
} else {
error.value = 'Login failed. Please check your credentials and try again.'
}
} catch (err) {
console.error('Login failed:', err)
error.value = 'An error occurred during login. Please try again.'
} finally {
isSubmitting.value = false
}
}
</script>
app/pages/profile.vue
<template>
<div class="container">
<h1>User Profile</h1>
<div class="stats">
<h2>Your Information</h2>
<p><strong>Username:</strong> {{ user?.username }}</p>
<p><strong>Burrito Considerations:</strong> {{ user?.burritoConsiderations }}</p>
</div>
<div style="margin-top: 2rem">
<button @click="triggerTestError" class="btn-primary" style="background-color: #dc3545">
Trigger Test Error (for PostHog)
</button>
</div>
<div style="margin-top: 2rem">
<h3>Your Burrito Journey</h3>
<p v-if="user?.burritoConsiderations === 0">
You haven't considered any burritos yet. Visit the Burrito Consideration page to start!
</p>
<p v-else-if="user?.burritoConsiderations === 1">
You've considered the burrito potential once. Keep going!
</p>
<p v-else-if="user && user.burritoConsiderations < 5">
You're getting the hang of burrito consideration!
</p>
<p v-else-if="user && user.burritoConsiderations < 10">
You're becoming a burrito consideration expert!
</p>
<p v-else>You are a true burrito consideration master! 🌯</p>
</div>
</div>
</template>
<script setup lang="ts">
definePageMeta({
middleware: 'auth'
})
const auth = useAuth()
const user = computed(() => auth.user.value)
const posthog = usePostHog()
const triggerTestError = () => {
try {
throw new Error('Test error for PostHog error tracking')
} catch (err) {
console.error('Captured error:', err)
posthog?.captureException(err)
}
}
</script>
app/utils/formValidation.ts
import { z } from 'zod'
export const loginSchema = z.object({
username: z
.string()
.min(1, 'Username is required')
.min(3, 'Username must be at least 3 characters')
.max(50, 'Username must be less than 50 characters'),
password: z
.string()
.min(1, 'Password is required')
.min(3, 'Password must be at least 3 characters'),
})
export type LoginFormData = z.infer<typeof loginSchema>
export function validateForm<T>(schema: z.ZodSchema<T>, data: unknown): {
success: boolean
data?: T
errors?: Record<string, string>
} {
const result = schema.safeParse(data)
if (result.success) {
return { success: true, data: result.data }
}
const errors: Record<string, string> = {}
result.error.errors.forEach((error) => {
const path = error.path.join('.')
errors[path] = error.message
})
return { success: false, errors }
}
nuxt.config.ts
import { fileURLToPath } from 'node:url'
import { resolve, dirname } from 'node:path'
const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
compatibilityDate: '2025-07-15',
devt