npm - @caoscompanybr/merlin - Versions diffs - 3.5.0 - Mend

@caoscompanybr/merlin 3.5.0

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 (762) hide show

package/.merlin-core/skills/general/next-best-practices/references/parallel-routes.md ADDED Viewed

@@ -0,0 +1,298 @@
+# Parallel & Intercepting Routes
+Parallel routes render multiple pages in the same layout. Intercepting routes show a different UI when navigating from within your app vs direct URL access. Together they enable modal patterns.
+## File Structure
+```
+app/
+├── @modal/                    # Parallel route slot
+│   ├── default.tsx            # Required! Returns null
+│   ├── (.)photos/             # Intercepts /photos/*
+│   │   └── [id]/
+│   │       └── page.tsx       # Modal content
+│   └── [...]catchall/         # Optional: catch unmatched
+│       └── page.tsx
+├── photos/
+│   └── [id]/
+│       └── page.tsx           # Full page (direct access)
+├── layout.tsx                 # Renders both children and @modal
+└── page.tsx
+```
+## Step 1: Root Layout with Slot
+```tsx
+// app/layout.tsx
+export default function RootLayout({
+  children,
+  modal,
+}: {
+  children: React.ReactNode;
+  modal: React.ReactNode;
+}) {
+  return (
+    <html>
+      <body>
+        {children}
+        {modal}
+      </body>
+    </html>
+  );
+}
+```
+## Step 2: Default File (Critical!)
+**Every parallel route slot MUST have a `default.tsx`** to prevent 404s on hard navigation.
+```tsx
+// app/@modal/default.tsx
+export default function Default() {
+  return null;
+}
+```
+Without this file, refreshing any page will 404 because Next.js can't determine what to render in the `@modal` slot.
+## Step 3: Intercepting Route (Modal)
+The `(.)` prefix intercepts routes at the same level.
+```tsx
+// app/@modal/(.)photos/[id]/page.tsx
+import { Modal } from "@/components/modal";
+export default async function PhotoModal({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  const photo = await getPhoto(id);
+  return (
+    <Modal>
+      <img src={photo.url} alt={photo.title} />
+    </Modal>
+  );
+}
+```
+## Step 4: Full Page (Direct Access)
+```tsx
+// app/photos/[id]/page.tsx
+export default async function PhotoPage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  const photo = await getPhoto(id);
+  return (
+    <div className="full-page">
+      <img src={photo.url} alt={photo.title} />
+      <h1>{photo.title}</h1>
+    </div>
+  );
+}
+```
+## Step 5: Modal Component with Correct Closing
+**Critical: Use `router.back()` to close modals, NOT `router.push()` or `<Link>`.**
+```tsx
+// components/modal.tsx
+"use client";
+import { useRouter } from "next/navigation";
+import { useCallback, useEffect, useRef } from "react";
+export function Modal({ children }: { children: React.ReactNode }) {
+  const router = useRouter();
+  const overlayRef = useRef<HTMLDivElement>(null);
+  // Close on escape key
+  useEffect(() => {
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key === "Escape") {
+        router.back(); // Correct
+      }
+    }
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [router]);
+  // Close on overlay click
+  const handleOverlayClick = useCallback(
+    (e: React.MouseEvent) => {
+      if (e.target === overlayRef.current) {
+        router.back(); // Correct
+      }
+    },
+    [router],
+  );
+  return (
+    <div
+      ref={overlayRef}
+      onClick={handleOverlayClick}
+      className="fixed inset-0 bg-black/50 flex items-center justify-center z-50"
+    >
+      <div className="bg-white rounded-lg p-6 max-w-2xl w-full mx-4">
+        <button
+          onClick={() => router.back()} // Correct!
+          className="absolute top-4 right-4"
+        >
+          Close
+        </button>
+        {children}
+      </div>
+    </div>
+  );
+}
+```
+### Why NOT `router.push('/')` or `<Link href="/">`?
+Using `push` or `Link` to "close" a modal:
+1. Adds a new history entry (back button shows modal again)
+2. Doesn't properly clear the intercepted route
+3. Can cause the modal to flash or persist unexpectedly
+`router.back()` correctly:
+1. Removes the intercepted route from history
+2. Returns to the previous page
+3. Properly unmounts the modal
+## Route Matcher Reference
+Matchers match **route segments**, not filesystem paths:
+| Matcher    | Matches       | Example                                                               |
+| ---------- | ------------- | --------------------------------------------------------------------- |
+| `(.)`      | Same level    | `@modal/(.)photos` intercepts `/photos`                               |
+| `(..)`     | One level up  | `@modal/(..)settings` from `/dashboard/@modal` intercepts `/settings` |
+| `(..)(..)` | Two levels up | Rarely used                                                           |
+| `(...)`    | From root     | `@modal/(...)photos` intercepts `/photos` from anywhere               |
+**Common mistake**: Thinking `(..)` means "parent folder" - it means "parent route segment".
+## Handling Hard Navigation
+When users directly visit `/photos/123` (bookmark, refresh, shared link):
+- The intercepting route is bypassed
+- The full `photos/[id]/page.tsx` renders
+- Modal doesn't appear (expected behavior)
+If you want the modal to appear on direct access too, you need additional logic:
+```tsx
+// app/photos/[id]/page.tsx
+import { Modal } from "@/components/modal";
+export default async function PhotoPage({ params }) {
+  const { id } = await params;
+  const photo = await getPhoto(id);
+  // Option: Render as modal on direct access too
+  return (
+    <Modal>
+      <img src={photo.url} alt={photo.title} />
+    </Modal>
+  );
+}
+```
+## Common Gotchas
+### 1. Missing `default.tsx` → 404 on Refresh
+Every `@slot` folder needs a `default.tsx` that returns `null` (or appropriate content).
+### 2. Modal Persists After Navigation
+You're using `router.push()` instead of `router.back()`.
+### 3. Nested Parallel Routes Need Defaults Too
+If you have `@modal` inside a route group, each level needs its own `default.tsx`:
+```
+app/
+├── (marketing)/
+│   ├── @modal/
+│   │   └── default.tsx     # Needed!
+│   └── layout.tsx
+└── layout.tsx
+```
+### 4. Intercepted Route Shows Wrong Content
+Check your matcher:
+- `(.)photos` intercepts `/photos` from the same route level
+- If your `@modal` is in `app/dashboard/@modal`, use `(.)photos` to intercept `/dashboard/photos`, not `/photos`
+### 5. TypeScript Errors with `params`
+In Next.js 15+, `params` is a Promise:
+```tsx
+// Correct
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+}
+```
+## Complete Example: Photo Gallery Modal
+```
+app/
+├── @modal/
+│   ├── default.tsx
+│   └── (.)photos/
+│       └── [id]/
+│           └── page.tsx
+├── photos/
+│   ├── page.tsx           # Gallery grid
+│   └── [id]/
+│       └── page.tsx       # Full photo page
+├── layout.tsx
+└── page.tsx
+```
+Links in the gallery:
+```tsx
+// app/photos/page.tsx
+import Link from "next/link";
+export default async function Gallery() {
+  const photos = await getPhotos();
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      {photos.map((photo) => (
+        <Link key={photo.id} href={`/photos/${photo.id}`}>
+          <img src={photo.thumbnail} alt={photo.title} />
+        </Link>
+      ))}
+    </div>
+  );
+}
+```
+Clicking a photo → Modal opens (intercepted)
+Direct URL → Full page renders
+Refresh while modal open → Full page renders

package/.merlin-core/skills/general/next-best-practices/references/route-handlers.md ADDED Viewed

@@ -0,0 +1,146 @@
+# Route Handlers
+Create API endpoints with `route.ts` files.
+## Basic Usage
+```tsx
+// app/api/users/route.ts
+export async function GET() {
+  const users = await getUsers();
+  return Response.json(users);
+}
+export async function POST(request: Request) {
+  const body = await request.json();
+  const user = await createUser(body);
+  return Response.json(user, { status: 201 });
+}
+```
+## Supported Methods
+`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
+## GET Handler Conflicts with page.tsx
+**A `route.ts` and `page.tsx` cannot coexist in the same folder.**
+```
+app/
+├── api/
+│   └── users/
+│       └── route.ts    # /api/users
+└── users/
+    ├── page.tsx        # /users (page)
+    └── route.ts        # Warning: Conflicts with page.tsx!
+```
+If you need both a page and an API at the same path, use different paths:
+```
+app/
+├── users/
+│   └── page.tsx        # /users (page)
+└── api/
+    └── users/
+        └── route.ts    # /api/users (API)
+```
+## Environment Behavior
+Route handlers run in a **Server Component-like environment**:
+- Yes: Can use `async/await`
+- Yes: Can access `cookies()`, `headers()`
+- Yes: Can use Node.js APIs
+- No: Cannot use React hooks
+- No: Cannot use React DOM APIs
+- No: Cannot use browser APIs
+```tsx
+// Bad: This won't work - no React DOM in route handlers
+import { renderToString } from "react-dom/server";
+export async function GET() {
+  const html = renderToString(<Component />); // Error!
+  return new Response(html);
+}
+```
+## Dynamic Route Handlers
+```tsx
+// app/api/users/[id]/route.ts
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const { id } = await params;
+  const user = await getUser(id);
+  if (!user) {
+    return Response.json({ error: "Not found" }, { status: 404 });
+  }
+  return Response.json(user);
+}
+```
+## Request Helpers
+```tsx
+export async function GET(request: Request) {
+  // URL and search params
+  const { searchParams } = new URL(request.url);
+  const query = searchParams.get("q");
+  // Headers
+  const authHeader = request.headers.get("authorization");
+  // Cookies (Next.js helper)
+  const cookieStore = await cookies();
+  const token = cookieStore.get("token");
+  return Response.json({ query, token });
+}
+```
+## Response Helpers
+```tsx
+// JSON response
+return Response.json({ data });
+// With status
+return Response.json({ error: "Not found" }, { status: 404 });
+// With headers
+return Response.json(data, {
+  headers: {
+    "Cache-Control": "max-age=3600",
+  },
+});
+// Redirect
+return Response.redirect(new URL("/login", request.url));
+// Stream
+return new Response(stream, {
+  headers: { "Content-Type": "text/event-stream" },
+});
+```
+## When to Use Route Handlers vs Server Actions
+| Use Case                 | Route Handlers | Server Actions |
+| ------------------------ | -------------- | -------------- |
+| Form submissions         | No             | Yes            |
+| Data mutations from UI   | No             | Yes            |
+| Third-party webhooks     | Yes            | No             |
+| External API consumption | Yes            | No             |
+| Public REST API          | Yes            | No             |
+| File uploads             | Both work      | Both work      |
+**Prefer Server Actions** for mutations triggered from your UI.
+**Use Route Handlers** for external integrations and public APIs.

package/.merlin-core/skills/general/next-best-practices/references/rsc-boundaries.md ADDED Viewed

@@ -0,0 +1,164 @@
+# RSC Boundaries
+Detect and prevent invalid patterns when crossing Server/Client component boundaries.
+## Detection Rules
+### 1. Async Client Components Are Invalid
+Client components **cannot** be async functions. Only Server Components can be async.
+**Detect:** File has `'use client'` AND component is `async function` or returns `Promise`
+```tsx
+// Bad: async client component
+"use client";
+export default async function UserProfile() {
+  const user = await getUser(); // Cannot await in client component
+  return <div>{user.name}</div>;
+}
+// Good: Remove async, fetch data in parent server component
+// page.tsx (server component - no 'use client')
+export default async function Page() {
+  const user = await getUser();
+  return <UserProfile user={user} />;
+}
+// UserProfile.tsx (client component)
+("use client");
+export function UserProfile({ user }: { user: User }) {
+  return <div>{user.name}</div>;
+}
+```
+```tsx
+// Bad: async arrow function client component
+"use client";
+const Dashboard = async () => {
+  const data = await fetchDashboard();
+  return <div>{data}</div>;
+};
+// Good: Fetch in server component, pass data down
+```
+### 2. Non-Serializable Props to Client Components
+Props passed from Server → Client must be JSON-serializable.
+**Detect:** Server component passes these to a client component:
+- Functions (except Server Actions with `'use server'`)
+- `Date` objects
+- `Map`, `Set`, `WeakMap`, `WeakSet`
+- Class instances
+- `Symbol` (unless globally registered)
+- Circular references
+```tsx
+// Bad: Function prop
+// page.tsx (server)
+export default function Page() {
+  const handleClick = () => console.log("clicked");
+  return <ClientButton onClick={handleClick} />;
+}
+// Good: Define function inside client component
+// ClientButton.tsx
+("use client");
+export function ClientButton() {
+  const handleClick = () => console.log("clicked");
+  return <button onClick={handleClick}>Click</button>;
+}
+```
+```tsx
+// Bad: Date object (silently becomes string, then crashes)
+// page.tsx (server)
+export default async function Page() {
+  const post = await getPost();
+  return <PostCard createdAt={post.createdAt} />; // Date object
+}
+// PostCard.tsx (client) - will crash on .getFullYear()
+("use client");
+export function PostCard({ createdAt }: { createdAt: Date }) {
+  return <span>{createdAt.getFullYear()}</span>; // Runtime error!
+}
+// Good: Serialize to string on server
+// page.tsx (server)
+export default async function Page() {
+  const post = await getPost();
+  return <PostCard createdAt={post.createdAt.toISOString()} />;
+}
+// PostCard.tsx (client)
+("use client");
+export function PostCard({ createdAt }: { createdAt: string }) {
+  const date = new Date(createdAt);
+  return <span>{date.getFullYear()}</span>;
+}
+```
+```tsx
+// Bad: Class instance
+const user = new UserModel(data)
+<ClientProfile user={user} /> // Methods will be stripped
+// Good: Pass plain object
+const user = await getUser()
+<ClientProfile user={{ id: user.id, name: user.name }} />
+```
+```tsx
+// Bad: Map/Set
+<ClientComponent items={new Map([['a', 1]])} />
+// Good: Convert to array/object
+<ClientComponent items={Object.fromEntries(map)} />
+<ClientComponent items={Array.from(set)} />
+```
+### 3. Server Actions Are the Exception
+Functions marked with `'use server'` CAN be passed to client components.
+```tsx
+// Valid: Server Action can be passed
+// actions.ts
+"use server";
+export async function submitForm(formData: FormData) {
+  // server-side logic
+}
+// page.tsx (server)
+import { submitForm } from "./actions";
+export default function Page() {
+  return <ClientForm onSubmit={submitForm} />; // OK!
+}
+// ClientForm.tsx (client)
+("use client");
+export function ClientForm({
+  onSubmit,
+}: {
+  onSubmit: (data: FormData) => Promise<void>;
+}) {
+  return <form action={onSubmit}>...</form>;
+}
+```
+## Quick Reference
+| Pattern                           | Valid? | Fix                                   |
+| --------------------------------- | ------ | ------------------------------------- |
+| `'use client'` + `async function` | No     | Fetch in server parent, pass data     |
+| Pass `() => {}` to client         | No     | Define in client or use server action |
+| Pass `new Date()` to client       | No     | Use `.toISOString()`                  |
+| Pass `new Map()` to client        | No     | Convert to object/array               |
+| Pass class instance to client     | No     | Pass plain object                     |
+| Pass server action to client      | Yes    | -                                     |
+| Pass `string/number/boolean`      | Yes    | -                                     |
+| Pass plain object/array           | Yes    | -                                     |

package/.merlin-core/skills/general/next-best-practices/references/runtime-selection.md ADDED Viewed

@@ -0,0 +1,40 @@
+# Runtime Selection
+## Use Node.js Runtime by Default
+Use the default Node.js runtime for new routes and pages. Only use Edge runtime if the project already uses it or there's a specific requirement.
+```tsx
+// Good: Default - no runtime config needed (uses Node.js)
+export default function Page() { ... }
+// Caution: Only if already used in project or specifically required
+export const runtime = 'edge'
+```
+## When to Use Each
+### Node.js Runtime (Default)
+- Full Node.js API support
+- File system access (`fs`)
+- Full `crypto` support
+- Database connections
+- Most npm packages work
+### Edge Runtime
+- Only for specific edge-location latency requirements
+- Limited API (no `fs`, limited `crypto`)
+- Smaller cold start
+- Geographic distribution needs
+## Detection
+**Before adding `runtime = 'edge'`**, check:
+1. Does the project already use Edge runtime?
+2. Is there a specific latency requirement?
+3. Are all dependencies Edge-compatible?
+If unsure, use Node.js runtime.