@frigear-nu/base 0.1.0 → 0.1.2

package/README.md

@@ -75,11 +75,26 @@ 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.
 - Keep changes here compatible with both consuming apps.
 - If you change module config or public runtime behavior, validate both app consumers in the same change.
+- Client-side navigation: the content page and landing template render `UPageHeader`, `UPageBody` and `ContentRenderer` directly, not their `Lazy*` variants. Every page needs them, and a lazy wrapper costs one more round trip on each navigation. `app.vue` shows `NuxtLoadingIndicator`. `@nuxt/ui` must be ≥ 4.12: older `ULink` renders `NuxtLink` in `custom` mode without its prefetch listeners, so links never prefetch on hover or focus.
 
 ## Publishing
 

package/app/app.config.ts

@@ -5,6 +5,10 @@ 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,

package/app/app.d.ts

@@ -8,6 +8,10 @@ declare module 'nuxt/schema' {
         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
@@ -23,6 +27,10 @@ declare module 'nuxt/schema' {
         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,10 +9,13 @@ useHead({
 })
 
 usePageSeo()
+useLocaleAlternates()
 </script>
 
 <template>
   <UApp>
+    <!-- Feedback while a client-side navigation loads; the default throttle hides it on fast ones. -->
+    <NuxtLoadingIndicator color="var(--ui-primary)" />
     <NuxtLayout>
       <NuxtPage />
     </NuxtLayout>

package/app/composables/useCurrentPage.ts

@@ -1,3 +1,12 @@
+/**
+ * Whether the current route can be a content page. Routes a module registers through `addModulePages` carry
+ * `meta.moduleName` and are never served from `@nuxt/content` (account, admin, auth, ...); any other page can opt out
+ * with `definePageMeta({ content: false })`. Skipping them avoids a content query (and, in the browser, loading the
+ * WASM SQLite dump behind it) on every navigation inside those areas.
+ */
+export const routeServedByContent = (meta: Record<string, unknown>) =>
+  meta.content !== false && !meta.moduleName
+
 export const useCurrentPage = () => {
   const route = useRoute()
   const { locale, stripLocalePrefix } = useContentLocale()
@@ -8,10 +17,16 @@ export const useCurrentPage = () => {
     () => `current-page:${collection.value}:${path.value}`,
     // Locale-suffixed collections (e.g. `pages_no`) share the same schema as
     // `pages`, so the cast keeps the return type stable across locales.
-    () => queryCollection(collection.value as 'pages').path(path.value).first(),
+    () => routeServedByContent(route.meta)
+      ? queryCollection(collection.value as 'pages').path(path.value).first()
+      : Promise.resolve(null),
     {
       watch: [path, locale, collection],
       dedupe: 'cancel',
+      // Content is static, so a path that was already loaded (revisit) reuses its payload entry instead of querying
+      // again. Only an explicit refresh asks the content database.
+      getCachedData: (key, nuxtApp, ctx) =>
+        ctx.cause === 'refresh:manual' ? undefined : (nuxtApp.payload.data[key] ?? nuxtApp.static.data[key]),
     },
   )
 }

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/app/composables/useNavigation.ts

@@ -1,13 +1,14 @@
 export const useNavigation = (tags?: string[]) => {
+  // Resolved in setup: calling a composable inside the handler, after an await, loses the Nuxt context.
+  const config = useConfig()
+
   return useAsyncData(
     () => `navigation:${tags?.join(',') || 'all'}`,
     async () => {
-      const { data: config } = await useConfig() // or however you access the pending promise
-      if (!tags) {
-        return config.value?.navigation || []
-      }
-      return (config.value?.navigation || [])
-        .filter(item => !tags || tags.some(tag => item?.tags?.includes(tag)))
+      const { data } = await config
+      const navigation = data.value?.navigation || []
+      if (!tags) return navigation
+      return navigation.filter(item => tags.some(tag => item?.tags?.includes(tag)))
     },
   )
 }

package/app/pages/[[lang]]/[...path].vue

@@ -11,18 +11,18 @@ if (!data.value) {
 <template>
   <UPage>
     <UContainer v-if="data && data.pageHeader">
-      <LazyUPageHeader
+      <UPageHeader
         v-bind="data.pageHeader"
         :ui="{ root: 'text-center', wrapper: 'lg:flex-col lg:items-center lg:justify-center' }"
       />
     </UContainer>
-    <LazyUPageBody>
+    <UPageBody>
       <component
         :is="data?.container ? UContainer : 'div'"
         v-if="data"
       >
-        <LazyContentRenderer :value="data" />
+        <ContentRenderer :value="data" />
       </component>
-    </LazyUPageBody>
+    </UPageBody>
   </UPage>
 </template>

package/app/templates/LandingPage.vue

@@ -6,7 +6,7 @@ if (!data.value) {
 </script>
 
 <template>
-  <LazyContentRenderer
+  <ContentRenderer
     v-if="data"
     :value="data"
   />

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.1.0",
+  "version": "0.1.2",
   "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,7 +24,7 @@
   ],
   "dependencies": {
     "@comark/nuxt": "0.6.2",
-    "@frigear-nu/menu": "0.1.0",
+    "@frigear-nu/menu": "0.1.2",
     "@iconify-json/lucide": "^1.2.127",
     "@iconify-json/simple-icons": "^1.2.94",
     "@nuxt/content": "^3.16.1",
@@ -34,7 +34,7 @@
     "@nuxt/image": "^2.1.0",
     "@nuxt/kit": "^4.6.1",
     "@nuxt/schema": "^4.6.1",
-    "@nuxt/ui": "^4.11.2",
+    "@nuxt/ui": "^4.12.0",
     "@nuxtjs/device": "4.0.0",
     "@nuxtjs/i18n": "^10.6.0",
     "@nuxtjs/robots": "^7.0.2",