fix: use SSR-safe provider in async-data keys to avoid hydration mismatch on org/user/search

Revert the useSettings/prehydrate refactor and instead fix the actual cause of
the empty-state on /org/[name] when the user has 'npm registry' selected: the
async-data cache key embedded the localStorage-backed search provider, so SSR
keyed by 'algolia' while client hydration keyed by 'npm', missing the SSR
payload and dropping to the empty default.

Introduces useEffectiveSearchProvider which defers the stored preference until
app:mounted, keeping SSR and initial hydration on the same key. After mount the
reactive key flips and useLazyAsyncData refetches once with the user's
preference. URL ?p= still wins everywhere and remains cacheable per-URL.

Closes #2753

Author: Adebesin-Cell

app/composables/npm/useOrgPackages.ts

@@ -10,13 +10,7 @@ import { mapWithConcurrency } from '#shared/utils/async'
  * 3. Falls back to lightweight server-side package-meta lookups
  */
 export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
-  const route = useRoute()
-  const { searchProvider } = useSearchProvider()
-  const searchProviderValue = computed(() => {
-    const p = normalizeSearchParam(route.query.p)
-    if (p === 'npm' || searchProvider.value === 'npm') return 'npm'
-    return 'algolia'
-  })
+  const searchProviderValue = useEffectiveSearchProvider()
   const { getPackagesByName } = useAlgoliaSearch()
 
   const asyncData = useLazyAsyncData(

app/composables/npm/useUserPackages.ts

@@ -19,13 +19,7 @@ const MAX_RESULTS = 250
  * ```
  */
 export function useUserPackages(username: MaybeRefOrGetter<string>) {
-  const route = useRoute()
-  const { searchProvider } = useSearchProvider()
-  const searchProviderValue = computed(() => {
-    const p = normalizeSearchParam(route.query.p)
-    if (p === 'npm' || searchProvider.value === 'npm') return 'npm'
-    return 'algolia'
-  })
+  const searchProviderValue = useEffectiveSearchProvider()
   // this is only used in npm path, but we need to extract it when the composable runs
   const { $npmRegistry } = useNuxtApp()
   const { searchByMaintainer } = useAlgoliaSearch()

app/composables/useGlobalSearch.ts

@@ -9,11 +9,7 @@ const SEARCH_DEBOUNCE_MS = 100
 export function useGlobalSearch(place: 'header' | 'content' = 'content') {
   const { settings } = useSettings()
   const { searchProvider } = useSearchProvider()
-  const searchProviderValue = computed(() => {
-    const p = normalizeSearchParam(route.query.p)
-    if (p === 'npm' || searchProvider.value === 'npm') return 'npm'
-    return 'algolia'
-  })
+  const searchProviderValue = useEffectiveSearchProvider()
 
   const router = useRouter()
   const route = useRoute()

app/composables/useSettings.ts

@@ -1,6 +1,9 @@
+import type { RemovableRef } from '@vueuse/core'
+import { useLocalStorage } from '@vueuse/core'
 import { ACCENT_COLORS, type AccentColorId } from '#shared/utils/constants'
 import type { LocaleObject } from '@nuxtjs/i18n'
 import { BACKGROUND_THEMES } from '#shared/utils/constants'
+import { normalizeSearchParam } from '#shared/utils/url'
 
 type BackgroundThemeId = keyof typeof BACKGROUND_THEMES
 
@@ -92,86 +95,22 @@ const DEFAULT_SETTINGS: AppSettings = {
 
 const STORAGE_KEY = 'npmx-settings'
 
-/**
- * Read settings from localStorage and merge with defaults.
- */
-function normaliseSettings(input: AppSettings): AppSettings {
-  return {
-    ...input,
-    searchProvider: input.searchProvider === 'npm' ? 'npm' : 'algolia',
-    sidebar: {
-      ...input.sidebar,
-      collapsed: Array.isArray(input.sidebar?.collapsed)
-        ? input.sidebar.collapsed.filter((v): v is string => typeof v === 'string')
-        : [],
-    },
-  }
-}
-
-function readFromLocalStorage(): AppSettings {
-  try {
-    const raw = localStorage.getItem(STORAGE_KEY)
-    if (raw) {
-      const stored = JSON.parse(raw)
-      return normaliseSettings({
-        ...DEFAULT_SETTINGS,
-        ...stored,
-        connector: { ...DEFAULT_SETTINGS.connector, ...stored.connector },
-        sidebar: { ...DEFAULT_SETTINGS.sidebar, ...stored.sidebar },
-        chartFilter: { ...DEFAULT_SETTINGS.chartFilter, ...stored.chartFilter },
-      })
-    }
-  } catch {}
-  return { ...DEFAULT_SETTINGS }
-}
-
-let syncInitialized = false
+// Shared settings instance (singleton per app)
+let settingsRef: RemovableRef<AppSettings> | null = null
 
 /**
- * Composable for managing application settings.
- *
- * Uses useState for SSR-safe hydration (server and client agree on initial
- * values during hydration) and syncs with localStorage on the client.
- * The onPrehydrate script in prehydrate.ts handles DOM-level patches
- * (accent color, bg theme, collapsed sections, etc.) to prevent visual
- * flash before hydration.
+ * Composable for managing application settings with localStorage persistence.
+ * Settings are shared across all components that use this composable.
  */
 export function useSettings() {
-  const settings = useState<AppSettings>(STORAGE_KEY, () => ({ ...DEFAULT_SETTINGS }))
-
-  if (import.meta.client && !syncInitialized) {
-    syncInitialized = true
-
-    // Read localStorage eagerly but apply after mount to prevent hydration
-    // mismatch. During hydration, useState provides server-matching defaults.
-    // After mount, we swap in the user's actual preferences from localStorage.
-    // Uses nuxtApp.hook('app:mounted') instead of onMounted so it works even
-    // when useSettings() is first called from a plugin (no component context).
-    const stored = readFromLocalStorage()
-    const nuxtApp = useNuxtApp()
-
-    if (nuxtApp.isHydrating) {
-      nuxtApp.hook('app:mounted', () => {
-        settings.value = stored
-      })
-    } else {
-      settings.value = stored
-    }
-
-    // Persist future changes back to localStorage
-    watch(
-      settings,
-      value => {
-        try {
-          localStorage.setItem(STORAGE_KEY, JSON.stringify(value))
-        } catch {}
-      },
-      { deep: true },
-    )
+  if (!settingsRef) {
+    settingsRef = useLocalStorage<AppSettings>(STORAGE_KEY, DEFAULT_SETTINGS, {
+      mergeDefaults: true,
+    })
   }
 
   return {
-    settings,
+    settings: settingsRef,
   }
 }
 
@@ -280,6 +219,31 @@ export function useSearchProvider() {
   }
 }
 
+/**
+ * SSR/hydration-safe search provider for use in async-data cache keys.
+ * Defers reading the localStorage-backed preference until after `app:mounted`
+ * so the server-rendered key matches initial hydration.
+ */
+export function useEffectiveSearchProvider() {
+  const route = useRoute()
+  const { searchProvider } = useSearchProvider()
+
+  const storedProviderReady = ref(import.meta.server ? false : !useNuxtApp().isHydrating)
+  if (import.meta.client && !storedProviderReady.value) {
+    useNuxtApp().hook('app:mounted', () => {
+      storedProviderReady.value = true
+    })
+  }
+
+  return computed<SearchProvider>(() => {
+    const p = normalizeSearchParam(route.query.p)
+    if (p === 'npm') return 'npm'
+    if (p === 'algolia') return 'algolia'
+    if (storedProviderReady.value && searchProvider.value === 'npm') return 'npm'
+    return 'algolia'
+  })
+}
+
 export function useBackgroundTheme() {
   const { t } = useI18n()
 

app/utils/prehydrate.ts

@@ -75,11 +75,6 @@ export function initPreferencesOnPrehydrate() {
       document.documentElement.dataset.kbdShortcuts = 'false'
     }
 
-    // Search provider (default: algolia)
-    if (settings.searchProvider === 'npm') {
-      document.documentElement.dataset.searchProvider = 'npm'
-    }
-
     // Code font ligatures (default: true)
     if (settings.codeLigatures === false) {
       document.documentElement.dataset.codeLigatures = 'false'