@jgamaraalv/ts-dev-kit 1.0.0

package/skills/react-best-practices/references/advanced-patterns.md

@@ -0,0 +1,91 @@
+# Advanced Patterns
+
+Specialized React patterns for edge cases.
+
+## Table of Contents
+
+- [Store Event Handlers in Refs](#store-event-handlers-in-refs)
+- [Initialize App Once Per Load](#initialize-app-once-per-load)
+
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler);
+    return () => window.removeEventListener(event, handler);
+  }, [event, handler]);
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler);
+  useEffect(() => {
+    handlerRef.current = handler;
+  }, [handler]);
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e);
+    window.addEventListener(event, listener);
+    return () => window.removeEventListener(event, listener);
+  }, [event]);
+}
+```
+
+**Alternative: use `useEffectEvent` (React 19+):**
+
+```tsx
+import { useEffectEvent } from "react";
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler);
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent);
+    return () => window.removeEventListener(event, onEvent);
+  }, [event]);
+}
+```
+
+---
+
+## Initialize App Once Per Load
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])`. Components can remount and effects will re-run. Use a module-level guard.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage();
+    checkAuthToken();
+  }, []);
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false;
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return;
+    didInit = true;
+    loadFromStorage();
+    checkAuthToken();
+  }, []);
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)

package/skills/react-best-practices/references/async-patterns.md

@@ -0,0 +1,233 @@
+# Async Patterns
+
+Eliminate request waterfalls -- the #1 performance killer in React/Next.js apps.
+
+## Table of Contents
+
+- [Prevent Waterfall Chains in API Routes](#prevent-waterfall-chains-in-api-routes)
+- [Defer Await Until Needed](#defer-await-until-needed)
+- [Dependency-Based Parallelization](#dependency-based-parallelization)
+- [Strategic Suspense Boundaries](#strategic-suspense-boundaries)
+
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth();
+  const config = await fetchConfig();
+  const data = await fetchData(session.user.id);
+  return Response.json({ data, config });
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth();
+  const configPromise = fetchConfig();
+  const session = await sessionPromise;
+  const [config, data] = await Promise.all([configPromise, fetchData(session.user.id)]);
+  return Response.json({ data, config });
+}
+```
+
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId);
+
+  if (skipProcessing) {
+    return { skipped: true };
+  }
+
+  return processUserData(userData);
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    return { skipped: true };
+  }
+
+  const userData = await fetchUserData(userId);
+  return processUserData(userData);
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId);
+  const resource = await getResource(resourceId);
+
+  if (!resource) {
+    return { error: "Not found" };
+  }
+
+  if (!permissions.canEdit) {
+    return { error: "Forbidden" };
+  }
+
+  return await updateResourceData(resource, permissions);
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId);
+
+  if (!resource) {
+    return { error: "Not found" };
+  }
+
+  const permissions = await fetchPermissions(userId);
+
+  if (!permissions.canEdit) {
+    return { error: "Forbidden" };
+  }
+
+  return await updateResourceData(resource, permissions);
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use vanilla `Promise.all()` with `.then()` chaining to maximize parallelism. Start all promises upfront and let dependent operations chain off their prerequisites.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([fetchUser(), fetchConfig()]);
+const profile = await fetchProfile(user.id);
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+const userPromise = fetchUser();
+const profilePromise = userPromise.then((user) => fetchProfile(user.id));
+
+const [user, config, profile] = await Promise.all([userPromise, fetchConfig(), profilePromise]);
+```
+
+**Optional: `better-all` library for complex dependency graphs:**
+
+```typescript
+import { all } from "better-all";
+
+const { user, config, profile } = await all({
+  async user() {
+    return fetchUser();
+  },
+  async config() {
+    return fetchConfig();
+  },
+  async profile() {
+    return fetchProfile((await this.$.user).id);
+  },
+});
+```
+
+Reference: [better-all](https://github.com/shuding/better-all)
+
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+  const data = await fetchData(); // Blocks entire page
+
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  );
+}
+```
+
+**Correct (wrapper shows immediately, data streams in):**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  );
+}
+
+async function DataDisplay() {
+  const data = await fetchData(); // Only blocks this component
+  return <div>{data.content}</div>;
+}
+```
+
+**Alternative (share promise across components with `use()`):**
+
+```tsx
+function Page() {
+  const dataPromise = fetchData();
+
+  return (
+    <div>
+      <div>Sidebar</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  );
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise);
+  return <div>{data.content}</div>;
+}
+```
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading to content jump)

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

@@ -0,0 +1,201 @@
+# Bundle Size Optimization
+
+Reduce JavaScript shipped to clients -- directly impacts load time and interactivity.
+
+## Table of Contents
+
+- [Avoid Barrel File Imports](#avoid-barrel-file-imports)
+- [Conditional Module Loading](#conditional-module-loading)
+- [Defer Non-Critical Third-Party Libraries](#defer-non-critical-third-party-libraries)
+- [Dynamic Imports for Heavy Components](#dynamic-imports-for-heavy-components)
+- [Preload Based on User Intent](#preload-based-on-user-intent)
+
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. Barrel files re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular libraries can have **up to 10,000 re-exports**. For many React packages, **importing takes 200-800ms**, affecting dev speed and production cold starts. Tree-shaking doesn't help when a library is marked as external.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from "lucide-react";
+// Loads 1,583 modules, takes ~2.8s extra in dev
+
+import { Button, TextField } from "@mui/material";
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct (imports only what you need):**
+
+```tsx
+import Check from "lucide-react/dist/esm/icons/check";
+import X from "lucide-react/dist/esm/icons/x";
+import Menu from "lucide-react/dist/esm/icons/menu";
+
+import Button from "@mui/material/Button";
+import TextField from "@mui/material/TextField";
+```
+
+**Alternative (Next.js 13.5+):**
+
+```js
+// next.config.js
+module.exports = {
+  experimental: {
+    optimizePackageImports: ["lucide-react", "@mui/material"],
+  },
+};
+
+// Then keep ergonomic barrel imports -- transformed at build time
+import { Check, X, Menu } from "lucide-react";
+```
+
+Commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@radix-ui/react-*`, `lodash`, `date-fns`.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+
+---
+
+## Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+```tsx
+function AnimationPlayer({
+  enabled,
+  setEnabled,
+}: {
+  enabled: boolean;
+  setEnabled: React.Dispatch<React.SetStateAction<boolean>>;
+}) {
+  const [frames, setFrames] = useState<Frame[] | null>(null);
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== "undefined") {
+      import("./animation-frames.js")
+        .then((mod) => setFrames(mod.frames))
+        .catch(() => setEnabled(false));
+    }
+  }, [enabled, frames, setEnabled]);
+
+  if (!frames) return <Skeleton />;
+  return <Canvas frames={frames} />;
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size.
+
+---
+
+## Defer Non-Critical Third-Party Libraries
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect (blocks initial bundle):**
+
+```tsx
+import { Analytics } from "@vercel/analytics/react";
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  );
+}
+```
+
+**Correct (loads after hydration):**
+
+```tsx
+import dynamic from "next/dynamic";
+
+const Analytics = dynamic(() => import("@vercel/analytics/react").then((m) => m.Analytics), {
+  ssr: false,
+});
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  );
+}
+```
+
+---
+
+## Dynamic Imports for Heavy Components
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect (Monaco bundles with main chunk ~300KB):**
+
+```tsx
+import { MonacoEditor } from "./monaco-editor";
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />;
+}
+```
+
+**Correct (Monaco loads on demand):**
+
+```tsx
+import dynamic from "next/dynamic";
+
+const MonacoEditor = dynamic(() => import("./monaco-editor").then((m) => m.MonacoEditor), {
+  ssr: false,
+});
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />;
+}
+```
+
+---
+
+## Preload Based on User Intent
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Preload on hover/focus:**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== "undefined") {
+      void import("./monaco-editor");
+    }
+  };
+
+  return (
+    <button onMouseEnter={preload} onFocus={preload} onClick={onClick}>
+      Open Editor
+    </button>
+  );
+}
+```
+
+**Preload when feature flag is enabled:**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== "undefined") {
+      void import("./monaco-editor").then((mod) => mod.init());
+    }
+  }, [flags.editorEnabled]);
+
+  return <FlagsContext.Provider value={flags}>{children}</FlagsContext.Provider>;
+}
+```

package/skills/react-best-practices/references/client-patterns.md

@@ -0,0 +1,178 @@
+# Client-Side Patterns
+
+Optimize client-side data fetching, event handling, and storage.
+
+## Table of Contents
+
+- [Deduplicate Global Event Listeners](#deduplicate-global-event-listeners)
+- [Version and Minimize localStorage Data](#version-and-minimize-localstorage-data)
+- [Use Passive Event Listeners](#use-passive-event-listeners)
+- [Use SWR for Automatic Deduplication](#use-swr-for-automatic-deduplication)
+
+---
+
+## Deduplicate Global Event Listeners
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) callback();
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, [key, callback]);
+}
+```
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import useSWRSubscription from "swr/subscription";
+
+const keyCallbacks = new Map<string, Set<() => void>>();
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) keyCallbacks.set(key, new Set());
+    keyCallbacks.get(key)!.add(callback);
+
+    return () => {
+      const set = keyCallbacks.get(key);
+      if (set) {
+        set.delete(callback);
+        if (set.size === 0) keyCallbacks.delete(key);
+      }
+    };
+  }, [key, callback]);
+
+  useSWRSubscription("global-keydown", () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach((cb) => cb());
+      }
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  });
+}
+```
+
+---
+
+## Version and Minimize localStorage Data
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+localStorage.setItem("userConfig", JSON.stringify(fullUserObject));
+```
+
+**Correct:**
+
+```typescript
+const VERSION = "v2";
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config));
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`);
+    return data ? JSON.parse(data) : null;
+  } catch {
+    return null;
+  }
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+Store minimal fields from server responses -- only what the UI needs.
+
+---
+
+## Use Passive Event Listeners
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  document.addEventListener("touchstart", handleTouch);
+  document.addEventListener("wheel", handleWheel);
+  return () => {
+    document.removeEventListener("touchstart", handleTouch);
+    document.removeEventListener("wheel", handleWheel);
+  };
+}, []);
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  document.addEventListener("touchstart", handleTouch, { passive: true });
+  document.addEventListener("wheel", handleWheel, { passive: true });
+  return () => {
+    document.removeEventListener("touchstart", handleTouch);
+    document.removeEventListener("wheel", handleWheel);
+  };
+}, []);
+```
+
+Use passive when: tracking/analytics, logging, any listener that doesn't call `preventDefault()`. Don't use when implementing custom swipe gestures or custom zoom controls.
+
+---
+
+## Use SWR for Automatic Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect (no deduplication, each instance fetches):**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([]);
+  useEffect(() => {
+    fetch("/api/users")
+      .then((r) => r.json())
+      .then(setUsers);
+  }, []);
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import useSWR from "swr";
+
+function UserList() {
+  const { data: users } = useSWR("/api/users", fetcher);
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from "swr/mutation";
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation("/api/user", updateUser);
+  return <button onClick={() => trigger()}>Update</button>;
+}
+```
+
+Reference: [SWR](https://swr.vercel.app)