@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/nextjs/server-components/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: Next.js Server Components
+description: RSC usage, "use client" directive, and Component Purity.
+metadata:
+  labels: [nextjs, rsc, components]
+  triggers:
+    files: ['**/*.tsx', '**/*.jsx']
+    keywords: [use client, Server Component, Client Component, hydration]
+---
+
+# Server & Client Components
+
+## **Priority: P0 (CRITICAL)**
+
+Next.js (App Router) uses React Server Components (RSC) by default.
+
+## Server Components (Default)
+
+- **Behavior**: Rendered on server, sent as HTML/Payload to client. Zero bundle size for included libs.
+- **Capabilities**: Async/Await, Direct DB access, Secrets usage.
+- **Restrictions**: No `useState`, `useEffect`, or Browser APIs (`window`, `localstorage`).
+
+## Client Components
+
+- **Directive**: Add `'use client'` at the VERY TOP of the file.
+- **Usage**: Interactivity (`onClick`), State (`useState`), Lifecycle effects, Browser APIs.
+- **Strategy**: Move Client Components to the leaves of the tree.
+  - _Bad_: Making the root layout a Client Component.
+  - _Good_: Wrapping a `<Button />` in a Client Component.
+
+## Composition Patterns
+
+- **Server-in-Client**: You cannot import a Server Component directly into a Client Component.
+  - _Fix_: Pass Server Component as `children` prop to the Client Component.
+
+```tsx
+// ClientWrapper.tsx
+'use client';
+export default function ClientWrapper({ children }) {
+  return <div>{children}</div>;
+}
+
+// Page.tsx (Server)
+<ClientWrapper>
+  <ServerComponent />
+</ClientWrapper>;
+```
+
+## Anti-Patterns
+
+- **Poisoning**: Importing server-only secrets into Client Components (Use `server-only` package to prevent).
+- **Over-fetching**: Passing large data props to Client Components (Serialization cost). Only pass IDs if possible.

package/rules/nextjs/server-components/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Next.js Server Components References
+
+## References
+
+- [**Component Patterns**](component-patterns.md) - RSC, client boundaries, data
+
+## Quick Checks
+
+- [ ] Default to Server Components
+- [ ] 'use client' only when needed
+- [ ] Fetch data in Server Components
+- [ ] Composition pattern for interactivity
+- [ ] Stream with Suspense

package/rules/nextjs/server-components/references/component-patterns.md

@@ -0,0 +1,175 @@
+# Next.js Server Component Patterns
+
+## Server vs Client Components
+
+```tsx
+// Server Component (default) - runs on server only
+async function UserList() {
+  const users = await db.users.findMany(); // Direct DB access
+  return (
+    <ul>
+      {users.map(user => <li key={user.id}>{user.name}</li>)}
+    </ul>
+  );
+}
+
+// Client Component - runs on client
+'use client';
+
+import { useState } from 'react';
+
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+## When to Use Client Components
+
+```tsx
+'use client';
+
+// Use 'use client' when you need:
+// - useState, useEffect, useReducer
+// - Event listeners (onClick, onChange)
+// - Browser APIs (window, document)
+// - Custom hooks with state
+// - Class components
+
+function InteractiveForm() {
+  const [value, setValue] = useState('');
+  
+  return (
+    <input
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+}
+```
+
+## Composition Pattern
+
+```tsx
+// Server Component with Client Component children
+async function Dashboard() {
+  const data = await fetchDashboardData();
+  
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      {/* Server-rendered data passed to client component */}
+      <InteractiveChart data={data.chartData} />
+      {/* Server Component */}
+      <StaticStats stats={data.stats} />
+    </div>
+  );
+}
+
+// Client Component receives serializable props
+'use client';
+
+function InteractiveChart({ data }: { data: ChartData[] }) {
+  const [selected, setSelected] = useState<string | null>(null);
+  return <Chart data={data} onSelect={setSelected} />;
+}
+```
+
+## Streaming with Suspense
+
+```tsx
+import { Suspense } from 'react';
+
+async function Page() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      
+      {/* Streams independently */}
+      <Suspense fallback={<StatsSkeleton />}>
+        <Stats />
+      </Suspense>
+      
+      <Suspense fallback={<ChartSkeleton />}>
+        <Chart />
+      </Suspense>
+      
+      <Suspense fallback={<TableSkeleton />}>
+        <DataTable />
+      </Suspense>
+    </div>
+  );
+}
+
+// Each component fetches its own data
+async function Stats() {
+  const stats = await getStats(); // Slow query
+  return <StatsDisplay stats={stats} />;
+}
+```
+
+## Passing Server Data to Client
+
+```tsx
+// Server Component fetches, Client Component interacts
+async function ProductPage({ id }: { id: string }) {
+  const product = await getProduct(id);
+  
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <p>{product.description}</p>
+      {/* Pass serializable data to client */}
+      <AddToCartButton productId={product.id} price={product.price} />
+    </div>
+  );
+}
+
+'use client';
+
+function AddToCartButton({ productId, price }: { productId: string; price: number }) {
+  const [adding, setAdding] = useState(false);
+  
+  async function handleClick() {
+    setAdding(true);
+    await addToCart(productId);
+    setAdding(false);
+  }
+  
+  return (
+    <button onClick={handleClick} disabled={adding}>
+      Add to Cart - ${price}
+    </button>
+  );
+}
+```
+
+## Avoid Client Component Wrappers
+
+```tsx
+// ❌ Bad - makes everything client
+'use client';
+export default function Layout({ children }) {
+  const [theme, setTheme] = useState('light');
+  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
+}
+
+// ✅ Good - minimal client boundary
+// ThemeProvider.tsx
+'use client';
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setTheme] = useState('light');
+  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
+}
+
+// layout.tsx (Server Component)
+export default function Layout({ children }) {
+  return (
+    <html>
+      <body>
+        <ThemeProvider>{children}</ThemeProvider>
+      </body>
+    </html>
+  );
+}
+```

package/rules/nextjs/state-management/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: Next.js State Management
+description: Best practices for managing state (Server URL vs Client Hooks).
+metadata:
+  labels: [nextjs, state, zustand, context]
+  triggers:
+    files: ['**/hooks/*.ts', '**/store.ts', '**/components/*.tsx']
+    keywords: [useState, useContext, zustand, redux]
+---
+
+# State Management
+
+## **Priority: P2 (MEDIUM)**
+
+Prefer Server State (URL) and Local State over Global Stores.
+
+## Principles
+
+1. **URL as Source of Truth**: For any state that should be shareable or persistent (Search queries, Filters, Pagination, Tabs), use the URL Search Params.
+   - _Why_: Keeps state syncable across refreshes and shareable links.
+   - _Tool_: `useSearchParams` hook.
+2. **Colocation**: Keep state as close to the component as possible. **Do not lift state** unless necessary to share between siblings.
+   - _Bad_: `App` component holding `searchTerm` for a `SearchBar` nested 5 levels deep.
+   - _Good_: `SearchBar` has internal state, or `MainContent` holds it if it needs to pass to siblings.
+3. **No Global Store Default**: Avoid Redux/Zustand for simple apps. Be skeptical of adding a library.
+   - _Use Cases for Global Store_: Complex interactors like a Music Player (persists across navigation), Shopping Cart (shared everywhere).
+
+## Patterns
+
+### 1. Granular State (Best Practice)
+
+Don't store large objects. Subscribe only to what you need to prevent unnecessary re-renders.
+
+```tsx
+// BAD: Re-renders on any change to 'user'
+const [user, setUser] = useState({ name: '', stats: {}, friends: [] });
+
+// GOOD: Independent states
+const [name, setName] = useState('');
+const [stats, setStats] = useState({});
+```
+
+### 2. URL-Driven State (Search/Filter)
+
+```tsx
+// Client Component
+'use client';
+import { useSearchParams, useRouter, usePathname } from 'next/navigation';
+
+export function Search() {
+  const searchParams = useSearchParams();
+  const { replace } = useRouter();
+  const pathname = usePathname();
+
+  function handleSearch(term: string) {
+    const params = new URLSearchParams(searchParams);
+    if (term) params.set('q', term);
+    else params.delete('q');
+
+    // Updates URL -> Server Component re-renders with new params
+    replace(`${pathname}?${params.toString()}`);
+  }
+}
+```
+
+### 3. Server State (TanStack Query / SWR)
+
+If you need "Live" data on the client (e.g., polling stock prices, chat), do not implement `useEffect` fetch manually. Use a library.
+
+```tsx
+// Automated caching, deduplication, and revalidation
+const { data, error } = useSWR('/api/user', fetcher);
+```

package/rules/nextjs/state-management/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Next.js State Management References
+
+## References
+
+- [**State Patterns**](state-patterns.md) - React Context, Zustand, server state
+
+## Quick Checks
+
+- [ ] Use React Context for simple global state
+- [ ] Use Zustand/Jotai for complex client state
+- [ ] Use React Query/SWR for server state
+- [ ] Minimize client-side state with RSC
+- [ ] Consider URL state for shareable state

package/rules/nextjs/state-management/references/state-patterns.md

@@ -0,0 +1,218 @@
+# Next.js State Management Patterns
+
+## React Context (Simple Global State)
+
+```typescript
+// contexts/theme-context.tsx
+'use client';
+
+import { createContext, useContext, useState } from 'react';
+
+type Theme = 'light' | 'dark';
+
+const ThemeContext = createContext<{
+  theme: Theme;
+  setTheme: (theme: Theme) => void;
+} | null>(null);
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setTheme] = useState<Theme>('light');
+
+  return (
+    <ThemeContext.Provider value={{ theme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (!context) throw new Error('useTheme must be used within ThemeProvider');
+  return context;
+}
+```
+
+## Zustand (Complex Client State)
+
+```typescript
+// stores/cart-store.ts
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+interface CartItem {
+  id: string;
+  name: string;
+  quantity: number;
+  price: number;
+}
+
+interface CartStore {
+  items: CartItem[];
+  addItem: (item: CartItem) => void;
+  removeItem: (id: string) => void;
+  clearCart: () => void;
+  total: () => number;
+}
+
+export const useCartStore = create<CartStore>()(
+  persist(
+    (set, get) => ({
+      items: [],
+      addItem: (item) =>
+        set((state) => {
+          const existing = state.items.find((i) => i.id === item.id);
+          if (existing) {
+            return {
+              items: state.items.map((i) =>
+                i.id === item.id ? { ...i, quantity: i.quantity + 1 } : i
+              ),
+            };
+          }
+          return { items: [...state.items, item] };
+        }),
+      removeItem: (id) =>
+        set((state) => ({ items: state.items.filter((i) => i.id !== id) })),
+      clearCart: () => set({ items: [] }),
+      total: () => get().items.reduce((acc, i) => acc + i.price * i.quantity, 0),
+    }),
+    { name: 'cart-storage' }
+  )
+);
+
+// Usage in component
+'use client';
+
+export function Cart() {
+  const { items, removeItem, total } = useCartStore();
+
+  return (
+    <div>
+      {items.map((item) => (
+        <div key={item.id}>
+          {item.name} x{item.quantity}
+          <button onClick={() => removeItem(item.id)}>Remove</button>
+        </div>
+      ))}
+      <p>Total: ${total()}</p>
+    </div>
+  );
+}
+```
+
+## React Query (Server State)
+
+```typescript
+// providers/query-provider.tsx
+'use client';
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { useState } from 'react';
+
+export function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(() => new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,
+        gcTime: 5 * 60 * 1000,
+      },
+    },
+  }));
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  );
+}
+
+// hooks/use-products.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+export function useProducts() {
+  return useQuery({
+    queryKey: ['products'],
+    queryFn: () => fetch('/api/products').then((res) => res.json()),
+  });
+}
+
+export function useCreateProduct() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: CreateProductDto) =>
+      fetch('/api/products', {
+        method: 'POST',
+        body: JSON.stringify(data),
+      }).then((res) => res.json()),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['products'] });
+    },
+  });
+}
+```
+
+## URL State (Shareable)
+
+```typescript
+'use client';
+
+import { useSearchParams, useRouter, usePathname } from 'next/navigation';
+import { useCallback } from 'react';
+
+export function useQueryState(key: string) {
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  const pathname = usePathname();
+
+  const value = searchParams.get(key);
+
+  const setValue = useCallback(
+    (newValue: string | null) => {
+      const params = new URLSearchParams(searchParams);
+      if (newValue === null) {
+        params.delete(key);
+      } else {
+        params.set(key, newValue);
+      }
+      router.push(`${pathname}?${params.toString()}`);
+    },
+    [key, pathname, router, searchParams]
+  );
+
+  return [value, setValue] as const;
+}
+
+// Usage
+function ProductFilters() {
+  const [category, setCategory] = useQueryState('category');
+  const [sort, setSort] = useQueryState('sort');
+
+  return (
+    <div>
+      <select value={category || ''} onChange={(e) => setCategory(e.target.value)}>
+        <option value="">All</option>
+        <option value="electronics">Electronics</option>
+      </select>
+    </div>
+  );
+}
+```
+
+## Server State with RSC
+
+```typescript
+// Prefer server components for data that doesn't need client interactivity
+// app/products/page.tsx
+async function ProductsPage() {
+  const products = await getProducts(); // Server fetch
+
+  return (
+    <div>
+      {products.map((product) => (
+        <ProductCard key={product.id} product={product} />
+      ))}
+      <AddToCartButton /> {/* Client component for interaction */}
+    </div>
+  );
+}
+```

package/rules/nextjs/styling/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: Next.js Styling & UI Performance
+description: Zero-runtime CSS strategies (Tailwind) and RSC compatibility.
+metadata:
+  labels: [nextjs, styling, tailwind, css]
+  triggers:
+    files: ['**/*.css', 'tailwind.config.ts', '**/components/ui/*.tsx']
+    keywords: [tailwind, css modules, styled-components, clsx, cn]
+---
+
+# Styling & UI Performance
+
+## **Priority: P1 (HIGH)**
+
+Prioritize **Zero-Runtime** CSS for Server Components.
+
+## Library Selection
+
+| Library                    | Verdict            | Reason                                             |
+| :------------------------- | :----------------- | :------------------------------------------------- |
+| **Tailwind / shadcn**      | **Preferred (P1)** | Zero-runtime, RSC compatible. Best for App Router. |
+| **CSS Modules**            | **Recommended**    | Scoped, zero-runtime.                              |
+| **MUI / Chakra (Runtime)** | **Avoid**          | Forces `use client` widely. Degrades performance.  |
+
+## Patterns
+
+1. **Dynamic Classes**: Use `clsx` + `tailwind-merge` (`cn` utility).
+   - _Reference_: [Dynamic Classes & Button Example](references/implementation.md)
+2. **Font Optimization**: Use `next/font` to prevent Cumulative Layout Shift (CLS).
+   - _Reference_: [Font Setup](references/implementation.md)
+3. **CLS Prevention**: Always specify `width`/`height` on images.

package/rules/nextjs/styling/references/implementation.md

@@ -0,0 +1,56 @@
+# Styling Implementation
+
+## Dynamic Classes Utility
+
+Standard `cn` helper for shadcn/ui and Tailwind.
+
+```typescript
+// lib/utils.ts
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+## Component Usage Example
+
+```typescript
+// components/ui/button.tsx
+export function Button({ className, variant, ...props }) {
+  return (
+    <button
+      className={cn(
+        // Base styles
+        "px-4 py-2 rounded font-medium transition-colors",
+        // Conditional variants
+        variant === 'primary' && "bg-blue-500 text-white",
+        // External overrides
+        className
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+## Font Optimization
+
+```typescript
+// app/layout.tsx
+import { Inter } from 'next/font/google';
+
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap', // Prevents FOIT
+});
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className={inter.className}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```

package/rules/react/component-patterns/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: React Component Patterns
+description: Modern React component architecture and composition patterns.
+metadata:
+  labels: [react, components, composition, patterns]
+  triggers:
+    files: ['**/*.jsx', '**/*.tsx']
+    keywords: [component, props, children, composition, hoc, render-props]
+---
+
+# React Component Patterns
+
+## **Priority: P0 (CRITICAL)**
+
+Standards for building scalable, maintainable React components.
+
+## Implementation Guidelines
+
+- **Function Components**: Only hooks. No classes.
+- **Composition**: Use `children` prop. Avoid inheritance.
+- **Props**: Explicit TS interfaces. Destructure in params.
+- **Boolean Props**: Shorthand `<Cmp isVisible />` vs `isVisible={true}`.
+- **Imports**: Group: `Built-in` -> `External` -> `Internal` -> `Styles`.
+- **Error Boundaries**: Wrap app/features with `react-error-boundary`.
+- **Size**: Small (< 250 lines). One component per file.
+- **Naming**: `PascalCase` components. `use*` hooks.
+- **Exports**: Named exports only.
+- **Conditionals**: Ternary (`Cond ? <A/> : <B/>`) over `&&` for rendering consistency.
+- **Hoisting**: Extract static JSX/Objects outside component to prevent recreation.
+
+## Anti-Patterns
+
+- **No Classes**: Use hooks.
+- **No Prop Drilling**: Use Context/Zustand.
+- **No Nested Definitions**: Define components at top level.
+- **No Index Keys**: Use stable IDs.
+- **No Inline Handlers**: Define before return.
+
+## Code
+
+```tsx
+// Composition
+export function Layout({ children, aside }: LayoutProps) {
+  return (
+    <div className='grid'>
+      <aside>{aside}</aside>
+      <main>{children}</main>
+    </div>
+  );
+}
+
+// Compound Component
+export function Select({ children }: { children: ReactNode }) {
+  return <select>{children}</select>;
+}
+Select.Option = ({ val, children }) => <option value={val}>{children}</option>;
+```
+
+## Reference & Examples
+
+For advanced patterns (HOCs, Render Props, Compound Components):
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+hooks | state-management | performance