@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/next-best-practices/references/data-patterns.md

@@ -0,0 +1,306 @@
+# Data Patterns
+
+Choose the right data fetching pattern for each use case.
+
+## Decision Tree
+
+```
+Need to fetch data?
+├── From a Server Component?
+│   └── Use: Fetch directly (no API needed)
+│
+├── From a Client Component?
+│   ├── Is it a mutation (POST/PUT/DELETE)?
+│   │   └── Use: Server Action
+│   └── Is it a read (GET)?
+│       └── Use: Route Handler OR pass from Server Component
+│
+├── Need external API access (webhooks, third parties)?
+│   └── Use: Route Handler
+│
+└── Need REST API for mobile app / external clients?
+    └── Use: Route Handler
+```
+
+## Pattern 1: Server Components (Preferred for Reads)
+
+Fetch data directly in Server Components - no API layer needed.
+
+```tsx
+// app/users/page.tsx
+async function UsersPage() {
+  // Direct database access - no API round-trip
+  const users = await db.user.findMany();
+
+  // Or fetch from external API
+  const posts = await fetch("https://api.example.com/posts").then((r) =>
+    r.json(),
+  );
+
+  return (
+    <ul>
+      {users.map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+**Benefits**:
+
+- No API to maintain
+- No client-server waterfall
+- Secrets stay on server
+- Direct database access
+
+## Pattern 2: Server Actions (Preferred for Mutations)
+
+Server Actions are the recommended way to handle mutations.
+
+```tsx
+// app/actions.ts
+"use server";
+
+import { revalidatePath } from "next/cache";
+
+export async function createPost(formData: FormData) {
+  const title = formData.get("title") as string;
+
+  await db.post.create({ data: { title } });
+
+  revalidatePath("/posts");
+}
+
+export async function deletePost(id: string) {
+  await db.post.delete({ where: { id } });
+
+  revalidateTag("posts");
+}
+```
+
+```tsx
+// app/posts/new/page.tsx
+import { createPost } from "@/app/actions";
+
+export default function NewPost() {
+  return (
+    <form action={createPost}>
+      <input name="title" required />
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+**Benefits**:
+
+- End-to-end type safety
+- Progressive enhancement (works without JS)
+- Automatic request handling
+- Integrated with React transitions
+
+**Constraints**:
+
+- POST only (no GET caching semantics)
+- Internal use only (no external access)
+- Cannot return non-serializable data
+
+## Pattern 3: Route Handlers (APIs)
+
+Use Route Handlers when you need a REST API.
+
+```tsx
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+// GET is cacheable
+export async function GET(request: NextRequest) {
+  const posts = await db.post.findMany();
+  return NextResponse.json(posts);
+}
+
+// POST for mutations
+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 });
+}
+```
+
+**When to use**:
+
+- External API access (mobile apps, third parties)
+- Webhooks from external services
+- GET endpoints that need HTTP caching
+- OpenAPI/Swagger documentation needed
+
+**When NOT to use**:
+
+- Internal data fetching (use Server Components)
+- Mutations from your UI (use Server Actions)
+
+## Avoiding Data Waterfalls
+
+### Problem: Sequential Fetches
+
+```tsx
+// Bad: Sequential waterfalls
+async function Dashboard() {
+  const user = await getUser(); // Wait...
+  const posts = await getPosts(); // Then wait...
+  const comments = await getComments(); // Then wait...
+
+  return <div>...</div>;
+}
+```
+
+### Solution 1: Parallel Fetching with Promise.all
+
+```tsx
+// Good: Parallel fetching
+async function Dashboard() {
+  const [user, posts, comments] = await Promise.all([
+    getUser(),
+    getPosts(),
+    getComments(),
+  ]);
+
+  return <div>...</div>;
+}
+```
+
+### Solution 2: Streaming with Suspense
+
+```tsx
+// Good: Show content progressively
+import { Suspense } from "react";
+
+async function Dashboard() {
+  return (
+    <div>
+      <Suspense fallback={<UserSkeleton />}>
+        <UserSection />
+      </Suspense>
+      <Suspense fallback={<PostsSkeleton />}>
+        <PostsSection />
+      </Suspense>
+    </div>
+  );
+}
+
+async function UserSection() {
+  const user = await getUser(); // Fetches independently
+  return <div>{user.name}</div>;
+}
+
+async function PostsSection() {
+  const posts = await getPosts(); // Fetches independently
+  return <PostList posts={posts} />;
+}
+```
+
+### Solution 3: Preload Pattern
+
+```tsx
+// lib/data.ts
+import { cache } from "react";
+
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } });
+});
+
+export const preloadUser = (id: string) => {
+  void getUser(id); // Fire and forget
+};
+```
+
+```tsx
+// app/user/[id]/page.tsx
+import { getUser, preloadUser } from "@/lib/data";
+
+export default async function UserPage({ params }) {
+  const { id } = await params;
+
+  // Start fetching early
+  preloadUser(id);
+
+  // Do other work...
+
+  // Data likely ready by now
+  const user = await getUser(id);
+  return <div>{user.name}</div>;
+}
+```
+
+## Client Component Data Fetching
+
+When Client Components need data:
+
+### Option 1: Pass from Server Component (Preferred)
+
+```tsx
+// Server Component
+async function Page() {
+  const data = await fetchData();
+  return <ClientComponent initialData={data} />;
+}
+
+// Client Component
+("use client");
+function ClientComponent({ initialData }) {
+  const [data, setData] = useState(initialData);
+  // ...
+}
+```
+
+### Option 2: Fetch on Mount (When Necessary)
+
+```tsx
+"use client";
+import { useEffect, useState } from "react";
+
+function ClientComponent() {
+  const [data, setData] = useState(null);
+
+  useEffect(() => {
+    fetch("/api/data")
+      .then((r) => r.json())
+      .then(setData);
+  }, []);
+
+  if (!data) return <Loading />;
+  return <div>{data.value}</div>;
+}
+```
+
+### Option 3: Server Action for Reads (Works But Not Ideal)
+
+Server Actions can be called from Client Components for reads, but this is not their intended purpose:
+
+```tsx
+"use client";
+import { getData } from "./actions";
+import { useEffect, useState } from "react";
+
+function ClientComponent() {
+  const [data, setData] = useState(null);
+
+  useEffect(() => {
+    getData().then(setData);
+  }, []);
+
+  return <div>{data?.value}</div>;
+}
+```
+
+**Note**: Server Actions always use POST, so no HTTP caching. Prefer Route Handlers for cacheable reads.
+
+## Quick Reference
+
+| Pattern                | Use Case                    | HTTP Method | Caching              |
+| ---------------------- | --------------------------- | ----------- | -------------------- |
+| Server Component fetch | Internal reads              | Any         | Full Next.js caching |
+| Server Action          | Mutations, form submissions | POST only   | No                   |
+| Route Handler          | External APIs, webhooks     | Any         | GET can be cached    |
+| Client fetch to API    | Client-side reads           | Any         | HTTP cache headers   |

package/.merlin-core/skills/general/next-best-practices/references/debug-tricks.md

@@ -0,0 +1,125 @@
+# Debug Tricks
+
+Tricks to speed up debugging Next.js applications.
+
+## MCP Endpoint (Dev Server)
+
+Next.js exposes a `/_next/mcp` endpoint in development for AI-assisted debugging via MCP (Model Context Protocol).
+
+- **Next.js 16+**: Enabled by default, use `next-devtools-mcp`
+- **Next.js < 16**: Requires `experimental.mcpServer: true` in next.config.js
+
+Reference: https://nextjs.org/docs/app/guides/mcp
+
+**Important**: Find the actual port of the running Next.js dev server (check terminal output or `package.json` scripts). Don't assume port 3000.
+
+### Request Format
+
+The endpoint uses JSON-RPC 2.0 over HTTP POST:
+
+```bash
+curl -X POST http://localhost:<port>/_next/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "tools/call",
+    "params": {
+      "name": "<tool-name>",
+      "arguments": {}
+    }
+  }'
+```
+
+### Available Tools
+
+#### `get_errors`
+
+Get current errors from dev server (build errors, runtime errors with source-mapped stacks):
+
+```json
+{ "name": "get_errors", "arguments": {} }
+```
+
+#### `get_routes`
+
+Discover all routes by scanning filesystem:
+
+```json
+{ "name": "get_routes", "arguments": {} }
+// Optional: { "name": "get_routes", "arguments": { "routerType": "app" } }
+```
+
+Returns: `{ "appRouter": ["/", "/api/users/[id]", ...], "pagesRouter": [...] }`
+
+#### `get_project_metadata`
+
+Get project path and dev server URL:
+
+```json
+{ "name": "get_project_metadata", "arguments": {} }
+```
+
+Returns: `{ "projectPath": "/path/to/project", "devServerUrl": "http://localhost:3000" }`
+
+#### `get_page_metadata`
+
+Get runtime metadata about current page render (requires active browser session):
+
+```json
+{ "name": "get_page_metadata", "arguments": {} }
+```
+
+Returns segment trie data showing layouts, boundaries, and page components.
+
+#### `get_logs`
+
+Get path to Next.js development log file:
+
+```json
+{ "name": "get_logs", "arguments": {} }
+```
+
+Returns path to `<distDir>/logs/next-development.log`
+
+#### `get_server_action_by_id`
+
+Locate a Server Action by ID:
+
+```json
+{
+  "name": "get_server_action_by_id",
+  "arguments": { "actionId": "<action-id>" }
+}
+```
+
+### Example: Get Errors
+
+```bash
+curl -X POST http://localhost:<port>/_next/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"get_errors","arguments":{}}}'
+```
+
+## Rebuild Specific Routes (Next.js 16+)
+
+Use `--debug-build-paths` to rebuild only specific routes instead of the entire app:
+
+```bash
+# Rebuild a specific route
+next build --debug-build-paths "/dashboard"
+
+# Rebuild routes matching a glob
+next build --debug-build-paths "/api/*"
+
+# Dynamic routes
+next build --debug-build-paths "/blog/[slug]"
+```
+
+Use this to:
+
+- Quickly verify a build fix without full rebuild
+- Debug static generation issues for specific pages
+- Iterate faster on build errors

package/.merlin-core/skills/general/next-best-practices/references/directives.md

@@ -0,0 +1,74 @@
+# Directives
+
+## React Directives
+
+These are React directives, not Next.js specific.
+
+### `'use client'`
+
+Marks a component as a Client Component. Required for:
+
+- React hooks (`useState`, `useEffect`, etc.)
+- Event handlers (`onClick`, `onChange`)
+- Browser APIs (`window`, `localStorage`)
+
+```tsx
+"use client";
+
+import { useState } from "react";
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+
+Reference: https://react.dev/reference/rsc/use-client
+
+### `'use server'`
+
+Marks a function as a Server Action. Can be passed to Client Components.
+
+```tsx
+"use server";
+
+export async function submitForm(formData: FormData) {
+  // Runs on server
+}
+```
+
+Or inline within a Server Component:
+
+```tsx
+export default function Page() {
+  async function submit() {
+    "use server";
+    // Runs on server
+  }
+  return <form action={submit}>...</form>;
+}
+```
+
+Reference: https://react.dev/reference/rsc/use-server
+
+---
+
+## Next.js Directive
+
+### `'use cache'`
+
+Marks a function or component for caching. Part of Next.js Cache Components.
+
+```tsx
+"use cache";
+
+export async function getCachedData() {
+  return await fetchData();
+}
+```
+
+Requires `cacheComponents: true` in `next.config.ts`.
+
+For detailed usage including cache profiles, `cacheLife()`, `cacheTag()`, and `updateTag()`, see the `next-cache-components` skill.
+
+Reference: https://nextjs.org/docs/app/api-reference/directives/use-cache