feat(meta): fall back to site.url for SEO base

When metaBaseUrl is unset, prefer nuxt-site-config site.url
over the request origin so SEO stacks need one source of truth.

Closes #240

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: s00d

docs/api/module-options.md

@@ -91,7 +91,7 @@ Meta tags generated for each localized page.
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `meta` | `boolean` | `true` | Generate SEO meta tags (`hreflang`, `canonical`, `og:url`, `og:locale`) automatically. |
-| `metaBaseUrl` | `string` | `undefined` | Base URL for SEO meta tags (canonical, og:url, hreflang). - `undefined` — dynamically resolved from the current request URL   (`useRequestURL().origin` on server, `window.location.origin` on client).   Best for multi-domain deployments. - A concrete URL string (e.g. `'https://example.com'`) — used as-is. |
+| `metaBaseUrl` | `string` | `undefined` | Base URL for SEO meta tags (canonical, og:url, hreflang). - A concrete URL string (e.g. `'https://example.com'`) — used as-is (highest priority). - `undefined` — falls back to `site.url` from `nuxt-site-config` when that module is   present, otherwise the current request origin   (`useRequestURL().origin` on server, `window.location.origin` on client). |
 | `metaTrustForwardedHost` | `boolean` | `true` | Trust the `X-Forwarded-Host` header when resolving the base URL for meta tags. Enable when the app runs behind a reverse proxy (nginx, Cloudflare, AWS ALB, etc.) that sets this header to the real client-facing hostname. |
 | `metaTrustForwardedProto` | `boolean` | `true` | Trust the `X-Forwarded-Proto` header when resolving the protocol for meta tags. Enable when the app runs behind a TLS-terminating proxy so that canonical URLs use `https://` even though the app itself listens on HTTP. |
 | `canonicalQueryWhitelist` | `string[]` | `['page', 'sort', 'filter', 'search', 'q', 'query', 'tag']` | List of query parameter names preserved in canonical and `og:url` meta tags. Parameters not in this list are stripped from the canonical URL. |

docs/api/packages.md

@@ -30,7 +30,7 @@ or CI failing.
 | [`@i18n-micro/test-utils`](/api/packages/test-utils) | `@i18n-micro/test-utils`, `@i18n-micro/test-utils/publish-smoke` | 36 |
 | [`@i18n-micro/types`](/api/packages/types) | `@i18n-micro/types` | 26 |
 | [`@i18n-micro/types-generator`](/api/packages/types-generator) | `@i18n-micro/types-generator`, `@i18n-micro/types-generator/nuxt` | 7 |
-| [`@i18n-micro/utils`](/api/packages/utils) | `@i18n-micro/utils/accept-language`, `@i18n-micro/utils/active-locales`, `@i18n-micro/utils/app-path`, `@i18n-micro/utils/build`, `@i18n-micro/utils/cache-control`, `@i18n-micro/utils/cookie`, `@i18n-micro/utils/deep-merge`, `@i18n-micro/utils/merge-i18n-head`, `@i18n-micro/utils/merge-source`, `@i18n-micro/utils/normalize`, `@i18n-micro/utils/parse-path`, `@i18n-micro/utils/payload-config`, `@i18n-micro/utils/payload-fetch`, `@i18n-micro/utils/payload-stats`, `@i18n-micro/utils/payload-url`, `@i18n-micro/utils/resolve-hreflang`, `@i18n-micro/utils/resolve-locale`, `@i18n-micro/utils/resolve-og-locale`, `@i18n-micro/utils/route`, `@i18n-micro/utils/route-pattern`, `@i18n-micro/utils/runtime-config`, `@i18n-micro/utils/source-loader` | 97 |
+| [`@i18n-micro/utils`](/api/packages/utils) | `@i18n-micro/utils/accept-language`, `@i18n-micro/utils/active-locales`, `@i18n-micro/utils/app-path`, `@i18n-micro/utils/auto-detect-path`, `@i18n-micro/utils/build`, `@i18n-micro/utils/cache-control`, `@i18n-micro/utils/cookie`, `@i18n-micro/utils/deep-merge`, `@i18n-micro/utils/merge-i18n-head`, `@i18n-micro/utils/merge-source`, `@i18n-micro/utils/normalize`, `@i18n-micro/utils/parse-path`, `@i18n-micro/utils/payload-config`, `@i18n-micro/utils/payload-fetch`, `@i18n-micro/utils/payload-stats`, `@i18n-micro/utils/payload-url`, `@i18n-micro/utils/resolve-hreflang`, `@i18n-micro/utils/resolve-locale`, `@i18n-micro/utils/resolve-og-locale`, `@i18n-micro/utils/route`, `@i18n-micro/utils/route-pattern`, `@i18n-micro/utils/runtime-config`, `@i18n-micro/utils/source-loader` | 98 |
 | [`@i18n-micro/vue`](/api/packages/vue) | `@i18n-micro/vue` | 27 |
 
 <!-- /generated:packages-index -->

docs/api/packages/utils.md

@@ -6,7 +6,7 @@ outline: 'deep'
 
 # `@i18n-micro/utils`
 
-97 exports across 22 entry points.
+98 exports across 23 entry points.
 Generated from the API snapshot that [`pnpm run api:surface`](/guide/maintenance-commands#api-surface)
 checks against the TypeScript sources.
 
@@ -44,6 +44,16 @@ import { /* … */ } from '@i18n-micro/utils/app-path'
 | --- | --- | --- |
 | `withoutAppBaseURL` | function | `(pathname: string, baseURL?: string \| null) => string` |
 
+## `@i18n-micro/utils/auto-detect-path`
+
+```ts
+import { /* … */ } from '@i18n-micro/utils/auto-detect-path'
+```
+
+| Export | Kind | Signature |
+| --- | --- | --- |
+| `shouldAttemptLocaleRedirect` | function | `(path: string, options?: { autoDetectPath?: string; hasLocalePrefix?: boolean; }) => boolean` |
+
 ## `@i18n-micro/utils/build`
 
 ```ts

docs/guide/configuration.md

@@ -21,7 +21,7 @@ The sections below explain how they work together; the
 | [`locales`](/api/module-options) | `Locale[]` | `[]` | List of supported locales. |
 | [`meta`](/api/module-options) | `boolean` | `true` | Generate SEO meta tags (`hreflang`, `canonical`, `og:url`, `og:locale`) automatically. |
 | [`strategy`](/api/module-options) | `Strategies` | `'prefix_except_default'` | URL routing strategy for locale prefixes. - `'no_prefix'` — no locale in URL; locale stored in cookie. - `'prefix_except_default'` — prefix all locales except the default. - `'prefix'` — always prefix, including the default locale. - `'prefix_and_default'` — like `prefix`, but the default locale is also accessible without prefix. |
-| [`metaBaseUrl`](/api/module-options) | `string` | `undefined` | Base URL for SEO meta tags (canonical, og:url, hreflang). - `undefined` — dynamically resolved from the current request URL   (`useRequestURL().origin` on server, `window.location.origin` on client). |
+| [`metaBaseUrl`](/api/module-options) | `string` | `undefined` | Base URL for SEO meta tags (canonical, og:url, hreflang). - A concrete URL string (e.g. `'https://example.com'`) — used as-is (highest priority). - `undefined` — falls back to `site.url` from `nuxt-site-config` when that module is   present, otherwise the current request origin   (`useRequestURL().origin` on server, `window.location.origin` on client). |
 | [`metaTrustForwardedHost`](/api/module-options) | `boolean` | `true` | Trust the `X-Forwarded-Host` header when resolving the base URL for meta tags. |
 | [`metaTrustForwardedProto`](/api/module-options) | `boolean` | `true` | Trust the `X-Forwarded-Proto` header when resolving the protocol for meta tags. |
 | [`hreflangBaseLanguage`](/api/module-options) | `boolean` | `false` | Also emit a bare-language `hreflang` derived from each locale's `iso` (e.g. `es-ES` → also `es`). |
@@ -366,22 +366,25 @@ meta: true // Generate alternate links, canonical URLs, etc.
 
 Base URL for SEO meta tags (canonical, og:url, hreflang).
 
-- `undefined` — dynamically resolved from the current request URL
+- A concrete URL string (e.g. `'https://example.com'`) — used as-is (highest priority).
+- `undefined` — falls back to `site.url` from `nuxt-site-config` when that module is
+  present, otherwise the current request origin
   (`useRequestURL().origin` on server, `window.location.origin` on client).
-  Best for multi-domain deployments.
-
-- A concrete URL string (e.g. `'https://example.com'`) — used as-is.
 
 <!-- /generated:option:metaBaseUrl -->
 
-- `undefined` (or omitted) — the base URL is resolved dynamically from the incoming request on the server (`useRequestURL().origin`, respects `X-Forwarded-Host` / `X-Forwarded-Proto` proxy headers) and from `window.location.origin` on the client. Ideal for **multi-domain** deployments where the same application serves multiple hostnames.
-- Any other string — used as a static base URL.
+Priority when unset: `site.url` from `nuxt-site-config` (if installed) → request origin
+(`useRequestURL().origin` on the server with `X-Forwarded-Host` / `X-Forwarded-Proto`,
+`window.location.origin` on the client). Ideal for **SEO stacks** that already set `site.url`,
+and for **multi-domain** deployments when `site.url` is omitted.
+
+- Any other string — used as a static base URL (wins over `site.url`).
 
 ```typescript
-// Dynamic — automatically uses the current request hostname (recommended for multi-domain)
-// Simply omit metaBaseUrl or set it to undefined
+// Prefer sharing the SEO stack origin — omit metaBaseUrl when site.url is set
+site: { url: 'https://example.com' }
 
-// Static — always uses the specified URL
+// Or pin an explicit override
 metaBaseUrl: 'https://example.com'
 ```
 #### `canonicalQueryWhitelist`

docs/guide/seo.md

@@ -100,11 +100,28 @@ export default defineNuxtConfig({
 
 ### 🌍 Dynamic `metaBaseUrl` for Multi-Domain Deployments
 
-By default (`metaBaseUrl` is `undefined`), canonical URLs, `og:url`, and `hreflang` links are generated using the hostname from the current request. This is resolved via `useRequestURL()` on the server and `window.location.origin` on the client.
+When `metaBaseUrl` is unset, absolute SEO URLs resolve in this order (#240):
 
-The module respects reverse-proxy headers (`X-Forwarded-Host`, `X-Forwarded-Proto`), so it works correctly behind nginx, Cloudflare, AWS ALB, and similar proxies.
+1. `site.url` from [`nuxt-site-config`](https://nuxtseo.com/docs/site-config) (if that module is present — e.g. via `@nuxtjs/seo`)
+2. Otherwise the hostname from the current request (`useRequestURL()` / `window.location.origin`)
 
-This means a single application instance can serve **multiple domains** with correct SEO tags for each:
+The request-origin fallback respects reverse-proxy headers (`X-Forwarded-Host`, `X-Forwarded-Proto`), so it works correctly behind nginx, Cloudflare, AWS ALB, and similar proxies.
+
+That means apps already setting `site.url` for sitemap / robots / schema.org do **not** need a second `metaBaseUrl` declaration:
+
+```typescript
+export default defineNuxtConfig({
+  site: {
+    url: process.env.NUXT_SITE_URL, // also used by micro for canonical / og:url / hreflang
+  },
+  i18n: {
+    meta: true,
+    // metaBaseUrl omitted — picks up site.url, then request origin
+  },
+})
+```
+
+Without `site.url`, a single application instance can still serve **multiple domains** with correct SEO tags for each via the request origin:
 
 ```typescript
 export default defineNuxtConfig({
@@ -127,7 +144,7 @@ While the same app serving `https://site-b.com/en/about` will produce:
 <link rel="canonical" href="https://site-b.com/en/about" /> <meta property="og:url" content="https://site-b.com/en/about" />
 ```
 
-If you need a fixed base URL instead, pass a static string:
+If you need a fixed base URL that always wins over `site.url`, pass a static string:
 
 ```typescript
 metaBaseUrl: 'https://example.com'

packages/types/src/index.ts

@@ -179,10 +179,10 @@ export interface ModuleOptions {
 
   /**
    * Base URL for SEO meta tags (canonical, og:url, hreflang).
-   * - `undefined` — dynamically resolved from the current request URL
+   * - A concrete URL string (e.g. `'https://example.com'`) — used as-is (highest priority).
+   * - `undefined` — falls back to `site.url` from `nuxt-site-config` when that module is
+   *   present, otherwise the current request origin
    *   (`useRequestURL().origin` on server, `window.location.origin` on client).
-   *   Best for multi-domain deployments.
-   * - A concrete URL string (e.g. `'https://example.com'`) — used as-is.
    * @default undefined
    */
   metaBaseUrl?: string

src/runtime/plugins/02.meta.ts

@@ -9,6 +9,18 @@ import { useI18nHead } from '../composables/useI18nHead'
 import { useLocaleHead } from '../composables/useLocaleHead'
 import type { PluginsInjections } from './01.plugin'
 
+function readSiteConfigUrl(nuxtApp: { $nuxtSiteConfig?: { get?: (opts?: object) => { url?: unknown } } }): string | undefined {
+  // Soft probe: only present when nuxt-site-config (via @nuxtjs/seo etc.) is installed.
+  const stack = nuxtApp.$nuxtSiteConfig
+  if (!stack || typeof stack.get !== 'function') return undefined
+  try {
+    const url = stack.get({ resolveRefs: true })?.url
+    return typeof url === 'string' && url.trim() ? url : undefined
+  } catch {
+    return undefined
+  }
+}
+
 export default defineNuxtPlugin((nuxtApp) => {
   const route = useRoute()
   const i18nRouteParams = useState<I18nRouteParams>('i18n-route-params', () => ({}))
@@ -25,16 +37,17 @@ export default defineNuxtPlugin((nuxtApp) => {
     return
   }
 
-  // Resolve base URL for SEO meta tags.
-  // undefined → dynamically resolve from the current request (supports multi-domain).
+  // Resolve base URL for SEO meta tags (#240):
+  //   metaBaseUrl (explicit) → site.url (nuxt-site-config) → request origin
   // Proxy-header options so the origin is correct behind nginx / Cloudflare / ALB / etc.:
   //   X-Forwarded-Host  → real hostname  (controlled by metaTrustForwardedHost)
   //   X-Forwarded-Proto → real protocol  (controlled by metaTrustForwardedProto)
   const url = useRequestURL({
     xForwardedHost: i18nConfig.metaTrustForwardedHost !== false,
     xForwardedProto: i18nConfig.metaTrustForwardedProto !== false,
   })
-  const baseUrl = i18nConfig.metaBaseUrl || url.origin
+  const siteUrl = readSiteConfigUrl(nuxtApp as { $nuxtSiteConfig?: { get?: (opts?: object) => { url?: unknown } } })
+  const baseUrl = (i18nConfig.metaBaseUrl || siteUrl || url.origin).replace(/\/+$/, '')
 
   const { metaObject, updateMeta } = useLocaleHead({
     addDirAttribute: true,

test/nuxt-seo.spec.ts

@@ -103,6 +103,17 @@ describe('@nuxtjs/seo integration (#133)', () => {
     expect(deHtml).toMatch(/<meta[^>]*name="description"[^>]*content="Deutsche Seitenbeschreibung"/)
   })
 
+  test('SSR: canonical and og:url use site.url when metaBaseUrl is unset (#240)', async ({ request }) => {
+    const html = await (await request.get('/en/about')).text()
+
+    expect(html).toMatch(/<link[^>]*rel="canonical"[^>]*href="https:\/\/example\.com\/en\/about"/)
+    expect(html).toMatch(/<meta[^>]*property="og:url"[^>]*content="https:\/\/example\.com\/en\/about"/)
+
+    const alternates = extractHreflangLinks(html)
+    expect(alternates.some((link) => link.hreflang === 'en-US' && link.href.startsWith('https://example.com/'))).toBe(true)
+    expect(alternates.some((link) => link.hreflang === 'de-DE' && link.href.startsWith('https://example.com/'))).toBe(true)
+  })
+
   test('SSR: canonical and og:url tags are present on localized pages', async ({ request }) => {
     const html = await (await request.get('/en/about')).text()