shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/skills/nextjs-vibe-coding/patterns/image-optimization.md

@@ -0,0 +1,227 @@
+# Image Optimization Pattern
+
+## Overview
+
+Next.js Image Optimization provides automatic resizing, optimization, and lazy loading. However, development environments using LocalStack require special handling due to private IP restrictions.
+
+---
+
+## LocalStack Development Workaround
+
+Next.js Image Optimization rejects images from private IPs (like `172.x.x.x`). LocalStack URLs resolve to `host-gateway` (typically 172.17.0.1), causing 400 Bad Request errors.
+
+### Problem
+
+```
+GET /_next/image?url=https://localstack.local.test/...
+400 Bad Request: "url" parameter is not allowed
+```
+
+### Solution: OptimizedAvatar Component
+
+```typescript
+"use client"
+
+import { useState, useEffect } from "react"
+import Image from "next/image"
+import { Avatar, AvatarFallback } from "@/components/ui/avatar"
+
+interface OptimizedAvatarProps {
+  src?: string | null
+  alt: string
+  fallback: string
+  size?: number
+  className?: string
+}
+
+function shouldSkipOptimization(url: string): boolean {
+  return url.includes("localstack.local.test") || url.includes("localhost:4566")
+}
+
+export function OptimizedAvatar({
+  src,
+  alt,
+  fallback,
+  size = 40,
+  className,
+}: OptimizedAvatarProps) {
+  const [imageError, setImageError] = useState(false)
+
+  // Reset error state when src changes
+  useEffect(() => {
+    setImageError(false)
+  }, [src])
+
+  const skipOptimization = src ? shouldSkipOptimization(src) : false
+
+  return (
+    <Avatar className={className} style={{ width: size, height: size }}>
+      {src && !imageError ? (
+        <Image
+          src={src}
+          alt={alt}
+          width={size}
+          height={size}
+          className="object-cover"
+          onError={() => setImageError(true)}
+          unoptimized={skipOptimization}
+        />
+      ) : (
+        <AvatarFallback style={{ width: size, height: size }}>
+          {fallback}
+        </AvatarFallback>
+      )}
+    </Avatar>
+  )
+}
+```
+
+---
+
+## Usage
+
+```tsx
+import { OptimizedAvatar } from "@/components/ui/optimized-avatar"
+
+export function UserProfile({ user }: { user: User }) {
+  const initials = user.name
+    ?.split(" ")
+    .map((n) => n[0])
+    .join("")
+    .toUpperCase() || "?"
+
+  return (
+    <OptimizedAvatar
+      src={user.image}
+      alt={user.name || "User avatar"}
+      fallback={initials}
+      size={48}
+    />
+  )
+}
+```
+
+---
+
+## Key Implementation Points
+
+### 1. Detect LocalStack URLs
+
+```typescript
+function shouldSkipOptimization(url: string): boolean {
+  return url.includes("localstack.local.test") || url.includes("localhost:4566")
+}
+```
+
+### 2. Use `unoptimized` Prop
+
+```tsx
+<Image
+  src={src}
+  unoptimized={skipOptimization}  // Bypasses Next.js optimization
+/>
+```
+
+### 3. Error Fallback
+
+```typescript
+const [imageError, setImageError] = useState(false)
+
+// On error, show fallback
+onError={() => setImageError(true)}
+```
+
+### 4. Reset on Source Change
+
+```typescript
+useEffect(() => {
+  setImageError(false)
+}, [src])
+```
+
+---
+
+## Docker Configuration
+
+Ensure containers can resolve LocalStack URLs:
+
+```yaml
+# docker-compose.yml
+services:
+  admin-app:
+    extra_hosts:
+      - "localstack.local.test:host-gateway"
+    environment:
+      - NODE_TLS_REJECT_UNAUTHORIZED=0  # For self-signed certs
+```
+
+---
+
+## S3 Bucket Policy
+
+Ensure bucket is publicly readable for avatar display:
+
+```bash
+AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test \
+aws --endpoint-url=http://localhost:4566 s3api put-bucket-policy \
+  --bucket app-uploads \
+  --policy '{
+    "Version": "2012-10-17",
+    "Statement": [{
+      "Sid": "PublicReadGetObject",
+      "Effect": "Allow",
+      "Principal": "*",
+      "Action": "s3:GetObject",
+      "Resource": "arn:aws:s3:::app-uploads/*"
+    }]
+  }' --region ap-northeast-1
+```
+
+---
+
+## Production vs Development
+
+| Environment | Image Source | Optimization |
+|-------------|--------------|--------------|
+| Production | AWS S3 / CloudFront | ✅ Enabled |
+| Development | LocalStack | ❌ Disabled (via `unoptimized`) |
+| Local File | `public/` directory | ✅ Enabled |
+
+---
+
+## Testing
+
+```typescript
+describe("OptimizedAvatar", () => {
+  it("skips optimization for LocalStack URLs", () => {
+    const { container } = render(
+      <OptimizedAvatar
+        src="https://localstack.local.test/app-uploads/avatar.jpg"
+        alt="Avatar"
+        fallback="AB"
+      />
+    )
+
+    const img = container.querySelector("img")
+    expect(img).toHaveAttribute("src", expect.stringContaining("localstack"))
+    // Should NOT go through /_next/image
+  })
+
+  it("shows fallback on error", async () => {
+    const { getByText } = render(
+      <OptimizedAvatar
+        src="https://invalid-url.test/broken.jpg"
+        alt="Avatar"
+        fallback="AB"
+      />
+    )
+
+    // Simulate error
+    fireEvent.error(screen.getByRole("img"))
+
+    await waitFor(() => {
+      expect(getByText("AB")).toBeInTheDocument()
+    })
+  })
+})
+```

package/plugin/shirokuma-skills-en/skills/nextjs-vibe-coding/patterns/radix-ui-hydration.md

@@ -0,0 +1,79 @@
+# Radix UI Hydration Pattern (CRITICAL)
+
+Quick reference for Radix UI hydration patterns.
+
+---
+
+## Problem
+
+Radix UI components generate dynamic IDs that differ between SSR and client:
+
+```
+Error: Hydration failed because the server rendered HTML didn't match the client.
+- Server: id="radix-:R1:"
+- Client: id="radix-:R2:"
+```
+
+## Solution
+
+Use `mounted` state pattern:
+
+```typescript
+"use client"
+
+import { useState, useEffect } from "react"
+
+export function MyComponent() {
+  const [mounted, setMounted] = useState(false)
+
+  useEffect(() => {
+    setMounted(true)
+  }, [])
+
+  // SSR: Render placeholder WITHOUT Radix UI
+  if (!mounted) {
+    return <Button disabled><Icon /></Button>
+  }
+
+  // Client: Render full component WITH Radix UI
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button><Icon /></Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent>
+        <DropdownMenuItem>Option 1</DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
+## Affected Components
+
+- `DropdownMenu` / `Select` / `Collapsible`
+- `Dialog` / `AlertDialog`
+- `ModeToggle` (theme switcher)
+- `LanguageSwitcher`
+- Any Radix UI primitive that generates IDs
+
+## Placeholder Requirements
+
+1. **Match Visual Appearance**: Same as trigger button
+2. **Disable Interaction**: Use `disabled` prop
+3. **Preserve Accessibility**: Keep `sr-only` text
+
+## Known Issue: React 19.2 / Next.js 15.5+ useId Change
+
+React 19.2 changed the default prefix for `useId`, causing hydration mismatches in Radix UI components (Dialog, Popover, DropdownMenu, etc.) on Next.js 15.5.0 and later.
+
+```
+Error: Hydration failed
+- Server: aria-controls="radix-:R15mkl:"
+- Client: aria-controls="radix-:R9dl5:"
+```
+
+**Workarounds**:
+- Downgrading to Next.js 15.4.7 has been reported to resolve the issue
+- The `mounted` state pattern remains an effective workaround
+- Radix UI fix status: [Issue #3700](https://github.com/radix-ui/primitives/issues/3700)

package/plugin/shirokuma-skills-en/skills/nextjs-vibe-coding/patterns/rate-limiting.md

@@ -0,0 +1,188 @@
+# Rate Limiting Pattern
+
+## Overview
+
+Rate limiting protects against abuse and brute-force attacks. Apply to destructive or expensive operations like deletes, password resets, and API calls.
+
+---
+
+## Implementation
+
+### Rate Limiter Configuration
+
+```typescript
+// lib/rate-limit.ts
+import { Redis } from "@upstash/redis"  // or ioredis
+
+const redis = new Redis({
+  url: process.env.REDIS_URL!,
+})
+
+export const RateLimiters = {
+  delete: { windowMs: 60_000, maxRequests: 10 },        // 10 deletes per minute
+  create: { windowMs: 60_000, maxRequests: 30 },        // 30 creates per minute
+  comment: { windowMs: 60_000, maxRequests: 5 },        // 5 comments per minute
+  passwordReset: { windowMs: 3600_000, maxRequests: 3 }, // 3 per hour
+  login: { windowMs: 300_000, maxRequests: 5 },         // 5 login attempts per 5 min
+}
+
+export interface RateLimitResult {
+  success: boolean
+  remaining: number
+  reset: number  // Unix timestamp when limit resets
+}
+
+export async function checkRateLimit(
+  key: string,
+  limiter: { windowMs: number; maxRequests: number }
+): Promise<RateLimitResult> {
+  const now = Date.now()
+  const windowStart = now - limiter.windowMs
+
+  // Remove old entries
+  await redis.zremrangebyscore(key, 0, windowStart)
+
+  // Count current requests
+  const count = await redis.zcard(key)
+
+  if (count >= limiter.maxRequests) {
+    // Get oldest entry to calculate reset time
+    const oldest = await redis.zrange(key, 0, 0, { withScores: true })
+    const resetTime = oldest.length > 0 ? oldest[0].score + limiter.windowMs : now + limiter.windowMs
+
+    return {
+      success: false,
+      remaining: 0,
+      reset: resetTime / 1000,  // Convert to seconds
+    }
+  }
+
+  // Add current request
+  await redis.zadd(key, { score: now, member: `${now}-${Math.random()}` })
+  await redis.expire(key, Math.ceil(limiter.windowMs / 1000))
+
+  return {
+    success: true,
+    remaining: limiter.maxRequests - count - 1,
+    reset: (now + limiter.windowMs) / 1000,
+  }
+}
+```
+
+---
+
+## Usage in Server Actions
+
+Apply rate limiting AFTER auth, BEFORE business logic:
+
+```typescript
+export async function deleteFeature(id: string): Promise<ActionResult> {
+  // Step 1: Auth + CSRF
+  const userId = await verifyAdminMutation()
+
+  // Step 2: Rate limiting
+  const rateLimitKey = `delete-feature:${userId}`
+  const rateLimitResult = await checkRateLimit(rateLimitKey, RateLimiters.delete)
+
+  if (!rateLimitResult.success) {
+    const waitSeconds = Math.ceil((rateLimitResult.reset * 1000 - Date.now()) / 1000)
+    return {
+      success: false,
+      error: `Rate limit exceeded. Try again in ${waitSeconds}s`,
+      code: "RATE_LIMIT_EXCEEDED",
+    }
+  }
+
+  // Step 3: Continue with operation...
+  // ...
+}
+```
+
+---
+
+## Operations Requiring Rate Limiting
+
+| Operation | Limiter | Reason |
+|-----------|---------|--------|
+| Delete | `RateLimiters.delete` | Prevent mass deletion |
+| Password Reset | `RateLimiters.passwordReset` | Prevent email flooding |
+| Login Attempts | `RateLimiters.login` | Prevent brute force |
+| Comment Creation | `RateLimiters.comment` | Prevent spam |
+| Email Verification | `RateLimiters.passwordReset` | Prevent email flooding |
+| File Uploads | `RateLimiters.create` | Prevent storage abuse |
+
+---
+
+## Key Patterns
+
+### 1. User-Based Keys
+
+```typescript
+const rateLimitKey = `delete-feature:${userId}`
+```
+
+### 2. IP-Based Keys (for unauthenticated endpoints)
+
+```typescript
+const ip = headersList.get("x-forwarded-for") || "unknown"
+const rateLimitKey = `password-reset:${ip}`
+```
+
+### 3. Combined Keys
+
+```typescript
+const rateLimitKey = `comment:${userId}:${postId}`
+```
+
+---
+
+## Error Response Pattern
+
+Always include `code` for programmatic handling:
+
+```typescript
+return {
+  success: false,
+  error: `Rate limit exceeded. Try again in ${waitSeconds}s`,
+  code: "RATE_LIMIT_EXCEEDED",
+}
+```
+
+---
+
+## UI Handling
+
+```typescript
+const result = await deleteFeature(id)
+
+if (!result.success) {
+  if (result.code === "RATE_LIMIT_EXCEEDED") {
+    toast.error(result.error)  // Shows wait time
+    return
+  }
+  // Handle other errors
+}
+```
+
+---
+
+## Testing Rate Limits
+
+```typescript
+it("enforces rate limit on delete", async () => {
+  // Mock rate limit exceeded
+  mockCheckRateLimit.mockResolvedValueOnce({
+    success: false,
+    remaining: 0,
+    reset: Date.now() / 1000 + 30,
+  })
+
+  const result = await deleteFeature("feature-1")
+
+  expect(result).toEqual({
+    success: false,
+    error: expect.stringContaining("Rate limit"),
+    code: "RATE_LIMIT_EXCEEDED",
+  })
+})
+```

package/plugin/shirokuma-skills-en/skills/nextjs-vibe-coding/patterns/tailwind-v4.md

@@ -0,0 +1,43 @@
+# Tailwind CSS v4 パターン
+
+Quick reference for Tailwind CSS v4 patterns.
+
+---
+
+## Quick Reference
+
+### shadcn/ui 追加後の必須作業
+
+```bash
+npx shadcn@latest add {component} -y
+./scripts/fix-tailwind-v4-css-vars.sh --yes apps/{app}/components/ui
+```
+
+### CSS 変数構文 (CRITICAL)
+
+```tsx
+// NG: v3 構文（CLI が生成する古い形式）
+className="bg-[--sidebar-background]"
+
+// OK: v4 構文
+className="bg-[var(--sidebar-background)]"
+```
+
+### 本番でのみ問題が発生する場合
+
+```css
+/* @property ではなく @theme inline を使用 */
+@theme inline {
+  --sidebar-width: 16rem;
+  --sidebar-width-icon: 3rem;
+}
+```
+
+---
+
+## Key Points
+
+- shadcn/ui は `npx shadcn@latest` を使用
+- CLI が生成する `[--var]` → `[var(--var)]` に変換必須
+- 本番で CSS 変数が効かない場合は `@theme inline` を使用
+- コンポーネント追加後は必ず fix スクリプトを実行