fix(seo): warn when a domain setup has no locale to annotate as x-default

[BobbieGoede]

• Follow-up to fix(seo): emit the same x-default on every domain #4089

x-default annotates a whole cluster of pages, and we deliberately cross-link the domains as one cluster, so #4089 started resolving it from the configured defaultLocale instead of whichever locale the current domain defaults to — otherwise every domain declared a different fallback for the same cluster.

defaultLocale is optional under multiDomainLocales though, since each domain resolves its own unprefixed locale through defaultForDomains, and the guide's example left it out. Those sites quietly stopped annotating a fallback at all. Leaving it out is still allowed, x-default is optional and a cluster has no other way to name a fallback, but it isn't silent any more and the guide covers it. The warning is logged where the alternate links are generated rather than at build time, since a project that doesn't use the SEO features has nothing to annotate.

The head test helper was passing routingOptions.defaultLocale straight in rather than resolving it the way createComposableContext does, which is what let the original bug through — it asserted the correct x-default while the code emitted one per domain. It now derives it, and that alone makes the old wiring fail three of the domain tests.

Summary by CodeRabbit

• Documentation

  • Added guidance for configuring a cluster-wide defaultLocale in multi-domain locale setups.
  • Clarified how defaultLocale controls x-default annotations and what happens when it is omitted.

• Bug Fixes

  • Improved handling of missing fallback configuration for domain-based alternate links.
  • Added a development warning when defaultLocale is required but not configured.
  • Ensured x-default links are omitted when no valid cluster fallback exists.

• Tests

  • Expanded coverage for cross-domain fallback behavior and missing configuration scenarios.

[coderabbitai]

Walkthrough

Adds optional cluster-wide defaultLocale handling for domain-based alternate links. Runtime head creation detects missing fallbacks and emits a development warning once. Tests cover configured and missing fallbacks, shared x-default URLs, and omitted annotations. Documentation explains the configuration and resulting x-default behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the core change: warning when a multi-domain setup lacks a default locale for x-default annotation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/x-default-cluster

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

test/routing-head.test.ts (1)

170-181: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Cover the warning side effect, not just the predicate.

This test only calls missesClusterFallback directly. Add a test that generates the head twice with a missing fallback, spies on console.warn, and asserts the development warning is emitted exactly once; this validates the warnedClusterFallback guard in src/runtime/routing/head.ts:40-43.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/routing-head.test.ts` around lines 170 - 181, The existing test only
validates the missesClusterFallback predicate; add coverage for the
head-generation warning side effect. Generate the head twice using a context
with a missing cluster fallback, spy on console.warn, and assert the development
warning is emitted exactly once, exercising the warnedClusterFallback guard in
the head-generation flow.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/content/docs/02.guide/10.multi-domain-locales.md`:
- Around line 218-223: The defaultLocale documentation should qualify that the
missing-value warning is emitted only in development and when SEO alternate
links are generated for a multi-domain setup. Update the warning sentence in the
“defaultLocale and x-default” section while preserving the existing explanation
of optional configuration and x-default behavior.

---

Nitpick comments:
In `@test/routing-head.test.ts`:
- Around line 170-181: The existing test only validates the
missesClusterFallback predicate; add coverage for the head-generation warning
side effect. Generate the head twice using a context with a missing cluster
fallback, spy on console.warn, and assert the development warning is emitted
exactly once, exercising the warnedClusterFallback guard in the head-generation
flow.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: df6062dd-026a-4d41-9c97-840910ce7eb5

📥 Commits

Reviewing files that changed from the base of the PR and between f0e5a46 and e8c78ff.

📒 Files selected for processing (3)

• docs/content/docs/02.guide/10.multi-domain-locales.md
• src/runtime/routing/head.ts
• test/routing-head.test.ts

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Qualify when the warning is emitted.

The runtime only logs this warning in development and when SEO alternate links are being generated for a multi-domain setup. Please document those conditions to avoid implying that production always logs a warning whenever defaultLocale is omitted.

Proposed wording

- A warning is logged when it isn't set.
+ In development, a warning is logged when alternate links are generated without `defaultLocale`.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	## `defaultLocale` and `x-default`
	The domains are annotated as one cluster, each page links to its alternates on the other domains. A cluster has a single fallback for unmatched languages, so the `x-default` alternate is taken from `defaultLocale` rather than from the locale a domain happens to default to - otherwise every domain would name a different one.
	`defaultLocale` is optional here, since each domain resolves its own unprefixed locale through `defaultForDomains`. Leaving it out means no `x-default` is annotated at all, which is allowed but drops a signal for visitors whose language matches none of your locales. A warning is logged when it isn't set.
	## `defaultLocale` and `x-default`
	The domains are annotated as one cluster, each page links to its alternates on the other domains. A cluster has a single fallback for unmatched languages, so the `x-default` alternate is taken from `defaultLocale` rather than from the locale a domain happens to default to - otherwise every domain would name a different one.
	`defaultLocale` is optional here, since each domain resolves its own unprefixed locale through `defaultForDomains`. Leaving it out means no `x-default` is annotated at all, which is allowed but drops a signal for visitors whose language matches none of your locales. In development, a warning is logged when alternate links are generated without `defaultLocale`.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/content/docs/02.guide/10.multi-domain-locales.md` around lines 218 -
223, The defaultLocale documentation should qualify that the missing-value
warning is emitted only in development and when SEO alternate links are
generated for a multi-domain setup. Update the warning sentence in the
“defaultLocale and x-default” section while preserving the existing explanation
of optional configuration and x-default behavior.