@0xsown/vibe-code-fe 1.0.0

package/skills/next-cache-components/SKILL.md

@@ -0,0 +1,411 @@
+---
+name: next-cache-components
+description: Next.js 16 Cache Components - PPR, use cache directive, cacheLife, cacheTag, updateTag
+---
+
+# Cache Components (Next.js 16+)
+
+Cache Components enable Partial Prerendering (PPR) - mix static, cached, and dynamic content in a single route.
+
+## Enable Cache Components
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+}
+
+export default nextConfig
+```
+
+This replaces the old `experimental.ppr` flag.
+
+---
+
+## Three Content Types
+
+With Cache Components enabled, content falls into three categories:
+
+### 1. Static (Auto-Prerendered)
+
+Synchronous code, imports, pure computations - prerendered at build time:
+
+```tsx
+export default function Page() {
+  return (
+    <header>
+      <h1>Our Blog</h1>  {/* Static - instant */}
+      <nav>...</nav>
+    </header>
+  )
+}
+```
+
+### 2. Cached (`use cache`)
+
+Async data that doesn't need fresh fetches every request:
+
+```tsx
+async function BlogPosts() {
+  'use cache'
+  cacheLife('hours')
+
+  const posts = await db.posts.findMany()
+  return <PostList posts={posts} />
+}
+```
+
+### 3. Dynamic (Suspense)
+
+Runtime data that must be fresh - wrap in Suspense:
+
+```tsx
+import { Suspense } from 'react'
+
+export default function Page() {
+  return (
+    <>
+      <BlogPosts />  {/* Cached */}
+
+      <Suspense fallback={<p>Loading...</p>}>
+        <UserPreferences />  {/* Dynamic - streams in */}
+      </Suspense>
+    </>
+  )
+}
+
+async function UserPreferences() {
+  const theme = (await cookies()).get('theme')?.value
+  return <p>Theme: {theme}</p>
+}
+```
+
+---
+
+## `use cache` Directive
+
+### File Level
+
+```tsx
+'use cache'
+
+export default async function Page() {
+  // Entire page is cached
+  const data = await fetchData()
+  return <div>{data}</div>
+}
+```
+
+### Component Level
+
+```tsx
+export async function CachedComponent() {
+  'use cache'
+  const data = await fetchData()
+  return <div>{data}</div>
+}
+```
+
+### Function Level
+
+```tsx
+export async function getData() {
+  'use cache'
+  return db.query('SELECT * FROM posts')
+}
+```
+
+---
+
+## Cache Profiles
+
+### Built-in Profiles
+
+```tsx
+'use cache'                    // Default: 5m stale, 15m revalidate
+```
+
+```tsx
+'use cache: remote'           // Platform-provided cache (Redis, KV)
+```
+
+```tsx
+'use cache: private'          // For compliance, allows runtime APIs
+```
+
+### `cacheLife()` - Custom Lifetime
+
+```tsx
+import { cacheLife } from 'next/cache'
+
+async function getData() {
+  'use cache'
+  cacheLife('hours')  // Built-in profile
+  return fetch('/api/data')
+}
+```
+
+Built-in profiles: `'default'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'max'`
+
+### Inline Configuration
+
+```tsx
+async function getData() {
+  'use cache'
+  cacheLife({
+    stale: 3600,      // 1 hour - serve stale while revalidating
+    revalidate: 7200, // 2 hours - background revalidation interval
+    expire: 86400,    // 1 day - hard expiration
+  })
+  return fetch('/api/data')
+}
+```
+
+---
+
+## Cache Invalidation
+
+### `cacheTag()` - Tag Cached Content
+
+```tsx
+import { cacheTag } from 'next/cache'
+
+async function getProducts() {
+  'use cache'
+  cacheTag('products')
+  return db.products.findMany()
+}
+
+async function getProduct(id: string) {
+  'use cache'
+  cacheTag('products', `product-${id}`)
+  return db.products.findUnique({ where: { id } })
+}
+```
+
+### `updateTag()` - Immediate Invalidation
+
+Use when you need the cache refreshed within the same request:
+
+```tsx
+'use server'
+
+import { updateTag } from 'next/cache'
+
+export async function updateProduct(id: string, data: FormData) {
+  await db.products.update({ where: { id }, data })
+  updateTag(`product-${id}`)  // Immediate - same request sees fresh data
+}
+```
+
+### `revalidateTag()` - Background Revalidation
+
+Use for stale-while-revalidate behavior:
+
+```tsx
+'use server'
+
+import { revalidateTag } from 'next/cache'
+
+export async function createPost(data: FormData) {
+  await db.posts.create({ data })
+  revalidateTag('posts')  // Background - next request sees fresh data
+}
+```
+
+---
+
+## Runtime Data Constraint
+
+**Cannot** access `cookies()`, `headers()`, or `searchParams` inside `use cache`.
+
+### Solution: Pass as Arguments
+
+```tsx
+// Wrong - runtime API inside use cache
+async function CachedProfile() {
+  'use cache'
+  const session = (await cookies()).get('session')?.value  // Error!
+  return <div>{session}</div>
+}
+
+// Correct - extract outside, pass as argument
+async function ProfilePage() {
+  const session = (await cookies()).get('session')?.value
+  return <CachedProfile sessionId={session} />
+}
+
+async function CachedProfile({ sessionId }: { sessionId: string }) {
+  'use cache'
+  // sessionId becomes part of cache key automatically
+  const data = await fetchUserData(sessionId)
+  return <div>{data.name}</div>
+}
+```
+
+### Exception: `use cache: private`
+
+For compliance requirements when you can't refactor:
+
+```tsx
+async function getData() {
+  'use cache: private'
+  const session = (await cookies()).get('session')?.value  // Allowed
+  return fetchData(session)
+}
+```
+
+---
+
+## Cache Key Generation
+
+Cache keys are automatic based on:
+- **Build ID** - invalidates all caches on deploy
+- **Function ID** - hash of function location
+- **Serializable arguments** - props become part of key
+- **Closure variables** - outer scope values included
+
+```tsx
+async function Component({ userId }: { userId: string }) {
+  const getData = async (filter: string) => {
+    'use cache'
+    // Cache key = userId (closure) + filter (argument)
+    return fetch(`/api/users/${userId}?filter=${filter}`)
+  }
+  return getData('active')
+}
+```
+
+---
+
+## Complete Example
+
+```tsx
+import { Suspense } from 'react'
+import { cookies } from 'next/headers'
+import { cacheLife, cacheTag } from 'next/cache'
+
+export default function DashboardPage() {
+  return (
+    <>
+      {/* Static shell - instant from CDN */}
+      <header><h1>Dashboard</h1></header>
+      <nav>...</nav>
+
+      {/* Cached - fast, revalidates hourly */}
+      <Stats />
+
+      {/* Dynamic - streams in with fresh data */}
+      <Suspense fallback={<NotificationsSkeleton />}>
+        <Notifications />
+      </Suspense>
+    </>
+  )
+}
+
+async function Stats() {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('dashboard-stats')
+
+  const stats = await db.stats.aggregate()
+  return <StatsDisplay stats={stats} />
+}
+
+async function Notifications() {
+  const userId = (await cookies()).get('userId')?.value
+  const notifications = await db.notifications.findMany({
+    where: { userId, read: false }
+  })
+  return <NotificationList items={notifications} />
+}
+```
+
+---
+
+## Migration from Previous Versions
+
+| Old Config | Replacement |
+|-----------|-------------|
+| `experimental.ppr` | `cacheComponents: true` |
+| `dynamic = 'force-dynamic'` | Remove (default behavior) |
+| `dynamic = 'force-static'` | `'use cache'` + `cacheLife('max')` |
+| `revalidate = N` | `cacheLife({ revalidate: N })` |
+| `unstable_cache()` | `'use cache'` directive |
+
+### Migrating `unstable_cache` to `use cache`
+
+`unstable_cache` has been replaced by the `use cache` directive in Next.js 16. When `cacheComponents` is enabled, convert `unstable_cache` calls to `use cache` functions:
+
+**Before (`unstable_cache`):**
+
+```tsx
+import { unstable_cache } from 'next/cache'
+
+const getCachedUser = unstable_cache(
+  async (id) => getUser(id),
+  ['my-app-user'],
+  {
+    tags: ['users'],
+    revalidate: 60,
+  }
+)
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const user = await getCachedUser(id)
+  return <div>{user.name}</div>
+}
+```
+
+**After (`use cache`):**
+
+```tsx
+import { cacheLife, cacheTag } from 'next/cache'
+
+async function getCachedUser(id: string) {
+  'use cache'
+  cacheTag('users')
+  cacheLife({ revalidate: 60 })
+  return getUser(id)
+}
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const user = await getCachedUser(id)
+  return <div>{user.name}</div>
+}
+```
+
+Key differences:
+- **No manual cache keys** - `use cache` generates keys automatically from function arguments and closures. The `keyParts` array from `unstable_cache` is no longer needed.
+- **Tags** - Replace `options.tags` with `cacheTag()` calls inside the function.
+- **Revalidation** - Replace `options.revalidate` with `cacheLife({ revalidate: N })` or a built-in profile like `cacheLife('minutes')`.
+- **Dynamic data** - `unstable_cache` did not support `cookies()` or `headers()` inside the callback. The same restriction applies to `use cache`, but you can use `'use cache: private'` if needed.
+
+---
+
+## Limitations
+
+- **Edge runtime not supported** - requires Node.js
+- **Static export not supported** - needs server
+- **Non-deterministic values** (`Math.random()`, `Date.now()`) execute once at build time inside `use cache`
+
+For request-time randomness outside cache:
+
+```tsx
+import { connection } from 'next/server'
+
+async function DynamicContent() {
+  await connection()  // Defer to request time
+  const id = crypto.randomUUID()  // Different per request
+  return <div>{id}</div>
+}
+```
+
+Sources:
+- [Cache Components Guide](https://nextjs.org/docs/app/getting-started/cache-components)
+- [use cache Directive](https://nextjs.org/docs/app/api-reference/directives/use-cache)
+- [unstable_cache (legacy)](https://nextjs.org/docs/app/api-reference/functions/unstable_cache)

package/skills/shadcn-ui/README.md

@@ -0,0 +1,248 @@
+# shadcn/ui Integration Skill
+
+## Install
+
+```bash
+npx skills add google-labs-code/stitch-skills --skill shadcn-ui --global
+```
+
+## What It Does
+
+This skill provides expert guidance for integrating shadcn/ui components into your React applications. It helps you discover, install, customize, and optimize shadcn/ui components while following best practices.
+
+## Example Prompts
+
+```text
+Help me set up shadcn/ui in my Next.js project
+
+Add a data table component with sorting and filtering to my app
+
+Show me how to customize the button component with a new variant
+
+Create a login form using shadcn/ui components with validation
+
+Build a dashboard layout with sidebar navigation using shadcn/ui blocks
+```
+
+## What is shadcn/ui?
+
+shadcn/ui is a collection of beautifully designed, accessible, and customizable components built with:
+- **Radix UI or Base UI**: Unstyled, accessible component primitives
+- **Tailwind CSS**: Utility-first styling framework
+- **TypeScript**: Full type safety
+
+**Key Difference**: Unlike traditional component libraries, shadcn/ui copies components directly into your project. This gives you:
+- Full control over the code
+- No version lock-in
+- Complete customization freedom
+- Zero runtime overhead
+
+## Skill Structure
+
+```text
+skills/shadcn-ui/
+├── SKILL.md              — Core instructions & workflow
+├── README.md             — This file
+├── examples/             — Example implementations
+│   ├── form-pattern.tsx       — Form with validation
+│   ├── data-table.tsx         — Advanced table with sorting
+│   └── auth-layout.tsx        — Authentication flow
+├── resources/            — Reference documentation
+│   ├── setup-guide.md         — Project initialization
+│   ├── component-catalog.md   — Component reference
+│   ├── customization-guide.md — Theming patterns
+│   └── migration-guide.md     — Migration from other libraries
+└── scripts/              — Utility scripts
+    └── verify-setup.sh        — Validate project configuration
+```
+
+## How It Works
+
+When activated, the agent follows this workflow:
+
+### 1. **Discovery & Planning**
+- Lists available components using shadcn MCP tools
+- Identifies required dependencies
+- Plans component composition strategy
+
+### 2. **Setup & Configuration**
+- Verifies or initializes `components.json`
+- Checks Tailwind CSS configuration
+- Validates import aliases and paths
+
+### 3. **Component Integration**
+- Retrieves component source code
+- Installs via CLI or manual integration
+- Handles dependency installation
+
+### 4. **Customization**
+- Applies theme customization
+- Creates component variants
+- Extends components with custom logic
+
+### 5. **Quality Assurance**
+- Validates TypeScript types
+- Checks accessibility compliance
+- Verifies responsive behavior
+
+## Prerequisites
+
+Your project should have:
+- **React 18+**
+- **Tailwind CSS 3.0+**
+- **TypeScript** (recommended)
+- **Node.js 18+**
+
+## Quick Start
+
+### For New Projects
+
+```bash
+# Create Next.js project with shadcn/ui
+npx create-next-app@latest my-app
+cd my-app
+npx shadcn@latest init
+
+# Add components
+npx shadcn@latest add button
+npx shadcn@latest add card
+```
+
+### For Existing Projects
+
+```bash
+# Initialize shadcn/ui
+npx shadcn@latest init
+
+# Configure when prompted:
+# - Choose style (default/new-york)
+# - Select base color
+# - Configure CSS variables
+# - Set import aliases
+
+# Add your first component
+npx shadcn@latest add button
+```
+
+## Available Components
+
+shadcn/ui provides 50+ components including:
+
+**Layout**: Accordion, Card, Separator, Tabs, Collapsible  
+**Forms**: Button, Input, Label, Checkbox, Radio Group, Select, Textarea  
+**Data Display**: Table, Badge, Avatar, Progress, Skeleton  
+**Overlays**: Dialog, Sheet, Popover, Tooltip, Dropdown Menu  
+**Navigation**: Navigation Menu, Tabs, Breadcrumb, Pagination  
+**Feedback**: Alert, Alert Dialog, Toast, Command  
+
+Plus complete **Blocks** like:
+- Authentication forms
+- Dashboard layouts
+- Calendar interfaces
+- Sidebar navigation
+- E-commerce components
+
+## Customization Approach
+
+### Theme-Level Customization
+Modify CSS variables in `globals.css`:
+```css
+:root {
+  --primary: 221.2 83.2% 53.3%;
+  --secondary: 210 40% 96.1%;
+  /* ... */
+}
+```
+
+### Component-Level Customization
+Components use `class-variance-authority` for variants:
+```typescript
+const buttonVariants = cva(
+  "base-classes",
+  {
+    variants: {
+      variant: { default: "...", destructive: "..." },
+      size: { default: "...", sm: "..." },
+    }
+  }
+)
+```
+
+### Composition
+Create higher-level components:
+```typescript
+// Compose existing components
+export function FeatureCard({ title, description, icon }) {
+  return (
+    <Card>
+      <CardHeader>
+        {icon}
+        <CardTitle>{title}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <p>{description}</p>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+## Integration with MCP Tools
+
+This skill leverages shadcn MCP server capabilities:
+
+- `list_components` - Browse component catalog
+- `get_component` - Retrieve component source
+- `get_component_metadata` - View props and dependencies
+- `get_component_demo` - See usage examples
+- `list_blocks` - Browse UI blocks
+- `get_block` - Retrieve block source with all files
+- `search_items_in_registries` - Find components in custom registries
+
+## Best Practices
+
+1. **Keep `ui/` pure**: Don't modify components in `components/ui/` directly
+2. **Compose, don't fork**: Create wrapper components instead of editing originals
+3. **Use the CLI**: Let `shadcn add` handle dependencies and updates
+4. **Maintain consistency**: Use the `cn()` utility for all class merging
+5. **Respect accessibility**: Preserve ARIA attributes and keyboard handlers
+6. **Test responsiveness**: shadcn components are responsive by default—keep it that way
+
+## Troubleshooting
+
+### "Module not found" errors
+Check your `tsconfig.json` includes path aliases:
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+### Styles not applying
+- Import `globals.css` in your root layout
+- Verify Tailwind config includes component paths
+- Check CSS variable definitions match component expectations
+
+### TypeScript errors
+- Ensure all Radix UI peer dependencies are installed
+- Run `npm install` after adding components via CLI
+- Check that React types are up to date
+
+## Further Reading
+
+- [Official Documentation](https://ui.shadcn.com)
+- [Component Source](https://github.com/shadcn-ui/ui)
+- [Radix UI Docs](https://www.radix-ui.com)
+- [Tailwind CSS Docs](https://tailwindcss.com)
+
+## Contributing
+
+Contributions to improve this skill are welcome! See the root [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
+## License
+
+See [LICENSE](../../LICENSE) in the repository root.