Configuration

app.config.ts reference for @xenterprises/nuxt-x-affiliate — covers xAffiliate (dashboard + brand + author + legal + tracking) and xAffiliateContent (merchants + currency).

Configuration

The layer exposes two config namespaces in app.config.ts — xAffiliate (five areas) and xAffiliateContent:

xAffiliate.legal — canonical legal pages + opt-in disclosures
xAffiliate.author — site author identity (E-E-A-T)
xAffiliate.brand — site brand identity (OG, Twitter, Organization schema)
xAffiliate.tracking — GTM / GA4 / Clarity IDs
xAffiliate.referral* / landing.* / signup.* — dashboard-family config
xAffiliateContent — merchant tagging + currency

Your app.config.tsmust live in the consuming project's app/ directory (app/app.config.ts). Nuxt 4's default srcDir is app/ — a root-level app.config.ts silently yields a merged config with only Nuxt UI defaults and none of your overrides.

Full example

export default defineAppConfig({
  xAffiliate: {
    // 1) Legal — central canonical pages + opt-in disclosures
    legal: {
      baseUrl: 'https://x.enterprises/legal',
      optIn: {
        health: false,           // → enables <XAFHealthDisclaimer>
        aiContent: true,         // → enables <XAFAIContentDisclosure>
        sponsoredContent: false, // → enables <XAFSponsoredContentDisclosure>
      },
    },

    // 2) Author — site-wide identity (E-E-A-T signal)
    author: {
      name: 'Jane Reviewer',
      role: 'Senior Kitchen Gear Editor',
      bio: '8 years reviewing kitchen equipment for home cooks.',
      image: '/team/jane.jpg',
      credentials: ['CNC-certified', '8 years testing kitchen gear'],
      social: {
        twitter: 'https://twitter.com/jane',
        linkedin: 'https://linkedin.com/in/jane',
        website: 'https://janereviews.com',
      },
    },

    // 3) Brand — drives Organization schema + meta tags
    brand: {
      name: 'BestKitchenGear.com',
      tagline: 'We test so you don\'t have to.',
      logo: 'https://bestkitchengear.com/logo.png',
      url: 'https://bestkitchengear.com',
      ogImage: 'https://bestkitchengear.com/og.png',
      twitter: 'bestkitchengear',
      ogType: 'website',
      locale: 'en_US',
    },

    // 4) Tracking — GTM / GA4 / Clarity auto-injection
    tracking: {
      gtmId: 'GTM-XXXXXXX',
      ga4Id: 'G-XXXXXXXX',
      clarityId: 'abc123def4',
      autoInject: true,
    },

    // 5) Referral / dashboard family
    referralParam: 'ref',
    referralBaseUrl: 'https://yoursite.com',
    cookieName: 'x_affiliate_ref',
    cookieDays: 30,
    currency: 'USD',
    shareMessage: 'Check this out!',
    landing: { /* ... */ },
    signup: { /* ... */ },
  },

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

1) `xAffiliate.legal`

Key	Type	Default	Description
`baseUrl`	`string`	`'https://x.enterprises/legal'`	Canonical URL where the site's legal pages live. Every consuming site points at the central home — no per-site legal pages to maintain.
`optIn.health`	`boolean`	`false`	When `true`, sites covering health/medical topics should render `<XAFHealthDisclaimer>` on relevant pages.
`optIn.aiContent`	`boolean`	`false`	When `true`, render `<XAFAIContentDisclosure>` per FTC 2024+ guidance on AI-assisted content.
`optIn.sponsoredContent`	`boolean`	`false`	When `true`, render `<XAFSponsoredContentDisclosure>` on paid-placement posts.
`pages.affiliateDisclosure`	`string`	`{baseUrl}/affiliate-disclosure`	Override the canonical disclosure URL.
`pages.privacy`	`string`	`{baseUrl}/privacy-policy`	Override the privacy policy URL.
`pages.terms`	`string`	`{baseUrl}/terms`	Override the terms URL.
`pages.cookies`	`string`	`{baseUrl}/cookie-policy`	Override the cookie policy URL.
`pages.earnings`	`string`	`{baseUrl}/earnings-disclaimer`	Override the earnings disclaimer URL.
`pages.aiContent`	`string`	`{baseUrl}/ai-content`	Override the AI content policy URL.
`pages.sponsoredContent`	`string`	`{baseUrl}/sponsored-content`	Override the sponsored content policy URL.
`pages.health`	`string`	`{baseUrl}/health-disclaimer`	Override the health disclaimer URL.
`pages.editorialPolicy`	`string`	`{baseUrl}/editorial-policy`	Override the editorial policy URL.
`pages.contact`	`string`	`{baseUrl}/contact`	Override the contact page URL.

The marketing layer (@xenterprises/nuxt-x-marketing) renders the 5-link default legal nav (Affiliate Disclosure, Privacy, Terms, Cookie, Earnings) using these URLs, plus the 3-link conditional set (Health, AI Content, Sponsored Content) driven by optIn.* flags.

2) `xAffiliate.author`

Key	Type	Required	Description
`name`	`string`	✅	Author name. Drives `<XAFAuthorBox>` and `Person` schema.
`role`	`string`		One-line role (e.g. "Senior Kitchen Gear Editor").
`bio`	`string`		1–3 sentence bio shown in the author box and `Person` schema description.
`image`	`string`		Avatar URL (square, 200×200+ recommended).
`credentials`	`string[]`		Trust badges shown as pills (e.g. `['CNC-certified', '8 years reviewing']`).
`social.twitter`	`string`		Twitter / X profile URL.
`social.linkedin`	`string`		LinkedIn profile URL.
`social.website`	`string`		Personal site URL.
`social.email`	`string`		Email address (`mailto:` link in author box).

3) `xAffiliate.brand`

Key	Type	Default	Description
`name`	`string`	`undefined`	Site name. Drives `<title>` template, OG `site_name`, and Organization schema. Every site must set this.
`tagline`	`string`	`undefined`	One-line tagline.
`logo`	`string`		Logo URL. Used in Organization schema + Open Graph.
`url`	`string`		Canonical site origin (e.g. `'https://bestkitchengear.com'`).
`ogImage`	`string`		Default social share image (1200×630 recommended).
`twitter`	`string`		Twitter handle without `@` (e.g. `'bestkitchengear'`).
`ogType`	`'website' \| 'article' \| 'product'`	`'website'`	Default Open Graph type. Per-page composables can override.
`locale`	`string`	`'en_US'`	OG locale meta.

4) `xAffiliate.tracking`

Read by <XAFCookieConsent /> and useXAFConsentTracking(). Scripts only fire after the matching consent category is granted.

Key	Type	Default	Description
`gtmId`	`string`		Google Tag Manager container ID (e.g. `'GTM-XXXXXXX'`). Fires the `analytics` category.
`ga4Id`	`string`		Google Analytics 4 measurement ID. Skipped when `gtmId` is set (avoids double-counting).
`clarityId`	`string`		Microsoft Clarity project ID. Skipped when `gtmId` is set.
`scripts`	`TrackingScript[]`	`[]`	Arbitrary scripts (Meta Pixel, Hotjar, Segment, etc.). Each fires when its `category` is granted.
`autoInject`	`boolean`	`true`	When `false`, no scripts are injected (state still tracked).

TrackingScript:

Field	Type	Description
`id`	`string`	Stable ID — used to dedupe re-injection. Required.
`src`	`string`	External script URL.
`inline`	`string`	Inline script body.
`category`	`'necessary' \| 'analytics' \| 'marketing'`	Category gate. Default `'analytics'`.
`attrs`	`Record<string, string>`	Extra attributes applied to the injected `<script>` (e.g. `{ async: '' }`).

See CookieConsent for the full pattern.

5) `xAffiliate` (dashboard family)

Key	Type	Default	Description
`referralParam`	`string`	`'ref'`	URL query parameter for referral codes.
`referralBaseUrl`	`string`	`undefined`	Base URL for generated referral links.
`cookieName`	`string`	`'x_affiliate_ref'`	Cookie name for storing referral codes.
`cookieDays`	`number`	`30`	Referral cookie expiration in days.
`currency`	`string`	`'USD'`	Default ISO 4217 currency code for earnings formatting.
`shareMessage`	`string`	`'Check this out!'`	Default social share message.
`landing.hero.title`	`string`	`'Earn Money With Our Affiliate Program'`	Landing page hero headline.
`landing.hero.description`	`string`	`'Join thousands of affiliates…'`	Landing page hero subtitle.
`landing.hero.ctaLabel`	`string`	`'Apply Now'`	Landing page hero CTA button label.
`landing.hero.highlightText`	`string`	`'Up to 30% commission'`	Highlight badge text.
`landing.hero.variant`	`'gradient' \| 'primary' \| 'dark'`	`'gradient'`	Visual style of the `XAFBanner` hero.
`landing.benefits`	`Array<{ icon, title, description }>`	3 defaults	Benefits cards shown on the landing page.
`signup.title`	`string`	`'Join Our Affiliate Program'`	Signup form title.
`signup.subtitle`	`string`	`'Earn commissions...'`	Signup form subtitle.
`signup.submitLabel`	`string`	`'Apply Now'`	Submit button label.
`signup.showWebsite`	`boolean`	`true`	Show website URL field.
`signup.showCompany`	`boolean`	`false`	Show company name field.
`signup.showMessage`	`boolean`	`true`	Show promotion strategy textarea.

6) `xAffiliateContent` (review-site content family)

Key	Type	Default	Description
`currency`	`string`	`'USD'`	ISO 4217 currency code used by `formatPrice()`.
`locale`	`string`	`'en-US'`	Locale for `Intl.NumberFormat` and date formatting.
`disclosure.text`	`string`	bundled default	FTC disclosure body text.
`disclosure.position`	`'above' \| 'below' \| 'none'`	`'above'`	Default position of `XAFDisclosure` inside `XAFBuyButton`.
`merchants`	`Record<MerchantId, XAffiliateContentMerchant>`	`{ amazon, walmart }`	Per-merchant config. Built-in merchants include `amazon` and `walmart` with sensible defaults for displayName, ctaLabel, color, and tagParam.

Per-merchant schema (`XAffiliateContentMerchant`)

Key	Type	Default (built-in)	Description
`displayName`	`string`	varies	Human-readable merchant name.
`ctaLabel`	`string`	varies	Default CTA button label (e.g. "Buy on Amazon").
`color`	`'primary' \| 'success' \| 'neutral'`	`'primary'`	Button color for `XAFBuyButton`.
`tagValue`	`string`	`undefined`	Affiliate tag value to append. Unset = no tagging. Sites must set their own tag per merchant — untagged outbound links silently break commission attribution.
`tagParam`	`string`	varies	URL parameter name (e.g. `tag` for Amazon, `wmlspartner` for Walmart).
`icon`	`string`		Iconify class for the merchant icon.

Built-in merchants

ID	displayName	ctaLabel	tagParam
`amazon`	`Amazon`	`Buy on Amazon`	`tag`
`walmart`	`Walmart`	`Buy on Walmart`	`wmlspartner`

Runtime Config / Environment Variables

None required. All configuration is through app.config.ts.

AI Context

package: "@xenterprises/nuxt-x-affiliate"
config-keys:
  - xAffiliate           # site-wide: legal + author + brand + tracking + referral
  - xAffiliateContent    # review-site: merchants + currency
config-pattern: |
  Every consuming site sets xAffiliate.legal.baseUrl to the canonical
  x.enterprises/legal home (no per-site legal pages). Per-site identity
  goes under xAffiliate.author + xAffiliate.brand. Per-merchant tag
  values go under xAffiliateContent.merchants.{amazon,walmart,...}.
  Legal.optIn.{health,aiContent,sponsoredContent} flags toggle the
  corresponding XAF*Disclosure components per-site.

Edit this pageorReport an issue

useXAFContentQuery

Source-agnostic paginated content query state manager — plus typed wrappers useXAFReviews / useXAFArticles / useXAFCategories and a debounced useXAFSearch.

Release Notes

Detailed release history for @xenterprises/nuxt-x-affiliate — what shipped in v0.3.5, v0.4.0, v0.4.1, v0.5.0, and v0.6.0, plus the breaking dashboard-folder consolidation landing in the next minor.