Nuxt 4: $fetch, useFetch y useAsyncData - Guía Completa de Obtención de Datos

// app/pages/posts.vue
<script setup lang="ts">
  // Se encarga de hacer la solicitud una vez (en el servidor) y transferir el estado.
  const { data: posts } = await useFetch('/api/posts')
</script>

// pages/dashboard.vue
<script setup lang="ts">
// Carga optimizada con manejo de estado detallado
const {
  data: dashboard,
  pending,
  error,
  refresh
} = await useAsyncData('dashboard', async () => {
  // Llamadas paralelas para mejor rendimiento
  const [user, stats, notifications] = await Promise.all([
    $fetch('/api/user/profile'),
    $fetch('/api/analytics/stats'),
    $fetch('/api/notifications/unread')
  ])

  return {
    user,
    stats,
    notifications
  }
}, {
  // Opciones avanzadas
  server: true,        // Ejecutar en servidor
  lazy: false,         // Esperar antes de renderizar
  default: () => ({    // Valor por defecto mientras carga
    user: null,
    stats: { views: 0, users: 0 },
    notifications: []
  })
})

// Refresco manual con debouncing
const debouncedRefresh = useDebounceFn(refresh, 300)

// Watch para refrescar automáticamente
watch(() => route.path, debouncedRefresh)
</script>

// components/ContactForm.vue
<script setup lang="ts">
const formData = ref({
  name: '',
  email: '',
  message: ''
})

const isSubmitting = ref(false)
const submitError = ref<string | null>(null)

async function submitForm() {
  isSubmitting.value = true
  submitError.value = null

  try {
    const response = await $fetch('/api/contact', {
      method: 'POST',
      body: formData.value,
      // Opciones adicionales
      timeout: 10000,
      retry: 2,
      retryDelay: 1000
    })

    // Manejo exitoso
    await navigateTo('/thank-you')
  } catch (error) {
    if (error.data?.message) {
      submitError.value = error.data.message
    } else {
      submitError.value = 'Error al enviar el formulario. Inténtalo nuevamente.'
    }
  } finally {
    isSubmitting.value = false
  }
}
</script>

// pages/products/[id].vue
<script setup lang="ts">
interface Product {
  id: number
  name: string
  price: number
  description: string
  category: string
}

interface ProductWithDetails extends Product {
  formattedPrice: string
  isInStock: boolean
  relatedProducts: Product[]
}

const { data: product, pending } = await useFetch<ProductWithDetails>(
  `/api/products/${route.params.id}`,
  {
    // Transformación de datos
    transform: (data: Product) => ({
      ...data,
      formattedPrice: new Intl.NumberFormat('es-MX', {
        style: 'currency',
        currency: 'MXN'
      }).format(data.price),
      isInStock: data.price > 0,
      relatedProducts: [] // Se llenará después
    }),
    // Caching avanzado
    server: true,
    key: `product-${route.params.id}`,
    // Opciones de caché
    getCachedData: (key) => {
      // Lógica de caché personalizada
      return nuxtApp.staticData[key] || nuxtApp.payload.data[key]
    }
  }
)

// Cargar productos relacionados después
watchEffect(async () => {
  if (product.value?.category) {
    const { data: related } = await $fetch<Product[]>(`/api/products/related/${product.value.category}`)
    product.value.relatedProducts = related
  }
})
</script>

// ✅ Buenas prácticas de keying
const { data } = await useAsyncData(`user-${userId}`, () => $fetch(`/api/users/${userId}`));

// Para datos dependientes de múltiples parámetros
const { data } = await useAsyncData(`search-${searchTerm}-${page}-${category}`, () =>
	$fetch("/api/search", {
		query: { q: searchTerm, page, category }
	})
);

// components/DataLoader.vue
<script setup lang="ts">
interface AsyncDataState<T> {
  data: Ref<T | null>
  pending: Ref<boolean>
  error: Ref<Error | null>
  refresh: () => Promise<void>
}

// Composable reusable
function useAsyncDataWithState<T>(
  key: string,
  handler: () => Promise<T>
): AsyncDataState<T> {
  const { data, pending, error, refresh } = useAsyncData(key, handler)

  return {
    data,
    pending,
    error,
    refresh
  }
}

// Uso en componente
const { data: posts, pending, error } = useAsyncDataWithState(
  'posts',
  () => $fetch('/api/posts')
)
</script>

<template>
  <div>
    <div v-if="pending" class="loading">
      Cargando posts...
    </div>

    <div v-else-if="error" class="error">
      Error: {{ error.message }}
      <button @click="refresh">Reintentar</button>
    </div>

    <div v-else-if="data" class="posts">
      <PostCard
        v-for="post in data"
        :key="post.id"
        :post="post"
      />
    </div>
  </div>
</template>

// Para datos no críticos que pueden cargar después
const { data: comments } = await useLazyFetch(`/api/posts/${postId}/comments`, {
	server: false, // Solo en cliente
	lazy: true // No bloquear renderizado
});

// Para datos que se actualizan frecuentemente
const { data: liveScore } = await useFetch("/api/live-score", {
	server: false,
	refresh: {
		// Refrescar cada 30 segundos
		interval: 30000
	}
});

// En Nuxt 4, esto es shallowRef por defecto
const { data } = await useAsyncData("large-dataset", () => $fetch("/api/large-dataset"));

// Si necesitas reactividad profunda (úselo con precaución)
const { data } = await useAsyncData("deep-reactive", () => $fetch("/api/nested-data"), {
	deep: true // Activa reactividad profunda
});

// Cache a nivel de componente
const { data } = await useFetch("/api/config", {
	key: "app-config",
	// Cache por 5 minutos
	server: true,
	transform: data => {
		// Los datos permanecerán en caché
		return data;
	}
});

// Cache condicional
const { data } = await useFetch("/api/user-preferences", {
	key: `user-prefs-${userId}`,
	server: false,
	// Solo cachear si no hay errores
	getCachedData: key => {
		const cached = nuxtApp.staticData[key] || nuxtApp.payload.data[key];
		return cached && !cached.error ? cached : null;
	}
});

// types/api.ts
export interface User {
  id: number
  name: string
  email: string
  avatar?: string
}

export interface ApiResponse<T> {
  data: T
  message: string
  success: boolean
}

// pages/users/[id].vue
<script setup lang="ts">
const route = useRoute()
const { data: user } = await useFetch<ApiResponse<User>>(`/api/users/${route.params.id}`)

// Acceso tipado seguro
if (user.value?.data) {
  console.log(user.value.data.name) // TypeScript conoce el tipo
}
</script>

// composables/useDashboard.ts
export interface DashboardData {
	user: User;
	stats: {
		views: number;
		clicks: number;
		conversions: number;
	};
	recentActivity: Activity[];
}

export function useDashboardData() {
	return useAsyncData<DashboardData>("dashboard", async () => {
		const [userResponse, statsResponse, activityResponse] = await Promise.all([$fetch<ApiResponse<User>>("/api/user/profile"), $fetch<ApiResponse<Stats>>("/api/analytics/stats"), $fetch<ApiResponse<Activity[]>>("/api/activity/recent")]);

		return {
			user: userResponse.data,
			stats: statsResponse.data,
			recentActivity: activityResponse.data
		};
	});
}

// Habilitar modo debug en desarrollo
const { data } = await useFetch("/api/debug-example", {
	// Muestra información de depuración en consola
	onRequestError({ request, error }) {
		console.error("Request error:", { request, error });
	},
	onResponseError({ response }) {
		console.error("Response error:", response.status, response.statusText);
	},
	onResponse({ response }) {
		console.log("Response received:", response._data);
	}
});

// Composable para medir performance
function useTrackedFetch<T>(url: string, options = {}) {
	const startTime = Date.now();

	return useFetch<T>(url, {
		...options,
		onResponse() {
			const duration = Date.now() - startTime;
			console.log(`Fetch to ${url} took ${duration}ms`);

			// Enviar a analytics si es lento
			if (duration > 1000) {
				$fetch("/api/analytics/slow-request", {
					method: "POST",
					body: { url, duration }
				});
			}
		}
	});
}