Skip to content

secondsky/claude-skills / plugins/nuxt-v4/skills/nuxt-data

nuxt-data

Verified

| Nuxt 4 data management: composables, data fetching with useFetch/useAsyncData, and state management with useState and Pinia. Use when: creating custom composables, fetching data with useFetch or useAsyncData, managing global state with useState, integrating Pinia, debugging reactive data issues, or implementing SSR-safe state patterns.

FileKindSize
SKILL.mdskill md13.3 KB
references/composables.mdmarkdown16.0 KB
references/data-fetching.mdmarkdown15.9 KB
templates/composables/useAuth.tsscript3.0 KB

references/data-fetching.md

View on GitHub
# Data Fetching - Complete Guide

Comprehensive guide to data fetching in Nuxt 4 with useFetch, useAsyncData, and $fetch.

## Table of Contents

- [Method Comparison](#method-comparison)
- [useFetch Deep Dive](#usefetch-deep-dive)
- [useAsyncData Deep Dive](#useasyncdata-deep-dive)
- [$fetch Patterns](#fetch-patterns)
- [Nuxt v4 Changes](#nuxt-v4-changes)
- [Error Handling](#error-handling)
- [Caching Strategies](#caching-strategies)
- [Advanced Patterns](#advanced-patterns)

## Method Comparison

| Feature | useFetch | useAsyncData | $fetch |
|---------|----------|--------------|--------|
| **SSR Support** | ✅ Yes | ✅ Yes | ❌ Client only |
| **Caching** | ✅ Automatic | ✅ Automatic | ❌ No |
| **Reactivity** | ✅ Reactive | ✅ Reactive | ❌ Not reactive |
| **Auto-refresh** | ✅ Yes | ✅ Yes | ❌ No |
| **Use Case** | Simple API calls | Custom logic | Client-side calls |
| **Key Required** | ❌ Optional | ✅ Required | N/A |

### When to Use Each

**useFetch**:
- Simple GET/POST/PUT/DELETE to APIs
- When you want automatic reactivity
- When caching is important
- SSR is needed

**useAsyncData**:
- Multiple API calls in parallel
- Custom async logic
- Complex data transformations
- Conditional data fetching

**$fetch**:
- Client-side only operations
- One-off requests
- Inside event handlers
- No caching needed

## useFetch Deep Dive

### Basic Usage

```typescript
// Simple GET request
const { data, error, pending, refresh, status } = await useFetch('/api/users')

// POST request
const { data } = await useFetch('/api/users', {
  method: 'POST',
  body: { name: 'John', email: 'john@example.com' }
})

// With TypeScript
interface User {
  id: string
  name: string
  email: string
}

const { data } = await useFetch<User[]>('/api/users')
// data is Ref<User[] | null>
```

### Reactive Parameters

**Key Feature in Nuxt v4**: Parameters are reactive by default!

```typescript
// Query params
const page = ref(1)
const limit = ref(10)

const { data } = await useFetch('/api/users', {
  query: {
    page,   // ✅ Auto-refetch when page changes
    limit   // ✅ Auto-refetch when limit changes
  }
})

// Change page → auto-refetch
page.value = 2  // Triggers new fetch

// URL params
const userId = ref('123')

const { data } = await useFetch(() => `/api/users/${userId.value}`)
// ✅ Auto-refetch when userId changes

userId.value = '456'  // Triggers new fetch
```

### Options

```typescript
const { data } = await useFetch('/api/users', {
  // HTTP method
  method: 'POST',

  // Query parameters
  query: { page: 1, limit: 10 },

  // Request body
  body: { name: 'John' },

  // Headers
  headers: {
    'Authorization': 'Bearer token',
    'Content-Type': 'application/json'
  },

  // Base URL (defaults to nuxt app baseURL)
  baseURL: 'https://api.example.com',

  // Transform response (must be deterministic!)
  transform: (data) => data.map(u => ({ id: u.id, name: u.name })),

  // Pick specific fields
  pick: ['id', 'name', 'email'],

  // Watch for changes (reactive)
  watch: [page, limit],

  // Immediate fetch (default: true)
  immediate: true,

  // Lazy (don't block navigation)
  lazy: false,

  // Server-only
  server: true,

  // Client-only
  client: true,

  // Deep reactivity (default: false in v4)
  deep: false,

  // Default value
  default: () => [],

  // Retry on error
  retry: 3,
  retryDelay: 500,

  // Timeout
  timeout: 10000,

  // Credentials
  credentials: 'include',

  // Cache (uses key for caching)
  key: 'users-list',

  // Dedupe (prevent duplicate requests)
  dedupe: 'cancel'  // or 'defer'
})
```

### Return Values

```typescript
const {
  data,      // Ref<T | null> - Response data
  error,     // Ref<Error | null> - Error object
  pending,   // Ref<boolean> - Loading state
  refresh,   // () => Promise<void> - Manual refresh
  execute,   // () => Promise<void> - Execute (for lazy fetch)
  status,    // Ref<'idle' | 'pending' | 'success' | 'error'> - Request status
  clear      // () => void - Clear data and error
} = await useFetch('/api/users')
```

### Transform Function

**Important**: Must be deterministic (same input = same output)!

```typescript
// ✅ Good - deterministic
const { data } = await useFetch('/api/users', {
  transform: (users) => users.map(u => ({
    id: u.id,
    name: u.name.toUpperCase(),
    initials: u.name.split(' ').map(n => n[0]).join('')
  }))
})

// ❌ Bad - non-deterministic
const { data } = await useFetch('/api/users', {
  transform: (users) => users.sort(() => Math.random() - 0.5)
})

// ❌ Bad - side effects
const { data } = await useFetch('/api/users', {
  transform: (users) => {
    console.log('Users loaded')  // Side effect!
    return users
  }
})
```

### Lazy Fetching

```typescript
// Don't block navigation
const { data, pending, execute } = await useFetch('/api/heavy-data', {
  lazy: true
})

// Execute manually when needed
const loadData = async () => {
  await execute()
}
```

### Manual Refresh

```typescript
const { data, refresh } = await useFetch('/api/users')

// Refresh data manually
const reloadUsers = async () => {
  await refresh()
}

// In template
<button @click="refresh">Reload</button>
```

## useAsyncData Deep Dive

### Basic Usage

```typescript
// Key is required!
const { data, error, pending } = await useAsyncData(
  'users',  // Unique key
  () => $fetch('/api/users')
)

// With TypeScript
interface User {
  id: string
  name: string
}

const { data } = await useAsyncData<User[]>(
  'users',
  () => $fetch('/api/users')
)
```

### Multiple API Calls

```typescript
const { data } = await useAsyncData('dashboard', async () => {
  const [users, posts, stats] = await Promise.all([
    $fetch('/api/users'),
    $fetch('/api/posts'),
    $fetch('/api/stats')
  ])

  return { users, posts, stats }
})

// Access data
data.value?.users
data.value?.posts
data.value?.stats
```

### Reactive Keys (Singleton Pattern)

**Nuxt v4 Feature**: Same key shares the same data!

```typescript
// Component A
const { data } = await useAsyncData(
  'app-config',
  () => $fetch('/api/config')
)

// Component B (gets same data!)
const { data: sameData } = await useAsyncData(
  'app-config',
  () => $fetch('/api/config')
)

// data and sameData point to the same ref!
```

### Computed Keys

```typescript
const userId = ref('123')

const { data } = await useAsyncData(
  () => `user-${userId.value}`,  // Reactive key
  () => $fetch(`/api/users/${userId.value}`)
)

// Change userId → new key → new fetch
userId.value = '456'  // Triggers new fetch with new key
```

### Options

```typescript
const { data } = await useAsyncData(
  'users',
  () => $fetch('/api/users'),
  {
    // Watch reactive dependencies
    watch: [page, limit],

    // Transform result
    transform: (data) => data.map(u => ({ id: u.id, name: u.name })),

    // Pick fields
    pick: ['id', 'name'],

    // Server-only
    server: true,

    // Lazy
    lazy: false,

    // Immediate
    immediate: true,

    // Default value
    default: () => [],

    // Deep reactivity
    deep: false,

    // Dedupe
    dedupe: 'cancel'
  }
)
```

### Custom Logic

```typescript
const { data, error } = await useAsyncData('user-posts', async () => {
  // Get user
  const user = await $fetch(`/api/users/${userId.value}`)

  // Get user's posts
  const posts = await $fetch(`/api/posts?userId=${user.id}`)

  // Get comments for each post
  const postsWithComments = await Promise.all(
    posts.map(async (post) => {
      const comments = await $fetch(`/api/comments?postId=${post.id}`)
      return { ...post, comments }
    })
  )

  return {
    user,
    posts: postsWithComments
  }
})
```

## $fetch Patterns

### Client-Side Only

```typescript
// Event handler
const handleSubmit = async () => {
  try {
    const response = await $fetch('/api/users', {
      method: 'POST',
      body: { name: 'John' }
    })

    console.log('User created:', response)
  } catch (error) {
    console.error('Failed:', error)
  }
}

// One-off request
const deleteUser = async (id: string) => {
  await $fetch(`/api/users/${id}`, { method: 'DELETE' })
}
```

### With Options

```typescript
const response = await $fetch('/api/users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token.value}`
  },
  body: { name: 'John', email: 'john@example.com' },
  query: { include: 'profile' },
  baseURL: 'https://api.example.com',
  timeout: 10000,
  retry: 3,
  retryDelay: 500
})
```

### Error Handling

```typescript
try {
  const user = await $fetch(`/api/users/${id}`)
} catch (error) {
  if (error.statusCode === 404) {
    console.error('User not found')
  } else if (error.statusCode === 401) {
    console.error('Unauthorized')
  } else {
    console.error('Unknown error:', error)
  }
}
```

## Nuxt v4 Changes

### Shallow Reactivity (Default)

**Breaking Change**: Default changed from `deep: true` to `deep: false`

```typescript
// Nuxt v4 - Shallow (default)
const { data } = await useFetch('/api/users')

// ✅ This works
data.value = newUsers

// ❌ This doesn't trigger reactivity
data.value[0].name = 'New Name'

// Need deep reactivity? Enable it:
const { data } = await useFetch('/api/users', {
  deep: true
})

// ✅ Now this works
data.value[0].name = 'New Name'
```

### Default Values Changed

**Breaking Change**: Default changed from `null` to `undefined`

```typescript
// Nuxt v3
const { data } = await useFetch('/api/users')
data.value  // null initially

// Nuxt v4
const { data } = await useFetch('/api/users')
data.value  // undefined initially

// Provide default value
const { data } = await useFetch('/api/users', {
  default: () => []
})
data.value  // [] initially
```

### Reactive Keys

New feature - computed/ref keys trigger refetch:

```typescript
const userId = ref('123')

// Nuxt v4 - Auto-refetch
const { data } = await useAsyncData(
  () => `user-${userId.value}`,
  () => $fetch(`/api/users/${userId.value}`)
)

userId.value = '456'  // Auto-refetch!
```

## Error Handling

### Basic Error Handling

```typescript
const { data, error, status } = await useFetch('/api/users')

if (error.value) {
  console.error('Error:', error.value.message)
  console.error('Status code:', error.value.statusCode)
  console.error('Status text:', error.value.statusMessage)
}

// Check status
if (status.value === 'error') {
  // Handle error
}
```

### Structured Error Handling

```typescript
const { data, error } = await useFetch('/api/users')

if (error.value) {
  const { statusCode, statusMessage, message } = error.value

  switch (statusCode) {
    case 400:
      showToast({ type: 'error', message: 'Invalid request' })
      break
    case 401:
      await navigateTo('/login')
      break
    case 403:
      showToast({ type: 'error', message: 'Access denied' })
      break
    case 404:
      showToast({ type: 'error', message: 'Not found' })
      break
    case 500:
      showToast({ type: 'error', message: 'Server error' })
      break
    default:
      showToast({ type: 'error', message: message || 'Unknown error' })
  }
}
```

### Retry on Error

```typescript
const { data } = await useFetch('/api/users', {
  retry: 3,          // Retry up to 3 times
  retryDelay: 500,   // Wait 500ms between retries
  onRequestError({ error }) {
    console.error('Request error:', error)
  },
  onResponseError({ response }) {
    console.error('Response error:', response.status)
  }
})
```

## Caching Strategies

### Automatic Caching

useFetch and useAsyncData cache by key:

```typescript
// First call - fetches from server
const { data } = await useFetch('/api/users', {
  key: 'users-list'
})

// Second call - uses cache
const { data: cachedData } = await useFetch('/api/users', {
  key: 'users-list'  // Same key = same cache
})
```

### Manual Cache Control

```typescript
const { data, refresh, clear } = await useFetch('/api/users')

// Refresh from server
await refresh()

// Clear cache
clear()
```

### Cache Invalidation

```typescript
const { data, refresh } = await useFetch('/api/users', {
  key: 'users-list'
})

// After creating new user
const createUser = async (user: User) => {
  await $fetch('/api/users', {
    method: 'POST',
    body: user
  })

  // Invalidate cache
  await refresh()
}
```

### Server-Side Caching with Route Rules

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/api/users': {
      swr: 3600  // Cache for 1 hour
    }
  }
})
```

## Advanced Patterns

### Infinite Scroll

```typescript
const page = ref(1)
const allUsers = ref<User[]>([])
const hasMore = ref(true)

const { data, pending, refresh } = await useFetch(() => `/api/users?page=${page.value}`)

watch(data, (newData) => {
  if (newData) {
    allUsers.value.push(...newData.items)
    hasMore.value = newData.hasNextPage
  }
})

const loadMore = async () => {
  if (hasMore.value && !pending.value) {
    page.value++
    await refresh()
  }
}
```

### Pagination

```typescript
const page = ref(1)
const limit = ref(10)

const { data: paginatedUsers } = await useFetch('/api/users', {
  query: { page, limit }
})

// Navigation
const nextPage = () => page.value++
const prevPage = () => page.value = Math.max(1, page.value - 1)
const goToPage = (p: number) => page.value = p
```

### Optimistic Updates

```typescript
const { data: users, refresh } = await useFetch<User[]>('/api/users')

const deleteUser = async (id: string) => {
  // Optimistic update
  const originalUsers = users.value
  users.value = users.value?.filter(u => u.id !== id) || []

  try {
    await $fetch(`/api/users/${id}`, { method: 'DELETE' })
  } catch (error) {
    // Rollback on error
    users.value = originalUsers
    showToast({ type: 'error', message: 'Failed to delete user' })
  }
}
```

### Dependent Queries

```typescript
const { data: user } = await useFetch(() => `/api/users/${userId.value}`)

// Only fetch posts when user is loaded
const { data: posts } = await useFetch(
  () => user.value ? `/api/posts?userId=${user.value.id}` : null
)
```

### Polling

```typescript
const { data, refresh } = await useFetch('/api/stats')

// Poll every 5 seconds
const intervalId = setInterval(refresh, 5000)

// Cleanup
onUnmounted(() => {
  clearInterval(intervalId)
})
```

### Abort Requests (v4.2)

```typescript
const controller = ref<AbortController>()

const { data } = await useAsyncData(
  'users',
  () => $fetch('/api/users', { signal: controller.value?.signal })
)

// Abort request
const abortRequest = () => {
  controller.value?.abort()
  controller.value = new AbortController()
}
```

### Parallel Requests

```typescript
const { data: dashboard } = await useAsyncData('dashboard', async () => {
  const [users, posts, comments, stats] = await Promise.all([
    $fetch('/api/users'),
    $fetch('/api/posts'),
    $fetch('/api/comments'),
    $fetch('/api/stats')
  ])

  return { users, posts, comments, stats }
})
```

### Sequential Requests (When Order Matters)

```typescript
const { data } = await useAsyncData('user-flow', async () => {
  // Step 1: Get user
  const user = await $fetch(`/api/users/${userId.value}`)

  // Step 2: Get user's team (depends on user)
  const team = await $fetch(`/api/teams/${user.teamId}`)

  // Step 3: Get team members (depends on team)
  const members = await $fetch(`/api/teams/${team.id}/members`)

  return { user, team, members }
})
```

## Best Practices

1. **Use useFetch for simple API calls**, useAsyncData for complex logic
2. **Always handle errors** explicitly
3. **Provide TypeScript types** for better DX
4. **Use reactive parameters** for auto-refetch
5. **Enable deep reactivity** only when needed (performance)
6. **Use unique keys** for caching and deduplication
7. **Provide default values** to avoid undefined/null checks
8. **Transform on server** when possible (better performance)
9. **Cache aggressively** with route rules
10. **Clean up subscriptions** in onUnmounted

## Common Pitfalls

❌ **Non-deterministic transforms**
❌ **Missing error handling**
❌ **Not using TypeScript**
❌ **Forgetting to watch reactive deps**
❌ **Using $fetch in SSR** (won't work!)
❌ **Not providing default values**
❌ **Enabling deep when not needed** (performance hit)
❌ **Missing cleanup** (memory leaks)

---

**Last Updated**: 2025-12-28
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall