{"id":16755,"library":"affiliate-better-auth","title":"Affiliate Better Auth","description":"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.","status":"active","version":"0.6.6","language":"javascript","source_language":"en","source_url":"https://github.com/BartoszTrading/affiliate-better-auth","tags":["javascript","better-auth","affiliate","referral","typescript"],"install":[{"cmd":"npm install affiliate-better-auth","lang":"bash","label":"npm"},{"cmd":"yarn add affiliate-better-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add affiliate-better-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for core authentication and plugin integration. This package extends Better Auth's functionality.","package":"better-auth","optional":false}],"imports":[{"note":"Used for server-side integration with Better Auth. The package is primarily ESM.","wrong":"const { affiliatePlugin } = require('affiliate-better-auth');","symbol":"affiliatePlugin","correct":"import { affiliatePlugin } from 'affiliate-better-auth';"},{"note":"Used for client-side integration, primarily to pass the plugin to createAuthClient. The package is primarily ESM.","wrong":"const { affiliateClientPlugin } = require('affiliate-better-auth');","symbol":"affiliateClientPlugin","correct":"import { affiliateClientPlugin } from 'affiliate-better-auth';"},{"note":"The core server-side Better Auth instance into which affiliatePlugin is loaded.","wrong":"import betterAuth from 'better-auth';","symbol":"betterAuth","correct":"import { betterAuth } from 'better-auth';"},{"note":"The client-side factory function for Better Auth; affiliateClientPlugin integrates here.","wrong":"import { createAuthClient } from 'better-auth';","symbol":"createAuthClient","correct":"import { createAuthClient } from 'better-auth/client';"}],"quickstart":{"code":"import { betterAuth } from 'better-auth';\nimport { affiliatePlugin } from 'affiliate-better-auth';\n\n// Configure Better Auth with the affiliate plugin\nexport const auth = betterAuth({\n\tplugins: [\n\t\t// Initialize the affiliate plugin on the server\n\t\taffiliatePlugin()\n\t]\n});\n\n// Example of accessing an affiliate endpoint (conceptual, not runnable directly without a server setup)\n// (You would typically expose these via your API routes)\n// auth.get('/affiliate/generate-link', (req, res) => {\n//   if (!req.session) return res.status(401).send('Unauthorized');\n//   const link = auth.plugins.affiliate.generateLink(req.session.userId);\n//   res.json({ link });\n// });\n\n// Client-side example (requires a separate client-side bundle)\n// import { createAuthClient } from 'better-auth/client';\n// import { affiliateClientPlugin } from 'affiliate-better-auth';\n// export const clientAuth = createAuthClient({\n// \tplugins: [\n// \t\taffiliateClientPlugin()\n// \t]\n// });\n// // To issue a cookie from the client after receiving a referral code, for example from a URL query parameter\n// // clientAuth.plugins.affiliate.issueCookie(codeFromQueryParams);","lang":"typescript","description":"Demonstrates server-side initialization of `affiliate-better-auth` by integrating `affiliatePlugin` into the `betterAuth` instance, enabling referral tracking functionalities and automatic schema generation."},"warnings":[{"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.","message":"This 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.","severity":"breaking","affected_versions":">=0.1.0"},{"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`.","message":"Referral 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"While 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: Cannot find module 'affiliate-better-auth' or 'better-auth'"},{"fix":"Ensure `affiliatePlugin()` is included in the `plugins` array when configuring `betterAuth` on the server: `betterAuth({ plugins: [affiliatePlugin()] })`.","cause":"The `affiliatePlugin` was not correctly initialized or the `auth` instance does not have the expected `affiliate` property on its `plugins` object.","error":"TypeError: auth.plugins.affiliate.generateLink is not a function"},{"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`.","cause":"Your installed version of `better-auth` does not match the required peer dependency range for `affiliate-better-auth`.","error":"Error: Peer dependency 'better-auth@^1.3.0' not installed or incompatible."}],"ecosystem":"npm","meta_description":null}