@cubis/foundry 0.3.64 → 0.3.66

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/nextjs-developer/steering/data-fetching.md

@@ -0,0 +1,266 @@
+# Data Fetching Patterns
+
+## Fetch in Server Components
+
+Server Components can fetch data directly without an API layer:
+
+```tsx
+// Direct database access
+async function ProductList() {
+  const products = await db.product.findMany({
+    orderBy: { createdAt: "desc" },
+    take: 20,
+  });
+  return (
+    <ul>
+      {products.map((p) => (
+        <ProductCard key={p.id} product={p} />
+      ))}
+    </ul>
+  );
+}
+
+// External API
+async function WeatherWidget({ city }: { city: string }) {
+  const res = await fetch(`https://api.weather.com/v1/${city}`);
+  if (!res.ok) throw new Error("Failed to fetch weather");
+  const data = await res.json();
+  return <div>{data.temperature}°C</div>;
+}
+```
+
+## Caching Strategies
+
+### Static Data (cached indefinitely)
+
+```tsx
+// Default behavior — cached at build time
+const data = await fetch("https://api.example.com/data");
+
+// Equivalent explicit form
+const data = await fetch("https://api.example.com/data", {
+  cache: "force-cache",
+});
+```
+
+### Time-Based Revalidation (ISR)
+
+```tsx
+// Revalidate every 60 seconds
+const data = await fetch("https://api.example.com/data", {
+  next: { revalidate: 60 },
+});
+
+// Page-level revalidation
+export const revalidate = 60; // seconds
+```
+
+### Dynamic Data (no cache)
+
+```tsx
+// Always fetch fresh
+const data = await fetch("https://api.example.com/data", {
+  cache: "no-store",
+});
+
+// Page-level dynamic
+export const dynamic = "force-dynamic";
+```
+
+### Tag-Based Revalidation
+
+```tsx
+// Tag a fetch
+const posts = await fetch('https://api.example.com/posts', {
+  next: { tags: ['posts'] },
+});
+
+// Revalidate by tag (in a Server Action)
+'use server';
+import { revalidateTag } from 'next/cache';
+
+export async function createPost() {
+  await db.post.create({ ... });
+  revalidateTag('posts'); // All fetches tagged 'posts' refetch
+}
+```
+
+## Parallel vs Sequential Fetching
+
+### Parallel (preferred)
+
+```tsx
+async function Dashboard() {
+  // Both requests start simultaneously
+  const [revenue, orders, customers] = await Promise.all([
+    getRevenue(),
+    getRecentOrders(),
+    getCustomerCount(),
+  ]);
+
+  return (
+    <div>
+      <RevenueChart data={revenue} />
+      <OrderList orders={orders} />
+      <CustomerCount count={customers} />
+    </div>
+  );
+}
+```
+
+### Sequential (when dependent)
+
+```tsx
+async function UserPosts({ userId }: { userId: string }) {
+  // Must get user first to know their preferences
+  const user = await getUser(userId);
+  // Then fetch posts based on user preferences
+  const posts = await getPosts({ category: user.preferredCategory });
+
+  return <PostList posts={posts} />;
+}
+```
+
+### Streaming with Suspense (best of both)
+
+```tsx
+import { Suspense } from "react";
+
+export default function Dashboard() {
+  return (
+    <div>
+      {/* Each section loads independently */}
+      <Suspense fallback={<Skeleton />}>
+        <Revenue />
+      </Suspense>
+      <Suspense fallback={<Skeleton />}>
+        <RecentOrders />
+      </Suspense>
+      <Suspense fallback={<Skeleton />}>
+        <TopProducts />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+## Client-Side Fetching
+
+### SWR
+
+```tsx
+"use client";
+
+import useSWR from "swr";
+
+const fetcher = (url: string) => fetch(url).then((r) => r.json());
+
+export function LivePrice({ productId }: { productId: string }) {
+  const { data, error, isLoading } = useSWR(
+    `/api/products/${productId}/price`,
+    fetcher,
+    { refreshInterval: 5000 }, // Poll every 5s
+  );
+
+  if (isLoading) return <PriceSkeleton />;
+  if (error) return <span>Error loading price</span>;
+  return <span>${data.price}</span>;
+}
+```
+
+### React Query (TanStack Query)
+
+```tsx
+"use client";
+
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+
+export function TodoList() {
+  const queryClient = useQueryClient();
+
+  const { data: todos, isLoading } = useQuery({
+    queryKey: ["todos"],
+    queryFn: () => fetch("/api/todos").then((r) => r.json()),
+  });
+
+  const mutation = useMutation({
+    mutationFn: (newTodo: string) =>
+      fetch("/api/todos", {
+        method: "POST",
+        body: JSON.stringify({ title: newTodo }),
+      }),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["todos"] }),
+  });
+
+  if (isLoading) return <Loading />;
+  return (
+    <ul>
+      {todos.map((todo) => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## When to Use What
+
+| Scenario                       | Approach                                            |
+| ------------------------------ | --------------------------------------------------- |
+| Static content (blog, docs)    | Server Component + `force-cache`                    |
+| Semi-static (product catalog)  | Server Component + `revalidate: 60`                 |
+| User-specific data             | Server Component + `no-store` + auth check          |
+| Real-time updates              | Client Component + SWR/React Query with polling     |
+| Infinite scroll                | Client Component + React Query `useInfiniteQuery`   |
+| Form submission result         | Server Action + `revalidatePath`/`revalidateTag`    |
+| Dashboard with mixed freshness | Suspense boundaries with different cache strategies |
+
+## Error Handling
+
+```tsx
+// error.tsx — automatic error boundary
+"use client";
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div>
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+## Request Deduplication
+
+Next.js automatically deduplicates `fetch` requests with the same URL and options during a single render pass:
+
+```tsx
+// Both components fetch the same URL — only ONE request is made
+async function Header() {
+  const user = await fetch("/api/user"); // Request 1
+  return <nav>{user.name}</nav>;
+}
+
+async function Sidebar() {
+  const user = await fetch("/api/user"); // Deduped — reuses Request 1
+  return <aside>{user.avatar}</aside>;
+}
+```
+
+For non-fetch data sources, use React `cache()`:
+
+```tsx
+import { cache } from "react";
+
+export const getUser = cache(async (id: string) => {
+  return await db.user.findUnique({ where: { id } });
+});
+```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/nextjs-developer/steering/deployment.md

@@ -0,0 +1,267 @@
+# Deployment Strategies
+
+## Vercel Deployment
+
+### Setup
+
+```bash
+# Install Vercel CLI
+npm i -g vercel
+
+# Deploy (auto-detects Next.js)
+vercel
+
+# Deploy to production
+vercel --prod
+```
+
+### Environment Variables
+
+```bash
+# Add via CLI
+vercel env add DATABASE_URL production
+vercel env add DATABASE_URL preview
+vercel env add DATABASE_URL development
+
+# Or via dashboard: Settings → Environment Variables
+```
+
+### vercel.json Configuration
+
+```json
+{
+  "framework": "nextjs",
+  "regions": ["iad1", "sfo1"],
+  "headers": [
+    {
+      "source": "/api/(.*)",
+      "headers": [{ "key": "Cache-Control", "value": "no-store" }]
+    }
+  ],
+  "redirects": [
+    {
+      "source": "/old-page",
+      "destination": "/new-page",
+      "permanent": true
+    }
+  ]
+}
+```
+
+### Preview Deployments
+
+- Every PR gets a unique preview URL automatically
+- Preview deployments use `preview` environment variables
+- Comment on PR with deployment URL
+
+## Docker Deployment
+
+### Dockerfile (multi-stage)
+
+```dockerfile
+# Stage 1: Dependencies
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --only=production
+
+# Stage 2: Build
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+# Stage 3: Production
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+EXPOSE 3000
+ENV PORT=3000
+CMD ["node", "server.js"]
+```
+
+### next.config.js for Docker
+
+```js
+module.exports = {
+  output: "standalone", // Required for Docker
+};
+```
+
+### Docker Compose
+
+```yaml
+version: "3.8"
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - DATABASE_URL=postgresql://user:pass@db:5432/mydb
+    depends_on:
+      - db
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: pass
+      POSTGRES_DB: mydb
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+volumes:
+  pgdata:
+```
+
+## Self-Hosting (Node.js)
+
+```bash
+# Build
+npm run build
+
+# Start production server
+npm start
+# or
+node .next/standalone/server.js
+```
+
+### PM2 Process Manager
+
+```js
+// ecosystem.config.js
+module.exports = {
+  apps: [
+    {
+      name: "nextjs-app",
+      script: "node_modules/.bin/next",
+      args: "start",
+      instances: "max",
+      exec_mode: "cluster",
+      env: {
+        NODE_ENV: "production",
+        PORT: 3000,
+      },
+    },
+  ],
+};
+```
+
+```bash
+pm2 start ecosystem.config.js
+pm2 save
+pm2 startup
+```
+
+### Nginx Reverse Proxy
+
+```nginx
+server {
+    listen 80;
+    server_name myapp.com;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+    }
+
+    # Cache static assets
+    location /_next/static {
+        proxy_pass http://localhost:3000;
+        add_header Cache-Control "public, max-age=31536000, immutable";
+    }
+}
+```
+
+## Monitoring
+
+### Error Tracking (Sentry)
+
+```bash
+npx @sentry/wizard@latest -i nextjs
+```
+
+```tsx
+// sentry.client.config.ts
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  tracesSampleRate: 0.1,
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0,
+});
+```
+
+### Analytics
+
+```tsx
+// app/layout.tsx
+import { Analytics } from "@vercel/analytics/react";
+import { SpeedInsights } from "@vercel/speed-insights/next";
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+        <SpeedInsights />
+      </body>
+    </html>
+  );
+}
+```
+
+### Health Check Endpoint
+
+```tsx
+// app/api/health/route.ts
+export async function GET() {
+  try {
+    // Check database connection
+    await db.$queryRaw`SELECT 1`;
+    return Response.json({
+      status: "healthy",
+      timestamp: new Date().toISOString(),
+    });
+  } catch (e) {
+    return Response.json(
+      { status: "unhealthy", error: "Database connection failed" },
+      { status: 503 },
+    );
+  }
+}
+```
+
+## Deployment Checklist
+
+- [ ] Environment variables set for production
+- [ ] `output: 'standalone'` if using Docker
+- [ ] Error tracking configured (Sentry or similar)
+- [ ] Analytics enabled
+- [ ] Health check endpoint available
+- [ ] HTTPS configured
+- [ ] Security headers set (CSP, HSTS, etc.)
+- [ ] Caching strategy verified
+- [ ] Preview deployments working for PRs
+- [ ] Rollback plan documented