Install Spurn on Next.js
@spurn/next gives a Next.js site three things: the tag as a component, server hits from proxy.ts, and conversions from your server code. It has no runtime dependencies besides next and react.
Before you start#
- Next.js 15 or later (16 uses
proxy.ts; 15 usesmiddleware.ts), React 18.2 or later. - Your site's keys from Spurn: Sites, then your site, then the Keys tab. The public key (
sp_pub_…) goes in the page. The secret key (sp_sec_…) stays on the server.
1. Install the package#
npm install @spurn/next
Add the secret key to your server environment, for example .env.local:
SPURN_SECRET_KEY=sp_sec_XXXXXXXXXXXXXXXXXXXXXXXX
Never prefix it with NEXT_PUBLIC_. That would ship it to every browser.
2. Add the tag#
Put SpurnScript once in the root layout:
// app/layout.tsx
import { SpurnScript } from '@spurn/next'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<SpurnScript siteKey="sp_pub_XXXXXXXXXXXXXXXXXXXXXXXX" />
</body>
</html>
)
}
| Prop | Default | |
|---|---|---|
siteKey | required | The public key. Safe in the browser. |
src | https://spurn.io/s.js | Where the tag loads from. |
strategy | afterInteractive | Or lazyOnload. |
nonce | none | For a Content Security Policy that uses nonces. |
The tag does nothing on organic visits. On a paid landing it scores the visit, and on later pages of that paid session it reports engagement.
3. Send server hits from the proxy#
A server hit gives Spurn the visitor's IP even when the page's JavaScript never runs, which is how bots that skip scripts get caught.
If you don't have a proxy.ts yet:
// proxy.ts
import { spurnProxy } from '@spurn/next/proxy'
export const proxy = spurnProxy()
export const config = {
matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
}
If you already have one, wrap it. Your response is returned unchanged:
// proxy.ts
import { NextResponse } from 'next/server'
import { withSpurn } from '@spurn/next/proxy'
export const proxy = withSpurn(async (request) => {
// your existing logic
return NextResponse.next()
})
On Next.js 15, use the same code in middleware.ts and export it as middleware.
The helper only acts on page requests whose URL has an ad click id or paid UTM tags. It sends the hit with event.waitUntil, so the response is never delayed, and it skips prefetches and client-side navigations. Every other request passes straight through.
Options, for both spurnProxy() and withSpurn(handler, options):
| Option | Default | |
|---|---|---|
secretKey | process.env.SPURN_SECRET_KEY | No key, no hits. |
endpoint | process.env.SPURN_ENDPOINT or https://spurn.io | |
ipHeader | first x-forwarded-for hop, then x-real-ip | Name a header your host sets and visitors can't forge, such as cf-connecting-ip behind Cloudflare. |
siteUrl | process.env.SPURN_SITE_URL, then the request URL | Your public origin, when the app sees an internal URL behind a reverse proxy. |
4. Report conversions#
After a payment succeeds, in a route handler or server action:
import { cookies } from 'next/headers'
import { after } from 'next/server'
import { readSpurnCookie, trackConversion } from '@spurn/next/server'
// `order` is your own record of the paid order.
const paidClick = readSpurnCookie((await cookies()).get('_spc')?.value)
after(() =>
trackConversion({
orderId: order.id, // '1001'
value: order.total, // 49.9, in major units
currency: order.currency, // 'USD'
...(paidClick ?? {}),
}),
)
_spc is the cookie the tag writes on a paid landing. readSpurnCookie turns it into { pageviewId, clickId }. trackConversion never throws: it resolves with { ok, status }, and status is 0 when no secret key is set or Spurn couldn't be reached. Wrapping it in after() keeps it off your response time. If the payment is confirmed by a webhook, the shopper's cookies aren't there; store the _spc value with the order at checkout and pass it in from the webhook.
Check it works#
- Add your own IP address to the allowlist in Spurn (Blocking, then Allowlist).
- Deploy, then open
https://yoursite.com/?gclid=test-123. - Open Clicks in Spurn. The visit appears within a minute. The site's Install tab shows Receiving and the time of the last server hit.
A test landing counts as a real paid click and uses one credit. Server hits from localhost carry your own machine's address; test on a deployed site.
Troubleshooting#
No server hits. Check SPURN_SECRET_KEY is set where the proxy runs, and that your matcher includes your landing pages.
Every hit has the same IP. Your host puts the visitor's address in a different header. Set ipHeader.
Clicks are rejected for the wrong site. Spurn checks the reporting page against your site's domain and extra hosts. Add preview or regional domains in Sites, then your site.
The tag is blocked by your CSP. Allow script-src https://spurn.io and connect-src https://spurn.io, or pass a nonce.
A consent banner. If you only load scripts after consent, render SpurnScript after it too. Server hits don't depend on it.
What data is sent#
- From the tag, on paid landings only: landing URL, referrer, browser signals used to spot automation, and engagement. See /docs/detection.
- From the proxy, on paid landings only: URL, IP address, user agent, referrer and language.
- From
trackConversion: order id, value, currency and the ids from_spc.