@codihaus/claude-skills 1.0.0 → 1.3.0

package/knowledge/stacks/nuxt/_index.md

@@ -0,0 +1,469 @@
+# Nuxt.js
+
+> Vue.js meta-framework with SSR, file-based routing, and auto-imports
+
+## Overview
+
+**What it is:**
+- Full-stack Vue.js framework
+- Server-side rendering (SSR) by default
+- File-based routing (pages/)
+- Auto-imported composables and components
+- Nitro server engine for API routes
+
+**When to use:**
+- Vue.js applications needing SEO (SSR)
+- Full-stack apps (frontend + API)
+- Projects wanting convention over configuration
+- Teams familiar with Vue ecosystem
+
+**Key concepts:**
+- **Pages** = File-based routes in `pages/`
+- **Composables** = Reusable logic in `composables/`
+- **Components** = Auto-imported from `components/`
+- **Server Routes** = API endpoints in `server/api/`
+- **Middleware** = Route guards in `middleware/`
+- **Plugins** = App initialization in `plugins/`
+
+## Best Practices
+
+### Project Structure
+
+```
+nuxt-app/
+├── assets/              # Uncompiled assets (SCSS, images)
+├── components/          # Auto-imported Vue components
+│   ├── common/          # Shared components
+│   ├── forms/           # Form components
+│   └── ui/              # UI primitives
+├── composables/         # Auto-imported composables
+│   ├── useAuth.ts       # Auth logic
+│   ├── useApi.ts        # API client
+│   └── use{Feature}.ts  # Feature-specific
+├── layouts/             # Page layouts
+├── middleware/          # Route middleware
+├── pages/               # File-based routes
+├── plugins/             # Nuxt plugins
+├── server/              # Nitro server
+│   ├── api/             # API routes
+│   ├── middleware/      # Server middleware
+│   └── utils/           # Server utilities
+├── stores/              # Pinia stores (if using)
+├── types/               # TypeScript types
+└── utils/               # Shared utilities
+```
+
+### Data Fetching
+
+```
+DO:
+✓ Use useFetch/useAsyncData for SSR-compatible fetching
+✓ Use $fetch for client-only or event handlers
+✓ Set key for caching: useFetch('/api/users', { key: 'users' })
+✓ Use lazy: true for non-critical data
+
+DON'T:
+✗ Use raw fetch() in components (breaks SSR hydration)
+✗ Fetch in onMounted for initial data
+✗ Forget error handling
+```
+
+### Composables
+
+```
+DO:
+✓ Name with use* prefix (useAuth, useProducts)
+✓ Return reactive refs and functions
+✓ Handle SSR context (check process.client if needed)
+✓ Keep composables focused (single responsibility)
+
+DON'T:
+✗ Use component-specific logic
+✗ Directly mutate external state
+✗ Forget to handle loading/error states
+```
+
+### Server Routes (Nitro)
+
+```
+DO:
+✓ Use server/api/ for API endpoints
+✓ Define event handlers with defineEventHandler
+✓ Use readBody for POST data
+✓ Return objects (auto-serialized)
+✓ Use server-only secrets (process.env)
+
+DON'T:
+✗ Expose secrets to client (use runtimeConfig.secret)
+✗ Skip input validation
+✗ Forget error handling
+```
+
+### State Management
+
+```
+DO:
+✓ Use useState for simple shared state
+✓ Use Pinia for complex state
+✓ Keep state minimal (derive where possible)
+✓ Use localStorage only via plugins (SSR-safe)
+
+DON'T:
+✗ Use Vue reactive() at module level (SSR leak)
+✗ Store derived data (compute it)
+✗ Forget SSR hydration
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Better Approach |
+|--------------|---------|-----------------|
+| `fetch()` in setup | SSR hydration mismatch | Use `useFetch()` |
+| Direct localStorage | Fails on server | Use `useState` + plugin |
+| Reactive at module level | State leak between requests | Use `useState()` |
+| Heavy sync operations | Blocks rendering | Use `lazy: true` or defer |
+| Ignoring loading state | Poor UX | Handle pending/error |
+| API secrets in client | Security risk | Use `runtimeConfig.secret` |
+
+## For /dev-specs
+
+### Page Specification
+
+```markdown
+## Page: /products/[id]
+
+### Route
+- Path: `/products/:id`
+- File: `pages/products/[id].vue`
+
+### Data Requirements
+- Product details (useFetch from API/Directus)
+- Related products (lazy load)
+
+### Components
+| Component | Purpose |
+|-----------|---------|
+| ProductGallery | Image carousel |
+| ProductInfo | Name, price, description |
+| AddToCart | Cart interaction |
+
+### SEO
+- Title: `{product.name} | Store`
+- Meta description: `{product.description}`
+- OG image: `{product.image}`
+```
+
+### Composable Specification
+
+```markdown
+## Composable: useProducts
+
+### Purpose
+Manage product data fetching and caching
+
+### Interface
+```typescript
+function useProducts() {
+  return {
+    products: Ref<Product[]>,
+    pending: Ref<boolean>,
+    error: Ref<Error | null>,
+    refresh: () => Promise<void>,
+    getProduct: (id: string) => Product | undefined,
+  }
+}
+```
+
+### Usage
+```vue
+const { products, pending } = useProducts()
+```
+```
+
+### Server Route Specification
+
+```markdown
+## API: POST /api/orders
+
+### Purpose
+Create new order
+
+### Request
+```typescript
+{
+  items: { productId: string, quantity: number }[],
+  shippingAddress: Address,
+}
+```
+
+### Response
+```typescript
+{ orderId: string, total: number, status: 'pending' }
+```
+
+### Errors
+| Code | Reason |
+|------|--------|
+| 400 | Invalid items or address |
+| 401 | Not authenticated |
+| 422 | Insufficient stock |
+```
+
+## For /dev-coding
+
+### Composable Pattern
+
+```typescript
+// composables/useProducts.ts
+export const useProducts = () => {
+  const products = useState<Product[]>('products', () => []);
+  const pending = ref(false);
+  const error = ref<Error | null>(null);
+
+  const fetch = async () => {
+    pending.value = true;
+    error.value = null;
+    try {
+      const data = await $fetch<Product[]>('/api/products');
+      products.value = data;
+    } catch (e) {
+      error.value = e as Error;
+    } finally {
+      pending.value = false;
+    }
+  };
+
+  const getProduct = (id: string) =>
+    products.value.find(p => p.id === id);
+
+  return {
+    products: readonly(products),
+    pending: readonly(pending),
+    error: readonly(error),
+    fetch,
+    getProduct,
+  };
+};
+```
+
+### Page with Data Fetching
+
+```vue
+<!-- pages/products/[id].vue -->
+<script setup lang="ts">
+const route = useRoute();
+const { data: product, pending, error } = await useFetch(
+  `/api/products/${route.params.id}`,
+  { key: `product-${route.params.id}` }
+);
+
+// SEO
+useSeoMeta({
+  title: () => product.value?.name ?? 'Product',
+  description: () => product.value?.description,
+});
+</script>
+
+<template>
+  <div v-if="pending">Loading...</div>
+  <div v-else-if="error">Error: {{ error.message }}</div>
+  <div v-else-if="product">
+    <h1>{{ product.name }}</h1>
+    <p>{{ product.price }}</p>
+  </div>
+</template>
+```
+
+### Server Route
+
+```typescript
+// server/api/products/[id].get.ts
+export default defineEventHandler(async (event) => {
+  const id = getRouterParam(event, 'id');
+
+  if (!id) {
+    throw createError({
+      statusCode: 400,
+      message: 'Product ID required',
+    });
+  }
+
+  // Fetch from Directus or database
+  const product = await getProduct(id);
+
+  if (!product) {
+    throw createError({
+      statusCode: 404,
+      message: 'Product not found',
+    });
+  }
+
+  return product;
+});
+```
+
+### Server Route with Body
+
+```typescript
+// server/api/orders.post.ts
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event);
+
+  // Validate
+  const parsed = orderSchema.safeParse(body);
+  if (!parsed.success) {
+    throw createError({
+      statusCode: 400,
+      message: 'Invalid order data',
+      data: parsed.error.flatten(),
+    });
+  }
+
+  // Create order
+  const order = await createOrder(parsed.data);
+
+  return { orderId: order.id, status: order.status };
+});
+```
+
+### Middleware (Auth)
+
+```typescript
+// middleware/auth.ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  const { user } = useAuth();
+
+  if (!user.value && to.meta.requiresAuth) {
+    return navigateTo('/login');
+  }
+});
+
+// Usage in page
+definePageMeta({
+  middleware: 'auth',
+  requiresAuth: true,
+});
+```
+
+### Plugin (Client-only)
+
+```typescript
+// plugins/localStorage.client.ts
+export default defineNuxtPlugin(() => {
+  return {
+    provide: {
+      localStorage: {
+        get: (key: string) => localStorage.getItem(key),
+        set: (key: string, value: string) => localStorage.setItem(key, value),
+      },
+    },
+  };
+});
+
+// Usage: const { $localStorage } = useNuxtApp()
+```
+
+## For /dev-review
+
+### SSR Compatibility Checklist
+
+- [ ] Using `useFetch`/`useAsyncData` for data
+- [ ] No `window`/`document` access without `process.client` check
+- [ ] Using `useState` instead of module-level reactive
+- [ ] Plugins marked `.client.ts` if browser-only
+- [ ] No localStorage without client check
+
+### Performance Checklist
+
+- [ ] Using `lazy: true` for below-fold data
+- [ ] Images optimized with `<NuxtImg>`
+- [ ] Components lazy-loaded where appropriate
+- [ ] Using `key` parameter for cache control
+- [ ] No blocking operations in setup
+
+### Security Checklist
+
+- [ ] Secrets in `runtimeConfig` (not `public`)
+- [ ] Server routes validate input
+- [ ] Auth middleware on protected routes
+- [ ] CSRF protection on mutations
+- [ ] No sensitive data in client bundle
+
+### Common Mistakes
+
+| Mistake | Impact | Fix |
+|---------|--------|-----|
+| `fetch()` instead of `useFetch` | Hydration mismatch | Use `useFetch` |
+| Missing `key` in useFetch | Cache conflicts | Add unique key |
+| Ignoring `pending` state | Flash of empty | Show loading |
+| Direct localStorage | SSR crash | Use plugin or client check |
+| Secrets in `public` config | Leaked to client | Use `runtimeConfig.secret` |
+
+## Integration
+
+### With Directus
+
+```typescript
+// composables/useDirectus.ts
+import { createDirectus, rest, authentication } from '@directus/sdk';
+
+export const useDirectus = () => {
+  const config = useRuntimeConfig();
+
+  const client = createDirectus<Schema>(config.public.directusUrl)
+    .with(rest())
+    .with(authentication('cookie', { credentials: 'include' }));
+
+  return client;
+};
+
+// composables/useProducts.ts
+export const useProducts = () => {
+  const directus = useDirectus();
+
+  return useAsyncData('products', () =>
+    directus.request(readItems('products', {
+      filter: { status: { _eq: 'published' } },
+    }))
+  );
+};
+```
+
+### With Pinia
+
+```typescript
+// stores/cart.ts
+export const useCartStore = defineStore('cart', () => {
+  const items = ref<CartItem[]>([]);
+
+  const total = computed(() =>
+    items.value.reduce((sum, item) => sum + item.price * item.quantity, 0)
+  );
+
+  const addItem = (product: Product, quantity = 1) => {
+    const existing = items.value.find(i => i.productId === product.id);
+    if (existing) {
+      existing.quantity += quantity;
+    } else {
+      items.value.push({ productId: product.id, ...product, quantity });
+    }
+  };
+
+  return { items, total, addItem };
+});
+```
+
+## Resources
+
+### Official Docs
+- Docs: https://nuxt.com/docs
+- Modules: https://nuxt.com/modules
+
+### Context7 Queries
+
+```
+Query: "Nuxt 3 useFetch best practices"
+Query: "Nuxt 3 server routes authentication"
+Query: "Nuxt 3 middleware patterns"
+Query: "Nuxt 3 Pinia setup"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "description": "Claude Code skills for software development workflow",
   "main": "src/index.js",
   "bin": {
@@ -40,6 +40,8 @@
     "bin",
     "src",
     "skills",
+    "knowledge",
+    "project-scripts",
     "templates",
     "README.md"
   ]