Skip to content

Commit 569bec9

Browse files
committed
Improve doc examples and tests clarity for deferred fallbacks
1 parent 0a10767 commit 569bec9

3 files changed

Lines changed: 40 additions & 38 deletions

File tree

‎docs/router/guide/document-head-management.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -248,15 +248,17 @@ export const Route = createFileRoute('/product/$slug')({
248248
meta: [
249249
// title and name/property meta dedupe automatically — no key needed
250250
{ title: 'Loading...' },
251+
{ name: 'theme-color', content: '#00b8db' },
251252
loaderData.dataPromise.then((data) => [
252253
{ title: data.title },
254+
{ name: 'theme-color', content: data.brandColor },
253255
]),
254256
],
255257
links: [
256-
// Use key so the fallback canonical is replaced by the resolved one
257-
{ rel: 'canonical', href: '/fallback-url', key: 'canonical' },
258+
// Use key so the fallback favicon is replaced by the resolved one
259+
{ rel: 'icon', href: '/favicon.ico', key: 'icon' },
258260
loaderData.dataPromise.then((data) => [
259-
{ rel: 'canonical', href: data.canonicalUrl, key: 'canonical' },
261+
{ rel: 'icon', href: data.iconUrl, key: 'icon' },
260262
]),
261263
],
262264
}),
@@ -266,7 +268,7 @@ export const Route = createFileRoute('/product/$slug')({
266268

267269
In this example:
268270

269-
1. **Before the promise resolves**, the page renders with the fallback `title` and the fallback canonical link
271+
1. **Before the promise resolves**, the page renders with the fallback `title`, the fallback `theme-color`, and the fallback favicon link
270272
2. **After the promise resolves**, `head()` is re-evaluated. The deferred entries now resolve immediately and appear after the fallback entries in the array. Since they share the same `key` (or `name`/`property`/`title`), deduplication keeps only the last occurrence — the resolved one
271273

272274
## Managing Body Scripts

‎packages/router-core/tests/deferred-head-loading.test.ts‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -778,7 +778,7 @@ describe('rejected deferred head promises', () => {
778778

779779
describe('deferred fallbacks: key-based replacement at render time', () => {
780780
it('keyed link fallback is replaced by the deferred resolution', async () => {
781-
const dataPromise = createControlledPromise<{ canonical: string }>()
781+
const dataPromise = createControlledPromise<{ iconUrl: string }>()
782782

783783
const rootRoute = new BaseRootRoute({})
784784
const indexRoute = new BaseRoute({
@@ -787,9 +787,9 @@ describe('deferred fallbacks: key-based replacement at render time', () => {
787787
loader: () => ({ dataPromise }),
788788
head: ({ loaderData }: { loaderData?: any }) => ({
789789
links: [
790-
{ rel: 'canonical', href: '/fallback', key: 'canonical' },
791-
loaderData?.dataPromise.then((d: { canonical: string }) => [
792-
{ rel: 'canonical', href: d.canonical, key: 'canonical' },
790+
{ rel: 'icon', href: '/favicon.ico', key: 'icon' },
791+
loaderData?.dataPromise.then((d: { iconUrl: string }) => [
792+
{ rel: 'icon', href: d.iconUrl, key: 'icon' },
793793
]),
794794
],
795795
}),
@@ -806,28 +806,28 @@ describe('deferred fallbacks: key-based replacement at render time', () => {
806806
const matchId = router.state.matches.find((m) => m.routeId === '/')!.id
807807
let match = router.getMatch(matchId)!
808808
expect(match.links).toEqual([
809-
{ rel: 'canonical', href: '/fallback', key: 'canonical' },
809+
{ rel: 'icon', href: '/favicon.ico', key: 'icon' },
810810
])
811811
expect(dedupByLastKey(match.links as any)).toEqual([
812-
{ rel: 'canonical', href: '/fallback', key: 'canonical' },
812+
{ rel: 'icon', href: '/favicon.ico', key: 'icon' },
813813
])
814814

815-
dataPromise.resolve({ canonical: '/resolved' })
815+
dataPromise.resolve({ iconUrl: '/tenant-icon.png' })
816816
await new Promise((r) => setTimeout(r, 10))
817817

818818
// Both entries are present in match data — render-time dedup picks the last.
819819
match = router.getMatch(matchId)!
820820
expect(match.links).toEqual([
821-
{ rel: 'canonical', href: '/fallback', key: 'canonical' },
822-
{ rel: 'canonical', href: '/resolved', key: 'canonical' },
821+
{ rel: 'icon', href: '/favicon.ico', key: 'icon' },
822+
{ rel: 'icon', href: '/tenant-icon.png', key: 'icon' },
823823
])
824824
expect(dedupByLastKey(match.links as any)).toEqual([
825-
{ rel: 'canonical', href: '/resolved', key: 'canonical' },
825+
{ rel: 'icon', href: '/tenant-icon.png', key: 'icon' },
826826
])
827827
})
828828

829829
it('without a key, fallback and resolved links both survive — demonstrates why the key exists', async () => {
830-
const dataPromise = createControlledPromise<{ canonical: string }>()
830+
const dataPromise = createControlledPromise<{ iconUrl: string }>()
831831

832832
const rootRoute = new BaseRootRoute({})
833833
const indexRoute = new BaseRoute({
@@ -836,9 +836,9 @@ describe('deferred fallbacks: key-based replacement at render time', () => {
836836
loader: () => ({ dataPromise }),
837837
head: ({ loaderData }: { loaderData?: any }) => ({
838838
links: [
839-
{ rel: 'canonical', href: '/fallback' },
840-
loaderData?.dataPromise.then((d: { canonical: string }) => [
841-
{ rel: 'canonical', href: d.canonical },
839+
{ rel: 'icon', href: '/favicon.ico' },
840+
loaderData?.dataPromise.then((d: { iconUrl: string }) => [
841+
{ rel: 'icon', href: d.iconUrl },
842842
]),
843843
],
844844
}),
@@ -851,14 +851,14 @@ describe('deferred fallbacks: key-based replacement at render time', () => {
851851
})
852852
await router.load()
853853

854-
dataPromise.resolve({ canonical: '/resolved' })
854+
dataPromise.resolve({ iconUrl: '/tenant-icon.png' })
855855
await new Promise((r) => setTimeout(r, 10))
856856

857857
const match = router.state.matches.find((m) => m.routeId === '/')!
858858
// dedupByLastKey is a no-op without keys — both links survive.
859859
expect(dedupByLastKey(match.links as any)).toEqual([
860-
{ rel: 'canonical', href: '/fallback' },
861-
{ rel: 'canonical', href: '/resolved' },
860+
{ rel: 'icon', href: '/favicon.ico' },
861+
{ rel: 'icon', href: '/tenant-icon.png' },
862862
])
863863
})
864864

‎packages/router-core/tests/head-dedup.test.ts‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,39 +4,39 @@ import { buildMetaTags, dedupByLastKey } from '../src'
44
describe('dedupByLastKey', () => {
55
it('keeps the last occurrence of each keyed entry', () => {
66
const items = [
7-
{ key: 'canonical', href: '/first' },
8-
{ key: 'canonical', href: '/second' },
9-
{ key: 'canonical', href: '/third' },
7+
{ key: 'icon', rel: 'icon', href: '/first.png' },
8+
{ key: 'icon', rel: 'icon', href: '/second.png' },
9+
{ key: 'icon', rel: 'icon', href: '/third.png' },
1010
]
1111
expect(dedupByLastKey(items)).toEqual([
12-
{ key: 'canonical', href: '/third' },
12+
{ key: 'icon', rel: 'icon', href: '/third.png' },
1313
])
1414
})
1515

1616
it('preserves keyless entries while deduplicating keyed ones', () => {
1717
const items = [
18-
{ href: '/favicon.ico' },
19-
{ key: 'canonical', href: '/fallback' },
20-
{ href: '/another-keyless' },
21-
{ key: 'canonical', href: '/resolved' },
18+
{ rel: 'manifest', href: '/manifest.json' },
19+
{ key: 'icon', rel: 'icon', href: '/favicon.ico' },
20+
{ rel: 'apple-touch-icon', href: '/touch-icon.png' },
21+
{ key: 'icon', rel: 'icon', href: '/tenant-icon.png' },
2222
]
2323
expect(dedupByLastKey(items)).toEqual([
24-
{ href: '/favicon.ico' },
25-
{ href: '/another-keyless' },
26-
{ key: 'canonical', href: '/resolved' },
24+
{ rel: 'manifest', href: '/manifest.json' },
25+
{ rel: 'apple-touch-icon', href: '/touch-icon.png' },
26+
{ key: 'icon', rel: 'icon', href: '/tenant-icon.png' },
2727
])
2828
})
2929

3030
it('deduplicates each key independently', () => {
3131
const items = [
32-
{ key: 'canonical', href: '/canonical-old' },
33-
{ key: 'alt-es', href: '/alt-old' },
34-
{ key: 'canonical', href: '/canonical-new' },
35-
{ key: 'alt-es', href: '/alt-new' },
32+
{ key: 'icon', rel: 'icon', href: '/icon-old.png' },
33+
{ key: 'apple-icon', rel: 'apple-touch-icon', href: '/apple-old.png' },
34+
{ key: 'icon', rel: 'icon', href: '/icon-new.png' },
35+
{ key: 'apple-icon', rel: 'apple-touch-icon', href: '/apple-new.png' },
3636
]
3737
expect(dedupByLastKey(items)).toEqual([
38-
{ key: 'canonical', href: '/canonical-new' },
39-
{ key: 'alt-es', href: '/alt-new' },
38+
{ key: 'icon', rel: 'icon', href: '/icon-new.png' },
39+
{ key: 'apple-icon', rel: 'apple-touch-icon', href: '/apple-new.png' },
4040
])
4141
})
4242

0 commit comments

Comments
 (0)