AgencyConfig: agency identity and configuration reference

AgencyConfig is the single source of truth for everything that varies between real estate agencies: identity, contact details, social presence, feature modules, locale settings, currency, measurement units, and the active theme. It is defined in app/types/agency.types.ts and consumed exclusively through the useSiteConfig() composable — components must never hardcode agency data. The file app/config/agencies/default.agency.ts ships a complete placeholder configuration that demonstrates every field; copy and rename it to create a new agency identity.

`MeasurementUnit` type

export type MeasurementUnit = 'metric' | 'imperial'

Controls the default unit label displayed for property and development area measurements (m² vs ft²). This is the agency-level default; individual Property and Development records may override it with their own sizeUnit field.

`AgencyConfig` interface

string

required

Unique agency identifier (e.g. 'default', 'acme-realty'). Used internally as a stable key; does not appear in the UI.

name

string

required

Agency display name rendered in the header, footer, and browser title. Zod enforces at least one non-whitespace character.

slogan

string

Optional short marketing tagline shown in hero sections and the footer (e.g. 'Find your ideal property').

logo

string

required

Path to the agency logo served from public/ (e.g. '/images/logo.svg'). Must begin with '/'. Zod enforces the leading slash.

favicon

string

Optional path to the favicon served from public/ (e.g. '/favicon.ico'). Must begin with '/' when present.

theme

string

required

ID of the theme this agency uses (e.g. 'default'). Must match a key in the themes registry (app/themes/index.ts). The cross-config validator throws a ZodError when this ID is not found in the registry.

defaultLocale

string

required

BCP 47 locale code that the site falls back to (e.g. 'en', 'es'). Must appear in both availableLocales and i18nLocales — the cross-config validator throws if either condition is not met.

availableLocales

string[]

required

Array of BCP 47 locale codes the agency supports (e.g. ['en', 'es']). Must be non-empty. Every entry must also be registered in the Nuxt i18n config (i18nLocales).

currency

string

required

ISO 4217 currency code used to format all prices (e.g. 'USD', 'MXN', 'EUR'). Applied by the currency-format.ts utility across property cards, detail pages, and development showcases. A format warning (non-throwing) is emitted when the value does not match the three-uppercase-letter ISO 4217 pattern.

measurementUnit

MeasurementUnit

required

Agency-wide default area unit. 'metric' renders m²; 'imperial' renders ft². Individual Property and Development records override this with their own sizeUnit field. No auto-conversion is performed — numbers are always rendered as-is.

contact

AgencyContactConfig

required

Primary contact details. See AgencyContactConfig below.

Social media profile URLs. See AgencySocialConfig below.

modules

AgencyModulesConfig

required

Feature-flag toggles. See AgencyModulesConfig below.

Nested interfaces

`AgencyContactConfig`

contact

AgencyContactConfig

Show fields

phone

string

required

Main agency phone number in any human-readable format. Rendered as a tel: link in the footer, header, and contact page.

string

required

WhatsApp contact number. May be human-formatted (spaces, dashes, country code prefix). buildWhatsAppLink in app/core/utils/whatsapp-link.ts normalizes it to a https://wa.me/ URL at render time. Always include the country code.

string

required

Primary contact email address. Rendered as a mailto: link. A format warning (non-throwing) is emitted when the value does not match the name@domain.tld pattern.

address

string

required

Physical office address. Displayed in the footer and contact page.

businessHours

string

Optional free-text business hours string (e.g. 'Mon–Fri 9am–6pm'). Displayed on the contact page when present.

`AgencySocialConfig`

Show fields

facebook

string

Full Facebook profile URL. Optional. A format warning is emitted when the value does not start with http://, https://, or www..

instagram

string

Full Instagram profile URL. Optional. Format warning rules apply.

string

Full LinkedIn company or personal profile URL. Optional. Format warning rules apply.

tiktok

string

Full TikTok profile URL. Optional. Format warning rules apply.

youtube

string

Full YouTube channel URL. Optional. Format warning rules apply.

`AgencyModulesConfig`

All six fields are required booleans. Setting a module to false removes its navigation entry (via the module field on NavItem) and disables its routes and components, allowing agencies that do not use a feature to ship without dead pages.

modules

AgencyModulesConfig

Show fields

properties

boolean

required

Enables the properties listing page, detail pages, and all property-related components.

developments

boolean

required

Enables the developments showcase section and its related components.

agents

boolean

required

Enables the agents team section and its related components.

blog

boolean

required

Enables blog functionality. Currently set to false in the default agency — the blog module is planned but not yet implemented.

testimonials

boolean

required

Enables the testimonials section on the homepage.

contact

boolean

required

Enables the contact page and contact form components.

Runtime validation

The file app/config/agencies/agency.schema.ts provides runtime validation for AgencyConfig. Two public functions are exported.

`validateAgencyConfig(agency, deps)`

function validateAgencyConfig(
  agency: AgencyConfig,
  deps: ValidateAgencyConfigDeps,
): ValidateAgencyConfigResult

Strict variant. Throws a ZodError on any structural or cross-config failure. Returns { agency, warnings } on success. The first parameter must be an already-typed AgencyConfig object (use safeParseAgencyConfig when the input is unknown).

import { validateAgencyConfig } from '~/config/agencies/agency.schema'
import { themes } from '~/themes'
import { defaultI18nLocales } from '~/config/i18n'

const { agency, warnings } = validateAgencyConfig(myAgencyConfig, {
  themes,
  i18nLocales: defaultI18nLocales,
})

if (warnings.length > 0) {
  warnings.forEach(w => console.warn('[AgencyConfig]', w))
}

`safeParseAgencyConfig(agency, deps)`

function safeParseAgencyConfig(
  agency: unknown,
  deps: ValidateAgencyConfigDeps,
): SafeParseAgencyConfigResult

Non-throwing variant. The first parameter is typed unknown — use this when the input may not yet conform to AgencyConfig (e.g. a raw JSON payload from a CMS or a multi-tenant config loader). Returns a tagged discriminated union so callers can handle validation errors without a try/catch:

export type SafeParseAgencyConfigResult =
  | { ok: true;  agency: AgencyConfig; warnings: string[] }
  | { ok: false; error: z.ZodError;    warnings: string[] }

Use this variant in multi-tenant loaders or server-side config resolution where you want to fall back to the default agency instead of crashing.

const result = safeParseAgencyConfig(unknownConfig, { themes, i18nLocales })
if (!result.ok) {
  console.error('Invalid agency config:', result.error.issues)
  // fall back to default agency...
}

Cross-config coherence checks

These rules throw a ZodError when violated:

Rule	Description
`defaultLocale ∈ availableLocales`	The default locale must be listed in the agency’s supported locales
`defaultLocale ∈ i18nLocales`	The default locale must be registered in Nuxt’s i18n config
Every `availableLocales[i] ∈ i18nLocales`	Every supported locale must be registered in Nuxt’s i18n config
`theme ∈ themes`	The theme ID must exist as a key in the themes registry

Format warnings

These checks log a console.warn but never throw. A site with format warnings still boots correctly. The shipped default.agency.ts triggers five warnings by design (one per social platform placeholder URL) to document what a real agency should update during rebranding.

Check	Condition
`contact.email`	Does not match `name@domain.tld` pattern
`currency`	Does not match the three-uppercase-letter ISO 4217 pattern
`social.*`	Any set social URL that does not start with `http://`, `https://`, or `www.`

`SiteConfig`

The resolved configuration object consumed across the app via useSiteConfig():

export interface SiteConfig {
  agency: AgencyConfig
  theme: ThemeConfig
}

SiteConfig pairs the active AgencyConfig with its resolved ThemeConfig. The theme.ts plugin resolves the theme at startup using resolveTheme(agency.theme) and injects CSS variables for the active theme via themeToCssVars.

`NavItem`

Powers navigation configuration in app/config/navigation.ts:

export interface NavItem {
  labelKey: string
  to: string
  module?: keyof AgencyModulesConfig
}

labelKey

string

required

i18n translation key for the navigation label. Never raw text — always a key looked up via $t().

string

required

Route path (e.g. '/properties', '/contact').

module

keyof AgencyModulesConfig

Optional module name. When set, layout components (AppHeader, AppMobileMenu, AppFooter) hide this nav entry when the corresponding module is disabled in AgencyConfig.modules.

Components

Data Models

Services & Composables

AgencyConfig: agency identity and configuration reference

`MeasurementUnit` type

`AgencyConfig` interface

Nested interfaces

`AgencyContactConfig`

`AgencySocialConfig`

`AgencyModulesConfig`

Runtime validation

`validateAgencyConfig(agency, deps)`

`safeParseAgencyConfig(agency, deps)`

Cross-config coherence checks

Format warnings

`SiteConfig`

`NavItem`

Build docs developers (and LLMs) love

Components

Data Models

Services & Composables

Documentation Index

​MeasurementUnit type

​AgencyConfig interface

​Nested interfaces

​AgencyContactConfig

​AgencySocialConfig

​AgencyModulesConfig

​Runtime validation

​validateAgencyConfig(agency, deps)

​safeParseAgencyConfig(agency, deps)

​Cross-config coherence checks

​Format warnings

​Related interfaces

​SiteConfig

​NavItem

Build docs developers (and LLMs) love

`MeasurementUnit` type

`AgencyConfig` interface

Nested interfaces

`AgencyContactConfig`

`AgencySocialConfig`

`AgencyModulesConfig`

Runtime validation

`validateAgencyConfig(agency, deps)`

`safeParseAgencyConfig(agency, deps)`

Cross-config coherence checks

Format warnings

Related interfaces

`SiteConfig`

`NavItem`