ads-fe 0.0.1

package/skills/nuxt/references/best-practices-data-fetching.md

@@ -0,0 +1,357 @@
+---
+name: data-fetching-best-practices
+description: Patterns and best practices for efficient data fetching in Nuxt
+---
+
+# Data Fetching Best Practices
+
+Effective data fetching patterns for SSR-friendly, performant Nuxt applications.
+
+## Choose the Right Tool
+
+| Scenario | Use |
+|----------|-----|
+| Component initial data | `useFetch` or `useAsyncData` |
+| User interactions (clicks, forms) | `$fetch` |
+| Third-party SDK/API | `useAsyncData` with custom function |
+| Multiple parallel requests | `useAsyncData` with `Promise.all` |
+
+## Await vs Non-Await Usage
+
+The `await` keyword controls whether data fetching **blocks navigation**:
+
+### With `await` - Blocking Navigation
+
+```vue
+<script setup lang="ts">
+// Navigation waits until data is fetched (uses Vue Suspense)
+const { data } = await useFetch('/api/posts')
+// data.value is available immediately after this line
+</script>
+```
+
+- **Server**: Fetches data and includes it in the payload
+- **Client hydration**: Uses payload data, no re-fetch
+- **Client navigation**: Blocks until data is ready
+
+### Without `await` - Non-Blocking (Lazy)
+
+```vue
+<script setup lang="ts">
+// Navigation proceeds immediately, data fetches in background
+const { data, status } = useFetch('/api/posts', { lazy: true })
+// data.value may be undefined initially - check status!
+</script>
+
+<template>
+  <div v-if="status === 'pending'">Loading...</div>
+  <div v-else>{{ data }}</div>
+</template>
+```
+
+Equivalent to using `useLazyFetch`:
+
+```vue
+<script setup lang="ts">
+const { data, status } = useLazyFetch('/api/posts')
+</script>
+```
+
+### When to Use Each
+
+| Pattern | Use Case |
+|---------|----------|
+| `await useFetch()` | Critical data needed for SEO/initial render |
+| `useFetch({ lazy: true })` | Non-critical data, better perceived performance |
+| `await useLazyFetch()` | Same as lazy, await only ensures initialization |
+
+## Avoid Double Fetching
+
+### ❌ Wrong: Using $fetch Alone in Setup
+
+```vue
+<script setup lang="ts">
+// This fetches TWICE: once on server, once on client
+const data = await $fetch('/api/posts')
+</script>
+```
+
+### ✅ Correct: Use useFetch
+
+```vue
+<script setup lang="ts">
+// Fetches on server, hydrates on client (no double fetch)
+const { data } = await useFetch('/api/posts')
+</script>
+```
+
+## Use Explicit Cache Keys
+
+### ❌ Avoid: Auto-generated Keys
+
+```vue
+<script setup lang="ts">
+// Key is auto-generated from file/line - can cause issues
+const { data } = await useAsyncData(() => fetchPosts())
+</script>
+```
+
+### ✅ Better: Explicit Keys
+
+```vue
+<script setup lang="ts">
+// Explicit key for predictable caching
+const { data } = await useAsyncData(
+  'posts',
+  () => fetchPosts(),
+)
+
+// Dynamic keys for parameterized data
+const route = useRoute()
+const { data: post } = await useAsyncData(
+  `post-${route.params.id}`,
+  () => fetchPost(route.params.id),
+)
+</script>
+```
+
+## Handle Loading States Properly
+
+```vue
+<script setup lang="ts">
+const { data, status, error } = await useFetch('/api/posts')
+</script>
+
+<template>
+  <div v-if="status === 'pending'">
+    <SkeletonLoader />
+  </div>
+  <div v-else-if="error">
+    <ErrorMessage :error="error" />
+  </div>
+  <div v-else>
+    <PostList :posts="data" />
+  </div>
+</template>
+```
+
+## Use Lazy Fetching for Non-critical Data
+
+```vue
+<script setup lang="ts">
+const id = useRoute().params.id
+
+// Critical data - blocks navigation
+const { data: post } = await useFetch(`/api/posts/${id}`)
+
+// Non-critical data - doesn't block navigation
+const { data: comments, status } = useFetch(`/api/posts/${id}/comments`, {
+  lazy: true,
+})
+
+// Or use useLazyFetch
+const { data: related } = useLazyFetch(`/api/posts/${id}/related`)
+</script>
+
+<template>
+  <article>
+    <h1>{{ post?.title }}</h1>
+    <p>{{ post?.content }}</p>
+  </article>
+
+  <section v-if="status === 'pending'">Loading comments...</section>
+  <CommentList v-else :comments="comments" />
+</template>
+```
+
+## Minimize Payload Size
+
+### Use `pick` for Simple Filtering
+
+```vue
+<script setup lang="ts">
+const { data } = await useFetch('/api/users', {
+  // Only include these fields in payload
+  pick: ['id', 'name', 'avatar'],
+})
+</script>
+```
+
+### Use `transform` for Complex Transformations
+
+```vue
+<script setup lang="ts">
+const { data } = await useFetch('/api/posts', {
+  transform: (posts) => {
+    return posts.map(post => ({
+      id: post.id,
+      title: post.title,
+      excerpt: post.content.slice(0, 100),
+      date: new Date(post.createdAt).toLocaleDateString(),
+    }))
+  },
+})
+</script>
+```
+
+## Parallel Fetching
+
+### Fetch Independent Data with useAsyncData
+
+```vue
+<script setup lang="ts">
+const { data } = await useAsyncData(
+  'dashboard',
+  async (_nuxtApp, { signal }) => {
+    const [user, posts, stats] = await Promise.all([
+      $fetch('/api/user', { signal }),
+      $fetch('/api/posts', { signal }),
+      $fetch('/api/stats', { signal }),
+    ])
+    return { user, posts, stats }
+  },
+)
+</script>
+```
+
+### Multiple useFetch Calls
+
+```vue
+<script setup lang="ts">
+// These run in parallel automatically
+const [{ data: user }, { data: posts }] = await Promise.all([
+  useFetch('/api/user'),
+  useFetch('/api/posts'),
+])
+</script>
+```
+
+## Efficient Refresh Patterns
+
+### Watch Reactive Dependencies
+
+```vue
+<script setup lang="ts">
+const page = ref(1)
+const category = ref('all')
+
+const { data } = await useFetch('/api/posts', {
+  query: { page, category },
+  // Auto-refresh when these change
+  watch: [page, category],
+})
+</script>
+```
+
+### Manual Refresh
+
+```vue
+<script setup lang="ts">
+const { data, refresh, status } = await useFetch('/api/posts')
+
+async function refreshPosts() {
+  await refresh()
+}
+</script>
+```
+
+### Conditional Fetching
+
+```vue
+<script setup lang="ts">
+const userId = ref<string | null>(null)
+
+const { data, execute } = useFetch(() => `/api/users/${userId.value}`, {
+  immediate: false, // Don't fetch until userId is set
+})
+
+// Later, when userId is available
+function loadUser(id: string) {
+  userId.value = id
+  execute()
+}
+</script>
+```
+
+## Server-only Fetching
+
+```vue
+<script setup lang="ts">
+// Only fetch on server, skip on client navigation
+const { data } = await useFetch('/api/static-content', {
+  server: true,
+  lazy: true,
+  getCachedData: (key, nuxtApp) => nuxtApp.payload.data[key],
+})
+</script>
+```
+
+## Error Handling
+
+```vue
+<script setup lang="ts">
+const { data, error, refresh } = await useFetch('/api/posts')
+
+// Watch for errors if need event-like handling
+watch(error, (err) => {
+  if (err) {
+    console.error('Fetch failed:', err)
+    // Show toast, redirect, etc.
+  }
+}, { immediate: true })
+</script>
+
+<template>
+  <div v-if="error">
+    <p>Failed to load: {{ error.message }}</p>
+    <button @click="refresh()">Retry</button>
+  </div>
+</template>
+```
+
+## Shared Data Across Components
+
+```vue
+<!-- ComponentA.vue -->
+<script setup lang="ts">
+const { data } = await useFetch('/api/user', { key: 'current-user' })
+</script>
+
+<!-- ComponentB.vue -->
+<script setup lang="ts">
+// Access cached data without refetching
+const { data: user } = useNuxtData('current-user')
+
+// Or refresh it
+const { refresh } = await useFetch('/api/user', { key: 'current-user' })
+</script>
+```
+
+## Avoid useAsyncData for Side Effects
+
+### ❌ Wrong: Side Effects in useAsyncData
+
+```vue
+<script setup lang="ts">
+// Don't trigger Pinia actions or side effects
+await useAsyncData(() => store.fetchUser()) // Can cause issues
+</script>
+```
+
+### ✅ Correct: Use callOnce for Side Effects
+
+```vue
+<script setup lang="ts">
+await callOnce(async () => {
+  await store.fetchUser()
+})
+</script>
+```
+
+<!-- 
+Source references:
+- https://nuxt.com/docs/getting-started/data-fetching
+- https://nuxt.com/docs/api/composables/use-fetch
+- https://nuxt.com/docs/api/composables/use-async-data
+- https://nuxt.com/docs/api/composables/use-lazy-fetch
+-->

package/skills/nuxt/references/best-practices-ssr.md

@@ -0,0 +1,355 @@
+---
+name: ssr-best-practices
+description: Avoiding SSR context leaks, hydration mismatches, and proper composable usage
+---
+
+# SSR Best Practices
+
+Patterns for avoiding common SSR pitfalls: context leaks, hydration mismatches, and composable errors.
+
+## The "Nuxt Instance Unavailable" Error
+
+This error occurs when calling Nuxt composables outside the proper context.
+
+### ❌ Wrong: Composable Outside Setup
+
+```ts
+// composables/bad.ts
+// Called at module level - no Nuxt context!
+const config = useRuntimeConfig()
+
+export function useMyComposable() {
+  return config.public.apiBase
+}
+```
+
+### ✅ Correct: Composable Inside Function
+
+```ts
+// composables/good.ts
+export function useMyComposable() {
+  // Called inside the composable - has context
+  const config = useRuntimeConfig()
+  return config.public.apiBase
+}
+```
+
+### Valid Contexts for Composables
+
+Nuxt composables work in:
+- `<script setup>` blocks
+- `setup()` function
+- `defineNuxtPlugin()` callbacks
+- `defineNuxtRouteMiddleware()` callbacks
+
+```ts
+// ✅ Plugin
+export default defineNuxtPlugin(() => {
+  const config = useRuntimeConfig() // Works
+})
+
+// ✅ Middleware
+export default defineNuxtRouteMiddleware(() => {
+  const route = useRoute() // Works
+})
+```
+
+## Avoid State Leaks Between Requests
+
+### ❌ Wrong: Module-level State
+
+```ts
+// composables/bad.ts
+// This state is SHARED between all requests on server!
+const globalState = ref({ user: null })
+
+export function useUser() {
+  return globalState
+}
+```
+
+### ✅ Correct: Use useState
+
+```ts
+// composables/good.ts
+export function useUser() {
+  // useState creates request-isolated state
+  return useState('user', () => ({ user: null }))
+}
+```
+
+### Why This Matters
+
+On the server, module-level state persists across requests, causing:
+- Data leaking between users
+- Security vulnerabilities
+- Memory leaks
+
+## Hydration Mismatch Prevention
+
+Hydration mismatches occur when server HTML differs from client render.
+
+### ❌ Wrong: Browser APIs in Setup
+
+```vue
+<script setup>
+// localStorage doesn't exist on server!
+const theme = localStorage.getItem('theme') || 'light'
+</script>
+```
+
+### ✅ Correct: Use SSR-safe Alternatives
+
+```vue
+<script setup>
+// useCookie works on both server and client
+const theme = useCookie('theme', { default: () => 'light' })
+</script>
+```
+
+### ❌ Wrong: Random/Time-based Values
+
+```vue
+<template>
+  <div>{{ Math.random() }}</div>
+  <div>{{ new Date().toLocaleTimeString() }}</div>
+</template>
+```
+
+### ✅ Correct: Use useState for Consistency
+
+```vue
+<script setup>
+// Value is generated once on server, hydrated on client
+const randomValue = useState('random', () => Math.random())
+</script>
+
+<template>
+  <div>{{ randomValue }}</div>
+</template>
+```
+
+### ❌ Wrong: Conditional Rendering on Client State
+
+```vue
+<template>
+  <!-- window doesn't exist on server -->
+  <div v-if="window?.innerWidth > 768">Desktop</div>
+</template>
+```
+
+### ✅ Correct: Use CSS or ClientOnly
+
+```vue
+<template>
+  <!-- CSS media queries work on both -->
+  <div class="hidden md:block">Desktop</div>
+  <div class="md:hidden">Mobile</div>
+
+  <!-- Or use ClientOnly for JS-dependent rendering -->
+  <ClientOnly>
+    <ResponsiveComponent />
+    <template #fallback>Loading...</template>
+  </ClientOnly>
+</template>
+```
+
+## Browser-only Code
+
+### Use `import.meta.client`
+
+```vue
+<script setup>
+if (import.meta.client) {
+  // Only runs in browser
+  window.addEventListener('scroll', handleScroll)
+}
+</script>
+```
+
+### Use `onMounted` for DOM Access
+
+```vue
+<script setup>
+const el = ref<HTMLElement>()
+
+onMounted(() => {
+  // Safe - only runs on client after hydration
+  el.value?.focus()
+  initThirdPartyLib()
+})
+</script>
+```
+
+### Dynamic Imports for Browser Libraries
+
+```vue
+<script setup>
+onMounted(async () => {
+  const { Chart } = await import('chart.js')
+  new Chart(canvas.value, config)
+})
+</script>
+```
+
+## Server-only Code
+
+### Use `import.meta.server`
+
+```vue
+<script setup>
+if (import.meta.server) {
+  // Only runs on server
+  const secrets = useRuntimeConfig().apiSecret
+}
+</script>
+```
+
+### Server Components
+
+```vue
+<!-- components/ServerData.server.vue -->
+<script setup>
+// This entire component only runs on server
+const data = await fetchSensitiveData()
+</script>
+
+<template>
+  <div>{{ data }}</div>
+</template>
+```
+
+## Async Composable Patterns
+
+### ❌ Wrong: Await Before Composable
+
+```vue
+<script setup>
+await someAsyncOperation()
+const route = useRoute() // May fail - context lost after await
+</script>
+```
+
+### ✅ Correct: Get Context First
+
+```vue
+<script setup>
+// Get all composables before any await
+const route = useRoute()
+const config = useRuntimeConfig()
+
+await someAsyncOperation()
+// Now safe to use route and config
+</script>
+```
+
+## Plugin Best Practices
+
+### Client-only Plugins
+
+```ts
+// plugins/analytics.client.ts
+export default defineNuxtPlugin(() => {
+  // Only runs on client
+  initAnalytics()
+})
+```
+
+### Server-only Plugins
+
+```ts
+// plugins/server-init.server.ts
+export default defineNuxtPlugin(() => {
+  // Only runs on server
+  initServerConnections()
+})
+```
+
+### Provide/Inject Pattern
+
+```ts
+// plugins/api.ts
+export default defineNuxtPlugin(() => {
+  const api = createApiClient()
+
+  return {
+    provide: {
+      api,
+    },
+  }
+})
+```
+
+```vue
+<script setup>
+const { $api } = useNuxtApp()
+const data = await $api.get('/users')
+</script>
+```
+
+## Third-party Library Integration
+
+### ❌ Wrong: Import at Top Level
+
+```vue
+<script setup>
+import SomeLibrary from 'browser-only-lib' // Breaks SSR
+</script>
+```
+
+### ✅ Correct: Dynamic Import
+
+```vue
+<script setup>
+let library: typeof import('browser-only-lib')
+
+onMounted(async () => {
+  library = await import('browser-only-lib')
+  library.init()
+})
+</script>
+```
+
+### Use ClientOnly Component
+
+```vue
+<template>
+  <ClientOnly>
+    <BrowserOnlyComponent />
+    <template #fallback>
+      <div class="skeleton">Loading...</div>
+    </template>
+  </ClientOnly>
+</template>
+```
+
+## Debugging SSR Issues
+
+### Check Rendering Context
+
+```vue
+<script setup>
+console.log('Server:', import.meta.server)
+console.log('Client:', import.meta.client)
+</script>
+```
+
+### Use Nuxt DevTools
+
+DevTools shows payload data and hydration state.
+
+### Common Error Messages
+
+| Error | Cause |
+|-------|-------|
+| "Nuxt instance unavailable" | Composable called outside setup context |
+| "Hydration mismatch" | Server/client HTML differs |
+| "window is not defined" | Browser API used during SSR |
+| "document is not defined" | DOM access during SSR |
+
+<!-- 
+Source references:
+- https://nuxt.com/docs/guide/concepts/auto-imports#vue-and-nuxt-composables
+- https://nuxt.com/docs/guide/best-practices/hydration
+- https://nuxt.com/docs/getting-started/state-management#best-practices
+-->