Files

T

yeuimu 6c61a4e871 feat(deploy): production deployment setup and fixes

- Debian-based api image (bookworm-slim), docker/debian mirrors, prisma
  binaryTargets for openssl 3.0
- nginx: admin SPA under /admin, TLS via acme.sh (ZeroSSL) + auto-renewal
  cron, http->https redirect
- prisma: add origin_goods.delisted migration, sync missing schema
  (good_image/tag_font_color/good_tags), fix users.createdAt Timestamptz
- api: CORS wildcard reflection, helmet CORP cross-origin, price
  backfill in persistProductDetail, categoryIcon ancestor fallback,
  mediaByColor per-color gallery in public goods detail
- admin: /admin base path (vite + router)
- import-data.mjs: udt_name casting, serial sequence advance fix

2026-08-26 14:23:09 +08:00

4.4 KiB

Raw Blame History

Suspense SSR Hydration Issues and Workarounds

Rule

<Suspense> has known issues with SSR hydration, particularly with async components. During initial hydration, Suspense may not properly include child components within its "cloak of suspense," leading to hydration mismatches, flickering, or runtime crashes.

Why This Matters

In SSR applications, hydration mismatches cause:

Visual flickering as the client re-renders
Loss of state in affected components
Console warnings in development (silent failures in production)
Potential runtime crashes in edge cases
Poor user experience, especially on slower networks

Bad Code

<template>
  <!-- Async component directly in Suspense can fail hydration -->
  <Suspense>
    <AsyncDashboard />
    <template #fallback>
      Loading...
    </template>
  </Suspense>
</template>

<script setup>
import { defineAsyncComponent } from 'vue'

const AsyncDashboard = defineAsyncComponent(
  () => import('./Dashboard.vue')
)
</script>

Good Code

Solution 1: Wrap Async Components with Suspense

<template>
  <!-- Each async component wrapped in its own Suspense -->
  <div class="dashboard">
    <Suspense>
      <AsyncHeader />
      <template #fallback><HeaderSkeleton /></template>
    </Suspense>

    <Suspense>
      <AsyncContent />
      <template #fallback><ContentSkeleton /></template>
    </Suspense>
  </div>
</template>

Solution 2: Use ClientOnly Wrapper (Nuxt/SSR Frameworks)

<template>
  <!-- Prevent SSR for problematic async components -->
  <ClientOnly>
    <Suspense>
      <AsyncDashboard />
      <template #fallback>
        Loading dashboard...
      </template>
    </Suspense>

    <template #fallback>
      <DashboardSkeleton />
    </template>
  </ClientOnly>
</template>

Solution 3: Prefetch with Proper Stale Time (with TanStack Query)

<script setup>
import { useQuery, useQueryClient } from '@tanstack/vue-query'

// IMPORTANT: All useQuery calls must be BEFORE any await
const { data, suspense } = useQuery({
  queryKey: ['dashboard'],
  queryFn: fetchDashboardData,
  staleTime: 1000 * 60 * 5, // 5 minutes - prevents refetch after hydration
})

// Wait for suspense AFTER all useQuery calls
await suspense()

// Now safe to use data
</script>

Solution 4: Handle Hydration Errors Gracefully

<script setup>
import { ref, onErrorCaptured, onMounted } from 'vue'

const hydrationError = ref(false)
const isClient = ref(false)

onMounted(() => {
  isClient.value = true
})

onErrorCaptured((err) => {
  if (err.message?.includes('hydration')) {
    hydrationError.value = true
    return false
  }
})
</script>

<template>
  <div v-if="hydrationError" class="hydration-recovery">
    <!-- Force client-only re-render -->
    <Suspense v-if="isClient">
      <AsyncContent />
      <template #fallback>Recovering...</template>
    </Suspense>
  </div>

  <Suspense v-else>
    <AsyncContent />
    <template #fallback>Loading...</template>
  </Suspense>
</template>

Common SSR + Suspense Issues

Issue	Cause	Solution
Hydration mismatch	Async chunk not loaded in time	Wrap with Suspense or use ClientOnly
Empty flash on Safari	Slow chunk loading	Preload critical chunks, use skeleton
useQuery after await error	Vue context lost after await	Put all useQuery calls before any await
Immediate refetch after hydration	staleTime too low	Set appropriate staleTime value

Key Points

Suspense + SSR has known edge cases - test thoroughly
Safari has slower chunk loading that triggers more hydration issues
With data-fetching libraries, ensure queries are set up before awaiting suspense
Consider ClientOnly wrappers for non-critical async content
Set appropriate staleTime to prevent unnecessary refetches after hydration
Use skeleton screens that match server-rendered content structure

4.4 KiB Raw Blame History