Registry / auth-security / affiliate-better-auth

affiliate-better-auth

library0.6.6jsnpmunverified

affiliate-better-auth is a specialized plugin designed to integrate referral and affiliate tracking capabilities into applications built with the Better Auth authentication system. It currently stands at version 0.6.6, with recent releases indicating an active development cadence, though the changelog mentions `0.1.0` for multiple versions. The library simplifies the process of adding referral links and tracking by automatically creating necessary database schemas via the Better Auth adapter. It provides both server-side and client-side plugins to manage referral code generation, cookie issuance for tracking, and recording referrals upon new user creation. Its key differentiators include its tight integration with the Better Auth ecosystem, offering a streamlined solution for applications already using Better Auth for authentication, rather than a standalone, more complex affiliate platform.

auth-security

npm install affiliate-better-auth

github ↗package ↗

INSTALL

IMPORT

SIG · AFFILIATE-BETTER-A

affiliate-better-auth

auth-securityjavascriptv0.6.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

affiliatePlugin

✓ import { affiliatePlugin } from 'affiliate-better-auth';

✗ const { affiliatePlugin } = require('affiliate-better-auth');

Used for server-side integration with Better Auth. The package is primarily ESM.

affiliateClientPlugin

✓ import { affiliateClientPlugin } from 'affiliate-better-auth';

✗ const { affiliateClientPlugin } = require('affiliate-better-auth');

Used for client-side integration, primarily to pass the plugin to createAuthClient. The package is primarily ESM.

betterAuth

✓ import { betterAuth } from 'better-auth';

✗ import betterAuth from 'better-auth';

The core server-side Better Auth instance into which affiliatePlugin is loaded.

createAuthClient

✓ import { createAuthClient } from 'better-auth/client';

✗ import { createAuthClient } from 'better-auth';

The client-side factory function for Better Auth; affiliateClientPlugin integrates here.

Demonstrates server-side initialization of `affiliate-better-auth` by integrating `affiliatePlugin` into the `betterAuth` instance, enabling referral tracking functionalities and automatic schema generation.

import { betterAuth } from 'better-auth'; import { affiliatePlugin } from 'affiliate-better-auth'; // Configure Better Auth with the affiliate plugin export const auth = betterAuth({ plugins: [ // Initialize the affiliate plugin on the server affiliatePlugin() ] }); // Example of accessing an affiliate endpoint (conceptual, not runnable directly without a server setup) // (You would typically expose these via your API routes) // auth.get('/affiliate/generate-link', (req, res) => { // if (!req.session) return res.status(401).send('Unauthorized'); // const link = auth.plugins.affiliate.generateLink(req.session.userId); // res.json({ link }); // }); // Client-side example (requires a separate client-side bundle) // import { createAuthClient } from 'better-auth/client'; // import { affiliateClientPlugin } from 'affiliate-better-auth'; // export const clientAuth = createAuthClient({ // plugins: [ // affiliateClientPlugin() // ] // }); // // To issue a cookie from the client after receiving a referral code, for example from a URL query parameter // // clientAuth.plugins.affiliate.issueCookie(codeFromQueryParams);

Debug

Known issues

breakingThis package is tightly coupled with `better-auth`. Major version upgrades of `better-auth` (e.g., from 1.x to 2.x) may introduce breaking changes requiring updates to `affiliate-better-auth` or its configuration.

fix

Always check the release notes for both `affiliate-better-auth` and `better-auth` when upgrading major versions. Ensure your `better-auth` peer dependency range is compatible.

affects: >=0.1.0

gotchaReferral tracking relies on an `affiliate` cookie being set. Users blocking cookies or using incognito modes may not be accurately tracked, or the referral link logic might not function as expected without manual handling.

fix

Communicate cookie usage clearly to users. For critical referral flows, consider fallback mechanisms or alternative tracking methods alongside cookie-based tracking. Ensure your frontend properly calls `POST /affiliate/issue-cookie`.

affects: >=0.1.0

gotchaThe package automatically creates minimal schema for `affiliate_code` and `affiliate` models via the Better Auth adapter. If you have existing tables or a different schema preference, this might lead to conflicts or require manual migration/adjustments.

fix

Review the automatically generated schema. If conflicts arise, you may need to manually adjust your database schema or fork the plugin to customize schema generation if allowed by Better Auth's plugin API.

affects: >=0.1.0

gotchaWhile recent `affiliate-better-auth` versions show `0.6.x`, the provided changelog consistently refers to `0.1.0`. This discrepancy might indicate a versioning inconsistency or a misaligned changelog, which can make tracking specific changes or breaking points difficult.

fix

Rely on the npm package version for compatibility and feature tracking (e.g., `0.6.6`). For detailed change information, consult the GitHub repository directly if the README/changelog is ambiguous.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'affiliate-better-auth' or 'better-auth'

One or both packages are not installed or are not resolvable in the module path. This can happen with incorrect `pnpm`, `npm`, or `yarn` commands.

fix

Run `pnpm add affiliate-better-auth better-auth` (or `npm i` / `yarn add`) in your project root to ensure both the plugin and its peer dependency are correctly installed.

TypeError: auth.plugins.affiliate.generateLink is not a function

The `affiliatePlugin` was not correctly initialized or the `auth` instance does not have the expected `affiliate` property on its `plugins` object.

fix

Ensure `affiliatePlugin()` is included in the `plugins` array when configuring `betterAuth` on the server: `betterAuth({ plugins: [affiliatePlugin()] })`.

Error: Peer dependency 'better-auth@^1.3.0' not installed or incompatible.

Your installed version of `better-auth` does not match the required peer dependency range for `affiliate-better-auth`.

fix

Install a compatible version of `better-auth`. For example, `npm install better-auth@^1.3.0` or update your `package.json` and run `npm install`.

Upgrade

Version history

0.6.6latest on npm

Audit

Dependencies

better-authrequiredPeer dependency required for core authentication and plugin integration. This package extends Better Auth's functionality.

Agent activity

44 hits · last 30 days

node

Resources

githubhttps://github.com/BartoszTrading/affiliate-better-auth ↗

packagehttps://www.npmjs.com/package/affiliate-better-auth ↗