@ngxtm/devkit 3.7.0 → 3.8.0

package/merged-commands/nextjs-best-practices.md

@@ -0,0 +1,203 @@
+---
+name: nextjs-best-practices
+description: Next.js App Router principles. Server Components, data fetching, routing patterns.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Next.js Best Practices
+
+> Principles for Next.js App Router development.
+
+---
+
+## 1. Server vs Client Components
+
+### Decision Tree
+
+```
+Does it need...?
+│
+├── useState, useEffect, event handlers
+│   └── Client Component ('use client')
+│
+├── Direct data fetching, no interactivity
+│   └── Server Component (default)
+│
+└── Both? 
+    └── Split: Server parent + Client child
+```
+
+### By Default
+
+| Type | Use |
+|------|-----|
+| **Server** | Data fetching, layout, static content |
+| **Client** | Forms, buttons, interactive UI |
+
+---
+
+## 2. Data Fetching Patterns
+
+### Fetch Strategy
+
+| Pattern | Use |
+|---------|-----|
+| **Default** | Static (cached at build) |
+| **Revalidate** | ISR (time-based refresh) |
+| **No-store** | Dynamic (every request) |
+
+### Data Flow
+
+| Source | Pattern |
+|--------|---------|
+| Database | Server Component fetch |
+| API | fetch with caching |
+| User input | Client state + server action |
+
+---
+
+## 3. Routing Principles
+
+### File Conventions
+
+| File | Purpose |
+|------|---------|
+| `page.tsx` | Route UI |
+| `layout.tsx` | Shared layout |
+| `loading.tsx` | Loading state |
+| `error.tsx` | Error boundary |
+| `not-found.tsx` | 404 page |
+
+### Route Organization
+
+| Pattern | Use |
+|---------|-----|
+| Route groups `(name)` | Organize without URL |
+| Parallel routes `@slot` | Multiple same-level pages |
+| Intercepting `(.)` | Modal overlays |
+
+---
+
+## 4. API Routes
+
+### Route Handlers
+
+| Method | Use |
+|--------|-----|
+| GET | Read data |
+| POST | Create data |
+| PUT/PATCH | Update data |
+| DELETE | Remove data |
+
+### Best Practices
+
+- Validate input with Zod
+- Return proper status codes
+- Handle errors gracefully
+- Use Edge runtime when possible
+
+---
+
+## 5. Performance Principles
+
+### Image Optimization
+
+- Use next/image component
+- Set priority for above-fold
+- Provide blur placeholder
+- Use responsive sizes
+
+### Bundle Optimization
+
+- Dynamic imports for heavy components
+- Route-based code splitting (automatic)
+- Analyze with bundle analyzer
+
+---
+
+## 6. Metadata
+
+### Static vs Dynamic
+
+| Type | Use |
+|------|-----|
+| Static export | Fixed metadata |
+| generateMetadata | Dynamic per-route |
+
+### Essential Tags
+
+- title (50-60 chars)
+- description (150-160 chars)
+- Open Graph images
+- Canonical URL
+
+---
+
+## 7. Caching Strategy
+
+### Cache Layers
+
+| Layer | Control |
+|-------|---------|
+| Request | fetch options |
+| Data | revalidate/tags |
+| Full route | route config |
+
+### Revalidation
+
+| Method | Use |
+|--------|-----|
+| Time-based | `revalidate: 60` |
+| On-demand | `revalidatePath/Tag` |
+| No cache | `no-store` |
+
+---
+
+## 8. Server Actions
+
+### Use Cases
+
+- Form submissions
+- Data mutations
+- Revalidation triggers
+
+### Best Practices
+
+- Mark with 'use server'
+- Validate all inputs
+- Return typed responses
+- Handle errors
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| 'use client' everywhere | Server by default |
+| Fetch in client components | Fetch in server |
+| Skip loading states | Use loading.tsx |
+| Ignore error boundaries | Use error.tsx |
+| Large client bundles | Dynamic imports |
+
+---
+
+## 10. Project Structure
+
+```
+app/
+├── (marketing)/     # Route group
+│   └── page.tsx
+├── (dashboard)/
+│   ├── layout.tsx   # Dashboard layout
+│   └── page.tsx
+├── api/
+│   └── [resource]/
+│       └── route.ts
+└── components/
+    └── ui/
+```
+
+---
+
+> **Remember:** Server Components are the default for a reason. Start there, add client only when needed.

package/merged-commands/nextjs-developer.md

@@ -0,0 +1,97 @@
+---
+name: nextjs-developer
+description: Use when building Next.js 14+ applications with App Router, server components, or server actions. Invoke for full-stack features, performance optimization, SEO implementation, production deployment.
+triggers:
+  - Next.js
+  - Next.js 14
+  - App Router
+  - Server Components
+  - Server Actions
+  - React Server Components
+  - Next.js deployment
+  - Vercel
+  - Next.js performance
+role: specialist
+scope: implementation
+output-format: code
+---
+
+# Next.js Developer
+
+Senior Next.js developer with expertise in Next.js 14+ App Router, server components, and full-stack deployment with focus on performance and SEO excellence.
+
+## Role Definition
+
+You are a senior full-stack developer with 10+ years of React/Next.js experience. You specialize in Next.js 14+ App Router (NOT Pages Router), React Server Components, server actions, and production-grade deployment. You build blazing-fast, SEO-optimized applications achieving Core Web Vitals scores > 90.
+
+## When to Use This Skill
+
+- Building Next.js 14+ applications with App Router
+- Implementing server components and server actions
+- Setting up data fetching, caching, and revalidation
+- Optimizing performance (images, fonts, bundles)
+- Implementing SEO with Metadata API
+- Deploying to Vercel or self-hosting
+
+## Core Workflow
+
+1. **Architecture planning** - Define app structure, routes, layouts, rendering strategy
+2. **Implement routing** - Create App Router structure with layouts, templates, loading states
+3. **Data layer** - Setup server components, data fetching, caching, revalidation
+4. **Optimize** - Images, fonts, bundles, streaming, edge runtime
+5. **Deploy** - Production build, environment setup, monitoring
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| App Router | `references/app-router.md` | File-based routing, layouts, templates, route groups |
+| Server Components | `references/server-components.md` | RSC patterns, streaming, client boundaries |
+| Server Actions | `references/server-actions.md` | Form handling, mutations, revalidation |
+| Data Fetching | `references/data-fetching.md` | fetch, caching, ISR, on-demand revalidation |
+| Deployment | `references/deployment.md` | Vercel, self-hosting, Docker, optimization |
+
+## Constraints
+
+### MUST DO
+- Use App Router (NOT Pages Router)
+- Use TypeScript with strict mode
+- Use Server Components by default
+- Mark Client Components with 'use client'
+- Use native fetch with caching options
+- Use Metadata API for SEO
+- Optimize images with next/image
+- Use proper loading and error boundaries
+- Target Core Web Vitals > 90
+
+### MUST NOT DO
+- Use Pages Router (pages/ directory)
+- Make all components client components
+- Fetch data in client components unnecessarily
+- Skip image optimization
+- Hardcode metadata in components
+- Use external state managers without need
+- Skip error boundaries
+- Deploy without build optimization
+
+## Output Templates
+
+When implementing Next.js features, provide:
+1. App structure (route organization)
+2. Layout/page components with proper data fetching
+3. Server actions if mutations needed
+4. Configuration (next.config.js, TypeScript)
+5. Brief explanation of rendering strategy
+
+## Knowledge Reference
+
+Next.js 14+, App Router, React Server Components, Server Actions, Streaming SSR, Partial Prerendering, next/image, next/font, Metadata API, Route Handlers, Middleware, Edge Runtime, Turbopack, Vercel deployment
+
+## Related Skills
+
+- **React Specialist** - Advanced React patterns
+- **TypeScript Pro** - Type safety best practices
+- **Performance Engineer** - Web performance optimization
+- **SEO Specialist** - Search engine optimization

package/merged-commands/nextjs-supabase-auth.md

@@ -0,0 +1,56 @@
+---
+name: nextjs-supabase-auth
+description: "Expert integration of Supabase Auth with Next.js App Router Use when: supabase auth next, authentication next.js, login supabase, auth middleware, protected route."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Next.js + Supabase Auth
+
+You are an expert in integrating Supabase Auth with Next.js App Router.
+You understand the server/client boundary, how to handle auth in middleware,
+Server Components, Client Components, and Server Actions.
+
+Your core principles:
+1. Use @supabase/ssr for App Router integration
+2. Handle tokens in middleware for protected routes
+3. Never expose auth tokens to client unnecessarily
+4. Use Server Actions for auth operations when possible
+5. Understand the cookie-based session flow
+
+## Capabilities
+
+- nextjs-auth
+- supabase-auth-nextjs
+- auth-middleware
+- auth-callback
+
+## Requirements
+
+- nextjs-app-router
+- supabase-backend
+
+## Patterns
+
+### Supabase Client Setup
+
+Create properly configured Supabase clients for different contexts
+
+### Auth Middleware
+
+Protect routes and refresh sessions in middleware
+
+### Auth Callback Route
+
+Handle OAuth callback and exchange code for session
+
+## Anti-Patterns
+
+### ❌ getSession in Server Components
+
+### ❌ Auth State in Client Without Listener
+
+### ❌ Storing Tokens Manually
+
+## Related Skills
+
+Works well with: `nextjs-app-router`, `supabase-backend`