ads-fe 0.0.1

package/skills/nuxt/references/features-composables.md

@@ -0,0 +1,276 @@
+---
+name: composables-auto-imports
+description: Auto-imported Vue APIs, Nuxt composables, and custom utilities
+---
+
+# Composables Auto-imports
+
+Nuxt automatically imports Vue APIs, Nuxt composables, and your custom composables/utilities.
+
+## Built-in Auto-imports
+
+### Vue APIs
+
+```vue
+<script setup lang="ts">
+// No imports needed - all auto-imported
+const count = ref(0)
+const doubled = computed(() => count.value * 2)
+
+watch(count, (newVal) => {
+  console.log('Count changed:', newVal)
+})
+
+onMounted(() => {
+  console.log('Component mounted')
+})
+
+// Lifecycle hooks
+onBeforeMount(() => {})
+onUnmounted(() => {})
+onBeforeUnmount(() => {})
+
+// Reactivity
+const state = reactive({ name: 'John' })
+const shallow = shallowRef({ deep: 'object' })
+</script>
+```
+
+### Nuxt Composables
+
+```vue
+<script setup lang="ts">
+// All auto-imported
+const route = useRoute()
+const router = useRouter()
+const config = useRuntimeConfig()
+const appConfig = useAppConfig()
+const nuxtApp = useNuxtApp()
+
+// Data fetching
+const { data } = await useFetch('/api/data')
+const { data: asyncData } = await useAsyncData('key', () => fetchData())
+
+// State
+const state = useState('key', () => 'initial')
+const cookie = useCookie('token')
+
+// Head/SEO
+useHead({ title: 'My Page' })
+useSeoMeta({ description: 'Page description' })
+
+// Request helpers (SSR)
+const headers = useRequestHeaders()
+const event = useRequestEvent()
+const url = useRequestURL()
+</script>
+```
+
+## Custom Composables (`app/composables/`)
+
+### Creating Composables
+
+```ts
+// composables/useCounter.ts
+export function useCounter(initial = 0) {
+  const count = ref(initial)
+  const increment = () => count.value++
+  const decrement = () => count.value--
+  return { count, increment, decrement }
+}
+```
+
+```ts
+// composables/useAuth.ts
+export function useAuth() {
+  const user = useState<User | null>('user', () => null)
+  const isLoggedIn = computed(() => !!user.value)
+
+  async function login(credentials: Credentials) {
+    user.value = await $fetch('/api/auth/login', {
+      method: 'POST',
+      body: credentials,
+    })
+  }
+
+  async function logout() {
+    await $fetch('/api/auth/logout', { method: 'POST' })
+    user.value = null
+  }
+
+  return { user, isLoggedIn, login, logout }
+}
+```
+
+### Using Composables
+
+```vue
+<script setup lang="ts">
+// Auto-imported - no import statement needed
+const { count, increment } = useCounter(10)
+const { user, isLoggedIn, login } = useAuth()
+</script>
+```
+
+### File Scanning Rules
+
+Only top-level files are scanned:
+
+```
+composables/
+├── useAuth.ts         → useAuth() ✓
+├── useCounter.ts      → useCounter() ✓
+├── index.ts           → exports ✓
+└── nested/
+    └── helper.ts      → NOT auto-imported ✗
+```
+
+Re-export nested composables:
+
+```ts
+// composables/index.ts
+export { useHelper } from './nested/helper'
+```
+
+Or configure scanning:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  imports: {
+    dirs: [
+      'composables',
+      'composables/**', // Scan all nested
+    ],
+  },
+})
+```
+
+## Utilities (`app/utils/`)
+
+```ts
+// utils/format.ts
+export function formatDate(date: Date) {
+  return date.toLocaleDateString()
+}
+
+export function formatCurrency(amount: number) {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+  }).format(amount)
+}
+```
+
+```vue
+<script setup lang="ts">
+// Auto-imported
+const date = formatDate(new Date())
+const price = formatCurrency(99.99)
+</script>
+```
+
+## Server Utils (`server/utils/`)
+
+```ts
+// server/utils/db.ts
+export function useDb() {
+  return createDbConnection()
+}
+
+// server/utils/auth.ts
+export function verifyToken(token: string) {
+  return jwt.verify(token, process.env.JWT_SECRET)
+}
+```
+
+```ts
+// server/api/users.ts
+export default defineEventHandler(() => {
+  const db = useDb() // Auto-imported
+  return db.query('SELECT * FROM users')
+})
+```
+
+## Third-party Package Imports
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  imports: {
+    presets: [
+      {
+        from: 'vue-i18n',
+        imports: ['useI18n'],
+      },
+      {
+        from: 'date-fns',
+        imports: ['format', 'parseISO', 'differenceInDays'],
+      },
+      {
+        from: '@vueuse/core',
+        imports: ['useMouse', 'useWindowSize'],
+      },
+    ],
+  },
+})
+```
+
+## Explicit Imports
+
+Use `#imports` alias when needed:
+
+```vue
+<script setup lang="ts">
+import { ref, computed, useFetch } from '#imports'
+</script>
+```
+
+## Composable Context Rules
+
+Nuxt composables must be called in valid context:
+
+```ts
+// ❌ Wrong - module level
+const config = useRuntimeConfig()
+
+export function useMyComposable() {}
+```
+
+```ts
+// ✅ Correct - inside function
+export function useMyComposable() {
+  const config = useRuntimeConfig()
+  return { apiBase: config.public.apiBase }
+}
+```
+
+**Valid contexts:**
+- `<script setup>` block
+- `setup()` function
+- `defineNuxtPlugin()` callback
+- `defineNuxtRouteMiddleware()` callback
+
+## Disabling Auto-imports
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  // Disable all auto-imports
+  imports: {
+    autoImport: false,
+  },
+
+  // Or disable only directory scanning (keep Vue/Nuxt imports)
+  imports: {
+    scan: false,
+  },
+})
+```
+
+<!-- 
+Source references:
+- https://nuxt.com/docs/guide/concepts/auto-imports
+- https://nuxt.com/docs/directory-structure/app/composables
+- https://nuxt.com/docs/directory-structure/app/utils
+-->

package/skills/nuxt/references/features-server.md

@@ -0,0 +1,265 @@
+---
+name: server-routes
+description: API routes, server middleware, and Nitro server engine in Nuxt
+---
+
+# Server Routes
+
+Nuxt includes Nitro server engine for building full-stack applications with API routes and server middleware.
+
+## API Routes
+
+Create files in `server/api/` directory:
+
+```ts
+// server/api/hello.ts
+export default defineEventHandler((event) => {
+  return { message: 'Hello World' }
+})
+```
+
+Access at `/api/hello`.
+
+### HTTP Methods
+
+```ts
+// server/api/users.get.ts - GET /api/users
+export default defineEventHandler(() => {
+  return getUsers()
+})
+
+// server/api/users.post.ts - POST /api/users
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event)
+  return createUser(body)
+})
+
+// server/api/users/[id].put.ts - PUT /api/users/:id
+export default defineEventHandler(async (event) => {
+  const id = getRouterParam(event, 'id')
+  const body = await readBody(event)
+  return updateUser(id, body)
+})
+
+// server/api/users/[id].delete.ts - DELETE /api/users/:id
+export default defineEventHandler((event) => {
+  const id = getRouterParam(event, 'id')
+  return deleteUser(id)
+})
+```
+
+### Route Parameters
+
+```ts
+// server/api/posts/[id].ts
+export default defineEventHandler((event) => {
+  const id = getRouterParam(event, 'id')
+  return getPost(id)
+})
+
+// Catch-all: server/api/[...path].ts
+export default defineEventHandler((event) => {
+  const path = getRouterParam(event, 'path')
+  return { path }
+})
+```
+
+### Query Parameters
+
+```ts
+// server/api/search.ts
+// GET /api/search?q=nuxt&page=1
+export default defineEventHandler((event) => {
+  const query = getQuery(event)
+  // { q: 'nuxt', page: '1' }
+  return search(query.q, Number(query.page))
+})
+```
+
+### Request Body
+
+```ts
+// server/api/submit.post.ts
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event)
+  // Validate and process body
+  return { success: true, data: body }
+})
+```
+
+### Headers and Cookies
+
+```ts
+// server/api/auth.ts
+export default defineEventHandler((event) => {
+  // Read headers
+  const auth = getHeader(event, 'authorization')
+
+  // Read cookies
+  const cookies = parseCookies(event)
+  const token = getCookie(event, 'token')
+
+  // Set headers
+  setHeader(event, 'X-Custom-Header', 'value')
+
+  // Set cookies
+  setCookie(event, 'token', 'new-token', {
+    httpOnly: true,
+    secure: true,
+    maxAge: 60 * 60 * 24, // 1 day
+  })
+
+  return { authenticated: !!token }
+})
+```
+
+## Server Middleware
+
+Runs on every request before routes:
+
+```ts
+// server/middleware/auth.ts
+export default defineEventHandler((event) => {
+  const token = getCookie(event, 'token')
+
+  // Attach data to event context
+  event.context.user = token ? verifyToken(token) : null
+})
+
+// server/middleware/log.ts
+export default defineEventHandler((event) => {
+  console.log(`${event.method} ${event.path}`)
+})
+```
+
+Access context in routes:
+
+```ts
+// server/api/profile.ts
+export default defineEventHandler((event) => {
+  const user = event.context.user
+  if (!user) {
+    throw createError({ statusCode: 401, message: 'Unauthorized' })
+  }
+  return user
+})
+```
+
+## Error Handling
+
+```ts
+// server/api/users/[id].ts
+export default defineEventHandler((event) => {
+  const id = getRouterParam(event, 'id')
+  const user = findUser(id)
+
+  if (!user) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'User not found',
+    })
+  }
+
+  return user
+})
+```
+
+## Server Utils
+
+Auto-imported in `server/utils/`:
+
+```ts
+// server/utils/db.ts
+export function useDb() {
+  return createDbConnection()
+}
+```
+
+```ts
+// server/api/users.ts
+export default defineEventHandler(() => {
+  const db = useDb() // Auto-imported
+  return db.query('SELECT * FROM users')
+})
+```
+
+## Server Plugins
+
+Run once when server starts:
+
+```ts
+// server/plugins/db.ts
+export default defineNitroPlugin((nitroApp) => {
+  // Initialize database connection
+  const db = createDbConnection()
+
+  // Add to context
+  nitroApp.hooks.hook('request', (event) => {
+    event.context.db = db
+  })
+})
+```
+
+## Streaming Responses
+
+```ts
+// server/api/stream.ts
+export default defineEventHandler((event) => {
+  setHeader(event, 'Content-Type', 'text/event-stream')
+  setHeader(event, 'Cache-Control', 'no-cache')
+  setHeader(event, 'Connection', 'keep-alive')
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      for (let i = 0; i < 10; i++) {
+        controller.enqueue(`data: ${JSON.stringify({ count: i })}\n\n`)
+        await new Promise(r => setTimeout(r, 1000))
+      }
+      controller.close()
+    },
+  })
+
+  return stream
+})
+```
+
+## Server Storage
+
+Key-value storage with multiple drivers:
+
+```ts
+// server/api/cache.ts
+export default defineEventHandler(async (event) => {
+  const storage = useStorage()
+
+  // Set value
+  await storage.setItem('key', { data: 'value' })
+
+  // Get value
+  const data = await storage.getItem('key')
+
+  return data
+})
+```
+
+Configure storage drivers in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  nitro: {
+    storage: {
+      redis: {
+        driver: 'redis',
+        url: 'redis://localhost:6379',
+      },
+    },
+  },
+})
+```
+
+<!-- 
+Source references:
+- https://nuxt.com/docs/getting-started/server
+- https://nuxt.com/docs/directory-structure/server
+- https://nitro.build/guide
+-->

package/skills/nuxt/references/features-state.md

@@ -0,0 +1,194 @@
+---
+name: state-management
+description: useState composable and SSR-friendly state management in Nuxt
+---
+
+# State Management
+
+Nuxt provides `useState` for SSR-friendly reactive state that persists across components.
+
+## useState
+
+SSR-safe replacement for `ref` that shares state across components:
+
+```vue
+<script setup lang="ts">
+// State is shared by key 'counter' across all components
+const counter = useState('counter', () => 0)
+</script>
+
+<template>
+  <div>
+    Counter: {{ counter }}
+    <button @click="counter++">+</button>
+    <button @click="counter--">-</button>
+  </div>
+</template>
+```
+
+## Creating Shared State
+
+Define reusable state composables:
+
+```ts
+// composables/useUser.ts
+export function useUser() {
+  return useState<User | null>('user', () => null)
+}
+
+export function useLocale() {
+  return useState('locale', () => 'en')
+}
+```
+
+```vue
+<script setup lang="ts">
+// Same state instance everywhere
+const user = useUser()
+const locale = useLocale()
+</script>
+```
+
+## Initializing State
+
+Use `callOnce` to initialize state with async data:
+
+```vue
+<script setup lang="ts">
+const config = useState('site-config')
+
+await callOnce(async () => {
+  config.value = await $fetch('/api/config')
+})
+</script>
+```
+
+## Best Practices
+
+### ❌ Don't Define State Outside Setup
+
+```ts
+// ❌ Wrong - causes memory leaks and shared state across requests
+export const globalState = ref({ user: null })
+```
+
+### ✅ Use useState Instead
+
+```ts
+// ✅ Correct - SSR-safe
+export const useGlobalState = () => useState('global', () => ({ user: null }))
+```
+
+## Clearing State
+
+```ts
+// Clear specific state
+clearNuxtState('counter')
+
+// Clear multiple states
+clearNuxtState(['counter', 'user'])
+
+// Clear all state (use with caution)
+clearNuxtState()
+```
+
+## With Pinia
+
+For complex state management, use Pinia:
+
+```bash
+npx nuxi module add pinia
+```
+
+```ts
+// stores/counter.ts
+export const useCounterStore = defineStore('counter', {
+  state: () => ({
+    count: 0,
+  }),
+  actions: {
+    increment() {
+      this.count++
+    },
+  },
+})
+```
+
+```ts
+// stores/user.ts (Composition API style)
+export const useUserStore = defineStore('user', () => {
+  const user = ref<User | null>(null)
+  const isLoggedIn = computed(() => !!user.value)
+
+  async function login(credentials: Credentials) {
+    user.value = await $fetch('/api/login', {
+      method: 'POST',
+      body: credentials,
+    })
+  }
+
+  return { user, isLoggedIn, login }
+})
+```
+
+```vue
+<script setup lang="ts">
+const counterStore = useCounterStore()
+const userStore = useUserStore()
+
+// Initialize store data once
+await callOnce(async () => {
+  await userStore.fetchUser()
+})
+</script>
+```
+
+## Advanced: Locale Example
+
+```ts
+// composables/useLocale.ts
+export function useLocale() {
+  return useState('locale', () => useDefaultLocale().value)
+}
+
+export function useDefaultLocale(fallback = 'en-US') {
+  const locale = ref(fallback)
+
+  if (import.meta.server) {
+    const reqLocale = useRequestHeaders()['accept-language']?.split(',')[0]
+    if (reqLocale) locale.value = reqLocale
+  }
+  else if (import.meta.client) {
+    const navLang = navigator.language
+    if (navLang) locale.value = navLang
+  }
+
+  return locale
+}
+```
+
+## State Serialization
+
+`useState` values are serialized to JSON. Avoid:
+
+- Functions
+- Classes
+- Symbols
+- Circular references
+
+```ts
+// ❌ Won't work
+useState('fn', () => () => console.log('hi'))
+useState('instance', () => new MyClass())
+
+// ✅ Works
+useState('data', () => ({ name: 'John', age: 30 }))
+useState('items', () => ['a', 'b', 'c'])
+```
+
+<!-- 
+Source references:
+- https://nuxt.com/docs/getting-started/state-management
+- https://nuxt.com/docs/api/composables/use-state
+- https://nuxt.com/docs/api/utils/clear-nuxt-state
+-->