@xenterprises/nuxt-x-affiliate

Nuxt layer for affiliate/referral program pages, tracking, and dashboard components. Provides everything needed to add an affiliate program to your Nuxt app: signup forms, referral link tracking, commission tier display, affiliate dashboards, and social sharing.

Install

npm install @xenterprises/nuxt-x-affiliate

Usage

Extend the layer in your nuxt.config.ts:

export default defineNuxtConfig({
  extends: [['@xenterprises/nuxt-x-affiliate', { install: true }]],
})

Override defaults in your app.config.ts:

export default defineAppConfig({
  xAffiliate: {
    referralParam: 'ref',
    referralBaseUrl: 'https://yoursite.com',
    cookieDays: 30,
    currency: 'USD',
    shareMessage: 'Check this out!',
  },
})

Components

All components use the XAF prefix and are auto-imported.

| Component | Description | |---|---| | XAFBanner | Promotional banner with hero text, CTA, and variant styling (gradient/primary/dark) | | XAFCommissionTiers | Displays commission tiers with current tier highlight and progress bar | | XAFDashboard | Full affiliate dashboard composing all sub-components | | XAFLeaderboard | Top affiliates ranking with earnings and referral counts | | XAFPayoutHistory | Payout history table with status badges | | XAFReferralLink | Referral link display with copy-to-clipboard | | XAFReferralTable | Referral tracking table with source, status, commission, and date | | XAFShareButtons | Social sharing buttons (Twitter, Facebook, LinkedIn, Email) | | XAFSignupForm | Affiliate application form with configurable fields | | XAFStatsCards | Stats overview cards (clicks, conversions, earnings, pending) |

Component Props

XAFBanner

| Prop | Type | Default | Description | |---|---|---|---| | title | string | required | Banner headline text | | description | string | - | Subtitle text | | ctaLabel | string | 'Join Now' | Call-to-action button label | | ctaTo | string | '/affiliate' | CTA link destination | | ctaColor | string | 'white' | CTA button color | | highlightText | string | - | Highlight badge text | | variant | 'primary' \| 'gradient' \| 'dark' | 'gradient' | Visual style | | showDecoration | boolean | true | Show background decoration |

XAFSignupForm

| Prop | Type | Default | Description | |---|---|---|---| | title | string | 'Join Our Affiliate Program' | Form title | | subtitle | string | 'Earn commissions...' | Form subtitle | | submitLabel | string | 'Apply Now' | Submit button label | | successMessage | string | 'Application submitted...' | Success feedback message | | showWebsite | boolean | true | Show website URL field | | showCompany | boolean | false | Show company name field | | showMessage | boolean | true | Show promotion strategy textarea |

Emits: submit(data: AffiliateFormData)

XAFStatsCards

| Prop | Type | Default | Description | |---|---|---|---| | stats | AffiliateStats \| null | required | Stats data object | | currency | string | 'USD' | Currency code for formatting |

XAFReferralLink

| Prop | Type | Default | Description | |---|---|---|---| | affiliate | Affiliate \| null | required | Current affiliate data | | referralUrl | string | required | Full referral URL to display/copy |

XAFCommissionTiers

| Prop | Type | Default | Description | |---|---|---|---| | tiers | CommissionTier[] | required | Array of commission tiers | | currentTierId | string \| null | null | ID of the affiliate's current tier | | nextTier | CommissionTier \| null | null | Next tier to reach | | progressToNextTier | number | 0 | Progress percentage (0-100) |

XAFLeaderboard

| Prop | Type | Default | Description | |---|---|---|---| | entries | { name, referrals, earnings }[] | required | Leaderboard entries | | title | string | 'Top Affiliates' | Section title | | period | string | 'This Month' | Time period badge | | currency | string | 'USD' | Currency code |

Composables

useAffiliate()

Core composable for managing affiliate state and computed properties.

const {
  config,            // Reactive app config for xAffiliate
  affiliate,         // Current affiliate (Affiliate | null)
  stats,             // Affiliate stats (AffiliateStats | null)
  referrals,         // Referral list (Referral[])
  payouts,           // Payout list (Payout[])
  tiers,             // Commission tiers (CommissionTier[])
  isLoading,         // Loading state
  error,             // Error message
  isAuthenticated,   // Whether affiliate is set
  isActive,          // Whether affiliate status is 'active'
  referralUrl,       // Computed referral URL with code
  currentTier,       // Current commission tier
  nextTier,          // Next tier to reach
  progressToNextTier, // Progress % to next tier
  setAffiliate,      // Set affiliate data
  setStats,          // Set stats data
  setReferrals,      // Set referrals data
  setPayouts,        // Set payouts data
  setTiers,          // Set commission tiers
  reset,             // Clear all state
} = useAffiliate()

useReferralTracking()

Composable for detecting and persisting referral codes via URL parameters and cookies.

const {
  referralCode,    // Detected referral code (string | null)
  referralSource,  // UTM source (string | null)
  detectReferral,  // Detect from URL params or cookie
  clearReferral,   // Clear stored referral
  hasReferral,     // Check if referral exists
  getReferralCode, // Get code from state or cookie
} = useReferralTracking()

Pages

The layer provides these pages:

| Route | Description | |---|---| | /affiliate | Landing page with hero, benefits, commission tiers, and signup form | | /affiliate/dashboard | Authenticated affiliate dashboard with all metrics and tools |

App Config Options

Configure the layer via app.config.ts under the xAffiliate key:

| Option | Type | Default | Description | |---|---|---|---| | referralParam | string | 'ref' | URL query parameter for referral codes | | referralBaseUrl | string | '' | Base URL for referral links | | cookieName | string | 'x_affiliate_ref' | Cookie name for storing referral codes | | cookieDays | number | 30 | Cookie expiration in days | | currency | string | 'USD' | Default currency for formatting | | shareMessage | string | 'Check this out!' | Default social share message | | landing.hero | object | See defaults | Hero section config (title, description, ctaLabel, highlightText, variant) | | landing.benefits | array | 3 defaults | Benefits cards (icon, title, description) | | signup.* | object | See defaults | Signup form config (title, subtitle, submitLabel, field visibility) |

Types

All types are exported from app/types/index.ts:

• Affiliate - Affiliate profile with status, tier, commission rate
• Referral - Individual referral with source, status, commission
• AffiliateStats - Aggregate stats (clicks, conversions, earnings)
• Payout - Payout record with amount, status, method
• CommissionTier - Tier definition with rate and bonuses
• AffiliateResource - Marketing material (banner, link, template)
• SharePlatform - Social share platform config

How It Works

The layer provides a complete affiliate/referral program UI kit built on Nuxt UI v4:

1. Referral Tracking (useReferralTracking): Detects referral codes from URL query parameters (e.g., ?ref=CODE), stores them in a cookie with configurable expiration, and persists across page navigations. SSR-safe with client-side cookie operations guarded by import.meta.server checks.

2. State Management (useAffiliate): Uses Nuxt's useState for SSR-safe shared state. The consuming app is responsible for fetching data from its API and calling setAffiliate(), setStats(), etc. to populate the state. Computed properties automatically derive the current tier, next tier, and progress from the data.

3. Configuration (app.config.ts): All UI text, form fields, and behavior are configurable through app.config.ts. The layer provides sensible defaults that can be overridden by the consuming app. Type augmentation ensures IDE autocomplete.

4. Components: Auto-imported with XAF prefix. Components use Nuxt UI primitives (UCard, UButton, UBadge, UProgress, etc.) for consistent styling and dark mode support. All components handle empty/null states gracefully.

5. Pages: Two routes are provided: a public landing/signup page and an authenticated dashboard. The dashboard checks isAuthenticated from the composable and shows a fallback when no affiliate is loaded.

Layer Architecture

• nuxt.config.ts: Registers @nuxt/ui module and Tailwind CSS. Minimal config - feature configuration lives in app.config.ts.
• app.config.ts: Defines all configurable options under the xAffiliate namespace with type augmentation for AppConfigInput. Consumer apps override values here.
• app/composables/: Two composables (useAffiliate, useReferralTracking) provide all state management and referral tracking logic. SSR-safe via useState and import.meta.server guards.
• app/components/X/AF/: 10 auto-imported components following the XAF naming convention. Built on Nuxt UI v4 primitives.
• app/pages/affiliate/: Landing page and dashboard route. The consuming app handles authentication and data fetching.
• app/types/: TypeScript interfaces for all domain objects.