Track leads with Better Auth

Automatically report sign-up leads to Refport using the @refport/better-auth plugin.

When a new user signs up through a Refport referral link, Refport needs to know about it so it can attribute the conversion to the right partner. The @refport/better-auth plugin handles this automatically at the server level — no extra code in your sign-up handler required.

Prerequisites

The refp_id cookie must be set on the user's browser before they sign up. This happens automatically when you call init() from refport-js (or use <RefportTracker>) on your frontend.
A Refport API key (find it in Settings → API Keys)

Setup

npm install refport @refport/better-auth

Create a Refport instance and register the plugin in your Better Auth config:

auth.ts

import { refportPlugin } from '@refport/better-auth';
import { betterAuth } from 'better-auth';
import { Refport } from 'refport';

const refport = new Refport({
  apiKey: process.env.REFPORT_API_KEY!,
});

export const auth = betterAuth({
  // ...your existing config
  plugins: [
    refportPlugin({ refport }),
  ],
});

Add the client-side plugin to your Better Auth client if you need TypeScript inference:

auth-client.ts

import { refportPluginClient } from '@refport/better-auth/client';
import { createAuthClient } from 'better-auth/client';

export const authClient = createAuthClient({
  plugins: [refportPluginClient()],
});

Make sure refport-js is initialised on every page so the refp_id cookie is captured when a visitor arrives via a referral link:

root-layout.ts

import { init } from 'refport-js';

init();

Or use the React component if your app is React-based:

layout.tsx

import { RefportTracker } from '@refport/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <RefportTracker />
        {children}
      </body>
    </html>
  );
}

What happens automatically

When a new user is created in Better Auth, the plugin:

Reads the refp_id cookie from the request
Calls refport.track.lead() with the user's ID, email, and name
Clears the cookie to prevent duplicate attribution
Logs (but does not throw) any errors so your sign-up flow is never interrupted

Verifying it works

After a test sign-up through a Refport link, open your Refport dashboard and navigate to Conversions. You should see a new lead event attributed to the link you used.

Configuration options

See the @refport/better-auth SDK reference for all plugin options, including custom event names and custom tracking functions.