@xenterprises/nuxt-x-affiliate

@xenterprises/nuxt-x-affiliate

The everything-layer for niche affiliate review sites. Two XAF-prefixed component families under one package:

• Referral / commission program (10 components, XAF* dashboard family) — signup forms, referral tracking, commission tiers, affiliate dashboards, social sharing (/affiliate, /affiliate/dashboard)
• Review-site content (89 components, XAF* review-site family) — star ratings, buy buttons, in-content disclosures, pros/cons, schema.org JSON-LD composables (Product/Review/FAQ/Breadcrumb/HowTo/Recipe/Article/BlogPosting), E-E-A-T author boxes, sticky CTAs, image galleries, video embeds, email capture, share buttons, opt-in legal disclosures, GDPR consent, customer reviews, decision matrices, image compare sliders, mega menus, decision flows, quizzes, polls, countdowns, shipping bars, bundles, newsletter archive, search results, trending, author archive, pagination, faceted search filters, taxonomy archives, currency switcher, page hero + section primitives, multi-language support (<XAFLocaleProvider> + useXafLocale()), plus the useXafExperiment() A/B testing composable (/reviews/[slug], /xaf smoke test)

See the XAF Components reference for the review-site family.

v0.4.1 — multi-language support. Adds <XAFLocaleProvider> + useXafLocale() for i18n. v0.4.0 added full Schema.org article coverage (useArticleSchema + useSiteMeta). v0.3.5 added 5 components + useXafExperiment. See Docus → nuxt-x-affiliate for the full reference.

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. The layer ships two families under the same prefix:

Referral / commission program family (app/components/X/AF/)

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)

Review-site content family (app/components/XAF/)

For niche review blogs (coffee-mug-warmer reviews, ergonomic-chair reviews, etc.) — wraps the useAffiliateContent composable with smart defaults, half-star ratings, FTC disclosures baked in, and multi-merchant support.

Component	Description
XAFStarRating	Half-star ratings with proper aria support
XAFBuyButton	The moneymaker — image, price, CTA, disclosure, tagging, tracking
XAFAffiliateLink	Slot-based link when you want full visual control over the CTA
XAFProsCons	1- or 2-column pros/cons; auto-collapses to 1 if either side is empty
XAFDisclosure	FTC disclosure text in 4 visual variants (inline / compact / banner / footer)
XAFArticleDisclosure	FTC 16 CFR §255.5 in-content snippet — sits at the top of every review / article page in-flow with the article typography. Optional Published/Updated timestamps.

See docs/XAF.md for the full review-site API reference and migration guide.

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()

useAffiliateContent() — review-site content API

Backs the XAF review-site family (<XAFBuyButton>, <XAFAffiliateLink>, etc.). Tag URLs, format prices, look up merchant metadata, and track clicks — all configured via app.config.ts under the xAffiliateContent key.

const {
  config,          // Resolved XAffiliateContentConfig (currency, locale, disclosure, merchants)
  getMerchant,     // (id: MerchantId) => XAffiliateContentMerchant — display metadata
  hasTag,          // (id: MerchantId) => boolean — is a tag configured for this merchant?
  taggedUrl,       // (merchant, url) => string — append tag, idempotent
  taggedLink,      // (link: AffiliateLink) => AffiliateLink — same, but on a structured object
  formatPrice,     // (amount: number) => string — Intl-formatted with configured currency/locale
  trackClick,      // (payload) => void — pushes affiliate_click to dataLayer if GTM/GA4 loaded
} = useAffiliateContent()

Configure merchants under app.config.ts:

export default defineAppConfig({
  xAffiliateContent: {
    currency: 'USD',
    locale: 'en-US',
    disclosure: {
      text: 'Affiliate link. We may earn a commission at no cost to you.',
      position: 'above', // 'above' | 'below' | 'none'
    },
    merchants: {
      amazon: { tagValue: 'yourtag-20' },
      walmart: { tagValue: 'TODO' },
    },
  },
})

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
/reviews/[slug]	Canonical review-page mockup showing the XAF review-site family wired together (<XAFArticleDisclosure> + <XAFStarRating> + <XAFBuyButton> + <XAFAffiliateLink> + <XAFProsCons>)
/xaf	XAF review-site smoke test — every variant of every review-site component for visual QA

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)

Review-site content config — xAffiliateContent

Configure the XAF review-site family under a separate top-level key. See the XAF reference for the full schema.

Option	Type	Default	Description
currency	string	'USD'	ISO 4217 currency code for price formatting
locale	string	'en-US'	Locale for currency / date formatting
disclosure.text	string	—	FTC disclosure text shown next to buy buttons
disclosure.position	'above' | 'below' | 'none'	—	Where the disclosure renders relative to the button
merchants.<id>.tagValue	string	—	Affiliate tag for the merchant (e.g. Amazon Associates tag)
merchants.<id>.displayName	string	title-cased id	Display name for the merchant
merchants.<id>.ctaLabel	string	'View on {merchant}'	Override the buy-button label
merchants.<id>.color	string	—	Nuxt UI color for the merchant chip / button
merchants.<id>.icon	string	—	Iconify class for the merchant icon

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/: Three composables — useAffiliate + useReferralTracking (referral program state and tracking), useAffiliateContent (review-site content API). All SSR-safe.
• app/components/X/AF/: 10 referral/commission components under the XAF prefix. Built on Nuxt UI v4 primitives.
• app/components/XAF/: 6 review-site components under the XAF prefix — <XAFStarRating>, <XAFBuyButton>, <XAFAffiliateLink>, <XAFProsCons>, <XAFDisclosure>, <XAFArticleDisclosure>.
• app/pages/affiliate/: Landing page and dashboard route. The consuming app handles authentication and data fetching.
• app/pages/reviews/[slug].vue: Canonical review-page mockup using the XAF review-site family.
• app/types/: TypeScript interfaces for the referral domain (Affiliate, Referral, Payout, CommissionTier, etc.) re-exported from app/types/index.ts, plus the review-site content types in app/types/affiliate.ts.