/nuxt-data

name: nuxt-data
description: "| 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."
license: MIT
metadata:
  version: 4.0.0
  author: Claude Skills Maintainers
  category: Framework
  framework: Nuxt
  framework-version: 4.x
  last-verified: 2025-12-28
  keywords:
    - useFetch
    - useAsyncData
    - $fetch
    - useState
    - composables
    - Pinia
    - data fetching
    - state management
    - reactive
    - shallow reactivity
    - reactive keys
    - transform
    - pending
    - error
    - refresh
    - dedupe
    - caching

Nuxt 4 Data Management

Composables, data fetching, and state management patterns for Nuxt 4 applications.

Quick Reference

Data Fetching Methods

| Method | Use Case | SSR | Caching | Reactive | |--------|----------|-----|---------|----------| | `useFetch` | Simple API calls | Yes | Yes | Yes | | `useAsyncData` | Custom async logic | Yes | Yes | Yes | | `$fetch` | Client-side only, events | No | No | No |

Composable Naming

| Prefix | Purpose | Example | |--------|---------|---------| | `use` | State/logic composable | `useAuth`, `useCart` | | `fetch` | Data fetching only | `fetchUsers` (rare) |

When to Load References

**Load `references/composables.md` when:**

• Writing custom composables with complex state
• Debugging state management issues or memory leaks
• Implementing SSR-safe patterns with browser APIs
• Building authentication or complex state composables
• Understanding singleton vs per-call composable patterns

**Load `references/data-fetching.md` when:**

• Implementing API data fetching with reactive parameters
• Troubleshooting shallow vs deep reactivity issues
• Debugging data not refreshing when params change
• Implementing pagination, infinite scroll, or search
• Understanding transform functions, caching, or error handling

**Load `references/pinia-integration.md` when:**

• Setting up Pinia for complex state management
• Creating stores with getters and actions
• Integrating Pinia with SSR
• Persisting state across page reloads

Composables

useState - The Foundation

`useState` creates SSR-safe, shared reactive state that persists across component instances.

// composables/useCounter.ts
export const useCounter = () => {
  // Singleton - shared across all components
  const count = useState('counter', () => 0)

  const increment = () => count.value++
  const decrement = () => count.value--
  const reset = () => count.value = 0

  return { count, increment, decrement, reset }
}

useState vs ref - Critical Distinction

// CORRECT: Shared state (singleton pattern)
export const useAuth = () => {
  const user = useState('auth-user', () => null)  // Shared!
  return { user }
}

// WRONG: Creates new instance every call!
export const useAuth = () => {
  const user = ref(null)  // Not shared!
  return { user }
}

**Rule**: Use `useState` for shared/global state. Use `ref` for local component state only.

Complete Authentication Composable

// composables/useAuth.ts
export const useAuth = () => {
  const user = useState<User | null>('auth-user', () => null)
  const isAuthenticated = computed(() => !!user.value)
  const isLoading = useState('auth-loading', () => false)

  const login = async (email: string, password: string) => {
    isLoading.value = true
    try {
      const data = await $fetch('/api/auth/login', {
        method: 'POST',
        body: { email, password }
      })
      user.value = data.user
      return { success: true }
    } catch (error) {
      return { success: false, error: error.message }
    } finally {
      isLoading.value = false
    }
  }

  const logout = async () => {
    await $fetch('/api/auth/logout', { method: 'POST' })
    user.value = null
    navigateTo('/login')
  }

  const checkSession = async () => {
    if (import.meta.server) return  // Skip on server
    try {
      const data = await $fetch('/api/auth/session')
      user.value = data.user
    } catch {
      user.value = null
    }
  }

  return { user, isAuthenticated, isLoading, login, logout, checkSession }
}

SSR-Safe Browser APIs

// composables/useLocalStorage.ts
export const useLocalStorage = <T>(key: string, defaultValue: T) => {
  const data = useState<T>(key, () => defaultValue)

  // Only access localStorage on client
  if (import.meta.client) {
    const stored = localStorage.getItem(key)
    if (stored) {
      data.value = JSON.parse(stored)
    }

    // Watch and persist changes
    watch(data, (newValue) => {
      localStorage.setItem(key, JSON.stringify(newValue))
    }, { deep: true })
  }

  return data
}

Data Fetching

useFetch - Basic Usage

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

// With options
const { data: users } = await useFetch('/api/users', {
  method: 'GET',
  query: { limit: 10, offset: 0 },
  headers: { 'X-Custom-Header': 'value' }
})

Reactive Parameters

<script setup lang="ts">
const page = ref(1)
const search = ref('')

// Auto-refetches when page or search changes
const { data: users, pending } = await useFetch('/api/users', {
  query: {
    page,
    search,
    limit: 10
  }
})

// Or with computed
const query = computed(() => ({
  page: page.value,
  search: search.value,
  limit: 10
}))

const { data } = await useFetch('/api/users', { query })
</script>

Transform Data

const { data: userNames } = await useFetch('/api/users', {
  transform: (users) => users.map(u => u.name)
})

// data.value is now string[] instead of User[]

Pick Specific Fields

const { data } = await use