rsc-universal 0.1.1

package/skills/nextjs/references/data-and-caching.md

@@ -0,0 +1,309 @@
+# Data fetching & caching — the two App Router models
+
+Deep dive behind the "Caching & data fetching" section of `SKILL.md`. **Detect the model first**
+(see the SKILL gate). Never mix v15 and v16 advice. Sources: nextjs.org/blog/next-15,
+nextjs.org/blog/next-16, the `use cache` / `cacheComponents` / `cacheLife` docs.
+
+## Mental model first
+
+Four caches sit between your code and the response:
+
+- **Request memoization** — `fetch`/`React.cache` dedupes identical calls within a single render.
+- **Data cache** — persists fetch results across requests/deploys (server-side).
+- **Full-route cache** — caches the rendered HTML + RSC payload of a static route at build/revalidate.
+- **Client router cache** — caches RSC payloads in the browser for back/forward navigation.
+
+| Concern         | v15 baseline                                       | v16 Cache Components                            |
+| --------------- | -------------------------------------------------- | ----------------------------------------------- |
+| Default `fetch` | Uncached                                           | Dynamic; cache only inside `"use cache"`        |
+| Opt-in cache    | `{ next: { revalidate, tags } }`, `unstable_cache` | `"use cache"` + `cacheLife()` + `cacheTag()`    |
+| Invalidate      | `revalidateTag` / `revalidatePath`                 | `updateTag` (immediate) / `revalidateTag` (SWR) |
+| Request dedupe  | `React.cache`                                      | `React.cache`                                   |
+| Static/dynamic  | route segment config (`dynamic`, `revalidate`)     | PPR by default (static shell + streamed holes)  |
+
+## v15 model in full
+
+`fetch` is uncached by default — the v13/14 "cached by default" mental model is wrong here.
+
+```ts
+// 1. uncached — re-fetched on every request
+const live = await fetch("https://api.example.com/now").then((r) => r.json());
+
+// 2. explicitly cache forever (until revalidated)
+const config = await fetch("https://api.example.com/config", {
+  cache: "force-cache",
+}).then((r) => r.json());
+
+// 3. time-based revalidation + tags for on-demand invalidation
+const posts = await fetch("https://api.example.com/posts", {
+  next: { revalidate: 3600, tags: ["posts"] },
+}).then((r) => r.json());
+```
+
+Route segment config controls a whole route's rendering:
+
+```ts
+// app/feed/page.tsx — top-level exports configure the segment
+export const dynamic = "force-dynamic"; // "auto" | "force-dynamic" | "error" | "force-static"
+export const revalidate = 3600; // ISR window in seconds
+export const fetchCache = "default-cache"; // override per-route fetch caching
+export const runtime = "nodejs"; // or "edge"
+```
+
+Request dedupe and non-`fetch` caching:
+
+```ts
+import { cache } from "react";
+import { unstable_cache } from "next/cache";
+import { db } from "@/lib/db";
+
+// React.cache: one call per request even if invoked from multiple components
+export const getUser = cache(async (id: string) => db.user.findUnique({ where: { id } }));
+
+// unstable_cache: persist a non-fetch result across requests, tagged + time-bounded
+export const getPosts = unstable_cache(
+  async () => db.post.findMany({ orderBy: { createdAt: "desc" } }),
+  ["posts-list"], // key parts
+  { tags: ["posts"], revalidate: 60 },
+);
+```
+
+```ts
+// invalidate from a Server Action
+"use server";
+import { revalidateTag, revalidatePath } from "next/cache";
+
+export async function publishPost(id: string) {
+  // ... auth + mutation ...
+  revalidateTag("posts"); // clears every fetch/unstable_cache tagged "posts"
+  revalidatePath("/feed"); // clears a specific route
+}
+```
+
+Reading `cookies()`, `headers()`, or `searchParams` opts a route into **dynamic rendering** — it can
+no longer be statically cached.
+
+## v16 Cache Components in full
+
+Enable in config; then opt into caching with the `"use cache"` directive.
+
+```ts
+// next.config.ts
+import type { NextConfig } from "next";
+const config: NextConfig = {
+  cacheComponents: true, // everything dynamic by default; cache is opt-in
+};
+export default config;
+```
+
+```ts
+// lib/products.ts — "use cache" at the function level
+// Next.js 16: cacheLife / cacheTag / updateTag are STABLE — no unstable_ prefix.
+import { cacheLife, cacheTag } from "next/cache";
+import { db } from "@/lib/db";
+
+export async function getProducts() {
+  "use cache";
+  cacheLife("hours"); // built-in profile: seconds | minutes | hours | days | weeks | max
+  cacheTag("products");
+  return db.product.findMany();
+}
+```
+
+> **15 → 16 transitional note only.** On the Next.js 15 *experimental* Cache Components preview these
+> were aliased: `import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from "next/cache"`.
+> On Next.js 16 they are stable — drop the `unstable_` aliases. If you still see the aliased form in a
+> repo, it is a leftover from the 15 preview, not the current API.
+
+```ts
+// custom cacheLife profile (registered in next.config.ts under experimental, or inline object)
+cacheLife({ stale: 60, revalidate: 300, expire: 3600 }); // seconds
+```
+
+`updateTag` and `revalidateTag` are **not** interchangeable on v16 — they have different timing:
+
+| Verb              | Timing                                                          | Where it runs                  |
+| ----------------- | -------------------------------------------------------------- | ------------------------------ |
+| `updateTag(tag)`  | **Immediate** expiry; the same request reads its own fresh write (read-your-writes). | **Server Actions only**        |
+| `revalidateTag(tag, profile)` | **Stale-while-revalidate**: serves stale now, refreshes in the background. On v16 it takes a second `cacheLife` profile argument; the single-arg form is deprecated. | Server Actions or Route Handlers |
+
+```ts
+// invalidate from a mutation
+"use server";
+import { updateTag, revalidateTag } from "next/cache";
+
+export async function restock() {
+  // ... auth + mutation ...
+  updateTag("products"); // user must see their own change on this very response
+}
+
+export async function nightlyReprice() {
+  // ... mutation ...
+  revalidateTag("products", "hours"); // ok to serve stale briefly; refresh in background
+}
+```
+
+| Inside `"use cache"` / `"use cache: remote"` you may NOT… | Do this instead                           |
+| --------------------------------------------------------- | ----------------------------------------- |
+| call `cookies()` / `headers()`                            | read outside, pass the value as an arg    |
+| read `searchParams`                                       | pass the parsed value as an arg           |
+| close over a request-scoped Promise                       | await/resolve it outside, pass the result |
+
+**Exception — `"use cache: private"`.** This variant *may* read `cookies()`, `headers()`, and
+`searchParams` directly. Its result is cached **only in the browser's memory** (never stored on the
+server, not persisted across reloads), so it is safe for per-user data. Use it when moving the
+request access outside and passing arguments is impractical; otherwise prefer plain `"use cache"`
+with arguments. `"use cache: remote"` stores the entry in the shared/remote cache and follows the
+same request-API restrictions as plain `"use cache"`. PPR streams the dynamic holes inside an
+otherwise-cached static shell, so the shell paints instantly.
+
+```ts
+// Bad: a dynamic, request-scoped Promise captured inside "use cache" hangs the build
+async function getDashboardBad(sessionPromise: Promise<Session>) {
+  "use cache";
+  const session = await sessionPromise; // ✗ closing over request-scoped work
+  return db.metrics.forUser(session.userId);
+}
+
+// Good: resolve the dynamic value OUTSIDE, pass the plain id in
+async function getDashboard(userId: string) {
+  "use cache";
+  cacheTag(`metrics:${userId}`);
+  return db.metrics.forUser(userId);
+}
+// caller (request-scoped): const s = await auth(); const data = await getDashboard(s.user.id);
+```
+
+## Mutations via Server Actions
+
+The canonical shape: authenticate → validate → mutate → invalidate → return a typed result.
+
+```ts
+// app/posts/actions.ts
+"use server";
+import { z } from "zod";
+import { revalidateTag } from "next/cache";
+import { auth } from "@/auth";
+import { db } from "@/lib/db";
+
+const TitleSchema = z.object({ id: z.string().uuid(), title: z.string().min(1).max(200) });
+
+type Result =
+  | { status: "ok"; data: { id: string; title: string } }
+  | { status: "error"; message: string };
+
+export async function renamePost(input: z.infer<typeof TitleSchema>): Promise<Result> {
+  const session = await auth();
+  if (!session?.user) return { status: "error", message: "Not authenticated" };
+
+  const parsed = TitleSchema.safeParse(input);
+  if (!parsed.success) return { status: "error", message: "Invalid input" };
+
+  const post = await db.post.update({
+    where: { id: parsed.data.id, authorId: session.user.id },
+    data: { title: parsed.data.title },
+  });
+  revalidateTag("posts"); // v15: stale-while-revalidate. On v16 use updateTag("posts") for
+  //                          immediate read-your-writes, or revalidateTag("posts", "hours") for SWR.
+  return { status: "ok", data: { id: post.id, title: post.title } };
+}
+```
+
+Pair this with optimistic UI on the client (`useOptimistic`) — see `react.md`.
+
+## Forms end-to-end
+
+One complete, runnable flow: zod schema → shared `z.infer` type → Server Action returning a
+discriminated union with a `fieldErrors` map → a client form via `useActionState` mapping those
+errors back to inputs.
+
+```ts
+// app/signup/actions.ts
+"use server";
+import { z } from "zod";
+import { db } from "@/lib/db";
+
+export const SignupSchema = z.object({
+  email: z.string().email("Enter a valid email"),
+  password: z.string().min(8, "At least 8 characters"),
+});
+export type SignupInput = z.infer<typeof SignupSchema>; // shared by form + DB layer
+
+export type SignupState = {
+  status: "idle" | "ok" | "error";
+  message?: string;
+  fieldErrors?: Partial<Record<keyof SignupInput, string>>;
+};
+
+export async function signup(_prev: SignupState, formData: FormData): Promise<SignupState> {
+  const parsed = SignupSchema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) {
+    const fe = parsed.error.flatten().fieldErrors;
+    return { status: "error", fieldErrors: { email: fe.email?.[0], password: fe.password?.[0] } };
+  }
+  const exists = await db.user.findUnique({ where: { email: parsed.data.email } });
+  if (exists) return { status: "error", fieldErrors: { email: "Already registered" } };
+
+  await db.user.create({ data: parsed.data });
+  return { status: "ok", message: "Account created" };
+}
+```
+
+```tsx
+// app/signup/form.tsx
+"use client";
+import { useActionState } from "react";
+import { useFormStatus } from "react-dom";
+import { signup, type SignupState } from "./actions";
+
+const initial: SignupState = { status: "idle" };
+
+function Submit() {
+  const { pending } = useFormStatus();
+  return <button disabled={pending}>{pending ? "Creating…" : "Sign up"}</button>;
+}
+
+export function SignupForm() {
+  const [state, action] = useActionState(signup, initial);
+  return (
+    <form action={action}>
+      <label htmlFor="email">Email</label>
+      <input id="email" name="email" type="email" aria-invalid={!!state.fieldErrors?.email} aria-describedby="email-err" />
+      {state.fieldErrors?.email && <p id="email-err" role="alert">{state.fieldErrors.email}</p>}
+
+      <label htmlFor="password">Password</label>
+      <input id="password" name="password" type="password" aria-invalid={!!state.fieldErrors?.password} aria-describedby="pw-err" />
+      {state.fieldErrors?.password && <p id="pw-err" role="alert">{state.fieldErrors.password}</p>}
+
+      <Submit />
+      {state.status === "ok" && <p role="status">{state.message}</p>}
+    </form>
+  );
+}
+```
+
+## Client cache layer (TanStack Query)
+
+Rely on RSC by default. Add TanStack Query when data lives client-side: client-initiated mutations
+with cache updates, infinite scroll, or a cross-component client cache that must stay in sync.
+
+```tsx
+"use client";
+import { useQuery } from "@tanstack/react-query";
+
+export function NotificationBell() {
+  const { data, isPending } = useQuery({
+    queryKey: ["notifications"],
+    queryFn: () => fetch("/api/notifications").then((r) => r.json()),
+    staleTime: 30_000,
+  });
+  if (isPending) return <span aria-busy="true" />;
+  return <span aria-label={`${data.count} notifications`}>{data.count}</span>;
+}
+```
+
+## See Also
+
+- `react.md` — `useActionState`, `useOptimistic`, and the form/hook discipline.
+- `security.md` — auth checks every mutation must perform before touching data.
+- `testing.md` — how to unit-test these Server Actions and the data functions.

package/skills/nextjs/references/metadata.md

@@ -0,0 +1,208 @@
+# Next.js metadata & SEO — `generateMetadata`, sitemap, robots, OpenGraph
+
+Deep dive behind the "Metadata & SEO" section of `SKILL.md`. This is the **build-side** layer:
+how the App Router emits `<title>`, `<meta>`, OpenGraph/Twitter tags, `sitemap.xml`, and
+`robots.txt`. For the *content/strategy* layer — keyword research, JSON-LD schema choice, GEO
+(getting cited by AI engines), and Core Web Vitals as a ranking signal — see
+`../../marketing/references/seo-geo.md`. Sources: the Next.js `generate-metadata`,
+`metadata/sitemap`, `metadata/robots`, and `metadata/opengraph-image` API docs.
+
+The Metadata API works the same on Next.js 15 and 16. `metadata`/`generateMetadata` are
+**Server-Component-only** exports — they cannot live in a `"use client"` file.
+
+## Static vs dynamic metadata
+
+Export a static `metadata` object when the values are known at build time; export an async
+`generateMetadata` when they depend on `params`, `searchParams`, or fetched data. Use **one or the
+other** in a given file, never both.
+
+```ts
+// app/layout.tsx — static, applied site-wide and merged into by child segments
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  metadataBase: new URL("https://example.com"), // makes relative OG/canonical URLs absolute
+  title: { default: "Acme", template: "%s · Acme" }, // child `title: "Pricing"` → "Pricing · Acme"
+  description: "The fastest way to ship.",
+  alternates: { canonical: "/" },
+};
+```
+
+```tsx
+// app/blog/[slug]/page.tsx — dynamic, derived from route params + data
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { getPost } from "@/lib/dal";
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}): Promise<Metadata> {
+  const { slug } = await params; // params is a Promise on v15+
+  const post = await getPost(slug); // deduped with the page's own fetch via React.cache
+  if (!post) return {};
+  return {
+    title: post.title,
+    description: post.excerpt,
+    alternates: { canonical: `/blog/${slug}` },
+    openGraph: {
+      title: post.title,
+      description: post.excerpt,
+      type: "article",
+      url: `/blog/${slug}`,
+      images: [{ url: post.cover, width: 1200, height: 630, alt: post.title }],
+    },
+    twitter: { card: "summary_large_image", title: post.title, description: post.excerpt },
+  };
+}
+```
+
+Wrap the data call in `React.cache` (see `data-and-caching.md`) so `generateMetadata` and the page
+component share **one** query per request instead of fetching twice.
+
+## OpenGraph & Twitter cards
+
+OpenGraph drives the link preview on social/chat surfaces; Twitter falls back to OpenGraph when its
+own fields are absent. Set `metadataBase` once in the root layout so relative `images`/`url`/
+`canonical` paths resolve to absolute URLs. The recommended OG image size is **1200×630**.
+
+```ts
+// app/layout.tsx (excerpt) — site-wide OpenGraph defaults; pages override `title`/`images`
+export const metadata: Metadata = {
+  metadataBase: new URL("https://example.com"),
+  openGraph: {
+    siteName: "Acme",
+    type: "website",
+    locale: "en_US",
+    images: ["/og-default.png"], // resolved against metadataBase → https://example.com/og-default.png
+  },
+};
+```
+
+### Dynamic OG images with `next/og`
+
+Colocate an `opengraph-image.tsx` in a route segment. Its `default` export returns an
+`ImageResponse` (from `next/og`), and Next.js wires up the `og:image` meta tag automatically —
+no `openGraph.images` entry needed. `ImageResponse` renders JSX to PNG via Satori, so only
+**flexbox + a subset of CSS** is supported (no `grid`, no external CSS).
+
+```tsx
+// app/blog/[slug]/opengraph-image.tsx
+import { ImageResponse } from "next/og";
+import { getPost } from "@/lib/dal";
+
+export const alt = "Blog post cover";
+export const size = { width: 1200, height: 630 };
+export const contentType = "image/png";
+
+export default async function Image({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = await getPost(slug);
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          display: "flex", // Satori requires explicit flex layout
+          flexDirection: "column",
+          justifyContent: "center",
+          width: "100%",
+          height: "100%",
+          padding: 80,
+          background: "#0a0a0a",
+          color: "#fff",
+          fontSize: 64,
+        }}
+      >
+        {post?.title ?? "Acme"}
+      </div>
+    ),
+    { ...size },
+  );
+}
+```
+
+## `sitemap.ts`
+
+Export a default function returning `MetadataRoute.Sitemap` from `app/sitemap.ts`. Next.js serves it
+at `/sitemap.xml`. It can be async and fetch routes from the DB/CMS.
+
+```ts
+// app/sitemap.ts
+import type { MetadataRoute } from "next";
+import { getAllPostSlugs } from "@/lib/dal";
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const base = "https://example.com";
+  const posts = await getAllPostSlugs(); // [{ slug, updatedAt }, ...]
+  return [
+    { url: base, lastModified: new Date(), changeFrequency: "weekly", priority: 1 },
+    { url: `${base}/pricing`, lastModified: new Date(), changeFrequency: "monthly", priority: 0.8 },
+    ...posts.map((p) => ({
+      url: `${base}/blog/${p.slug}`,
+      lastModified: p.updatedAt,
+      changeFrequency: "monthly" as const,
+      priority: 0.5,
+    })),
+  ];
+}
+```
+
+A single sitemap is capped at **50,000 URLs**. Past that, use `generateSitemaps()` to split into
+multiple files (`/sitemap/0.xml`, `/sitemap/1.xml`, …) and return an array of `{ id }`.
+
+```ts
+// app/sitemap.ts — sharded for large catalogs
+import type { MetadataRoute } from "next";
+import { countProducts, getProductPage } from "@/lib/dal";
+
+export async function generateSitemaps() {
+  const pages = Math.ceil((await countProducts()) / 50_000);
+  return Array.from({ length: pages }, (_, id) => ({ id }));
+}
+
+export default async function sitemap({ id }: { id: number }): Promise<MetadataRoute.Sitemap> {
+  const products = await getProductPage(id, 50_000);
+  return products.map((p) => ({ url: `https://example.com/p/${p.slug}`, lastModified: p.updatedAt }));
+}
+```
+
+## `robots.ts`
+
+Export a default function returning `MetadataRoute.Robots` from `app/robots.ts`; Next.js serves it
+at `/robots.txt`. Point it at the sitemap and disallow private paths.
+
+```ts
+// app/robots.ts
+import type { MetadataRoute } from "next";
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [{ userAgent: "*", allow: "/", disallow: ["/api/", "/admin/", "/draft/"] }],
+    sitemap: "https://example.com/sitemap.xml",
+    host: "https://example.com",
+  };
+}
+```
+
+For the **AI-crawler** stance (allowing retrieval/citation bots like `OAI-SearchBot`/`PerplexityBot`
+while optionally opting out of training crawlers like `GPTBot`/`ClaudeBot`/`Google-Extended`), the
+per-bot `robots.txt` policy lives in `../../marketing/references/seo-geo.md` — keep the `robots.ts`
+`rules` array in sync with the policy decided there.
+
+## What to verify on review
+
+- `metadataBase` is set once in the root layout (otherwise relative OG/canonical URLs are dropped).
+- Exactly one of `metadata` / `generateMetadata` per file; neither in a `"use client"` file.
+- `generateMetadata`'s data fetch is `React.cache`-wrapped to dedupe with the page.
+- Every indexable page has a unique `title`, `description`, and `alternates.canonical`.
+- OG images are absolute (or relative under a set `metadataBase`) and ~1200×630.
+- `sitemap.ts` excludes `noindex`/auth-gated routes; `robots.ts` disallows them and links the sitemap.
+
+## See Also
+
+- `../../marketing/references/seo-geo.md` — keyword research, JSON-LD schema, GEO (AI-engine citation),
+  per-engine optimization, and the SEO/GEO QA gate. This file emits the tags; that file decides the
+  strategy and content structure behind them.
+- `performance.md` — Core Web Vitals (LCP/CLS/INP), a direct ranking signal.
+- `data-and-caching.md` — `React.cache` dedupe so metadata and the page share one query.