npm - @cubis/foundry - Versions diffs - 0.3.10 - Mend

@cubis/foundry 0.3.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3913) hide show

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/nextjs-developer/steering/app-router.md ADDED Viewed

@@ -0,0 +1,218 @@
+# App Router Architecture
+## File Conventions
+| File            | Purpose                                                 |
+| --------------- | ------------------------------------------------------- |
+| `layout.tsx`    | Shared UI, persists across navigations, wraps children  |
+| `template.tsx`  | Like layout but re-mounts on navigation (new instance)  |
+| `page.tsx`      | Unique UI for a route, makes route publicly accessible  |
+| `loading.tsx`   | Loading UI using Suspense boundary                      |
+| `error.tsx`     | Error boundary for the segment                          |
+| `not-found.tsx` | 404 UI for the segment                                  |
+| `route.ts`      | API endpoint (cannot coexist with page.tsx in same dir) |
+## Layout Patterns
+```tsx
+// Root layout — required, wraps entire app
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+// Nested layout — wraps a segment and its children
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex">
+      <Sidebar />
+      <main className="flex-1">{children}</main>
+    </div>
+  );
+}
+```
+### Layout Rules
+- Root layout must contain `<html>` and `<body>` tags
+- Layouts do NOT re-render when navigating between child routes
+- Layouts cannot access `pathname` — use `usePathname()` in a Client Component
+- Data fetched in a layout is NOT passed to children — fetch in each segment
+## Route Groups
+Group routes without affecting the URL structure using `(folderName)`:
+```
+app/
+├── (marketing)/
+│   ├── layout.tsx      # Marketing layout
+│   ├── about/page.tsx  # /about
+│   └── blog/page.tsx   # /blog
+├── (shop)/
+│   ├── layout.tsx      # Shop layout
+│   ├── products/page.tsx  # /products
+│   └── cart/page.tsx      # /cart
+└── layout.tsx          # Root layout
+```
+Use cases:
+- Different layouts for different sections
+- Organizing routes by team or feature
+- Opting specific segments into a layout
+## Parallel Routes
+Render multiple pages simultaneously in the same layout using named slots (`@folder`):
+```tsx
+// app/layout.tsx
+export default function Layout({
+  children,
+  analytics,
+  team,
+}: {
+  children: React.ReactNode;
+  analytics: React.ReactNode;
+  team: React.ReactNode;
+}) {
+  return (
+    <>
+      {children}
+      {analytics}
+      {team}
+    </>
+  );
+}
+```
+```
+app/
+├── layout.tsx
+├── page.tsx
+├── @analytics/
+│   └── page.tsx
+└── @team/
+    └── page.tsx
+```
+### Parallel Route Rules
+- Slots are NOT route segments — `@analytics` doesn't affect the URL
+- Each slot can have its own `loading.tsx` and `error.tsx`
+- Use `default.tsx` in slots to handle unmatched routes
+## Intercepting Routes
+Intercept a route to show it in the current layout while preserving context:
+| Convention | Matches       |
+| ---------- | ------------- |
+| `(.)`      | Same level    |
+| `(..)`     | One level up  |
+| `(..)(..)` | Two levels up |
+| `(...)`    | From root     |
+```
+app/
+├── feed/
+│   ├── page.tsx
+│   └── (..)photo/[id]/page.tsx  # Intercepts /photo/[id] from /feed
+└── photo/
+    └── [id]/page.tsx            # Full page when accessed directly
+```
+Common pattern: modal on click, full page on direct URL or refresh.
+## Dynamic Routes
+```tsx
+// app/blog/[slug]/page.tsx — dynamic segment
+export default function Post({ params }: { params: { slug: string } }) {
+  return <h1>{params.slug}</h1>;
+}
+// app/shop/[...categories]/page.tsx — catch-all
+// Matches /shop/a, /shop/a/b, /shop/a/b/c
+export default function Category({
+  params,
+}: {
+  params: { categories: string[] };
+}) {
+  return <div>{params.categories.join(" > ")}</div>;
+}
+// app/shop/[[...categories]]/page.tsx — optional catch-all
+// Also matches /shop (without segments)
+```
+## Static Generation for Dynamic Routes
+```tsx
+// Generate static params at build time
+export async function generateStaticParams() {
+  const posts = await getPosts();
+  return posts.map((post) => ({ slug: post.slug }));
+}
+// dynamicParams = false → return 404 for unknown params
+export const dynamicParams = false;
+```
+## Route Handlers (API Routes)
+```tsx
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from "next/server";
+export async function GET(request: NextRequest) {
+  const posts = await db.post.findMany();
+  return NextResponse.json(posts);
+}
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const post = await db.post.create({ data: body });
+  return NextResponse.json(post, { status: 201 });
+}
+```
+### Route Handler Rules
+- Cannot coexist with `page.tsx` in the same route segment
+- Supported methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
+- `GET` handlers are cached by default when not using `Request` object
+- Use `NextRequest` for access to cookies, headers, URL search params
+## Middleware
+```tsx
+// middleware.ts (at project root)
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+export function middleware(request: NextRequest) {
+  // Auth check
+  const token = request.cookies.get("token");
+  if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
+    return NextResponse.redirect(new URL("/login", request.url));
+  }
+  return NextResponse.next();
+}
+export const config = {
+  matcher: ["/dashboard/:path*", "/api/:path*"],
+};
+```

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/nextjs-developer/steering/data-fetching.md ADDED Viewed

@@ -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 } });
+});
+```