ads-fe 0.0.1

package/skills/nuxt/references/core-cli.md

@@ -0,0 +1,263 @@
+---
+name: cli-commands
+description: Nuxt CLI commands for development, building, and project management
+---
+
+# CLI Commands
+
+Nuxt provides CLI commands via `nuxi` (or `npx nuxt`) for development, building, and project management.
+
+## Project Initialization
+
+### Create New Project
+
+```bash
+# Interactive project creation
+npx nuxi@latest init my-app
+
+# With specific package manager
+npx nuxi@latest init my-app --packageManager pnpm
+
+# With modules
+npx nuxi@latest init my-app --modules "@nuxt/ui,@nuxt/image"
+
+# From template
+npx nuxi@latest init my-app --template v3
+
+# Skip module selection prompt
+npx nuxi@latest init my-app --no-modules
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `-t, --template` | Template name |
+| `--packageManager` | npm, pnpm, yarn, or bun |
+| `-M, --modules` | Modules to install (comma-separated) |
+| `--gitInit` | Initialize git repository |
+| `--no-install` | Skip installing dependencies |
+
+## Development
+
+### Start Dev Server
+
+```bash
+# Start development server (default: http://localhost:3000)
+npx nuxt dev
+
+# Custom port
+npx nuxt dev --port 4000
+
+# Open in browser
+npx nuxt dev --open
+
+# Listen on all interfaces (for mobile testing)
+npx nuxt dev --host 0.0.0.0
+
+# With HTTPS
+npx nuxt dev --https
+
+# Clear console on restart
+npx nuxt dev --clear
+
+# Create public tunnel
+npx nuxt dev --tunnel
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `-p, --port` | Port to listen on |
+| `-h, --host` | Host to listen on |
+| `-o, --open` | Open in browser |
+| `--https` | Enable HTTPS |
+| `--tunnel` | Create public tunnel (via untun) |
+| `--qr` | Show QR code for mobile |
+| `--clear` | Clear console on restart |
+
+**Environment Variables:**
+- `NUXT_PORT` or `PORT` - Default port
+- `NUXT_HOST` or `HOST` - Default host
+
+## Building
+
+### Production Build
+
+```bash
+# Build for production
+npx nuxt build
+
+# Build with prerendering
+npx nuxt build --prerender
+
+# Build with specific preset
+npx nuxt build --preset node-server
+npx nuxt build --preset cloudflare-pages
+npx nuxt build --preset vercel
+
+# Build with environment
+npx nuxt build --envName staging
+```
+
+Output is created in `.output/` directory.
+
+### Static Generation
+
+```bash
+# Generate static site (prerenders all routes)
+npx nuxt generate
+```
+
+Equivalent to `nuxt build --prerender`. Creates static HTML files for deployment to static hosting.
+
+### Preview Production Build
+
+```bash
+# Preview after build
+npx nuxt preview
+
+# Custom port
+npx nuxt preview --port 4000
+```
+
+## Utilities
+
+### Prepare (Type Generation)
+
+```bash
+# Generate TypeScript types and .nuxt directory
+npx nuxt prepare
+```
+
+Run after cloning or when types are missing.
+
+### Type Check
+
+```bash
+# Run TypeScript type checking
+npx nuxt typecheck
+```
+
+### Analyze Bundle
+
+```bash
+# Analyze production bundle
+npx nuxt analyze
+```
+
+Opens visual bundle analyzer.
+
+### Cleanup
+
+```bash
+# Remove generated files (.nuxt, .output, node_modules/.cache)
+npx nuxt cleanup
+```
+
+### Info
+
+```bash
+# Show environment info (useful for bug reports)
+npx nuxt info
+```
+
+### Upgrade
+
+```bash
+# Upgrade Nuxt to latest version
+npx nuxt upgrade
+
+# Upgrade to nightly release
+npx nuxt upgrade --nightly
+```
+
+## Module Commands
+
+### Add Module
+
+```bash
+# Add a Nuxt module
+npx nuxt module add @nuxt/ui
+npx nuxt module add @nuxt/image
+```
+
+Installs and adds to `nuxt.config.ts`.
+
+### Build Module (for module authors)
+
+```bash
+# Build a Nuxt module
+npx nuxt build-module
+```
+
+## DevTools
+
+```bash
+# Enable DevTools globally
+npx nuxt devtools enable
+
+# Disable DevTools
+npx nuxt devtools disable
+```
+
+## Common Workflows
+
+### Development
+
+```bash
+# Install dependencies and start dev
+pnpm install
+pnpm dev  # or npx nuxt dev
+```
+
+### Production Deployment
+
+```bash
+# Build and preview locally
+pnpm build
+pnpm preview
+
+# Or for static hosting
+pnpm generate
+```
+
+### After Cloning
+
+```bash
+# Install deps and prepare types
+pnpm install
+npx nuxt prepare
+```
+
+## Environment-specific Builds
+
+```bash
+# Development build
+npx nuxt build --envName development
+
+# Staging build
+npx nuxt build --envName staging
+
+# Production build (default)
+npx nuxt build --envName production
+```
+
+Corresponds to `$development`, `$env.staging`, `$production` in `nuxt.config.ts`.
+
+## Layer Extension
+
+```bash
+# Dev with additional layer
+npx nuxt dev --extends ./base-layer
+
+# Build with layer
+npx nuxt build --extends ./base-layer
+```
+
+<!-- 
+Source references:
+- https://nuxt.com/docs/api/commands/dev
+- https://nuxt.com/docs/api/commands/build
+- https://nuxt.com/docs/api/commands/generate
+- https://nuxt.com/docs/api/commands/init
+-->

package/skills/nuxt/references/core-config.md

@@ -0,0 +1,162 @@
+---
+name: configuration
+description: Nuxt configuration files including nuxt.config.ts, app.config.ts, and runtime configuration
+---
+
+# Nuxt Configuration
+
+Nuxt uses configuration files to customize application behavior. The main configuration options are `nuxt.config.ts` for build-time settings and `app.config.ts` for runtime settings.
+
+## nuxt.config.ts
+
+The main configuration file at the root of your project:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  // Configuration options
+  devtools: { enabled: true },
+  modules: ['@nuxt/ui'],
+})
+```
+
+### Environment Overrides
+
+Configure environment-specific settings:
+
+```ts
+export default defineNuxtConfig({
+  $production: {
+    routeRules: {
+      '/**': { isr: true },
+    },
+  },
+  $development: {
+    // Development-specific config
+  },
+  $env: {
+    staging: {
+      // Staging environment config
+    },
+  },
+})
+```
+
+Use `--envName` flag to select environment: `nuxt build --envName staging`
+
+## Runtime Config
+
+For values that need to be overridden via environment variables:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  runtimeConfig: {
+    // Server-only keys
+    apiSecret: '123',
+    // Keys within public are exposed to client
+    public: {
+      apiBase: '/api',
+    },
+  },
+})
+```
+
+Override with environment variables:
+
+```ini
+# .env
+NUXT_API_SECRET=api_secret_token
+NUXT_PUBLIC_API_BASE=https://api.example.com
+```
+
+Access in components/composables:
+
+```vue
+<script setup lang="ts">
+const config = useRuntimeConfig()
+// Server: config.apiSecret, config.public.apiBase
+// Client: config.public.apiBase only
+</script>
+```
+
+## App Config
+
+For public tokens determined at build time (not overridable via env vars):
+
+```ts
+// app/app.config.ts
+export default defineAppConfig({
+  title: 'Hello Nuxt',
+  theme: {
+    dark: true,
+    colors: {
+      primary: '#ff0000',
+    },
+  },
+})
+```
+
+Access in components:
+
+```vue
+<script setup lang="ts">
+const appConfig = useAppConfig()
+</script>
+```
+
+## runtimeConfig vs app.config
+
+| Feature | runtimeConfig | app.config |
+|---------|--------------|------------|
+| Client-side | Hydrated | Bundled |
+| Environment variables | Yes | No |
+| Reactive | Yes | Yes |
+| Hot module replacement | No | Yes |
+| Non-primitive JS types | No | Yes |
+
+**Use runtimeConfig** for secrets and values that change per environment.
+**Use app.config** for public tokens, theme settings, and non-sensitive config.
+
+## External Tool Configuration
+
+Nuxt uses `nuxt.config.ts` as single source of truth. Configure external tools within it:
+
+```ts
+export default defineNuxtConfig({
+  // Nitro configuration
+  nitro: {
+    // nitro options
+  },
+  // Vite configuration
+  vite: {
+    // vite options
+    vue: {
+      // @vitejs/plugin-vue options
+    },
+  },
+  // PostCSS configuration
+  postcss: {
+    // postcss options
+  },
+})
+```
+
+## Vue Configuration
+
+Enable Vue experimental features:
+
+```ts
+export default defineNuxtConfig({
+  vue: {
+    propsDestructure: true,
+  },
+})
+```
+
+<!-- 
+Source references:
+- https://nuxt.com/docs/getting-started/configuration
+- https://nuxt.com/docs/guide/going-further/runtime-config
+- https://nuxt.com/docs/api/nuxt-config
+-->

package/skills/nuxt/references/core-data-fetching.md

@@ -0,0 +1,236 @@
+---
+name: data-fetching
+description: useFetch, useAsyncData, and $fetch for SSR-friendly data fetching
+---
+
+# Data Fetching
+
+Nuxt provides composables for SSR-friendly data fetching that prevent double-fetching and handle hydration.
+
+## Overview
+
+- `$fetch` - Basic fetch utility (use for client-side events)
+- `useFetch` - SSR-safe wrapper around $fetch (use for component data)
+- `useAsyncData` - SSR-safe wrapper for any async function
+
+## useFetch
+
+Primary composable for fetching data in components:
+
+```vue
+<script setup lang="ts">
+const { data, status, error, refresh, clear } = await useFetch('/api/posts')
+</script>
+
+<template>
+  <div v-if="status === 'pending'">Loading...</div>
+  <div v-else-if="error">Error: {{ error.message }}</div>
+  <div v-else>
+    <article v-for="post in data" :key="post.id">
+      {{ post.title }}
+    </article>
+  </div>
+</template>
+```
+
+### With Options
+
+```ts
+const { data } = await useFetch('/api/posts', {
+  // Query parameters
+  query: { page: 1, limit: 10 },
+  // Request body (for POST/PUT)
+  body: { title: 'New Post' },
+  // HTTP method
+  method: 'POST',
+  // Only pick specific fields
+  pick: ['id', 'title'],
+  // Transform response
+  transform: (posts) => posts.map(p => ({ ...p, slug: slugify(p.title) })),
+  // Custom key for caching
+  key: 'posts-list',
+  // Don't fetch on server
+  server: false,
+  // Don't block navigation
+  lazy: true,
+  // Don't fetch immediately
+  immediate: false,
+  // Default value
+  default: () => [],
+})
+```
+
+### Reactive Parameters
+
+```vue
+<script setup lang="ts">
+const page = ref(1)
+const { data } = await useFetch('/api/posts', {
+  query: { page }, // Automatically refetches when page changes
+})
+</script>
+```
+
+### Computed URL
+
+```vue
+<script setup lang="ts">
+const id = ref(1)
+const { data } = await useFetch(() => `/api/posts/${id.value}`)
+// Refetches when id changes
+</script>
+```
+
+## useAsyncData
+
+For wrapping any async function:
+
+```vue
+<script setup lang="ts">
+const { data, error } = await useAsyncData('user', () => {
+  return myCustomFetch('/user/profile')
+})
+</script>
+```
+
+### Multiple Requests
+
+```vue
+<script setup lang="ts">
+const { data } = await useAsyncData('cart', async () => {
+  const [coupons, offers] = await Promise.all([
+    $fetch('/api/coupons'),
+    $fetch('/api/offers'),
+  ])
+  return { coupons, offers }
+})
+</script>
+```
+
+## $fetch
+
+For client-side events (form submissions, button clicks):
+
+```vue
+<script setup lang="ts">
+async function submitForm() {
+  const result = await $fetch('/api/submit', {
+    method: 'POST',
+    body: { name: 'John' },
+  })
+}
+</script>
+```
+
+**Important**: Don't use `$fetch` alone in setup for initial data - it will fetch twice (server + client). Use `useFetch` or `useAsyncData` instead.
+
+## Return Values
+
+All composables return:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | `Ref<T>` | Fetched data |
+| `error` | `Ref<Error>` | Error if request failed |
+| `status` | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>` | Request status |
+| `refresh` | `() => Promise` | Refetch data |
+| `execute` | `() => Promise` | Alias for refresh |
+| `clear` | `() => void` | Reset data and error |
+
+## Lazy Fetching
+
+Don't block navigation:
+
+```vue
+<script setup lang="ts">
+// Using lazy option
+const { data, status } = await useFetch('/api/posts', { lazy: true })
+
+// Or use lazy variants
+const { data, status } = await useLazyFetch('/api/posts')
+const { data, status } = await useLazyAsyncData('key', fetchFn)
+</script>
+```
+
+## Refresh & Watch
+
+```vue
+<script setup lang="ts">
+const category = ref('tech')
+
+const { data, refresh } = await useFetch('/api/posts', {
+  query: { category },
+  // Auto-refresh when category changes
+  watch: [category],
+})
+
+// Manual refresh
+const refreshData = () => refresh()
+</script>
+```
+
+## Caching
+
+Data is cached by key. Share data across components:
+
+```vue
+<script setup lang="ts">
+// In component A
+const { data } = await useFetch('/api/user', { key: 'current-user' })
+
+// In component B - uses cached data
+const { data } = useNuxtData('current-user')
+</script>
+```
+
+Refresh cached data globally:
+
+```ts
+// Refresh specific key
+await refreshNuxtData('current-user')
+
+// Refresh all data
+await refreshNuxtData()
+
+// Clear cached data
+clearNuxtData('current-user')
+```
+
+## Interceptors
+
+```ts
+const { data } = await useFetch('/api/auth', {
+  onRequest({ options }) {
+    options.headers.set('Authorization', `Bearer ${token}`)
+  },
+  onRequestError({ error }) {
+    console.error('Request failed:', error)
+  },
+  onResponse({ response }) {
+    // Process response
+  },
+  onResponseError({ response }) {
+    if (response.status === 401) {
+      navigateTo('/login')
+    }
+  },
+})
+```
+
+## Passing Headers (SSR)
+
+`useFetch` automatically proxies cookies/headers from client to server. For `$fetch`:
+
+```vue
+<script setup lang="ts">
+const headers = useRequestHeaders(['cookie'])
+const data = await $fetch('/api/user', { headers })
+</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
+-->