@jgamaraalv/ts-dev-kit 1.0.0

package/skills/react-best-practices/references/rerender-optimization.md

@@ -0,0 +1,316 @@
+# Re-render Optimization
+
+Reduce unnecessary React re-renders through better state management and memoization.
+
+## Table of Contents
+
+- [Defer State Reads to Usage Point](#defer-state-reads-to-usage-point)
+- [Narrow Effect Dependencies](#narrow-effect-dependencies)
+- [Calculate Derived State During Rendering](#calculate-derived-state-during-rendering)
+- [Use Functional setState Updates](#use-functional-setstate-updates)
+- [Hoist Default Non-primitive Props](#hoist-default-non-primitive-props)
+- [Extract to Memoized Components](#extract-to-memoized-components)
+- [Put Interaction Logic in Event Handlers](#put-interaction-logic-in-event-handlers)
+- [Use useRef for Transient Values](#use-useref-for-transient-values)
+
+---
+
+## Defer State Reads to Usage Point
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect (subscribes to all searchParams changes):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams();
+
+  const handleShare = () => {
+    const ref = searchParams.get("ref");
+    shareChat(chatId, { ref });
+  };
+
+  return <button onClick={handleShare}>Share</button>;
+}
+```
+
+**Correct (reads on demand, no subscription):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search);
+    const ref = params.get("ref");
+    shareChat(chatId, { ref });
+  };
+
+  return <button onClick={handleShare}>Share</button>;
+}
+```
+
+---
+
+## Narrow Effect Dependencies
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect (re-runs on any user field change):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id);
+}, [user]);
+```
+
+**Correct (re-runs only when id changes):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id);
+}, [user.id]);
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) enableMobileMode();
+}, [width]);
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768;
+useEffect(() => {
+  if (isMobile) enableMobileMode();
+}, [isMobile]);
+```
+
+---
+
+## Calculate Derived State During Rendering
+
+If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render.
+
+**Incorrect (redundant state and effect):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState("First");
+  const [lastName, setLastName] = useState("Last");
+  const [fullName, setFullName] = useState("");
+
+  useEffect(() => {
+    setFullName(firstName + " " + lastName);
+  }, [firstName, lastName]);
+
+  return <p>{fullName}</p>;
+}
+```
+
+**Correct (derive during render):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState("First");
+  const [lastName, setLastName] = useState("Last");
+  const fullName = firstName + " " + lastName;
+
+  return <p>{fullName}</p>;
+}
+```
+
+Reference: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
+
+---
+
+## Use Functional setState Updates
+
+When updating state based on the current state value, use the functional update form. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect (requires state as dependency):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems);
+
+  const addItems = useCallback(
+    (newItems: Item[]) => {
+      setItems([...items, ...newItems]);
+    },
+    [items], // Recreated on every items change
+  );
+
+  return <ItemsEditor items={items} onAdd={addItems} />;
+}
+```
+
+**Correct (stable callbacks, no stale closures):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems);
+
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems((curr) => [...curr, ...newItems]);
+  }, []); // No dependencies needed
+
+  const removeItem = useCallback((id: string) => {
+    setItems((curr) => curr.filter((item) => item.id !== id));
+  }, []); // Safe and stable
+
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />;
+}
+```
+
+**When to use:** Any setState depending on current state, inside useCallback/useMemo, event handlers, async operations. **When direct updates are fine:** Setting state to a static value (`setCount(0)`), setting from props/arguments only.
+
+**Note:** React Compiler can optimize some cases automatically, but functional updates are still recommended for correctness.
+
+---
+
+## Hoist Default Non-primitive Props
+
+When memoized components have default non-primitive parameter values, new instances are created on every re-render, breaking memoization.
+
+**Incorrect (`onClick` has different values on every rerender):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+  // ...
+});
+```
+
+**Correct (stable default value):**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+  // ...
+});
+```
+
+---
+
+## Extract to Memoized Components
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect (computes avatar even when loading):**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user);
+    return <Avatar id={id} />;
+  }, [user]);
+
+  if (loading) return <Skeleton />;
+  return <div>{avatar}</div>;
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user]);
+  return <Avatar id={id} />;
+});
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />;
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  );
+}
+```
+
+**Note:** React Compiler automatically optimizes re-renders, making manual `memo()`/`useMemo()` unnecessary.
+
+---
+
+## Put Interaction Logic in Event Handlers
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect.
+
+**Incorrect (event modeled as state + effect):**
+
+```tsx
+function Form() {
+  const [submitted, setSubmitted] = useState(false);
+  const theme = useContext(ThemeContext);
+
+  useEffect(() => {
+    if (submitted) {
+      post("/api/register");
+      showToast("Registered", theme);
+    }
+  }, [submitted, theme]);
+
+  return <button onClick={() => setSubmitted(true)}>Submit</button>;
+}
+```
+
+**Correct (do it in the handler):**
+
+```tsx
+function Form() {
+  const theme = useContext(ThemeContext);
+
+  function handleSubmit() {
+    post("/api/register");
+    showToast("Registered", theme);
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>;
+}
+```
+
+Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
+
+---
+
+## Use useRef for Transient Values
+
+When a value changes frequently and you don't want a re-render on every update (mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`.
+
+**Incorrect (renders every update):**
+
+```tsx
+function Tracker() {
+  const [lastX, setLastX] = useState(0);
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => setLastX(e.clientX);
+    window.addEventListener("mousemove", onMove);
+    return () => window.removeEventListener("mousemove", onMove);
+  }, []);
+
+  return <div style={{ position: "fixed", top: 0, left: lastX, width: 8, height: 8 }} />;
+}
+```
+
+**Correct (no re-render for tracking):**
+
+```tsx
+function Tracker() {
+  const lastXRef = useRef(0);
+  const dotRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      lastXRef.current = e.clientX;
+      if (dotRef.current) {
+        dotRef.current.style.transform = `translateX(${e.clientX}px)`;
+      }
+    };
+    window.addEventListener("mousemove", onMove);
+    return () => window.removeEventListener("mousemove", onMove);
+  }, []);
+
+  return <div ref={dotRef} style={{ position: "fixed", top: 0, width: 8, height: 8 }} />;
+}
+```

package/skills/react-best-practices/references/server-performance.md

@@ -0,0 +1,274 @@
+# Server-Side Performance
+
+Optimize RSC data fetching, caching, and serialization.
+
+## Table of Contents
+
+- [Use after() for Non-Blocking Operations](#use-after-for-non-blocking-operations)
+- [Authenticate Server Actions](#authenticate-server-actions)
+- [Cross-Request LRU Caching](#cross-request-lru-caching)
+- [Per-Request Deduplication with React.cache()](#per-request-deduplication-with-reactcache)
+- [Avoid Duplicate Serialization in RSC Props](#avoid-duplicate-serialization-in-rsc-props)
+- [Parallel Data Fetching with Component Composition](#parallel-data-fetching-with-component-composition)
+- [Minimize Serialization at RSC Boundaries](#minimize-serialization-at-rsc-boundaries)
+
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. Prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+export async function POST(request: Request) {
+  await updateDatabase(request);
+  const userAgent = request.headers.get("user-agent") || "unknown";
+  await logUserAction({ userAgent }); // Blocks response
+  return new Response(JSON.stringify({ status: "success" }));
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from "next/server";
+import { headers, cookies } from "next/headers";
+
+export async function POST(request: Request) {
+  await updateDatabase(request);
+
+  after(async () => {
+    const userAgent = (await headers()).get("user-agent") || "unknown";
+    const sessionCookie = (await cookies()).get("session-id")?.value || "anonymous";
+    logUserAction({ sessionCookie, userAgent });
+  });
+
+  return new Response(JSON.stringify({ status: "success" }));
+}
+```
+
+Common use cases: analytics tracking, audit logging, notifications, cache invalidation.
+
+`after()` runs even if the response fails or redirects. Works in Server Actions, Route Handlers, and Server Components.
+
+Reference: [next/server after()](https://nextjs.org/docs/app/api-reference/functions/after)
+
+---
+
+## Authenticate Server Actions
+
+Server Actions (`"use server"`) are exposed as public endpoints. Always verify authentication and authorization **inside** each Server Action -- do not rely solely on middleware or layout guards.
+
+**Incorrect (no authentication check):**
+
+```typescript
+"use server";
+
+export async function deleteUser(userId: string) {
+  await db.user.delete({ where: { id: userId } });
+  return { success: true };
+}
+```
+
+**Correct (authentication + authorization + validation):**
+
+```typescript
+"use server";
+
+import { verifySession } from "@/lib/auth";
+import { z } from "zod";
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+});
+
+export async function updateProfile(data: unknown) {
+  const validated = updateProfileSchema.parse(data);
+  const session = await verifySession();
+  if (!session) throw new Error("Unauthorized");
+  if (session.user.id !== validated.userId) throw new Error("Can only update own profile");
+
+  await db.user.update({
+    where: { id: validated.userId },
+    data: { name: validated.name, email: validated.email },
+  });
+
+  return { success: true };
+}
+```
+
+Reference: [Next.js Authentication Guide](https://nextjs.org/docs/app/guides/authentication)
+
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests, use an LRU cache.
+
+```typescript
+import { LRUCache } from "lru-cache";
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000, // 5 minutes
+});
+
+export async function getUser(id: string) {
+  const cached = cache.get(id);
+  if (cached) return cached;
+
+  const user = await db.user.findUnique({ where: { id } });
+  cache.set(id, user);
+  return user;
+}
+```
+
+With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), LRU caching is especially effective because multiple concurrent requests share the same function instance. In traditional serverless, consider Redis for cross-process caching.
+
+Reference: [node-lru-cache](https://github.com/isaacs/node-lru-cache)
+
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+```typescript
+import { cache } from "react";
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth();
+  if (!session?.user?.id) return null;
+  return await db.user.findUnique({ where: { id: session.user.id } });
+});
+```
+
+**Avoid inline objects as arguments** -- `React.cache()` uses `Object.is` equality. Inline objects always create new references, causing cache misses.
+
+```typescript
+// Incorrect (always cache miss)
+const getUser = cache(async (params: { uid: number }) => {
+  /* ... */
+});
+getUser({ uid: 1 });
+getUser({ uid: 1 }); // Miss -- new object reference
+
+// Correct (cache hit)
+const getUser = cache(async (uid: number) => {
+  /* ... */
+});
+getUser(1);
+getUser(1); // Hit -- same primitive value
+```
+
+**Next.js note:** `fetch` is automatically deduplicated within a single request. `React.cache()` is still essential for database queries, auth checks, heavy computations, and any non-fetch async work.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)
+
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+RSC-to-client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations in the client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays x 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />;
+
+// Client: transform there
+("use client");
+const sorted = useMemo(() => [...usernames].sort(), [usernames]);
+```
+
+Operations that break deduplication (create new references): `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`, `{...obj}`, `structuredClone()`.
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need the original.
+
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader();
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  );
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader();
+  return <div>{data}</div>;
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems();
+  return <nav>{items.map(renderItem)}</nav>;
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  );
+}
+```
+
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The RSC/Client boundary serializes all object properties into the HTML response. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser(); // 50 fields
+  return <Profile user={user} />;
+}
+
+("use client");
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>; // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser();
+  return <Profile name={user.name} />;
+}
+
+("use client");
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>;
+}
+```