1---
2name: data-fetching-best-practices
3description: Patterns and best practices for efficient data fetching in Nuxt
4---
5 
6# Data Fetching Best Practices
7 
8Effective data fetching patterns for SSR-friendly, performant Nuxt applications.
9 
10## Choose the Right Tool
11 
12| Scenario | Use |
13|----------|-----|
14| Component initial data | `useFetch` or `useAsyncData` |
15| User interactions (clicks, forms) | `$fetch` |
16| Third-party SDK/API | `useAsyncData` with custom function |
17| Multiple parallel requests | `useAsyncData` with `Promise.all` |
18 
19## Await vs Non-Await Usage
20 
21The `await` keyword controls whether data fetching **blocks navigation**:
22 
23### With `await` - Blocking Navigation
24 
25```vue
26<script setup lang="ts">
27// Navigation waits until data is fetched (uses Vue Suspense)
28const { data } = await useFetch('/api/posts')
29// data.value is available immediately after this line
30</script>
31```
32 
33- **Server**: Fetches data and includes it in the payload
34- **Client hydration**: Uses payload data, no re-fetch
35- **Client navigation**: Blocks until data is ready
36 
37### Without `await` - Non-Blocking (Lazy)
38 
39```vue
40<script setup lang="ts">
41// Navigation proceeds immediately, data fetches in background
42const { data, status } = useFetch('/api/posts', { lazy: true })
43// data.value may be undefined initially - check status!
44</script>
45 
46<template>
47  <div v-if="status === 'pending'">Loading...</div>
48  <div v-else>{{ data }}</div>
49</template>
50```
51 
52Equivalent to using `useLazyFetch`:
53 
54```vue
55<script setup lang="ts">
56const { data, status } = useLazyFetch('/api/posts')
57</script>
58```
59 
60### When to Use Each
61 
62| Pattern | Use Case |
63|---------|----------|
64| `await useFetch()` | Critical data needed for SEO/initial render |
65| `useFetch({ lazy: true })` | Non-critical data, better perceived performance |
66| `await useLazyFetch()` | Same as lazy, await only ensures initialization |
67 
68## Avoid Double Fetching
69 
70### ❌ Wrong: Using $fetch Alone in Setup
71 
72```vue
73<script setup lang="ts">
74// This fetches TWICE: once on server, once on client
75const data = await $fetch('/api/posts')
76</script>
77```
78 
79### ✅ Correct: Use useFetch
80 
81```vue
82<script setup lang="ts">
83// Fetches on server, hydrates on client (no double fetch)
84const { data } = await useFetch('/api/posts')
85</script>
86```
87 
88## Use Explicit Cache Keys
89 
90### ❌ Avoid: Auto-generated Keys
91 
92```vue
93<script setup lang="ts">
94// Key is auto-generated from file/line - can cause issues
95const { data } = await useAsyncData(() => fetchPosts())
96</script>
97```
98 
99### ✅ Better: Explicit Keys
100 
101```vue
102<script setup lang="ts">
103// Explicit key for predictable caching
104const { data } = await useAsyncData(
105  'posts',
106  () => fetchPosts(),
107)
108 
109// Dynamic keys for parameterized data
110const route = useRoute()
111const { data: post } = await useAsyncData(
112  `post-${route.params.id}`,
113  () => fetchPost(route.params.id),
114)
115</script>
116```
117 
118## Handle Loading States Properly
119 
120```vue
121<script setup lang="ts">
122const { data, status, error } = await useFetch('/api/posts')
123</script>
124 
125<template>
126  <div v-if="status === 'pending'">
127    <SkeletonLoader />
128  </div>
129  <div v-else-if="error">
130    <ErrorMessage :error="error" />
131  </div>
132  <div v-else>
133    <PostList :posts="data" />
134  </div>
135</template>
136```
137 
138## Use Lazy Fetching for Non-critical Data
139 
140```vue
141<script setup lang="ts">
142const id = useRoute().params.id
143 
144// Critical data - blocks navigation
145const { data: post } = await useFetch(`/api/posts/${id}`)
146 
147// Non-critical data - doesn't block navigation
148const { data: comments, status } = useFetch(`/api/posts/${id}/comments`, {
149  lazy: true,
150})
151 
152// Or use useLazyFetch
153const { data: related } = useLazyFetch(`/api/posts/${id}/related`)
154</script>
155 
156<template>
157  <article>
158    <h1>{{ post?.title }}</h1>
159    <p>{{ post?.content }}</p>
160  </article>
161 
162  <section v-if="status === 'pending'">Loading comments...</section>
163  <CommentList v-else :comments="comments" />
164</template>
165```
166 
167## Minimize Payload Size
168 
169### Use `pick` for Simple Filtering
170 
171```vue
172<script setup lang="ts">
173const { data } = await useFetch('/api/users', {
174  // Only include these fields in payload
175  pick: ['id', 'name', 'avatar'],
176})
177</script>
178```
179 
180### Use `transform` for Complex Transformations
181 
182```vue
183<script setup lang="ts">
184const { data } = await useFetch('/api/posts', {
185  transform: (posts) => {
186    return posts.map(post => ({
187      id: post.id,
188      title: post.title,
189      excerpt: post.content.slice(0, 100),
190      date: new Date(post.createdAt).toLocaleDateString(),
191    }))
192  },
193})
194</script>
195```
196 
197## Parallel Fetching
198 
199### Fetch Independent Data with useAsyncData
200 
201```vue
202<script setup lang="ts">
203const { data } = await useAsyncData(
204  'dashboard',
205  async (_nuxtApp, { signal }) => {
206    const [user, posts, stats] = await Promise.all([
207      $fetch('/api/user', { signal }),
208      $fetch('/api/posts', { signal }),
209      $fetch('/api/stats', { signal }),
210    ])
211    return { user, posts, stats }
212  },
213)
214</script>
215```
216 
217### Multiple useFetch Calls
218 
219```vue
220<script setup lang="ts">
221// These run in parallel automatically
222const [{ data: user }, { data: posts }] = await Promise.all([
223  useFetch('/api/user'),
224  useFetch('/api/posts'),
225])
226</script>
227```
228 
229## Efficient Refresh Patterns
230 
231### Watch Reactive Dependencies
232 
233```vue
234<script setup lang="ts">
235const page = ref(1)
236const category = ref('all')
237 
238const { data } = await useFetch('/api/posts', {
239  query: { page, category },
240  // Auto-refresh when these change
241  watch: [page, category],
242})
243</script>
244```
245 
246### Manual Refresh
247 
248```vue
249<script setup lang="ts">
250const { data, refresh, status } = await useFetch('/api/posts')
251 
252async function refreshPosts() {
253  await refresh()
254}
255</script>
256```
257 
258### Conditional Fetching
259 
260```vue
261<script setup lang="ts">
262const userId = ref<string | null>(null)
263 
264const { data, execute } = useFetch(() => `/api/users/${userId.value}`, {
265  immediate: false, // Don't fetch until userId is set
266})
267 
268// Later, when userId is available
269function loadUser(id: string) {
270  userId.value = id
271  execute()
272}
273</script>
274```
275 
276## Server-only Fetching
277 
278```vue
279<script setup lang="ts">
280// Only fetch on server, skip on client navigation
281const { data } = await useFetch('/api/static-content', {
282  server: true,
283  lazy: true,
284  getCachedData: (key, nuxtApp) => nuxtApp.payload.data[key],
285})
286</script>
287```
288 
289## Error Handling
290 
291```vue
292<script setup lang="ts">
293const { data, error, refresh } = await useFetch('/api/posts')
294 
295// Watch for errors if need event-like handling
296watch(error, (err) => {
297  if (err) {
298    console.error('Fetch failed:', err)
299    // Show toast, redirect, etc.
300  }
301}, { immediate: true })
302</script>
303 
304<template>
305  <div v-if="error">
306    <p>Failed to load: {{ error.message }}</p>
307    <button @click="refresh()">Retry</button>
308  </div>
309</template>
310```
311 
312## Shared Data Across Components
313 
314```vue
315<!-- ComponentA.vue -->
316<script setup lang="ts">
317const { data } = await useFetch('/api/user', { key: 'current-user' })
318</script>
319 
320<!-- ComponentB.vue -->
321<script setup lang="ts">
322// Access cached data without refetching
323const { data: user } = useNuxtData('current-user')
324 
325// Or refresh it
326const { refresh } = await useFetch('/api/user', { key: 'current-user' })
327</script>
328```
329 
330## Avoid useAsyncData for Side Effects
331 
332### ❌ Wrong: Side Effects in useAsyncData
333 
334```vue
335<script setup lang="ts">
336// Don't trigger Pinia actions or side effects
337await useAsyncData(() => store.fetchUser()) // Can cause issues
338</script>
339```
340 
341### ✅ Correct: Use callOnce for Side Effects
342 
343```vue
344<script setup lang="ts">
345await callOnce(async () => {
346  await store.fetchUser()
347})
348</script>
349```
350 
351<!-- 
352Source references:
353- https://nuxt.com/docs/getting-started/data-fetching
354- https://nuxt.com/docs/api/composables/use-fetch
355- https://nuxt.com/docs/api/composables/use-async-data
356- https://nuxt.com/docs/api/composables/use-lazy-fetch
357-->
358