|
| 1 | +# Simple Analytics for Next.js |
| 2 | + |
| 3 | +This package provides a simple way to add privacy-friendly pageview and event tracking using Simple Analytics to your Next.js application. |
| 4 | + |
| 5 | +## Documentation |
| 6 | + |
| 7 | +You can find the full documentation for this package at [simpleanalytics-next-docs.vercel.app](https://simpleanalytics-next-docs.vercel.app). |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +To install the package, run: |
| 12 | + |
| 13 | +```bash |
| 14 | +npm i @simpleanalytics/next |
| 15 | +``` |
| 16 | + |
| 17 | +## Usage |
| 18 | + |
| 19 | +### Configure environment variables |
| 20 | + |
| 21 | +You need to pass the website domain you have added to the [Simple Analytics dashboard](https://dashboard.simpleanalytics.com/) as an environment variable: |
| 22 | + |
| 23 | +```txt |
| 24 | +NEXT_PUBLIC_SIMPLE_ANALYTICS_HOSTNAME=example.com |
| 25 | +SIMPLE_ANALYTICS_HOSTNAME=example.com |
| 26 | +``` |
| 27 | + |
| 28 | +### Update your Next.js config to enable client-side analytics |
| 29 | + |
| 30 | +To enable client-side tracking and to ensure the Simple Analytics script you must add the Next.js plugin `withSimpleAnalytics` from `@simpleanalytics/next` in your Next.js config (`next.config.ts`): |
| 31 | + |
| 32 | +```typescript |
| 33 | +import { NextConfig } from "next"; |
| 34 | +import withSimpleAnalytics from "@simpleanalytics/next/plugin"; |
| 35 | + |
| 36 | +const nextConfig: NextConfig = { |
| 37 | + /* the rest of your Next.js config */ |
| 38 | +}; |
| 39 | + |
| 40 | +export default withSimpleAnalytics(nextConfig); |
| 41 | +``` |
| 42 | + |
| 43 | +### Include the analytics script |
| 44 | + |
| 45 | +The client-side analytics component, `SimpleAnalytics`, imports the Simple Analytics tracking script: |
| 46 | + |
| 47 | +```tsx |
| 48 | +import { SimpleAnalytics } from "@simpleanalytics/next"; |
| 49 | + |
| 50 | +export default function RootLayout({ |
| 51 | + children, |
| 52 | +}: Readonly<{ |
| 53 | + children: React.ReactNode; |
| 54 | +}>) { |
| 55 | + return ( |
| 56 | + <html lang="en"> |
| 57 | + <body> |
| 58 | + {children} |
| 59 | + <SimpleAnalytics /> |
| 60 | + </body> |
| 61 | + </html> |
| 62 | + ); |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +### Tracking events |
| 67 | + |
| 68 | +#### Usage in client components |
| 69 | + |
| 70 | +To start tracking programmatically tracking events in client components use the `trackEvent` function. |
| 71 | +This requires the `<SimpleAnalytics />` component to be present on the page or layout. |
| 72 | + |
| 73 | +```tsx |
| 74 | +"use client"; |
| 75 | + |
| 76 | +import { trackEvent } from "@simpleanalytics/next"; |
| 77 | +import { useState } from "react"; |
| 78 | + |
| 79 | +export default function Page() { |
| 80 | + return ( |
| 81 | + <div> |
| 82 | + <button |
| 83 | + onClick={() => { |
| 84 | + trackEvent("clicked"); |
| 85 | + }} |
| 86 | + > |
| 87 | + increment |
| 88 | + </button> |
| 89 | + </div> |
| 90 | + ); |
| 91 | +} |
| 92 | +``` |
| 93 | + |
| 94 | +#### Usage in Server Actions |
| 95 | + |
| 96 | +To track events in server actions, use the `trackEvent` function from `@simpleanalytics/next/server`. |
| 97 | +This function requires you to pass the request headers that can be obtained using `headers`. |
| 98 | + |
| 99 | +```typescript |
| 100 | +"use server"; |
| 101 | + |
| 102 | +import { after } from "next/server"; |
| 103 | +import { headers } from "next/headers"; |
| 104 | +import { trackEvent } from "@simpleanalytics/next/server"; |
| 105 | + |
| 106 | +export async function exampleAction() { |
| 107 | + // Add your logic here... |
| 108 | + |
| 109 | + after(async () => { |
| 110 | + await trackEvent("event_in_example_action", { |
| 111 | + headers: await headers(), |
| 112 | + }); |
| 113 | + }); |
| 114 | + |
| 115 | + return { success: true }; |
| 116 | +} |
| 117 | +``` |
0 commit comments