1---
2title: Async Component Best Practices
3impact: MEDIUM
4impactDescription: Poor async component strategy can delay interactivity in SSR apps and create loading UI flicker
5type: best-practice
6tags: [vue3, async-components, ssr, hydration, performance, ux]
7---
8 
9# Async Component Best Practices
10 
11**Impact: MEDIUM** - Async components should reduce JavaScript cost without degrading perceived performance. Focus on hydration timing in SSR and stable loading UX.
12 
13## Task List
14 
15- Use lazy hydration strategies for non-critical SSR component trees
16- Import only the hydration helpers you actually use
17- Keep `loadingComponent` delay near the default `200ms` unless real UX data suggests otherwise
18- Configure `delay` and `timeout` together for predictable loading behavior
19 
20## Use Lazy Hydration Strategies in SSR
21 
22In Vue 3.5+, async components can delay hydration until idle time, visibility, media query match, or user interaction.
23 
24**BAD:**
25```vue
26<script setup lang="ts">
27import { defineAsyncComponent } from 'vue'
28 
29const AsyncComments = defineAsyncComponent({
30  loader: () => import('./Comments.vue')
31})
32</script>
33```
34 
35**GOOD:**
36```vue
37<script setup lang="ts">
38import {
39  defineAsyncComponent,
40  hydrateOnVisible,
41  hydrateOnIdle
42} from 'vue'
43 
44const AsyncComments = defineAsyncComponent({
45  loader: () => import('./Comments.vue'),
46  hydrate: hydrateOnVisible({ rootMargin: '100px' })
47})
48 
49const AsyncFooter = defineAsyncComponent({
50  loader: () => import('./Footer.vue'),
51  hydrate: hydrateOnIdle(5000)
52})
53</script>
54```
55 
56## Prevent Loading Spinner Flicker
57 
58Avoid showing loading UI immediately for components that usually resolve quickly.
59 
60**BAD:**
61```vue
62<script setup lang="ts">
63import { defineAsyncComponent } from 'vue'
64import LoadingSpinner from './LoadingSpinner.vue'
65 
66const AsyncDashboard = defineAsyncComponent({
67  loader: () => import('./Dashboard.vue'),
68  loadingComponent: LoadingSpinner,
69  delay: 0
70})
71</script>
72```
73 
74**GOOD:**
75```vue
76<script setup lang="ts">
77import { defineAsyncComponent } from 'vue'
78import LoadingSpinner from './LoadingSpinner.vue'
79import ErrorDisplay from './ErrorDisplay.vue'
80 
81const AsyncDashboard = defineAsyncComponent({
82  loader: () => import('./Dashboard.vue'),
83  loadingComponent: LoadingSpinner,
84  errorComponent: ErrorDisplay,
85  delay: 200,
86  timeout: 30000
87})
88</script>
89```
90 
91## Delay Guidelines
92 
93| Scenario | Recommended Delay |
94|----------|-------------------|
95| Small component, fast network | `200ms` |
96| Known heavy component | `100ms` |
97| Background or non-critical UI | `300-500ms` |
98