codecruise 0.1.0

package/config/agents/stack/nextjs/rules/performance.md

@@ -0,0 +1,403 @@
+# Performance Rules - Next.js
+
+Core Web Vitals optimization and performance patterns.
+
+---
+
+## Core Web Vitals
+
+### PERF-001: Optimize Largest Contentful Paint (LCP)
+
+```typescript
+// Priority loading for hero images
+import Image from 'next/image';
+
+// Above-the-fold images
+<Image
+  src="/hero.jpg"
+  alt="Hero"
+  width={1200}
+  height={600}
+  priority  // Preload this image
+  fetchPriority="high"
+/>
+
+// Preload critical fonts
+// app/layout.tsx
+import { Inter } from 'next/font/google';
+
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap',  // Prevent FOIT
+  preload: true,
+});
+```
+
+### PERF-002: Minimize Cumulative Layout Shift (CLS)
+
+```typescript
+// Always specify dimensions for images
+<Image
+  src={user.avatar}
+  alt={user.name}
+  width={48}
+  height={48}  // Prevents layout shift
+/>
+
+// Use aspect-ratio for dynamic content
+<div className="aspect-video">
+  <iframe src={videoUrl} className="w-full h-full" />
+</div>
+
+// Reserve space for loading content
+<div className="min-h-[200px]">
+  <Suspense fallback={<Skeleton className="h-[200px]" />}>
+    <DynamicContent />
+  </Suspense>
+</div>
+```
+
+### PERF-003: Optimize First Input Delay (FID) / INP
+
+```typescript
+// Defer non-critical JavaScript
+import dynamic from 'next/dynamic';
+
+// Load heavy components only when needed
+const Analytics = dynamic(() => import('./Analytics'), {
+  ssr: false,  // Client-only
+});
+
+// Use startTransition for non-urgent updates
+import { startTransition } from 'react';
+
+function SearchInput() {
+  const [query, setQuery] = useState('');
+
+  return (
+    <input
+      value={query}
+      onChange={(e) => {
+        // Immediate update for input
+        setQuery(e.target.value);
+
+        // Deferred update for search results
+        startTransition(() => {
+          setSearchResults(e.target.value);
+        });
+      }}
+    />
+  );
+}
+```
+
+---
+
+## Bundle Optimization
+
+### PERF-004: Dynamic imports for large components
+
+```typescript
+import dynamic from 'next/dynamic';
+
+// Heavy components
+const Editor = dynamic(() => import('./Editor'), {
+  loading: () => <Skeleton className="h-96" />,
+  ssr: false,
+});
+
+const Chart = dynamic(() => import('./Chart'), {
+  loading: () => <Skeleton className="h-64" />,
+});
+
+// Conditionally loaded
+const AdminPanel = dynamic(() => import('./AdminPanel'));
+
+function Dashboard({ isAdmin }) {
+  return (
+    <div>
+      <Chart data={data} />
+      {isAdmin && <AdminPanel />}
+    </div>
+  );
+}
+```
+
+### PERF-005: Optimize imports
+
+```typescript
+// BAD - Imports entire library
+import { format } from 'date-fns';
+import _ from 'lodash';
+
+// GOOD - Tree-shakeable imports
+import format from 'date-fns/format';
+import debounce from 'lodash/debounce';
+
+// Or use lighter alternatives
+import { formatDistance } from 'date-fns/formatDistance';
+```
+
+### PERF-006: Analyze bundle size
+
+```javascript
+// next.config.js
+const withBundleAnalyzer = require('@next/bundle-analyzer')({
+  enabled: process.env.ANALYZE === 'true',
+});
+
+module.exports = withBundleAnalyzer({
+  // config
+});
+
+// Run: ANALYZE=true npm run build
+```
+
+---
+
+## Image Optimization
+
+### PERF-007: Use responsive images
+
+```typescript
+<Image
+  src="/hero.jpg"
+  alt="Hero"
+  width={1200}
+  height={600}
+  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+  // Generates multiple sizes, browser picks best one
+/>
+```
+
+### PERF-008: Lazy load below-fold images
+
+```typescript
+// Default behavior - lazy loaded
+<Image
+  src="/gallery/1.jpg"
+  alt="Gallery item"
+  width={400}
+  height={300}
+  loading="lazy"  // Default, can be explicit
+/>
+
+// Only use priority for above-fold
+<Image
+  src="/hero.jpg"
+  priority  // Only for LCP image
+/>
+```
+
+### PERF-009: Use modern formats
+
+```javascript
+// next.config.js
+module.exports = {
+  images: {
+    formats: ['image/avif', 'image/webp'],
+    deviceSizes: [640, 750, 828, 1080, 1200, 1920],
+    imageSizes: [16, 32, 48, 64, 96, 128, 256],
+  },
+};
+```
+
+---
+
+## Caching
+
+### PERF-010: Configure fetch caching
+
+```typescript
+// Cached by default in Server Components
+const data = await fetch('https://api.example.com/data');
+
+// Revalidate every hour
+const data = await fetch('https://api.example.com/data', {
+  next: { revalidate: 3600 },
+});
+
+// No cache (dynamic data)
+const data = await fetch('https://api.example.com/data', {
+  cache: 'no-store',
+});
+
+// Tags for selective revalidation
+const data = await fetch('https://api.example.com/users', {
+  next: { tags: ['users'] },
+});
+
+// Revalidate by tag
+import { revalidateTag } from 'next/cache';
+revalidateTag('users');
+```
+
+### PERF-011: Use unstable_cache for DB queries
+
+```typescript
+import { unstable_cache } from 'next/cache';
+
+const getCachedUser = unstable_cache(
+  async (userId: string) => {
+    return db.user.findUnique({ where: { id: userId } });
+  },
+  ['user'],  // Cache key parts
+  {
+    revalidate: 3600,  // 1 hour
+    tags: ['users'],
+  }
+);
+
+// Usage
+const user = await getCachedUser(userId);
+```
+
+### PERF-012: Implement stale-while-revalidate
+
+```typescript
+// Route segment config
+export const revalidate = 60; // Revalidate at most every 60 seconds
+
+// Or per-fetch
+const data = await fetch(url, {
+  next: { revalidate: 60 },
+});
+```
+
+---
+
+## Streaming & Suspense
+
+### PERF-013: Stream long-running data fetches
+
+```typescript
+import { Suspense } from 'react';
+
+export default function Page() {
+  return (
+    <div>
+      {/* Renders immediately */}
+      <Header />
+
+      {/* Streams when ready */}
+      <Suspense fallback={<StatsSkeleton />}>
+        <SlowStats />
+      </Suspense>
+
+      {/* Another stream */}
+      <Suspense fallback={<RecommendationsSkeleton />}>
+        <Recommendations />
+      </Suspense>
+
+      {/* Renders immediately */}
+      <Footer />
+    </div>
+  );
+}
+```
+
+### PERF-014: Parallel data fetching
+
+```typescript
+// BAD - Sequential (waterfall)
+async function Page() {
+  const user = await getUser();
+  const posts = await getPosts();
+  const comments = await getComments();
+}
+
+// GOOD - Parallel
+async function Page() {
+  const [user, posts, comments] = await Promise.all([
+    getUser(),
+    getPosts(),
+    getComments(),
+  ]);
+}
+
+// BETTER - Stream independently
+function Page() {
+  return (
+    <>
+      <Suspense fallback={<UserSkeleton />}>
+        <UserSection />
+      </Suspense>
+      <Suspense fallback={<PostsSkeleton />}>
+        <PostsSection />
+      </Suspense>
+    </>
+  );
+}
+```
+
+---
+
+## Font Optimization
+
+### PERF-015: Use next/font
+
+```typescript
+// app/layout.tsx
+import { Inter, Roboto_Mono } from 'next/font/google';
+
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-inter',
+});
+
+const robotoMono = Roboto_Mono({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-roboto-mono',
+});
+
+export default function RootLayout({ children }) {
+  return (
+    <html className={`${inter.variable} ${robotoMono.variable}`}>
+      <body className="font-sans">{children}</body>
+    </html>
+  );
+}
+
+// tailwind.config.js
+module.exports = {
+  theme: {
+    fontFamily: {
+      sans: ['var(--font-inter)'],
+      mono: ['var(--font-roboto-mono)'],
+    },
+  },
+};
+```
+
+---
+
+## Monitoring
+
+### PERF-016: Track Web Vitals
+
+```typescript
+// app/layout.tsx
+import { SpeedInsights } from '@vercel/speed-insights/next';
+import { Analytics } from '@vercel/analytics/react';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <SpeedInsights />
+        <Analytics />
+      </body>
+    </html>
+  );
+}
+
+// Or custom reporting
+// app/web-vitals.ts
+export function reportWebVitals(metric) {
+  console.log(metric);
+  // Send to analytics
+}
+```