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/cursor/skills/nextjs-developer/steering/server-components.md ADDED Viewed

@@ -0,0 +1,252 @@
+# Server Components & Client Components
+## Component Types Decision Tree
+```
+Does the component need...
+  Browser APIs (window, document)?     → Client Component
+  Event handlers (onClick, onChange)?   → Client Component
+  React hooks (useState, useEffect)?   → Client Component
+  None of the above?                   → Server Component (default)
+```
+## Server Components (Default)
+Server Components run only on the server. They can:
+- Fetch data directly (no API layer needed)
+- Access backend resources (DB, filesystem)
+- Keep sensitive data on server (tokens, keys)
+- Reduce client bundle size
+```tsx
+// No directive needed — server by default
+import { db } from "@/lib/db";
+async function ProductList() {
+  const products = await db.product.findMany();
+  return (
+    <ul>
+      {products.map((product) => (
+        <li key={product.id}>
+          <h2>{product.name}</h2>
+          <p>${product.price}</p>
+          <AddToCartButton productId={product.id} /> {/* Client Component */}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+### Server Component Rules
+- Cannot use hooks (`useState`, `useEffect`, etc.)
+- Cannot use browser APIs
+- Cannot use event handlers
+- Cannot use Context providers (but can pass data to Client Components)
+- CAN import and render Client Components
+- CAN pass serializable props to Client Components
+## Client Components
+```tsx
+"use client"; // Must be at the top of the file
+import { useState, useTransition } from "react";
+export function AddToCartButton({ productId }: { productId: string }) {
+  const [isPending, startTransition] = useTransition();
+  const handleAdd = () => {
+    startTransition(async () => {
+      await addToCart(productId);
+    });
+  };
+  return (
+    <button onClick={handleAdd} disabled={isPending}>
+      {isPending ? "Adding..." : "Add to Cart"}
+    </button>
+  );
+}
+```
+### Client Component Rules
+- `'use client'` marks the boundary — all imports become client
+- Keep `'use client'` as deep in the tree as possible (leaf components)
+- Can render Server Components passed as `children` or props
+- Cannot `import` a Server Component directly
+## Composition Patterns
+### Pattern: Server wrapper, Client leaf
+```tsx
+// Server Component — fetches data
+async function ProductPage({ params }: { params: { id: string } }) {
+  const product = await getProduct(params.id);
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <p>{product.description}</p>
+      {/* Client Component only where interactivity is needed */}
+      <PriceSelector variants={product.variants} />
+      <AddToCartButton productId={product.id} />
+    </div>
+  );
+}
+```
+### Pattern: Passing Server Components as children
+```tsx
+// Client Component
+"use client";
+export function Sidebar({ children }: { children: React.ReactNode }) {
+  const [isOpen, setIsOpen] = useState(true);
+  return isOpen ? <aside>{children}</aside> : null;
+}
+// Server Component — passes server content through client
+export default function Layout({ children }) {
+  return (
+    <Sidebar>
+      <NavLinks /> {/* This is a Server Component rendered inside Client */}
+    </Sidebar>
+  );
+}
+```
+### Pattern: Context with Server Components
+```tsx
+// providers.tsx — Client Component
+"use client";
+import { ThemeProvider } from "next-themes";
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>;
+}
+// layout.tsx — Server Component
+import { Providers } from "./providers";
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+## Streaming SSR & Suspense
+### Loading UI with Suspense
+```tsx
+import { Suspense } from "react";
+export default function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      {/* Each section streams independently */}
+      <Suspense fallback={<RevenueChartSkeleton />}>
+        <RevenueChart />
+      </Suspense>
+      <Suspense fallback={<RecentOrdersSkeleton />}>
+        <RecentOrders />
+      </Suspense>
+    </div>
+  );
+}
+```
+### Streaming with loading.tsx
+```tsx
+// app/dashboard/loading.tsx
+// Automatically wraps page.tsx in Suspense
+export default function Loading() {
+  return <DashboardSkeleton />;
+}
+```
+### Parallel Data Fetching
+```tsx
+// Fetch in parallel, not sequentially
+async function Dashboard() {
+  // ✅ Parallel — both start immediately
+  const [revenue, orders] = await Promise.all([
+    getRevenue(),
+    getRecentOrders(),
+  ]);
+  return (
+    <div>
+      <RevenueChart data={revenue} />
+      <OrderList orders={orders} />
+    </div>
+  );
+}
+```
+## Partial Prerendering (PPR)
+PPR combines static and dynamic content in a single route:
+```tsx
+// next.config.js
+module.exports = {
+  experimental: { ppr: true },
+};
+// Static shell renders immediately, dynamic parts stream in
+export default function ProductPage({ params }) {
+  return (
+    <div>
+      {/* Static — rendered at build time */}
+      <ProductHeader />
+      <ProductDescription />
+      {/* Dynamic — streams in */}
+      <Suspense fallback={<PriceSkeleton />}>
+        <DynamicPrice productId={params.id} />
+      </Suspense>
+      <Suspense fallback={<ReviewsSkeleton />}>
+        <Reviews productId={params.id} />
+      </Suspense>
+    </div>
+  );
+}
+```
+## Common Mistakes
+```tsx
+// ❌ Don't import server-only code in client components
+"use client";
+import { db } from "@/lib/db"; // This will fail
+// ❌ Don't use hooks in server components
+async function Page() {
+  const [state, setState] = useState(0); // Error
+}
+// ❌ Don't make everything a client component
+("use client"); // Don't put this on layout.tsx or page.tsx unless needed
+// ✅ Use 'server-only' package to prevent accidental client imports
+import "server-only";
+export async function getSecretData() {
+  return process.env.SECRET_KEY;
+}
+```

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/nextjs-developer/steering/testing.md ADDED Viewed

@@ -0,0 +1,329 @@
+# Testing Next.js Applications
+## Testing Stack
+| Tool                      | Purpose                             |
+| ------------------------- | ----------------------------------- |
+| Jest / Vitest             | Unit tests, component tests         |
+| React Testing Library     | Component rendering and interaction |
+| Playwright                | E2E tests on real browsers          |
+| MSW (Mock Service Worker) | API mocking                         |
+## Project Setup
+### Vitest + React Testing Library
+```bash
+npm install -D vitest @vitejs/plugin-react @testing-library/react @testing-library/jest-dom jsdom
+```
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: "jsdom",
+    setupFiles: ["./tests/setup.ts"],
+    globals: true,
+  },
+  resolve: {
+    alias: { "@": new URL("./src", import.meta.url).pathname },
+  },
+});
+```
+```ts
+// tests/setup.ts
+import "@testing-library/jest-dom/vitest";
+```
+### Playwright
+```bash
+npm install -D @playwright/test
+npx playwright install
+```
+```ts
+// playwright.config.ts
+import { defineConfig, devices } from "@playwright/test";
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: "html",
+  use: {
+    baseURL: "http://localhost:3000",
+    trace: "on-first-retry",
+  },
+  projects: [
+    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+    { name: "webkit", use: { ...devices["Desktop Safari"] } },
+    { name: "mobile", use: { ...devices["iPhone 14"] } },
+  ],
+  webServer: {
+    command: "npm run dev",
+    url: "http://localhost:3000",
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+## Unit Testing
+### Testing Utility Functions
+```tsx
+// lib/utils.test.ts
+import { describe, it, expect } from "vitest";
+import { formatPrice, slugify } from "./utils";
+describe("formatPrice", () => {
+  it("should format cents to dollars", () => {
+    expect(formatPrice(1999)).toBe("$19.99");
+  });
+  it("should handle zero", () => {
+    expect(formatPrice(0)).toBe("$0.00");
+  });
+});
+describe("slugify", () => {
+  it("should convert to lowercase kebab-case", () => {
+    expect(slugify("Hello World")).toBe("hello-world");
+  });
+  it("should remove special characters", () => {
+    expect(slugify("Hello & World!")).toBe("hello-world");
+  });
+});
+```
+### Testing Server Actions
+```tsx
+// app/actions.test.ts
+import { describe, it, expect, vi } from "vitest";
+import { createPost } from "./actions";
+vi.mock("@/lib/db", () => ({
+  db: {
+    post: {
+      create: vi.fn().mockResolvedValue({ id: "1", title: "Test" }),
+    },
+  },
+}));
+describe("createPost", () => {
+  it("should create a post with valid data", async () => {
+    const formData = new FormData();
+    formData.set("title", "Test Post");
+    formData.set("content", "Test content");
+    const result = await createPost({}, formData);
+    expect(result.success).toBe(true);
+  });
+  it("should return errors for invalid data", async () => {
+    const formData = new FormData();
+    formData.set("title", ""); // Empty title
+    const result = await createPost({}, formData);
+    expect(result.errors?.title).toBeDefined();
+  });
+});
+```
+## Component Testing
+### Testing Server Components
+```tsx
+// components/ProductCard.test.tsx
+import { render, screen } from "@testing-library/react";
+import { ProductCard } from "./ProductCard";
+describe("ProductCard", () => {
+  const product = {
+    id: "1",
+    name: "Test Product",
+    price: 29.99,
+    image: "/test.jpg",
+  };
+  it("should render product name and price", () => {
+    render(<ProductCard product={product} />);
+    expect(screen.getByText("Test Product")).toBeInTheDocument();
+    expect(screen.getByText("$29.99")).toBeInTheDocument();
+  });
+  it("should render product image with alt text", () => {
+    render(<ProductCard product={product} />);
+    const img = screen.getByAltText("Test Product");
+    expect(img).toBeInTheDocument();
+  });
+});
+```
+### Testing Client Components with Interactions
+```tsx
+// components/Counter.test.tsx
+import { render, screen, fireEvent } from "@testing-library/react";
+import { Counter } from "./Counter";
+describe("Counter", () => {
+  it("should increment on click", () => {
+    render(<Counter initialCount={0} />);
+    const button = screen.getByRole("button", { name: /increment/i });
+    fireEvent.click(button);
+    expect(screen.getByText("1")).toBeInTheDocument();
+  });
+  it("should decrement on click", () => {
+    render(<Counter initialCount={5} />);
+    const button = screen.getByRole("button", { name: /decrement/i });
+    fireEvent.click(button);
+    expect(screen.getByText("4")).toBeInTheDocument();
+  });
+});
+```
+## E2E Testing with Playwright
+### Basic Navigation Test
+```tsx
+// e2e/navigation.spec.ts
+import { test, expect } from "@playwright/test";
+test("should navigate to about page", async ({ page }) => {
+  await page.goto("/");
+  await page.click("text=About");
+  await expect(page).toHaveURL("/about");
+  await expect(page.locator("h1")).toContainText("About");
+});
+```
+### Form Submission Test
+```tsx
+// e2e/contact.spec.ts
+import { test, expect } from "@playwright/test";
+test("should submit contact form", async ({ page }) => {
+  await page.goto("/contact");
+  await page.fill('[name="name"]', "John Doe");
+  await page.fill('[name="email"]', "john@example.com");
+  await page.fill('[name="message"]', "Hello!");
+  await page.click('button[type="submit"]');
+  await expect(page.locator(".success-message")).toBeVisible();
+});
+```
+### Authentication Flow
+```tsx
+// e2e/auth.spec.ts
+import { test, expect } from "@playwright/test";
+test.describe("Authentication", () => {
+  test("should login and redirect to dashboard", async ({ page }) => {
+    await page.goto("/login");
+    await page.fill('[name="email"]', "user@example.com");
+    await page.fill('[name="password"]', "password123");
+    await page.click('button[type="submit"]');
+    await expect(page).toHaveURL("/dashboard");
+    await expect(page.locator("nav")).toContainText("Welcome");
+  });
+  test("should show error for invalid credentials", async ({ page }) => {
+    await page.goto("/login");
+    await page.fill('[name="email"]', "wrong@example.com");
+    await page.fill('[name="password"]', "wrong");
+    await page.click('button[type="submit"]');
+    await expect(page.locator(".error")).toContainText("Invalid credentials");
+  });
+});
+```
+### Visual Regression
+```tsx
+// e2e/visual.spec.ts
+import { test, expect } from "@playwright/test";
+test("homepage visual regression", async ({ page }) => {
+  await page.goto("/");
+  await expect(page).toHaveScreenshot("homepage.png", {
+    maxDiffPixelRatio: 0.01,
+  });
+});
+```
+## API Mocking with MSW
+```tsx
+// tests/mocks/handlers.ts
+import { http, HttpResponse } from "msw";
+export const handlers = [
+  http.get("/api/products", () => {
+    return HttpResponse.json([
+      { id: "1", name: "Product 1", price: 19.99 },
+      { id: "2", name: "Product 2", price: 29.99 },
+    ]);
+  }),
+  http.post("/api/products", async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: "3", ...body }, { status: 201 });
+  }),
+];
+// tests/mocks/server.ts
+import { setupServer } from "msw/node";
+import { handlers } from "./handlers";
+export const server = setupServer(...handlers);
+// tests/setup.ts
+import { server } from "./mocks/server";
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+## Running Tests
+```bash
+# Unit + component tests
+npm test
+npx vitest --run
+# E2E tests
+npx playwright test
+npx playwright test --ui          # Interactive UI mode
+npx playwright test --headed      # See browser
+npx playwright show-report        # View HTML report
+# Coverage
+npx vitest --coverage
+# Update snapshots
+npx playwright test --update-snapshots
+```