@frigear-nu/base 0.0.6 → 0.1.1

package/README.md

@@ -75,6 +75,20 @@ localized/non-localized setup, see the [Base Layer docs](../../apps/docs/content
 
 Page front matter also accepts `container: true`, which wraps the rendered body in a `UContainer` (use it for plain prose pages such as legal; pages built from `u-page-*` sections manage their own containers). It also accepts `seo: { title, description, image, noindex }`, and `config.yaml` accepts `seo: { titleTemplate, description, image }`; the layer ships no SEO defaults, see the docs.
 
+## Languages and hreflang
+
+With more than one i18n locale, every page gets `<link rel="alternate" hreflang>` tags for each locale plus
+`x-default`, and `og:locale:alternate` for the other locales (`useLocaleAlternates()`, called from `app.vue`).
+
+- The alternates come from the app's `i18n.locales`, through `@nuxtjs/i18n`'s `useLocaleHead()`. The canonical,
+  `og:url`, `og:locale` and `<html lang>` stay with `nuxt-seo-utils`.
+- Each locale's `language` (BCP 47) decides its hreflang; a locale without one gets no alternate. Include a region
+  (`da-DK`, `en-GB`) for `og:locale:alternate`, which leaves out bare languages such as `en`.
+- Hrefs are absolute like the canonical: from `site.url` when set, otherwise from the request origin. Prerendered
+  routes need `site.url` at build time; without it their alternate links are skipped with a warning.
+- Opt out with `seo: { localeAlternates: false }` in `app.config.ts`, for apps that write their own hreflang tags or
+  enable i18n's `experimental.strictSeo`.
+
 ## Notes
 
 - This package is a shared workspace dependency and is linked via `workspace:*` from apps.

package/app/app.config.ts

@@ -5,7 +5,13 @@ export default defineAppConfig({
       neutral: 'slate',
     },
   },
+  seo: {
+    // Emits hreflang and og:locale:alternate tags on multi-locale sites. Turn off when the app writes its own.
+    localeAlternates: true,
+  },
   header: {
+    // Shows the colour-mode toggle in the header. Apps whose account menu offers Appearance can turn it off.
+    colorMode: true,
     icon: {
       desktop: false,
       mobile: true,

package/app/app.d.ts

@@ -1,11 +1,17 @@
 declare module 'nuxt/schema' {
   interface AppConfigInput {
     header?: {
+      /** Show the colour-mode toggle in the header (default `true`). */
+      colorMode?: boolean
       icon?: {
         desktop?: boolean
         mobile?: boolean
       }
     }
+    seo?: {
+      /** Emit hreflang alternates and `og:locale:alternate` on multi-locale sites (default `true`). */
+      localeAlternates?: boolean
+    }
     socials?: Record<string, string>
     github?: {
       url?: string
@@ -14,11 +20,17 @@ declare module 'nuxt/schema' {
 
   interface AppConfig {
     header?: {
+      /** Show the colour-mode toggle in the header (default `true`). */
+      colorMode?: boolean
       icon?: {
         desktop?: boolean
         mobile?: boolean
       }
     }
+    seo?: {
+      /** Emit hreflang alternates and `og:locale:alternate` on multi-locale sites (default `true`). */
+      localeAlternates?: boolean
+    }
     socials?: Record<string, string>
     github?: {
       url?: string

package/app/app.vue

@@ -9,6 +9,7 @@ useHead({
 })
 
 usePageSeo()
+useLocaleAlternates()
 </script>
 
 <template>

package/app/components/App/AppHeader.vue

@@ -2,6 +2,9 @@
 const { data: config } = await useConfig()
 const { data: navigation } = useMenu('main')
 const multiLocale = useRuntimeConfig().public.multiLocale === true
+// Off when the account menu offers Appearance instead (the footer toggle stays for signed-out visitors).
+const appConfig = useAppConfig()
+const colorModeButton = computed(() => appConfig.header?.colorMode !== false)
 </script>
 
 <template>
@@ -18,7 +21,7 @@ const multiLocale = useRuntimeConfig().public.multiLocale === true
     <template #right>
       <AppHeaderCTA />
       <LanguageSelect v-if="multiLocale" />
-      <UColorModeButton />
+      <UColorModeButton v-if="colorModeButton" />
       <AppHeaderRight />
     </template>
 

package/app/components/App/AppHeaderBody.vue

@@ -2,17 +2,24 @@
 import type { ContentNavigationItem } from '@nuxt/content'
 
 const { data: config } = await useConfig()
+// The same entries as the desktop header (`main` menu, including items modules add); the content config's
+// `navigation` when the menu has none.
+const { data: menu } = await useMenu('main')
+const appConfig = useAppConfig()
 
 const items = computed(() => {
-  const iconOnMobile = useAppConfig().header?.icon?.mobile
+  // The content config's `navigation` is only a list when the host sets one.
+  const fallback = Array.isArray(config.value?.navigation) ? config.value.navigation : []
+  const source = menu.value?.length ? menu.value : fallback
+  const iconOnMobile = appConfig.header?.icon?.mobile
 
   if (typeof iconOnMobile === 'boolean' && !iconOnMobile) {
-    return config.value?.navigation?.map(item => ({
+    return source.map(item => ({
       ...item,
       icon: undefined,
     }))
   } else {
-    return config.value?.navigation
+    return source
   }
 })
 
@@ -21,15 +28,15 @@ const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
 
 <template>
   <div class="mt-4">
-    <UPageGrid v-if="config?.navigation">
+    <UPageGrid v-if="items?.length">
       <UPageCard
-        v-for="item in items "
+        v-for="item in items"
         :key="item.label"
         :title="item.label"
         :icon="item.icon"
         :description="item.description"
         :to="item.to"
-        class="hober:shadow-lg"
+        class="hover:shadow-lg"
         variant="subtle"
         :ui="{ title: 'text-xl font-semibold' }"
       />

package/app/composables/useLocaleAlternates.ts

@@ -0,0 +1,74 @@
+import { hasProtocol, parseURL, stringifyParsedURL } from 'ufo'
+
+let warnedMissingSiteUrl = false
+
+/**
+ * Adds the i18n language alternates to the head of every page: a
+ * `<link rel="alternate" hreflang>` per locale plus `x-default`, and
+ * `og:locale:alternate` for the other locales.
+ *
+ * Only those tags are taken from `useLocaleHead()`. Its canonical, `og:url`
+ * and `lang` would duplicate the ones nuxt-seo-utils already sets, so they
+ * are dropped. Hrefs are made absolute with the same site resolver
+ * nuxt-seo-utils uses for the canonical, so both share `site.url`.
+ *
+ * Emits nothing on single-locale sites or when the app config sets
+ * `seo.localeAlternates: false`. Without a `site.url` the resolver falls
+ * back to the request origin; a prerender has neither, and relative hrefs are
+ * ignored by search engines, so the links are skipped instead.
+ */
+export const useLocaleAlternates = () => {
+  const appConfig = useAppConfig()
+  const { locales } = useI18n()
+  const error = useError()
+  const localeHead = useLocaleHead({ dir: false, lang: false, seo: true })
+  const resolveUrl = createSitePathResolver({ absolute: true, withBase: true })
+
+  const enabled = computed(() =>
+    appConfig.seo?.localeAlternates !== false && locales.value.length > 1 && !error.value,
+  )
+
+  // i18n prefixes hrefs with its own `baseUrl` when one is set; keep only the
+  // path so the site resolver decides the origin.
+  const toAbsolute = (href: string) => {
+    const { pathname, search, hash } = parseURL(href)
+    return resolveUrl(stringifyParsedURL({ pathname, search, hash })).value
+  }
+
+  useHead({
+    link: () => {
+      if (!enabled.value) return []
+      const links = (localeHead.value.link ?? [])
+        .flatMap(link => (link.rel === 'alternate' && 'hreflang' in link && link.hreflang && link.href)
+          ? [{
+              key: `locale-alternate-${link.hreflang}`,
+              rel: 'alternate' as const,
+              hreflang: link.hreflang,
+              href: toAbsolute(link.href),
+            }]
+          : [])
+      if (links.some(link => !hasProtocol(link.href))) {
+        if ((import.meta.dev || import.meta.prerender) && !warnedMissingSiteUrl) {
+          warnedMissingSiteUrl = true
+          console.warn('[@frigear-nu/base] hreflang alternates need an absolute `site.url`; set it (at build time for prerendered routes). Skipping them.')
+        }
+        return []
+      }
+      return links
+    },
+    meta: () => {
+      if (!enabled.value) return []
+      // Same rule as nuxt-seo-utils' `og:locale`: `ll_TT` only, values
+      // without a territory are not valid Open Graph locales.
+      return (localeHead.value.meta ?? [])
+        .filter(meta => meta.property === 'og:locale:alternate' && meta.content)
+        .map(meta => String(meta.content).replace(/-/g, '_'))
+        .filter(content => content.includes('_'))
+        .map(content => ({
+          key: `og-locale-alternate-${content}`,
+          property: 'og:locale:alternate',
+          content,
+        }))
+    },
+  })
+}

package/modules/config.ts

@@ -6,5 +6,15 @@ export default defineNuxtModule({
   meta: {
     name: 'config',
   },
-  setup() {},
+  setup(_options, nuxt) {
+    // `useLocaleAlternates()` reads `useLocaleHead()`, which warns on every render without an i18n `baseUrl`.
+    // Default it to `site.url`; `@nuxtjs/i18n` merges its own options under this value.
+    const options = nuxt.options as typeof nuxt.options & { site?: { url?: string }, i18n?: { baseUrl?: unknown } }
+    const siteUrl = options.site?.url
+    const publicConfig = nuxt.options.runtimeConfig.public as Record<string, unknown>
+    const i18n = (publicConfig.i18n ||= {}) as { baseUrl?: unknown }
+    if (siteUrl && !options.i18n?.baseUrl && !i18n.baseUrl) {
+      i18n.baseUrl = siteUrl
+    }
+  },
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frigear-nu/base",
-  "version": "0.0.6",
+  "version": "0.1.1",
   "description": "Shared Nuxt layer for Frigear websites - bundled modules, UI defaults, content collections, layouts and routing.",
   "homepage": "https://docs.frigear.dev/layers/base",
   "repository": {
@@ -24,17 +24,17 @@
   ],
   "dependencies": {
     "@comark/nuxt": "0.6.2",
-    "@frigear-nu/menu": "0.0.11",
+    "@frigear-nu/menu": "0.1.1",
     "@iconify-json/lucide": "^1.2.127",
     "@iconify-json/simple-icons": "^1.2.94",
-    "@nuxt/content": "3.16.0",
+    "@nuxt/content": "^3.16.1",
     "@nuxt/fonts": "^1.0.0",
     "@nuxt/hints": "^1.1.4",
     "@nuxt/icon": "^2.5.1",
     "@nuxt/image": "^2.1.0",
-    "@nuxt/kit": "^4.6.0",
-    "@nuxt/schema": "^4.6.0",
-    "@nuxt/ui": "^4.11.0",
+    "@nuxt/kit": "^4.6.1",
+    "@nuxt/schema": "^4.6.1",
+    "@nuxt/ui": "^4.11.2",
     "@nuxtjs/device": "4.0.0",
     "@nuxtjs/i18n": "^10.6.0",
     "@nuxtjs/robots": "^7.0.2",
@@ -50,11 +50,11 @@
     "zod": "^4.5.4"
   },
   "peerDependencies": {
-    "nuxt": "^4.6.0"
+    "nuxt": "^4.6.1"
   },
   "devDependencies": {
     "@nuxt/eslint": "^1.17.0",
-    "eslint": "^10.9.1",
+    "eslint": "^10.12.0",
     "nuxt": "^4.6.1",
     "typescript": "^6.0.3",
     "vue-tsc": "^3.3.11"