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/error-handling.md ADDED Viewed

@@ -0,0 +1,232 @@
+# Error Handling
+Handle errors gracefully in Next.js applications.
+Reference: https://nextjs.org/docs/app/getting-started/error-handling
+## Error Boundaries
+### `error.tsx`
+Catches errors in a route segment and its children:
+```tsx
+"use client";
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={() => reset()}>Try again</button>
+    </div>
+  );
+}
+```
+**Important:** `error.tsx` must be a Client Component.
+### `global-error.tsx`
+Catches errors in root layout:
+```tsx
+"use client";
+export default function GlobalError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <html>
+      <body>
+        <h2>Something went wrong!</h2>
+        <button onClick={() => reset()}>Try again</button>
+      </body>
+    </html>
+  );
+}
+```
+**Important:** Must include `<html>` and `<body>` tags.
+## Server Actions: Navigation API Gotcha
+**Do NOT wrap navigation APIs in try-catch.** They throw special errors that Next.js handles internally.
+Reference: https://nextjs.org/docs/app/api-reference/functions/redirect#behavior
+```tsx
+'use server'
+import { redirect } from 'next/navigation'
+import { notFound } from 'next/navigation'
+// Bad: try-catch catches the navigation "error"
+async function createPost(formData: FormData) {
+  try {
+    const post = await db.post.create({ ... })
+    redirect(`/posts/${post.id}`)  // This throws!
+  } catch (error) {
+    // redirect() throw is caught here - navigation fails!
+    return { error: 'Failed to create post' }
+  }
+}
+// Good: Call navigation APIs outside try-catch
+async function createPost(formData: FormData) {
+  let post
+  try {
+    post = await db.post.create({ ... })
+  } catch (error) {
+    return { error: 'Failed to create post' }
+  }
+  redirect(`/posts/${post.id}`)  // Outside try-catch
+}
+// Good: Re-throw navigation errors
+async function createPost(formData: FormData) {
+  try {
+    const post = await db.post.create({ ... })
+    redirect(`/posts/${post.id}`)
+  } catch (error) {
+    if (error instanceof Error && error.message === 'NEXT_REDIRECT') {
+      throw error  // Re-throw navigation errors
+    }
+    return { error: 'Failed to create post' }
+  }
+}
+```
+Same applies to:
+- `redirect()` - 307 temporary redirect
+- `permanentRedirect()` - 308 permanent redirect
+- `notFound()` - 404 not found
+- `forbidden()` - 403 forbidden
+- `unauthorized()` - 401 unauthorized
+Use `unstable_rethrow()` to re-throw these errors in catch blocks:
+```tsx
+import { unstable_rethrow } from "next/navigation";
+async function action() {
+  try {
+    // ...
+    redirect("/success");
+  } catch (error) {
+    unstable_rethrow(error); // Re-throws Next.js internal errors
+    return { error: "Something went wrong" };
+  }
+}
+```
+## Redirects
+```tsx
+import { redirect, permanentRedirect } from "next/navigation";
+// 307 Temporary - use for most cases
+redirect("/new-path");
+// 308 Permanent - use for URL migrations (cached by browsers)
+permanentRedirect("/new-url");
+```
+## Auth Errors
+Trigger auth-related error pages:
+```tsx
+import { forbidden, unauthorized } from "next/navigation";
+async function Page() {
+  const session = await getSession();
+  if (!session) {
+    unauthorized(); // Renders unauthorized.tsx (401)
+  }
+  if (!session.hasAccess) {
+    forbidden(); // Renders forbidden.tsx (403)
+  }
+  return <Dashboard />;
+}
+```
+Create corresponding error pages:
+```tsx
+// app/forbidden.tsx
+export default function Forbidden() {
+  return <div>You don't have access to this resource</div>;
+}
+// app/unauthorized.tsx
+export default function Unauthorized() {
+  return <div>Please log in to continue</div>;
+}
+```
+## Not Found
+### `not-found.tsx`
+Custom 404 page for a route segment:
+```tsx
+export default function NotFound() {
+  return (
+    <div>
+      <h2>Not Found</h2>
+      <p>Could not find the requested resource</p>
+    </div>
+  );
+}
+```
+### Triggering Not Found
+```tsx
+import { notFound } from "next/navigation";
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  const post = await getPost(id);
+  if (!post) {
+    notFound(); // Renders closest not-found.tsx
+  }
+  return <div>{post.title}</div>;
+}
+```
+## Error Hierarchy
+Errors bubble up to the nearest error boundary:
+```
+app/
+├── error.tsx           # Catches errors from all children
+├── blog/
+│   ├── error.tsx       # Catches errors in /blog/*
+│   └── [slug]/
+│       ├── error.tsx   # Catches errors in /blog/[slug]
+│       └── page.tsx
+└── layout.tsx          # Errors here go to global-error.tsx
+```

package/.merlin-core/skills/general/next-best-practices/references/file-conventions.md ADDED Viewed

@@ -0,0 +1,141 @@
+# File Conventions
+Next.js App Router uses file-based routing with special file conventions.
+## Project Structure
+Reference: https://nextjs.org/docs/app/getting-started/project-structure
+```
+app/
+├── layout.tsx          # Root layout (required)
+├── page.tsx            # Home page (/)
+├── loading.tsx         # Loading UI
+├── error.tsx           # Error UI
+├── not-found.tsx       # 404 UI
+├── global-error.tsx    # Global error UI
+├── route.ts            # API endpoint
+├── template.tsx        # Re-rendered layout
+├── default.tsx         # Parallel route fallback
+├── blog/
+│   ├── page.tsx        # /blog
+│   └── [slug]/
+│       └── page.tsx    # /blog/:slug
+└── (group)/            # Route group (no URL impact)
+    └── page.tsx
+```
+## Special Files
+| File            | Purpose                                  |
+| --------------- | ---------------------------------------- |
+| `page.tsx`      | UI for a route segment                   |
+| `layout.tsx`    | Shared UI for segment and children       |
+| `loading.tsx`   | Loading UI (Suspense boundary)           |
+| `error.tsx`     | Error UI (Error boundary)                |
+| `not-found.tsx` | 404 UI                                   |
+| `route.ts`      | API endpoint                             |
+| `template.tsx`  | Like layout but re-renders on navigation |
+| `default.tsx`   | Fallback for parallel routes             |
+## Route Segments
+```
+app/
+├── blog/               # Static segment: /blog
+├── [slug]/             # Dynamic segment: /:slug
+├── [...slug]/          # Catch-all: /a/b/c
+├── [[...slug]]/        # Optional catch-all: / or /a/b/c
+└── (marketing)/        # Route group (ignored in URL)
+```
+## Parallel Routes
+```
+app/
+├── @analytics/
+│   └── page.tsx
+├── @sidebar/
+│   └── page.tsx
+└── layout.tsx          # Receives { analytics, sidebar } as props
+```
+## Intercepting Routes
+```
+app/
+├── feed/
+│   └── page.tsx
+├── @modal/
+│   └── (.)photo/[id]/  # Intercepts /photo/[id] from /feed
+│       └── page.tsx
+└── photo/[id]/
+    └── page.tsx
+```
+Conventions:
+- `(.)` - same level
+- `(..)` - one level up
+- `(..)(..)` - two levels up
+- `(...)` - from root
+## Private Folders
+```
+app/
+├── _components/        # Private folder (not a route)
+│   └── Button.tsx
+└── page.tsx
+```
+Prefix with `_` to exclude from routing.
+## Middleware / Proxy
+### Next.js 14-15: `middleware.ts`
+```ts
+// middleware.ts (root of project)
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+export function middleware(request: NextRequest) {
+  // Auth, redirects, rewrites, etc.
+  return NextResponse.next();
+}
+export const config = {
+  matcher: ["/dashboard/:path*", "/api/:path*"],
+};
+```
+### Next.js 16+: `proxy.ts`
+Renamed for clarity - same capabilities, different names:
+```ts
+// proxy.ts (root of project)
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+export function proxy(request: NextRequest) {
+  // Same logic as middleware
+  return NextResponse.next();
+}
+export const proxyConfig = {
+  matcher: ["/dashboard/:path*", "/api/:path*"],
+};
+```
+| Version | File            | Export         | Config        |
+| ------- | --------------- | -------------- | ------------- |
+| v14-15  | `middleware.ts` | `middleware()` | `config`      |
+| v16+    | `proxy.ts`      | `proxy()`      | `proxyConfig` |
+**Migration**: Run `npx @next/codemod@latest upgrade` to auto-rename.
+## File Conventions Reference
+Reference: https://nextjs.org/docs/app/api-reference/file-conventions

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

@@ -0,0 +1,257 @@
+# Font Optimization
+Use `next/font` for automatic font optimization with zero layout shift.
+## Google Fonts
+```tsx
+// app/layout.tsx
+import { Inter } from "next/font/google";
+const inter = Inter({ subsets: ["latin"] });
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" className={inter.className}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+## Multiple Fonts
+```tsx
+import { Inter, Roboto_Mono } from "next/font/google";
+const inter = Inter({
+  subsets: ["latin"],
+  variable: "--font-inter",
+});
+const robotoMono = Roboto_Mono({
+  subsets: ["latin"],
+  variable: "--font-roboto-mono",
+});
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+Use in CSS:
+```css
+body {
+  font-family: var(--font-inter);
+}
+code {
+  font-family: var(--font-roboto-mono);
+}
+```
+## Font Weights and Styles
+```tsx
+// Single weight
+const inter = Inter({
+  subsets: ["latin"],
+  weight: "400",
+});
+// Multiple weights
+const inter = Inter({
+  subsets: ["latin"],
+  weight: ["400", "500", "700"],
+});
+// Variable font (recommended) - includes all weights
+const inter = Inter({
+  subsets: ["latin"],
+  // No weight needed - variable fonts support all weights
+});
+// With italic
+const inter = Inter({
+  subsets: ["latin"],
+  style: ["normal", "italic"],
+});
+```
+## Local Fonts
+```tsx
+import localFont from "next/font/local";
+const myFont = localFont({
+  src: "./fonts/MyFont.woff2",
+});
+// Multiple files for different weights
+const myFont = localFont({
+  src: [
+    {
+      path: "./fonts/MyFont-Regular.woff2",
+      weight: "400",
+      style: "normal",
+    },
+    {
+      path: "./fonts/MyFont-Bold.woff2",
+      weight: "700",
+      style: "normal",
+    },
+  ],
+});
+// Variable font
+const myFont = localFont({
+  src: "./fonts/MyFont-Variable.woff2",
+  variable: "--font-my-font",
+});
+```
+## Tailwind CSS Integration
+```tsx
+// app/layout.tsx
+import { Inter } from "next/font/google";
+const inter = Inter({
+  subsets: ["latin"],
+  variable: "--font-inter",
+});
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className={inter.variable}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+```js
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ["var(--font-inter)"],
+      },
+    },
+  },
+};
+```
+## Preloading Subsets
+Only load needed character subsets:
+```tsx
+// Latin only (most common)
+const inter = Inter({ subsets: ["latin"] });
+// Multiple subsets
+const inter = Inter({ subsets: ["latin", "latin-ext", "cyrillic"] });
+```
+## Display Strategy
+Control font loading behavior:
+```tsx
+const inter = Inter({
+  subsets: ["latin"],
+  display: "swap", // Default - shows fallback, swaps when loaded
+});
+// Options:
+// 'auto' - browser decides
+// 'block' - short block period, then swap
+// 'swap' - immediate fallback, swap when ready (recommended)
+// 'fallback' - short block, short swap, then fallback
+// 'optional' - short block, no swap (use if font is optional)
+```
+## Don't Use Manual Font Links
+Always use `next/font` instead of `<link>` tags for Google Fonts.
+```tsx
+// Bad: Manual link tag (blocks rendering, no optimization)
+<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
+// Bad: Missing display and preconnect
+<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
+// Good: Use next/font (self-hosted, zero layout shift)
+import { Inter } from 'next/font/google'
+const inter = Inter({ subsets: ['latin'] })
+```
+## Common Mistakes
+```tsx
+// Bad: Importing font in every component
+// components/Button.tsx
+import { Inter } from 'next/font/google'
+const inter = Inter({ subsets: ['latin'] }) // Creates new instance each time!
+// Good: Import once in layout, use CSS variable
+// app/layout.tsx
+const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
+// Bad: Using @import in CSS (blocks rendering)
+/* globals.css */
+@import url('https://fonts.googleapis.com/css2?family=Inter');
+// Good: Use next/font (self-hosted, no network request)
+import { Inter } from 'next/font/google'
+// Bad: Loading all weights when only using a few
+const inter = Inter({ subsets: ['latin'] }) // Loads all weights
+// Good: Specify only needed weights (for non-variable fonts)
+const inter = Inter({ subsets: ['latin'], weight: ['400', '700'] })
+// Bad: Missing subset - loads all characters
+const inter = Inter({})
+// Good: Always specify subset
+const inter = Inter({ subsets: ['latin'] })
+```
+## Font in Specific Components
+```tsx
+// For component-specific fonts, export from a shared file
+// lib/fonts.ts
+import { Inter, Playfair_Display } from "next/font/google";
+export const inter = Inter({ subsets: ["latin"], variable: "--font-inter" });
+export const playfair = Playfair_Display({
+  subsets: ["latin"],
+  variable: "--font-playfair",
+});
+// components/Heading.tsx
+import { playfair } from "@/lib/fonts";
+export function Heading({ children }) {
+  return <h1 className={playfair.className}>{children}</h1>;
+}
+```