@adonis0123/react-best-practices 1.0.0

package/rules/server-cache-lru.md

@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```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
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)

package/rules/server-cache-react.md

@@ -0,0 +1,26 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```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 }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.

package/rules/server-parallel-fetching.md

@@ -0,0 +1,79 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## 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 to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**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>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Layout({ children }: { children: ReactNode }) {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      {children}
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

package/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. 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>
+}
+```

package/uninstall-skill.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { getEnabledTargets, extractSkillName, detectInstallLocation } = require('./utils');
+
+function uninstallFromTarget(target, config) {
+  console.log(`\n🗑️  Uninstalling from ${target.name}...`);
+
+  const isGlobal = process.env.npm_config_global === 'true';
+  const location = detectInstallLocation(target.paths, isGlobal);
+
+  // Extract skill name from package name (remove scope prefix)
+  const skillName = extractSkillName(config.name);
+
+  // Path format using skill name
+  const skillNameTargetDir = path.join(location.base, skillName);
+
+  // Path format with full package name (including scope)
+  const fullPackageNameTargetDir = path.join(location.base, config.name);
+
+  let removed = false;
+
+  // Check and remove path using skill name
+  if (fs.existsSync(skillNameTargetDir)) {
+    fs.rmSync(skillNameTargetDir, { recursive: true, force: true });
+    console.log(`  ✓ Removed skill directory: ${skillName}`);
+    removed = true;
+  }
+
+  // Check and remove path with full package name (for compatibility)
+  if (fs.existsSync(fullPackageNameTargetDir) && fullPackageNameTargetDir !== skillNameTargetDir) {
+    fs.rmSync(fullPackageNameTargetDir, { recursive: true, force: true });
+    console.log(`  ✓ Removed skill directory: ${config.name}`);
+    removed = true;
+  }
+
+  // Update manifest
+  const manifestPath = path.join(location.base, '.skills-manifest.json');
+  if (fs.existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      if (manifest.skills && manifest.skills[config.name]) {
+        delete manifest.skills[config.name];
+        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+        console.log(`  ✓ Updated manifest`);
+      }
+    } catch (error) {
+      console.warn('  Warning: Could not update manifest:', error.message);
+    }
+  }
+
+  if (removed) {
+    console.log(`  ✅ Uninstalled from ${target.name}`);
+    return true;
+  } else {
+    console.log(`  ℹ️  Skill was not installed in ${target.name}`);
+    return false;
+  }
+}
+
+function uninstallSkill() {
+  console.log('🗑️  Uninstalling AI Coding Skill...\n');
+
+  // Read configuration
+  const configPath = path.join(__dirname, '.claude-skill.json');
+  if (!fs.existsSync(configPath)) {
+    console.warn('Warning: .claude-skill.json not found, skipping cleanup');
+    return;
+  }
+
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+
+  // Get enabled targets
+  const enabledTargets = getEnabledTargets(config);
+
+  console.log(`Uninstalling skill "${config.name}" from ${enabledTargets.length} target(s):`);
+  enabledTargets.forEach(target => {
+    console.log(`  • ${target.name}`);
+  });
+
+  // Uninstall from all enabled targets
+  const uninstalledFrom = [];
+  for (const target of enabledTargets) {
+    try {
+      const success = uninstallFromTarget(target, config);
+      if (success) {
+        uninstalledFrom.push(target.name);
+      }
+    } catch (error) {
+      console.error(`\n❌ Failed to uninstall from ${target.name}:`, error.message);
+    }
+  }
+
+  // Summary
+  console.log('\n' + '='.repeat(60));
+  if (uninstalledFrom.length > 0) {
+    console.log('✅ Uninstallation Complete!');
+    console.log('='.repeat(60));
+    console.log('\nUninstalled from:');
+    uninstalledFrom.forEach(target => {
+      console.log(`  • ${target}`);
+    });
+  } else {
+    console.log('ℹ️  Skill was not installed');
+    console.log('='.repeat(60));
+  }
+}
+
+// Execute uninstall
+try {
+  uninstallSkill();
+} catch (error) {
+  console.error('\n⚠️  Warning during uninstall:', error.message);
+  // Don't exit with error code as uninstall should be best-effort
+}

package/utils.js

@@ -0,0 +1,94 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CWD = process.env.INIT_CWD || process.cwd();
+
+/**
+ * Get enabled target configurations
+ */
+function getEnabledTargets(config) {
+  // If no targets configuration, use default Claude Code configuration
+  if (!config.targets) {
+    return [{
+      name: 'claude-code',
+      paths: {
+        global: '.claude/skills',
+        project: '.claude/skills'
+      }
+    }];
+  }
+
+  // Return all enabled targets
+  return Object.entries(config.targets)
+    .filter(([_, target]) => target.enabled)
+    .map(([name, target]) => ({
+      name,
+      paths: target.paths
+    }));
+}
+
+/**
+ * Extract skill name from package name (remove scope prefix)
+ */
+function extractSkillName(packageName) {
+  return packageName.startsWith('@') ?
+    packageName.split('/')[1] || packageName :
+    packageName;
+}
+
+/**
+ * Detect installation location
+ */
+function detectInstallLocation(targetPaths, isGlobal) {
+  if (isGlobal) {
+    // Global installation: install to user home directory
+    return {
+      type: 'personal',
+      base: path.join(os.homedir(), targetPaths.global)
+    };
+  } else {
+    // Project-level installation: find the actual project root directory
+    let projectRoot = CWD;
+
+    // Search upward, skip node_modules directories, find the actual project root
+    while (projectRoot !== path.dirname(projectRoot)) {
+      // Check if this is a project root directory (contains package.json or .git)
+      const hasPackageJson = fs.existsSync(path.join(projectRoot, 'package.json'));
+      const hasGit = fs.existsSync(path.join(projectRoot, '.git'));
+
+      // Check if current directory is in node_modules
+      const isInNodeModules = projectRoot.includes('/node_modules/') ||
+                             path.basename(projectRoot) === 'node_modules';
+
+      if ((hasPackageJson || hasGit) && !isInNodeModules) {
+        // Found the actual project root directory
+        break;
+      }
+
+      // Continue searching upward
+      projectRoot = path.dirname(projectRoot);
+    }
+
+    // Verify the final path is reasonable
+    const finalIsInNodeModules = projectRoot.includes('/node_modules/') ||
+                                path.basename(projectRoot) === 'node_modules';
+
+    if (finalIsInNodeModules) {
+      // If suitable project root not found, use current working directory (with warning)
+      console.warn('⚠ Warning: Could not find project root directory, using current directory');
+      projectRoot = CWD;
+    }
+
+    return {
+      type: 'project',
+      base: path.join(projectRoot, targetPaths.project)
+    };
+  }
+}
+
+module.exports = {
+  getEnabledTargets,
+  extractSkillName,
+  detectInstallLocation
+};