npm - @kood/claude-code - Versions diffs - 0.3.12 → 0.3.14 - Mend

@kood/claude-code 0.3.12 → 0.3.14

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 (92) hide show

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/bundle-conditional.md ADDED Viewed

@@ -0,0 +1,31 @@
+---
+title: Conditional Module Loading
+impact: HIGH
+impactDescription: loads large data only when needed
+tags: bundle, conditional-loading, lazy-loading
+---
+## Conditional Module Loading
+Load large data or modules only when a feature is activated.
+**Example (lazy-load animation frames):**
+```tsx
+function AnimationPlayer({ enabled }: { enabled: 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])
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/bundle-defer-third-party.md ADDED Viewed

@@ -0,0 +1,49 @@
+---
+title: Defer Non-Critical Third-Party Libraries
+impact: MEDIUM
+impactDescription: loads after hydration
+tags: bundle, third-party, analytics, defer
+---
+## 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>
+  )
+}
+```

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/bundle-lazy-routes.md ADDED Viewed

@@ -0,0 +1,67 @@
+---
+title: Route-Based Code Splitting
+impact: CRITICAL
+impactDescription: 30-50% smaller initial bundle
+tags: bundle, lazy-loading, code-splitting, routes
+---
+## Route-Based Code Splitting
+TanStack Router automatically code-splits by route. Use `lazy()` for heavy components within routes to reduce bundle size further.
+**Incorrect (heavy component loaded upfront):**
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import HeavyEditor from '@/components/HeavyEditor' // 500KB bundle
+export const Route = createFileRoute('/editor')({
+  component: () => <HeavyEditor />
+})
+// Entire 500KB loads even if user never visits /editor
+```
+**Correct (lazy load heavy components):**
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { lazy, Suspense } from 'react'
+const HeavyEditor = lazy(() => import('@/components/HeavyEditor'))
+export const Route = createFileRoute('/editor')({
+  component: () => (
+    <Suspense fallback={<EditorSkeleton />}>
+      <HeavyEditor />
+    </Suspense>
+  )
+})
+// 500KB only loads when user navigates to /editor
+```
+**For multiple heavy dependencies:**
+```tsx
+import { lazy, Suspense } from 'react'
+const ChartComponent = lazy(() => import('@/components/ChartComponent'))
+const PDFViewer = lazy(() => import('@/components/PDFViewer'))
+const VideoPlayer = lazy(() => import('@/components/VideoPlayer'))
+export const Route = createFileRoute('/dashboard')({
+  component: () => (
+    <div>
+      <Suspense fallback={<ChartSkeleton />}>
+        <ChartComponent />
+      </Suspense>
+      <Suspense fallback={<PDFSkeleton />}>
+        <PDFViewer />
+      </Suspense>
+    </div>
+  )
+})
+```
+Heavy libraries to consider lazy loading: chart libraries (recharts, chart.js), rich text editors (tiptap, slate), PDF viewers, video players, 3D renderers, data visualization.
+This reduces initial bundle by 30-50% and improves Time to Interactive.

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/bundle-preload.md ADDED Viewed

@@ -0,0 +1,50 @@
+---
+title: Preload Based on User Intent
+impact: MEDIUM
+impactDescription: reduces perceived latency
+tags: bundle, preload, user-intent, hover
+---
+## Preload Based on User Intent
+Preload heavy bundles before they're needed to reduce perceived latency.
+**Example (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>
+  )
+}
+```
+**Example (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>
+}
+```
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/client-event-listeners.md ADDED Viewed

@@ -0,0 +1,74 @@
+---
+title: Deduplicate Global Event Listeners
+impact: LOW
+impactDescription: single listener for N components
+tags: client, swr, event-listeners, subscription
+---
+## 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])
+}
+```
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+**Correct (N instances = 1 listener):**
+```tsx
+import useSWRSubscription from 'swr/subscription'
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  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)
+  })
+}
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ })
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/client-tanstack-query.md ADDED Viewed

@@ -0,0 +1,77 @@
+---
+title: Use TanStack Query for Automatic Caching and Deduplication
+impact: MEDIUM-HIGH
+impactDescription: eliminates duplicate requests
+tags: client, cache, tanstack-query, deduplication
+---
+## Use TanStack Query for Automatic Caching and Deduplication
+Wrap server function calls with TanStack Query to enable automatic request deduplication, caching, and background refetching.
+**Incorrect (no deduplication, each component fetches):**
+```tsx
+import { useState, useEffect } from 'react'
+import { getUsers } from '@/functions/data'
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    getUsers().then(setUsers)
+  }, [])
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>
+}
+// If UserList is used 3 times on a page, getUsers() is called 3 times
+```
+**Correct (automatic deduplication, single request):**
+```tsx
+import { useQuery } from '@tanstack/react-query'
+import { getUsers } from '@/functions/data'
+function UserList() {
+  const { data: users = [] } = useQuery({
+    queryKey: ['users'],
+    queryFn: () => getUsers()
+  })
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>
+}
+// Multiple instances share one request, with automatic cache invalidation
+```
+**With mutations:**
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { getUsers, createUser } from '@/functions/data'
+function UserManager() {
+  const queryClient = useQueryClient()
+  const { data: users = [] } = useQuery({
+    queryKey: ['users'],
+    queryFn: () => getUsers()
+  })
+  const mutation = useMutation({
+    mutationFn: createUser,
+    onSuccess: () => {
+      // Automatically refetch users
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+    }
+  })
+  return <div>...</div>
+}
+```
+TanStack Query provides: request deduplication, background refetching, cache invalidation, optimistic updates, retry logic, and loading/error states.
+Reference: [TanStack Query](https://tanstack.com/query)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-batch-dom-css.md ADDED Viewed

@@ -0,0 +1,82 @@
+---
+title: Batch DOM CSS Changes
+impact: MEDIUM
+impactDescription: reduces reflows/repaints
+tags: javascript, dom, css, performance, reflow
+---
+## Batch DOM CSS Changes
+Avoid changing styles one property at a time. Group multiple CSS changes together via classes or `cssText` to minimize browser reflows.
+**Incorrect (multiple reflows):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line triggers a reflow
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+**Correct (add class - single reflow):**
+```typescript
+// CSS file
+.highlighted-box {
+  width: 100px;
+  height: 200px;
+  background-color: blue;
+  border: 1px solid black;
+}
+// JavaScript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+}
+```
+**Correct (change cssText - single reflow):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.style.cssText = `
+    width: 100px;
+    height: 200px;
+    background-color: blue;
+    border: 1px solid black;
+  `
+}
+```
+**React example:**
+```tsx
+// Incorrect: changing styles one by one
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      ref.current.style.height = '200px'
+      ref.current.style.backgroundColor = 'blue'
+    }
+  }, [isHighlighted])
+  return <div ref={ref}>Content</div>
+}
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+Prefer CSS classes over inline styles when possible. Classes are cached by the browser and provide better separation of concerns.

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-cache-function-results.md ADDED Viewed

@@ -0,0 +1,80 @@
+---
+title: Cache Repeated Function Calls
+impact: MEDIUM
+impactDescription: avoid redundant computation
+tags: javascript, cache, memoization, performance
+---
+## Cache Repeated Function Calls
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+**Incorrect (redundant computation):**
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+**Correct (cached results):**
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+**Simpler pattern for single-value functions:**
+```typescript
+let isLoggedInCache: boolean | null = null
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-cache-property-access.md ADDED Viewed

@@ -0,0 +1,28 @@
+---
+title: Cache Property Access in Loops
+impact: LOW-MEDIUM
+impactDescription: reduces lookups
+tags: javascript, loops, optimization, caching
+---
+## Cache Property Access in Loops
+Cache object property lookups in hot paths.
+**Incorrect (3 lookups × N iterations):**
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+**Correct (1 lookup total):**
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-cache-storage.md ADDED Viewed

@@ -0,0 +1,70 @@
+---
+title: Cache Storage API Calls
+impact: LOW-MEDIUM
+impactDescription: reduces expensive I/O
+tags: javascript, localStorage, storage, caching, performance
+---
+## Cache Storage API Calls
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+**Incorrect (reads storage on every call):**
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+**Correct (Map cache):**
+```typescript
+const storageCache = new Map<string, string | null>()
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+**Cookie caching:**
+```typescript
+let cookieCache: Record<string, string> | null = null
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+**Important (invalidate on external changes):**
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-combine-iterations.md ADDED Viewed

@@ -0,0 +1,32 @@
+---
+title: Combine Multiple Array Iterations
+impact: LOW-MEDIUM
+impactDescription: reduces iterations
+tags: javascript, arrays, loops, performance
+---
+## Combine Multiple Array Iterations
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+**Incorrect (3 iterations):**
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+**Correct (1 iteration):**
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-early-exit.md ADDED Viewed

@@ -0,0 +1,50 @@
+---
+title: Early Return from Functions
+impact: LOW-MEDIUM
+impactDescription: avoids unnecessary computation
+tags: javascript, functions, optimization, early-return
+---
+## Early Return from Functions
+Return early when result is determined to skip unnecessary processing.
+**Incorrect (processes all items even after finding answer):**
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+**Correct (returns immediately on first error):**
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+  return { valid: true }
+}
+```