From 22d852329593ae0e902d39129ea50323991d1f97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Tue, 17 Nov 2026 12:18:12 +0000 Subject: [PATCH 1/6] perf: fetch the blog list only when it is needed useBlog() runs on every page through the search palette, and its useAsyncData started right away, downloading /api/content/site/list (about 250 KB) on each load. Callers already go through fetchList(). Amp-Thread-ID: https://ampcode.com/threads/T-01a1e525-9983-7071-a70a-d5ef82f1ba95 --- app/composables/useBlog.ts | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/app/composables/useBlog.ts b/app/composables/useBlog.ts index b8e164c3e..948bdc2d7 100644 --- a/app/composables/useBlog.ts +++ b/app/composables/useBlog.ts @@ -1,17 +1,18 @@ import type { BlogArticle, BlogCategory } from '#shared/types' export const useBlog = () => { - const { data: articles, refresh } = useAsyncData('blog', async () => { + const { data: articles, execute } = useAsyncData('blog', async () => { const items = await listByDir('/blog') return items .filter(article => article.extension !== '.yml') .sort((a, b) => String(b.date).localeCompare(String(a.date))) as BlogArticle[] - }, { default: () => [] }) + // `fetchList()` loads it: the search palette calls this on every page, and the list is over 250 KB. + }, { default: () => [], immediate: false }) async function fetchList() { if (!articles.value?.length) { - return refresh() + return execute() } } From 8690a77e4f17db0b38e5ef9b430bd1294d52f3d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Tue, 17 Nov 2026 12:18:12 +0000 Subject: [PATCH 2/6] perf: render the docs navigation only on docs pages Every page put the docs navigation (about 80 KB) in its payload, while only docs pages render from it. Other pages load it on the client once the app is ready, for the search palette. Amp-Thread-ID: https://ampcode.com/threads/T-01a1e525-9983-7071-a70a-d5ef82f1ba95 --- app/app.vue | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/app/app.vue b/app/app.vue index 453e7424d..cfaee79d4 100644 --- a/app/app.vue +++ b/app/app.vue @@ -33,10 +33,22 @@ watch(() => colorMode.preference, (newMode, oldMode) => { const pull = usePullPreview() const locale = useDocsLocale() -const { data: navigation } = await useFetch(() => { +const { data: navigation, execute: fetchNavigation } = useFetch(() => { if (pull.value) return pullNavigationPath(docsVersion.value, pull.value) return locale.value ? l10nNavigationPath(locale.value, docsVersion.value) : navigationPath(docsVersion.value) -}, { key: () => `navigation:${docsVersion.value}` }) +}, { key: () => `navigation:${docsVersion.value}`, immediate: false }) + +// Docs pages render from the navigation (aside, breadcrumb, surround); elsewhere only the search +// palette uses it, so it stays out of their HTML payload (about 80 KB) and loads once the page is idle. +const isDocsRoute = computed(() => route.path === '/docs' || route.path.startsWith('/docs/')) +if (isDocsRoute.value) { + await fetchNavigation() +} else if (import.meta.client) { + onNuxtReady(() => fetchNavigation()) +} +watch(isDocsRoute, (value) => { + if (value && !navigation.value) fetchNavigation() +}) const searchKeys = computed(() => searchInstanceKeys(docsVersion.value)) // Client-only: an SSR value gets baked into the page's ISR entry and would pin search to a stale commit. From 49bdaeb1bbe89b1a9b22d0d75e438f226203b9b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Tue, 17 Nov 2026 12:18:14 +0000 Subject: [PATCH 3/6] perf: load only the Latin subsets of Inter Each other subset added eight inline @font-face rules to every page. Amp-Thread-ID: https://ampcode.com/threads/T-01a1e525-9983-7071-a70a-d5ef82f1ba95 --- nuxt.config.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/nuxt.config.ts b/nuxt.config.ts index dd0579abd..f0cccdb11 100644 --- a/nuxt.config.ts +++ b/nuxt.config.ts @@ -732,7 +732,9 @@ export default defineNuxtConfig({ }, fonts: { families: [ - { name: 'Inter', weights: [400, 500, 600, 700], global: true }, + // Latin only, like Outfit: each other subset (Cyrillic, Greek, Vietnamese…) adds 8 inline `@font-face` + // rules to every page, and text in those scripts falls back to the system font. + { name: 'Inter', weights: [400, 500, 600, 700], subsets: ['latin', 'latin-ext'], global: true }, { name: 'Outfit', weights: [400, 500, 600, 700], global: true } ] }, From 22c9d2bb08d867005d896597309d4e35db2f92b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Tue, 17 Nov 2026 12:18:14 +0000 Subject: [PATCH 4/6] perf(home): trim the payload and hydrate sections on scroll The homepage now sends only the module fields its cards read and the ten showcase websites it shows, and the sections below the hero hydrate when they become visible instead of in one long task on load. Amp-Thread-ID: https://ampcode.com/threads/T-01a1e525-9983-7071-a70a-d5ef82f1ba95 --- app/pages/index.vue | 69 ++++++++++++++++++++++++++++++--------------- 1 file changed, 46 insertions(+), 23 deletions(-) diff --git a/app/pages/index.vue b/app/pages/index.vue index a7e367ab3..e42bac8ff 100644 --- a/app/pages/index.vue +++ b/app/pages/index.vue @@ -11,11 +11,20 @@ const [{ data: page }, { data: officialModules }, { data: showcase }, { data: sp useAsyncData('index', () => useContent('site').get('/')), useFetch('/api/v1/modules', { key: 'official-modules', + // Only what `ModuleItem` reads: the payload carries every module object otherwise. transform: (res: { modules: Module[], stats: Stats }) => res.modules .filter(module => module.type === 'official') - .sort((a, b) => b.stats.stars - a.stats.stars) + .sort((a, b) => b.stats!.stars - a.stats!.stars) + .map(({ name, npm, description, icon, category, type, sponsor, repo, website, health, stats }) => ({ + name, npm, description, icon, category, type, sponsor, repo, website, health, + stats: { version: stats!.version, downloads: stats!.downloads, stars: stats!.stars, publishedAt: stats!.publishedAt, createdAt: stats!.createdAt } + }) as Module) + }), + useAsyncData('showcase-home', async () => { + const doc = await useContent('site').get('/showcase') + // The carousel shows the first 10 websites. + return { websites: (doc?.data.websites as any[]).slice(0, 10).map(({ name, url }) => ({ name, url })) } }), - useAsyncData('showcase', () => useContent('site').get('/showcase')), useFetch('/api/sponsors', { key: 'sponsors-home', transform(sponsors: SponsorsByTier) { @@ -36,13 +45,15 @@ const [{ data: page }, { data: officialModules }, { data: showcase }, { data: sp ]) const pageData = computed(() => page.value?.data) -const showcaseData = computed(() => showcase.value?.data) // Merge via computed, not mutation: useFetch `data` is a shallowRef (Nuxt 4 // default), so writing module.health in place would not trigger a re-render. const { health } = useModuleHealth() +// The health map loads on the client only: merge it once the modules section hydrated, or its server +// HTML (without the health badges) would not match. +const modulesHydrated = ref(false) const officialModulesWithHealth = computed(() => - (officialModules.value || []).map(m => ({ ...m, health: health.value[m.name] ?? m.health ?? null })) + (officialModules.value || []).map(m => ({ ...m, health: (modulesHydrated.value && health.value[m.name]) || m.health || null })) ) const stats = useStats() @@ -234,7 +245,10 @@ useNuxtBirthday() - + - + - - + - - + - From 916e64fae3f584a70e08bb890db06d41f6f07a2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Tue, 17 Nov 2026 14:09:13 +0000 Subject: [PATCH 5/6] perf: let docs pages fetch the navigation they render Move the navigation fetch into a useDocsNavigation() composable. The docs page awaits it with its content, so it stays server-rendered there, and app.vue and error.vue load it on the client for the search palette. This replaces the route check in app.vue and also keeps it out of error pages. Amp-Thread-ID: https://ampcode.com/threads/T-01a1e525-9983-7071-a70a-d5ef82f1ba95 --- app/app.vue | 25 +++---------------------- app/composables/useDocsNavigation.ts | 20 ++++++++++++++++++++ app/error.vue | 11 +++-------- app/pages/docs/[...slug].vue | 17 +++++++++++------ test/nuxt/docs-navigation.spec.ts | 26 +++++++++----------------- 5 files changed, 46 insertions(+), 53 deletions(-) create mode 100644 app/composables/useDocsNavigation.ts diff --git a/app/app.vue b/app/app.vue index cfaee79d4..5695e7aca 100644 --- a/app/app.vue +++ b/app/app.vue @@ -1,9 +1,6 @@ diff --git a/app/composables/useDocsNavigation.ts b/app/composables/useDocsNavigation.ts new file mode 100644 index 000000000..b607531af --- /dev/null +++ b/app/composables/useDocsNavigation.ts @@ -0,0 +1,20 @@ +import type { NavigationItem } from 'comark-content' +import { navigationPath } from '#shared/utils/content' +import { pullNavigationPath } from '#shared/utils/pull' +import { l10nNavigationPath } from '#shared/utils/l10n' + +/** + * The navigation of the active docs version. Docs pages await it, so it is server-rendered there; + * other pages only need it for the search palette and pass `{ lazy: true, server: false }` to keep + * it out of their HTML payload (about 80 KB). Both share the `navigation:` key. + */ +export function useDocsNavigation(options: { lazy?: boolean, server?: boolean } = {}) { + const { version } = useDocsVersion() + const pull = usePullPreview() + const locale = useDocsLocale() + + return useFetch(() => { + if (pull.value) return pullNavigationPath(version.value, pull.value) + return locale.value ? l10nNavigationPath(locale.value, version.value) : navigationPath(version.value) + }, { key: () => `navigation:${version.value}`, ...options }) +} diff --git a/app/error.vue b/app/error.vue index 016278abb..2a1b57091 100644 --- a/app/error.vue +++ b/app/error.vue @@ -1,9 +1,7 @@ diff --git a/app/pages/docs/[...slug].vue b/app/pages/docs/[...slug].vue index 301e233a2..0b606d42b 100644 --- a/app/pages/docs/[...slug].vue +++ b/app/pages/docs/[...slug].vue @@ -23,7 +23,9 @@ const markdownComponents = { VideoAccordion } -const navigation = inject>('navigation', ref([])) +// Awaited with the page below, so docs pages server-render their aside, breadcrumb and surround links. +const navigationFetch = useDocsNavigation() +const navigation = computed(() => navigationFetch.data.value ?? []) const menuDrawerOpen = ref(false) const onThisPageDrawerOpen = ref(false) @@ -81,11 +83,14 @@ const instanceKey = computed(() => { const { data: indexable } = useL10nIndexable(path) -const { data: page, status, refresh: refreshPage } = await useAsyncData(pageKey, () => { - const pagePath = path.value - const client = useContent(instanceKey.value) - return paintResponse().then(() => client.get(pagePath)) -}) +const [{ data: page, status, refresh: refreshPage }] = await Promise.all([ + useAsyncData(pageKey, () => { + const pagePath = path.value + const client = useContent(instanceKey.value) + return paintResponse().then(() => client.get(pagePath)) + }), + navigationFetch +]) const locale = useDocsLocale() diff --git a/test/nuxt/docs-navigation.spec.ts b/test/nuxt/docs-navigation.spec.ts index 2f3498d4f..6ec816df8 100644 --- a/test/nuxt/docs-navigation.spec.ts +++ b/test/nuxt/docs-navigation.spec.ts @@ -1,31 +1,23 @@ -import type { NavigationItem } from 'comark-content' -import { mockComponent, mountSuspended, registerEndpoint } from '@nuxt/test-utils/runtime' +import { mountSuspended, registerEndpoint } from '@nuxt/test-utils/runtime' import { describe, expect, it, vi } from 'vitest' -import { defineComponent, h, inject, type Ref } from 'vue' +import { defineComponent, h } from 'vue' import { navigationPath } from '#shared/utils/content' -import App from '~/app.vue' // One root per version, so the rendered paths tell which tree was fetched. for (const version of ['3.x', '4.x'] as const) { registerEndpoint(navigationPath(version), () => [{ title: 'Docs', path: `/docs/${version}` }]) } -registerEndpoint('/api/content/heads', () => ({})) -// `app.vue` lazy loads the agent, whose imports can still be in flight when the environment tears down. -mockComponent('AgentPanel', { render: () => null }) -mockComponent('AgentFloatingInput', { render: () => null }) - -// Stands in for the layout, and renders the roots of the tree `app.vue` provides. -const NavigationRoots = defineComponent(() => { - const navigation = inject>('navigation')! - return () => h('p', { id: 'navigation-roots' }, navigation.value.map(item => item.path).join(',')) +// Renders the roots of the tree, as the docs page reads them. +const NavigationRoots = defineComponent(async () => { + const { data: navigation } = await useDocsNavigation() + return () => h('p', { id: 'navigation-roots' }, (navigation.value ?? []).map(item => item.path).join(',')) }) -describe('app.vue', () => { +describe('useDocsNavigation', () => { it('fetches the new version\'s navigation when the route switches version', async () => { - const wrapper = await mountSuspended(App, { - route: '/docs/4.x/getting-started/introduction', - global: { stubs: { NuxtLayout: NavigationRoots } } + const wrapper = await mountSuspended(NavigationRoots, { + route: '/docs/4.x/getting-started/introduction' }) const roots = () => wrapper.find('#navigation-roots').text() expect(roots()).toBe('/docs/4.x') From 84dcfe15c4180b4166a2581ee8b82a3c212cf47a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Tue, 17 Nov 2026 14:25:33 +0000 Subject: [PATCH 6/6] perf: fetch the search navigation once the app is ready `lazy` still starts the request while the page mounts. Outside the docs, the navigation is only for the search palette, so start it from onNuxtReady instead. Amp-Thread-ID: https://ampcode.com/threads/T-01a1e525-9983-7071-a70a-d5ef82f1ba95 --- app/app.vue | 2 +- app/composables/useDocsNavigation.ts | 21 +++++++++++++++------ app/error.vue | 2 +- 3 files changed, 17 insertions(+), 8 deletions(-) diff --git a/app/app.vue b/app/app.vue index 5695e7aca..f842b7366 100644 --- a/app/app.vue +++ b/app/app.vue @@ -30,7 +30,7 @@ watch(() => colorMode.preference, (newMode, oldMode) => { const locale = useDocsLocale() // Docs pages await their own call, which server-renders it for them. -const { data: navigation } = useDocsNavigation({ lazy: true, server: false }) +const { data: navigation } = useDocsNavigation({ deferred: true }) const searchKeys = computed(() => searchInstanceKeys(docsVersion.value)) // Client-only: an SSR value gets baked into the page's ISR entry and would pin search to a stale commit. diff --git a/app/composables/useDocsNavigation.ts b/app/composables/useDocsNavigation.ts index b607531af..ee3c04fb9 100644 --- a/app/composables/useDocsNavigation.ts +++ b/app/composables/useDocsNavigation.ts @@ -4,17 +4,26 @@ import { pullNavigationPath } from '#shared/utils/pull' import { l10nNavigationPath } from '#shared/utils/l10n' /** - * The navigation of the active docs version. Docs pages await it, so it is server-rendered there; - * other pages only need it for the search palette and pass `{ lazy: true, server: false }` to keep - * it out of their HTML payload (about 80 KB). Both share the `navigation:` key. + * The navigation of the active docs version. Docs pages await it, so it is server-rendered there. + * Other pages only need it for the search palette: `deferred` keeps it out of their HTML payload + * (about 80 KB) and fetches it once the app is idle. Both share the `navigation:` key. */ -export function useDocsNavigation(options: { lazy?: boolean, server?: boolean } = {}) { +export function useDocsNavigation({ deferred = false } = {}) { const { version } = useDocsVersion() const pull = usePullPreview() const locale = useDocsLocale() - return useFetch(() => { + const navigation = useFetch(() => { if (pull.value) return pullNavigationPath(version.value, pull.value) return locale.value ? l10nNavigationPath(locale.value, version.value) : navigationPath(version.value) - }, { key: () => `navigation:${version.value}`, ...options }) + }, { key: () => `navigation:${version.value}`, server: !deferred, immediate: !deferred }) + + // Not `lazy`, which still starts the request while the page mounts. + if (deferred && import.meta.client) { + onNuxtReady(() => { + if (!navigation.data.value) navigation.execute() + }) + } + + return navigation } diff --git a/app/error.vue b/app/error.vue index 2a1b57091..136382ded 100644 --- a/app/error.vue +++ b/app/error.vue @@ -14,7 +14,7 @@ const route = useRoute() const { version: docsVersion } = useDocsVersion() // Only the client-only search palette uses it. -const { data: navigation } = useDocsNavigation({ lazy: true, server: false }) +const { data: navigation } = useDocsNavigation({ deferred: true }) const searchKeys = computed(() => searchInstanceKeys(docsVersion.value)) // Client-only: an SSR value gets baked into the page's ISR entry and would pin search to a stale commit.