@caoscompanybr/merlin 3.5.0

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

@@ -0,0 +1,108 @@
+# Functions
+
+Next.js function APIs.
+
+Reference: https://nextjs.org/docs/app/api-reference/functions
+
+## Navigation Hooks (Client)
+
+| Hook                        | Purpose                                                        | Reference                                                                                |
+| --------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `useRouter`                 | Programmatic navigation (`push`, `replace`, `back`, `refresh`) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-router)                   |
+| `usePathname`               | Get current pathname                                           | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-pathname)                 |
+| `useSearchParams`           | Read URL search parameters                                     | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-search-params)            |
+| `useParams`                 | Access dynamic route parameters                                | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-params)                   |
+| `useSelectedLayoutSegment`  | Active child segment (one level)                               | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segment)  |
+| `useSelectedLayoutSegments` | All active segments below layout                               | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segments) |
+| `useLinkStatus`             | Check link prefetch status                                     | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-link-status)              |
+| `useReportWebVitals`        | Report Core Web Vitals metrics                                 | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-report-web-vitals)        |
+
+## Server Functions
+
+| Function     | Purpose                                      | Reference                                                              |
+| ------------ | -------------------------------------------- | ---------------------------------------------------------------------- |
+| `cookies`    | Read/write cookies                           | [Docs](https://nextjs.org/docs/app/api-reference/functions/cookies)    |
+| `headers`    | Read request headers                         | [Docs](https://nextjs.org/docs/app/api-reference/functions/headers)    |
+| `draftMode`  | Enable preview of unpublished CMS content    | [Docs](https://nextjs.org/docs/app/api-reference/functions/draft-mode) |
+| `after`      | Run code after response finishes streaming   | [Docs](https://nextjs.org/docs/app/api-reference/functions/after)      |
+| `connection` | Wait for connection before dynamic rendering | [Docs](https://nextjs.org/docs/app/api-reference/functions/connection) |
+| `userAgent`  | Parse User-Agent header                      | [Docs](https://nextjs.org/docs/app/api-reference/functions/userAgent)  |
+
+## Generate Functions
+
+| Function                | Purpose                                 | Reference                                                                           |
+| ----------------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
+| `generateStaticParams`  | Pre-render dynamic routes at build time | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-static-params)  |
+| `generateMetadata`      | Dynamic metadata                        | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-metadata)       |
+| `generateViewport`      | Dynamic viewport config                 | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-viewport)       |
+| `generateSitemaps`      | Multiple sitemaps for large sites       | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-sitemaps)       |
+| `generateImageMetadata` | Multiple OG images per route            | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-image-metadata) |
+
+## Request/Response
+
+| Function        | Purpose                        | Reference                                                                  |
+| --------------- | ------------------------------ | -------------------------------------------------------------------------- |
+| `NextRequest`   | Extended Request with helpers  | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-request)   |
+| `NextResponse`  | Extended Response with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-response)  |
+| `ImageResponse` | Generate OG images             | [Docs](https://nextjs.org/docs/app/api-reference/functions/image-response) |
+
+## Common Examples
+
+### Navigation
+
+Use `next/link` for internal navigation instead of `<a>` tags.
+
+```tsx
+// Bad: Plain anchor tag
+<a href="/about">About</a>;
+
+// Good: Next.js Link
+import Link from "next/link";
+
+<Link href="/about">About</Link>;
+```
+
+Active link styling:
+
+```tsx
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+
+export function NavLink({ href, children }) {
+  const pathname = usePathname();
+
+  return (
+    <Link href={href} className={pathname === href ? "active" : ""}>
+      {children}
+    </Link>
+  );
+}
+```
+
+### Static Generation
+
+```tsx
+// app/blog/[slug]/page.tsx
+export async function generateStaticParams() {
+  const posts = await getPosts();
+  return posts.map((post) => ({ slug: post.slug }));
+}
+```
+
+### After Response
+
+```tsx
+import { after } from "next/server";
+
+export async function POST(request: Request) {
+  const data = await processRequest(request);
+
+  after(async () => {
+    await logAnalytics(data);
+  });
+
+  return Response.json({ success: true });
+}
+```

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

@@ -0,0 +1,88 @@
+# Hydration Errors
+
+Diagnose and fix React hydration mismatch errors.
+
+## Error Signs
+
+- "Hydration failed because the initial UI does not match"
+- "Text content does not match server-rendered HTML"
+
+## Debugging
+
+In development, click the hydration error to see the server/client diff.
+
+## Common Causes and Fixes
+
+### Browser-only APIs
+
+```tsx
+// Bad: Causes mismatch - window doesn't exist on server
+<div>{window.innerWidth}</div>;
+
+// Good: Use client component with mounted check
+("use client");
+import { useState, useEffect } from "react";
+
+export function ClientOnly({ children }: { children: React.ReactNode }) {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  return mounted ? children : null;
+}
+```
+
+### Date/Time Rendering
+
+Server and client may be in different timezones:
+
+```tsx
+// Bad: Causes mismatch
+<span>{new Date().toLocaleString()}</span>;
+
+// Good: Render on client only
+("use client");
+const [time, setTime] = useState<string>();
+useEffect(() => setTime(new Date().toLocaleString()), []);
+```
+
+### Random Values or IDs
+
+```tsx
+// Bad: Random values differ between server and client
+<div id={Math.random().toString()}>
+
+// Good: Use useId hook
+import { useId } from 'react'
+
+function Input() {
+  const id = useId()
+  return <input id={id} />
+}
+```
+
+### Invalid HTML Nesting
+
+```tsx
+// Bad: Invalid - div inside p
+<p><div>Content</div></p>
+
+// Bad: Invalid - p inside p
+<p><p>Nested</p></p>
+
+// Good: Valid nesting
+<div><p>Content</p></div>
+```
+
+### Third-party Scripts
+
+Scripts that modify DOM during hydration.
+
+```tsx
+// Good: Use next/script with afterInteractive
+import Script from "next/script";
+
+export default function Page() {
+  return (
+    <Script src="https://example.com/script.js" strategy="afterInteractive" />
+  );
+}
+```

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

@@ -0,0 +1,179 @@
+# Image Optimization
+
+Use `next/image` for automatic image optimization.
+
+## Always Use next/image
+
+```tsx
+// Bad: Avoid native img
+<img src="/hero.png" alt="Hero" />;
+
+// Good: Use next/image
+import Image from "next/image";
+<Image src="/hero.png" alt="Hero" width={800} height={400} />;
+```
+
+## Required Props
+
+Images need explicit dimensions to prevent layout shift:
+
+```tsx
+// Local images - dimensions inferred automatically
+import heroImage from './hero.png'
+<Image src={heroImage} alt="Hero" />
+
+// Remote images - must specify width/height
+<Image src="https://example.com/image.jpg" alt="Hero" width={800} height={400} />
+
+// Or use fill for parent-relative sizing
+<div style={{ position: 'relative', width: '100%', height: 400 }}>
+  <Image src="/hero.png" alt="Hero" fill style={{ objectFit: 'cover' }} />
+</div>
+```
+
+## Remote Images Configuration
+
+Remote domains must be configured in `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+  images: {
+    remotePatterns: [
+      {
+        protocol: "https",
+        hostname: "example.com",
+        pathname: "/images/**",
+      },
+      {
+        protocol: "https",
+        hostname: "*.cdn.com", // Wildcard subdomain
+      },
+    ],
+  },
+};
+```
+
+## Responsive Images
+
+Use `sizes` to tell the browser which size to download:
+
+```tsx
+// Full-width hero
+<Image
+  src="/hero.png"
+  alt="Hero"
+  fill
+  sizes="100vw"
+/>
+
+// Responsive grid (3 columns on desktop, 1 on mobile)
+<Image
+  src="/card.png"
+  alt="Card"
+  fill
+  sizes="(max-width: 768px) 100vw, 33vw"
+/>
+
+// Fixed sidebar image
+<Image
+  src="/avatar.png"
+  alt="Avatar"
+  width={200}
+  height={200}
+  sizes="200px"
+/>
+```
+
+## Blur Placeholder
+
+Prevent layout shift with placeholders:
+
+```tsx
+// Local images - automatic blur hash
+import heroImage from './hero.png'
+<Image src={heroImage} alt="Hero" placeholder="blur" />
+
+// Remote images - provide blurDataURL
+<Image
+  src="https://example.com/image.jpg"
+  alt="Hero"
+  width={800}
+  height={400}
+  placeholder="blur"
+  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
+/>
+
+// Or use color placeholder
+<Image
+  src="https://example.com/image.jpg"
+  alt="Hero"
+  width={800}
+  height={400}
+  placeholder="empty"
+  style={{ backgroundColor: '#e0e0e0' }}
+/>
+```
+
+## Priority Loading
+
+Use `priority` for above-the-fold images (LCP):
+
+```tsx
+// Hero image - loads immediately
+<Image src="/hero.png" alt="Hero" fill priority />
+
+// Below-fold images - lazy loaded by default (no priority needed)
+<Image src="/card.png" alt="Card" width={400} height={300} />
+```
+
+## Common Mistakes
+
+```tsx
+// Bad: Missing sizes with fill - downloads largest image
+<Image src="/hero.png" alt="Hero" fill />
+
+// Good: Add sizes for proper responsive behavior
+<Image src="/hero.png" alt="Hero" fill sizes="100vw" />
+
+// Bad: Using width/height for aspect ratio only
+<Image src="/hero.png" alt="Hero" width={16} height={9} />
+
+// Good: Use actual display dimensions or fill with sizes
+<Image src="/hero.png" alt="Hero" fill sizes="100vw" style={{ objectFit: 'cover' }} />
+
+// Bad: Remote image without config
+<Image src="https://untrusted.com/image.jpg" alt="Image" width={400} height={300} />
+// Error: Invalid src prop, hostname not configured
+
+// Good: Add hostname to next.config.js remotePatterns
+```
+
+## Static Export
+
+When using `output: 'export'`, use `unoptimized` or custom loader:
+
+```tsx
+// Option 1: Disable optimization
+<Image src="/hero.png" alt="Hero" width={800} height={400} unoptimized />;
+
+// Option 2: Global config
+// next.config.js
+module.exports = {
+  output: "export",
+  images: { unoptimized: true },
+};
+
+// Option 3: Custom loader (Cloudinary, Imgix, etc.)
+const cloudinaryLoader = ({ src, width, quality }) => {
+  return `https://res.cloudinary.com/demo/image/upload/w_${width},q_${quality || 75}/${src}`;
+};
+
+<Image
+  loader={cloudinaryLoader}
+  src="sample.jpg"
+  alt="Sample"
+  width={800}
+  height={400}
+/>;
+```

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

@@ -0,0 +1,296 @@
+# Metadata
+
+Add SEO metadata to Next.js pages using the Metadata API.
+
+## Important: Server Components Only
+
+The `metadata` object and `generateMetadata` function are **only supported in Server Components**. They cannot be used in Client Components.
+
+If the target page has `'use client'`:
+
+1. Remove `'use client'` if possible, move client logic to child components
+2. Or extract metadata to a parent Server Component layout
+3. Or split the file: Server Component with metadata imports Client Components
+
+## Static Metadata
+
+```tsx
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Page Title",
+  description: "Page description for search engines",
+};
+```
+
+## Dynamic Metadata
+
+```tsx
+import type { Metadata } from "next";
+
+type Props = { params: Promise<{ slug: string }> };
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params;
+  const post = await getPost(slug);
+  return { title: post.title, description: post.description };
+}
+```
+
+## Avoid Duplicate Fetches
+
+Use React `cache()` when the same data is needed for both metadata and page:
+
+```tsx
+import { cache } from "react";
+
+export const getPost = cache(async (slug: string) => {
+  return await db.posts.findFirst({ where: { slug } });
+});
+```
+
+## Viewport
+
+Separate from metadata for streaming support:
+
+```tsx
+import type { Viewport } from "next";
+
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1,
+  themeColor: "#000000",
+};
+
+// Or dynamic
+export function generateViewport({ params }): Viewport {
+  return { themeColor: getThemeColor(params) };
+}
+```
+
+## Title Templates
+
+In root layout for consistent naming:
+
+```tsx
+export const metadata: Metadata = {
+  title: { default: "Site Name", template: "%s | Site Name" },
+};
+```
+
+## Metadata File Conventions
+
+Reference: https://nextjs.org/docs/app/getting-started/project-structure#metadata-file-conventions
+
+Place these files in `app/` directory (or route segments):
+
+| File                            | Purpose                                       |
+| ------------------------------- | --------------------------------------------- |
+| `favicon.ico`                   | Favicon                                       |
+| `icon.png` / `icon.svg`         | App icon                                      |
+| `apple-icon.png`                | Apple app icon                                |
+| `opengraph-image.png`           | OG image                                      |
+| `twitter-image.png`             | Twitter card image                            |
+| `sitemap.ts` / `sitemap.xml`    | Sitemap (use `generateSitemaps` for multiple) |
+| `robots.ts` / `robots.txt`      | Robots directives                             |
+| `manifest.ts` / `manifest.json` | Web app manifest                              |
+
+## SEO Best Practice: Static Files Are Often Enough
+
+For most sites, **static metadata files provide excellent SEO coverage**:
+
+```
+app/
+├── favicon.ico
+├── opengraph-image.png     # Works for both OG and Twitter
+├── sitemap.ts
+├── robots.ts
+└── layout.tsx              # With title/description metadata
+```
+
+**Tips:**
+
+- A single `opengraph-image.png` covers both Open Graph and Twitter (Twitter falls back to OG)
+- Static `title` and `description` in layout metadata is sufficient for most pages
+- Only use dynamic `generateMetadata` when content varies per page
+
+---
+
+# OG Image Generation
+
+Generate dynamic Open Graph images using `next/og`.
+
+## Important Rules
+
+1. **Use `next/og`** - not `@vercel/og` (it's built into Next.js)
+2. **No searchParams** - OG images can't access search params, use route params instead
+3. **Avoid Edge runtime** - Use default Node.js runtime
+
+```tsx
+// Good
+import { ImageResponse } from "next/og";
+
+// Bad
+// import { ImageResponse } from '@vercel/og'
+// export const runtime = 'edge'
+```
+
+## Basic OG Image
+
+```tsx
+// app/opengraph-image.tsx
+import { ImageResponse } from "next/og";
+
+export const alt = "Site Name";
+export const size = { width: 1200, height: 630 };
+export const contentType = "image/png";
+
+export default function Image() {
+  return new ImageResponse(
+    <div
+      style={{
+        fontSize: 128,
+        background: "white",
+        width: "100%",
+        height: "100%",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+      }}
+    >
+      Hello World
+    </div>,
+    { ...size },
+  );
+}
+```
+
+## Dynamic OG Image
+
+```tsx
+// app/blog/[slug]/opengraph-image.tsx
+import { ImageResponse } from "next/og";
+
+export const alt = "Blog Post";
+export const size = { width: 1200, height: 630 };
+export const contentType = "image/png";
+
+type Props = { params: Promise<{ slug: string }> };
+
+export default async function Image({ params }: Props) {
+  const { slug } = await params;
+  const post = await getPost(slug);
+
+  return new ImageResponse(
+    <div
+      style={{
+        fontSize: 48,
+        background: "linear-gradient(to bottom, #1a1a1a, #333)",
+        color: "white",
+        width: "100%",
+        height: "100%",
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "center",
+        padding: 48,
+      }}
+    >
+      <div style={{ fontSize: 64, fontWeight: "bold" }}>{post.title}</div>
+      <div style={{ marginTop: 24, opacity: 0.8 }}>{post.description}</div>
+    </div>,
+    { ...size },
+  );
+}
+```
+
+## Custom Fonts
+
+```tsx
+import { ImageResponse } from "next/og";
+import { join } from "path";
+import { readFile } from "fs/promises";
+
+export default async function Image() {
+  const fontPath = join(process.cwd(), "assets/fonts/Inter-Bold.ttf");
+  const fontData = await readFile(fontPath);
+
+  return new ImageResponse(
+    <div style={{ fontFamily: "Inter", fontSize: 64 }}>Custom Font Text</div>,
+    {
+      width: 1200,
+      height: 630,
+      fonts: [{ name: "Inter", data: fontData, style: "normal" }],
+    },
+  );
+}
+```
+
+## File Naming
+
+- `opengraph-image.tsx` - Open Graph (Facebook, LinkedIn)
+- `twitter-image.tsx` - Twitter/X cards (optional, falls back to OG)
+
+## Styling Notes
+
+ImageResponse uses Flexbox layout:
+
+- Use `display: 'flex'`
+- No CSS Grid support
+- Styles must be inline objects
+
+## Multiple OG Images
+
+Use `generateImageMetadata` for multiple images per route:
+
+```tsx
+// app/blog/[slug]/opengraph-image.tsx
+import { ImageResponse } from "next/og";
+
+export async function generateImageMetadata({ params }) {
+  const images = await getPostImages(params.slug);
+  return images.map((img, idx) => ({
+    id: idx,
+    alt: img.alt,
+    size: { width: 1200, height: 630 },
+    contentType: "image/png",
+  }));
+}
+
+export default async function Image({ params, id }) {
+  const images = await getPostImages(params.slug);
+  const image = images[id];
+  return new ImageResponse(/* ... */);
+}
+```
+
+## Multiple Sitemaps
+
+Use `generateSitemaps` for large sites:
+
+```tsx
+// app/sitemap.ts
+import type { MetadataRoute } from "next";
+
+export async function generateSitemaps() {
+  // Return array of sitemap IDs
+  return [{ id: 0 }, { id: 1 }, { id: 2 }];
+}
+
+export default async function sitemap({
+  id,
+}: {
+  id: number;
+}): Promise<MetadataRoute.Sitemap> {
+  const start = id * 50000;
+  const end = start + 50000;
+  const products = await getProducts(start, end);
+
+  return products.map((product) => ({
+    url: `https://example.com/product/${product.id}`,
+    lastModified: product.updatedAt,
+  }));
+}
+```
+
+Generates `/sitemap/0.xml`, `/sitemap/1.xml`, etc.