Loading profile...
+ }
+
+ const info = extractProfileInfo(profile)
+
+ return (
+
+ {info.avatar && 
}
+
+ )
+}
+
+// ============================================================
+// FOLLOW/UNFOLLOW USER
+// ============================================================
+
+const followUser = async (ndk: NDK, pubkeyToFollow: string) => {
+ if (!ndk.signer) {
+ throw new Error('No signer available')
+ }
+
+ // Fetch current contact list (kind 3)
+ const currentUser = await ndk.signer.user()
+ const contactListFilter = {
+ kinds: [3],
+ authors: [currentUser.pubkey]
+ }
+
+ const existingEvents = await ndk.fetchEvents(contactListFilter)
+ const existingContactList = existingEvents.size > 0
+ ? Array.from(existingEvents)[0]
+ : null
+
+ // Get existing p tags
+ const existingPTags = existingContactList
+ ? existingContactList.tags.filter(tag => tag[0] === 'p')
+ : []
+
+ // Check if already following
+ const alreadyFollowing = existingPTags.some(tag => tag[1] === pubkeyToFollow)
+ if (alreadyFollowing) {
+ console.log('Already following this user')
+ return
+ }
+
+ // Create new contact list with added user
+ const event = new NDKEvent(ndk)
+ event.kind = 3
+ event.content = existingContactList?.content || ''
+ event.tags = [
+ ...existingPTags,
+ ['p', pubkeyToFollow]
+ ]
+
+ await event.sign()
+ await event.publish()
+
+ console.log('โ
Now following user')
+}
+
+// ============================================================
+// USAGE EXAMPLE
+// ============================================================
+
+async function profileExample(ndk: NDK) {
+ // Fetch by different identifiers
+ const profile1 = await fetchProfileByNpub(ndk, 'npub1...')
+ const profile2 = await fetchProfileByNip05(ndk, 'user@domain.com')
+ const profile3 = await fetchProfileByPubkey(ndk, 'hex pubkey...')
+
+ // Extract display info
+ const info = extractProfileInfo(profile1)
+ console.log('Display name:', info.displayName)
+ console.log('Avatar:', info.avatar)
+
+ // Update own profile
+ await updateProfile(ndk, {
+ name: 'My Name',
+ about: 'My bio',
+ picture: 'https://example.com/avatar.jpg',
+ lud16: 'me@getalby.com'
+ })
+
+ // Follow someone
+ await followUser(ndk, 'pubkey to follow')
+}
+
+export {
+ fetchProfileByNpub,
+ fetchProfileByPubkey,
+ fetchProfileByNip05,
+ fetchProfileByIdentifier,
+ getCurrentUser,
+ extractProfileInfo,
+ updateProfile,
+ fetchMultipleProfiles,
+ convertPubkeyFormats,
+ useProfile,
+ followUser
+}
+
diff --git a/.claude/skills/ndk/examples/README.md b/.claude/skills/ndk/examples/README.md
new file mode 100644
index 0000000..25b990a
--- /dev/null
+++ b/.claude/skills/ndk/examples/README.md
@@ -0,0 +1,94 @@
+# NDK Examples Index
+
+Complete code examples extracted from the Plebeian Market production codebase.
+
+## Available Examples
+
+### 01-initialization.ts
+- Basic NDK initialization
+- Multiple NDK instances (main + zap relays)
+- Connection with timeout protection
+- Connection status checking
+- Full initialization flow with error handling
+
+### 02-authentication.ts
+- NIP-07 browser extension login
+- Private key signer
+- NIP-46 remote signer (Bunker)
+- Auto-login from localStorage
+- Saving auth credentials
+- Logout functionality
+- Getting current user
+
+### 03-publishing-events.ts
+- Basic note publishing
+- Events with tags (mentions, hashtags, replies)
+- Product listings (parameterized replaceable events)
+- Order creation events
+- Status update events
+- Batch publishing
+- Custom signer usage
+- Comprehensive error handling
+
+### 04-querying-subscribing.ts
+- Basic fetch queries
+- Multiple author queries
+- Tag filtering
+- Time range filtering
+- Event ID lookup
+- Real-time subscriptions
+- Subscription cleanup patterns
+- React integration hooks
+- React Query integration
+- Waiting for specific events
+- Payment monitoring
+
+### 05-users-profiles.ts
+- Fetch profile by npub
+- Fetch profile by hex pubkey
+- Fetch profile by NIP-05
+- Universal identifier lookup
+- Get current user
+- Extract profile information
+- Update user profile
+- Batch fetch multiple profiles
+- Convert between pubkey formats (hex/npub)
+- React hooks for profiles
+- Follow/unfollow users
+
+## Usage
+
+Each file contains:
+- Fully typed TypeScript code
+- JSDoc comments explaining the pattern
+- Error handling examples
+- Integration patterns with React/TanStack Query
+- Real-world usage examples
+
+All examples are based on actual production code from the Plebeian Market application.
+
+## Running Examples
+
+```typescript
+import { initializeNDK } from './01-initialization'
+import { loginWithExtension } from './02-authentication'
+import { publishBasicNote } from './03-publishing-events'
+
+// Initialize NDK
+const { ndk, isConnected } = await initializeNDK()
+
+if (isConnected) {
+ // Authenticate
+ const { user } = await loginWithExtension(ndk)
+
+ // Publish
+ await publishBasicNote(ndk, 'Hello Nostr!')
+}
+```
+
+## Additional Resources
+
+- See `../ndk-skill.md` for detailed documentation
+- See `../quick-reference.md` for quick lookup
+- Check the main codebase for more complex patterns
+
diff --git a/.claude/skills/ndk/ndk-skill.md b/.claude/skills/ndk/ndk-skill.md
new file mode 100644
index 0000000..680fb43
--- /dev/null
+++ b/.claude/skills/ndk/ndk-skill.md
@@ -0,0 +1,701 @@
+# NDK (Nostr Development Kit) - Claude Skill Reference
+
+## Overview
+
+NDK is the primary Nostr development kit with outbox-model support, designed for building Nostr applications with TypeScript/JavaScript. This reference is based on analyzing production usage in the Plebeian Market codebase.
+
+## Core Concepts
+
+### 1. NDK Initialization
+
+**Basic Pattern:**
+```typescript
+import NDK from '@nostr-dev-kit/ndk'
+
+// Simple initialization
+const ndk = new NDK({
+ explicitRelayUrls: ['wss://relay.damus.io', 'wss://relay.nostr.band']
+})
+
+await ndk.connect()
+```
+
+**Store-based Pattern (Production):**
+```typescript
+// From src/lib/stores/ndk.ts
+const ndk = new NDK({
+ explicitRelayUrls: relays || defaultRelaysUrls,
+})
+
+// Separate NDK for zaps on specialized relays
+const zapNdk = new NDK({
+ explicitRelayUrls: ZAP_RELAYS,
+})
+
+// Connect with timeout protection
+const connectPromise = ndk.connect()
+const timeoutPromise = new Promise((_, reject) =>
+ setTimeout(() => reject(new Error('Connection timeout')), timeoutMs)
+)
+await Promise.race([connectPromise, timeoutPromise])
+```
+
+### 2. Authentication & Signers
+
+NDK supports multiple signer types for different authentication methods:
+
+#### NIP-07 (Browser Extension)
+```typescript
+import { NDKNip07Signer } from '@nostr-dev-kit/ndk'
+
+const signer = new NDKNip07Signer()
+await signer.blockUntilReady()
+ndk.signer = signer
+
+const user = await signer.user()
+```
+
+#### Private Key Signer
+```typescript
+import { NDKPrivateKeySigner } from '@nostr-dev-kit/ndk'
+
+const signer = new NDKPrivateKeySigner(privateKeyHex)
+await signer.blockUntilReady()
+ndk.signer = signer
+
+const user = await signer.user()
+```
+
+#### NIP-46 (Remote Signer / Bunker)
+```typescript
+import { NDKNip46Signer } from '@nostr-dev-kit/ndk'
+
+const localSigner = new NDKPrivateKeySigner(localPrivateKey)
+const remoteSigner = new NDKNip46Signer(ndk, bunkerUrl, localSigner)
+await remoteSigner.blockUntilReady()
+ndk.signer = remoteSigner
+
+const user = await remoteSigner.user()
+```
+
+**Key Points:**
+- Always call `blockUntilReady()` before using a signer
+- Store signer reference in your state management
+- Set `ndk.signer` to enable signing operations
+- Use `await signer.user()` to get the authenticated user
+
+### 3. Event Creation & Publishing
+
+#### Basic Event Pattern
+```typescript
+import { NDKEvent } from '@nostr-dev-kit/ndk'
+
+// Create event
+const event = new NDKEvent(ndk)
+event.kind = 1 // Kind 1 = text note
+event.content = "Hello Nostr!"
+event.tags = [
+ ['t', 'nostr'],
+ ['p', recipientPubkey]
+]
+
+// Sign and publish
+await event.sign() // Uses ndk.signer automatically
+await event.publish()
+
+// Get event ID after signing
+console.log(event.id)
+```
+
+#### Production Pattern with Error Handling
+```typescript
+// From src/publish/orders.tsx
+const event = new NDKEvent(ndk)
+event.kind = ORDER_PROCESS_KIND
+event.content = orderNotes || ''
+event.tags = [
+ ['p', sellerPubkey],
+ ['subject', `Order for ${productName}`],
+ ['type', 'order-creation'],
+ ['order', orderId],
+ ['amount', totalAmount],
+ ['item', productRef, quantity.toString()],
+]
+
+// Optional tags
+if (shippingRef) {
+ event.tags.push(['shipping', shippingRef])
+}
+
+try {
+ await event.sign(signer) // Can pass explicit signer
+ await event.publish()
+ return event.id
+} catch (error) {
+ console.error('Failed to publish event:', error)
+ throw error
+}
+```
+
+**Key Points:**
+- Create event with `new NDKEvent(ndk)`
+- Set `kind`, `content`, and `tags` properties
+- Optional: Set `created_at` timestamp (defaults to now)
+- Call `await event.sign()` before publishing
+- Call `await event.publish()` to broadcast to relays
+- Access `event.id` after signing for the event hash
+
+### 4. Querying Events with Filters
+
+#### fetchEvents() - One-time Fetch
+```typescript
+import { NDKFilter } from '@nostr-dev-kit/ndk'
+
+// Simple filter
+const filter: NDKFilter = {
+ kinds: [30402], // Product listings
+ authors: [merchantPubkey],
+ limit: 50
+}
+
+const events = await ndk.fetchEvents(filter)
+// Returns Set{info.displayName}
+ {info.bio &&{info.bio}
} + {info.nip05 && โ {info.nip05}} + {info.lightningAddress && โก {info.lightningAddress}} +{data}
+}
+```
+
+### Server Function
+```typescript
+'use server'
+
+export async function createUser(formData: FormData) {
+ const name = formData.get('name')
+ return await db.user.create({ data: { name } })
+}
+```
+
+## Related Skills
+
+- **typescript** - TypeScript patterns for React
+- **ndk** - Nostr integration with React
+- **skill-creator** - Creating reusable component libraries
+
+## Resources
+
+- [React Documentation](https://react.dev)
+- [React API Reference](https://react.dev/reference/react)
+- [React Hooks Reference](https://react.dev/reference/react/hooks)
+- [React Server Components](https://react.dev/reference/rsc)
+- [React Compiler](https://react.dev/reference/react-compiler)
+
+## Version
+
+This skill is based on React 19.2 and includes the latest features and APIs.
+
diff --git a/.claude/skills/react/SKILL.md b/.claude/skills/react/SKILL.md
new file mode 100644
index 0000000..abe826f
--- /dev/null
+++ b/.claude/skills/react/SKILL.md
@@ -0,0 +1,1026 @@
+---
+name: react
+description: This skill should be used when working with React 19, including hooks, components, server components, concurrent features, and React DOM APIs. Provides comprehensive knowledge of React patterns, best practices, and modern React architecture.
+---
+
+# React 19 Skill
+
+This skill provides comprehensive knowledge and patterns for working with React 19 effectively in modern applications.
+
+## When to Use This Skill
+
+Use this skill when:
+- Building React applications with React 19 features
+- Working with React hooks and component patterns
+- Implementing server components and server functions
+- Using concurrent features and transitions
+- Optimizing React application performance
+- Troubleshooting React-specific issues
+- Working with React DOM APIs and client/server rendering
+- Using React Compiler features
+
+## Core Concepts
+
+### React 19 Overview
+
+React 19 introduces significant improvements:
+- **Server Components** - Components that render on the server
+- **Server Functions** - Functions that run on the server from client code
+- **Concurrent Features** - Better performance with concurrent rendering
+- **React Compiler** - Automatic memoization and optimization
+- **Form Actions** - Built-in form handling with useActionState
+- **Improved Hooks** - New hooks like useOptimistic, useActionState
+- **Better Hydration** - Improved SSR and hydration performance
+
+### Component Fundamentals
+
+Use functional components with hooks:
+
+```typescript
+// Functional component with props interface
+interface ButtonProps {
+ label: string
+ onClick: () => void
+ variant?: 'primary' | 'secondary'
+}
+
+const Button = ({ label, onClick, variant = 'primary' }: ButtonProps) => {
+ return (
+
+ )
+}
+```
+
+**Key Principles:**
+- Use functional components over class components
+- Define prop interfaces in TypeScript
+- Use destructuring for props
+- Provide default values for optional props
+- Keep components focused and composable
+
+## React Hooks Reference
+
+### State Hooks
+
+#### useState
+Manage local component state:
+
+```typescript
+const [count, setCount] = useState
+ {msg.text}
+
+ ))}
+
+
+)
+```
+
+### Other Hooks
+
+#### useId
+Generate unique IDs for accessibility:
+
+```typescript
+const id = useId()
+
+return (
+ <>
+
+
+
+)
+```
+
+#### useSyncExternalStore
+Subscribe to external stores:
+
+```typescript
+const subscribe = (callback: () => void) => {
+ store.subscribe(callback)
+ return () => store.unsubscribe(callback)
+}
+
+const getSnapshot = () => store.getState()
+const getServerSnapshot = () => store.getInitialState()
+
+const state = useSyncExternalStore(
+ subscribe,
+ getSnapshot,
+ getServerSnapshot
+)
+```
+
+#### useDebugValue
+Display custom label in React DevTools:
+
+```typescript
+const useCustomHook = (value: string) => {
+ useDebugValue(value ? `Active: ${value}` : 'Inactive')
+ return value
+}
+```
+
+## React Components
+
+### Fragment
+Group elements without extra DOM nodes:
+
+```typescript
+// Short syntax
+<>
+ {data}
+}, (prevProps, nextProps) => {
+ // Return true if props are equal (skip render)
+ return prevProps.data === nextProps.data
+})
+```
+
+### lazy
+Code-split components:
+
+```typescript
+const Dashboard = lazy(() => import('./Dashboard'))
+
+
+ {posts.map(post => (
+
+ )
+}
+
+export default Page
+```
+
+**Benefits:**
+- Direct database access
+- Zero bundle size for server-only code
+- Automatic code splitting
+- Better performance
+
+### Server Functions
+
+Functions that run on server, callable from client:
+
+```typescript
+'use server'
+
+export async function createPost(formData: FormData) {
+ const title = formData.get('title') as string
+ const content = formData.get('content') as string
+
+ const post = await db.post.create({
+ data: { title, content }
+ })
+
+ revalidatePath('/posts')
+ return post
+}
+```
+
+**Usage from client:**
+
+```typescript
+'use client'
+
+import { createPost } from './actions'
+
+const PostForm = () => {
+ const [state, formAction] = useActionState(createPost, null)
+
+ return (
+
+ )
+}
+```
+
+### Directives
+
+#### 'use client'
+Mark file as client component:
+
+```typescript
+'use client'
+
+import { useState } from 'react'
+
+// This component runs on client
+export const Counter = () => {
+ const [count, setCount] = useState(0)
+ return
+}
+```
+
+#### 'use server'
+Mark functions as server functions:
+
+```typescript
+'use server'
+
+export async function updateUser(userId: string, data: UserData) {
+ return await db.user.update({ where: { id: userId }, data })
+}
+```
+
+## React DOM
+
+### Client APIs
+
+#### createRoot
+Create root for client rendering (React 19):
+
+```typescript
+import { createRoot } from 'react-dom/client'
+
+const root = createRoot(document.getElementById('root')!)
+root.render({children}
,
+ document.body
+ )
+}
+```
+
+#### flushSync
+Force synchronous update:
+
+```typescript
+import { flushSync } from 'react-dom'
+
+flushSync(() => {
+ setCount(1)
+})
+// DOM is updated synchronously
+```
+
+### Form Components
+
+####
+```
+
+#### useFormStatus
+
+```typescript
+import { useFormStatus } from 'react-dom'
+
+const SubmitButton = () => {
+ const { pending } = useFormStatus()
+
+ return (
+
+ )
+}
+```
+
+## React Compiler
+
+### Configuration
+
+Configure React Compiler in babel or bundler config:
+
+```javascript
+// babel.config.js
+module.exports = {
+ plugins: [
+ ['react-compiler', {
+ compilationMode: 'annotation', // or 'all'
+ panicThreshold: 'all_errors',
+ }]
+ ]
+}
+```
+
+### Directives
+
+#### "use memo"
+Force memoization of component:
+
+```typescript
+'use memo'
+
+const ExpensiveComponent = ({ data }: Props) => {
+ const processed = expensiveComputation(data)
+ return {processed}
+}
+```
+
+#### "use no memo"
+Prevent automatic memoization:
+
+```typescript
+'use no memo'
+
+const SimpleComponent = ({ text }: Props) => {
+ return {text}
+}
+```
+
+## Best Practices
+
+### Component Design
+
+1. **Keep components focused** - Single responsibility principle
+2. **Prefer composition** - Build complex UIs from simple components
+3. **Extract custom hooks** - Reusable logic in hooks
+4. **Named return variables** - Use named returns in functions
+5. **Type everything** - Proper TypeScript interfaces for all props
+
+### Performance
+
+1. **Use React.memo sparingly** - Only for expensive components
+2. **Optimize context** - Split contexts to avoid unnecessary re-renders
+3. **Lazy load routes** - Code-split at route boundaries
+4. **Use transitions** - Mark non-urgent updates with useTransition
+5. **Virtualize lists** - Use libraries like react-window for long lists
+
+### State Management
+
+1. **Local state first** - useState for component-specific state
+2. **Lift state up** - Only when multiple components need it
+3. **Use reducers for complex state** - useReducer for complex logic
+4. **Context for global state** - Theme, auth, etc.
+5. **External stores** - TanStack Query, Zustand for complex apps
+
+### Error Handling
+
+1. **Error boundaries** - Catch rendering errors
+2. **Guard clauses** - Early returns for invalid states
+3. **Null checks** - Always check for null/undefined
+4. **Try-catch in effects** - Handle async errors
+5. **User-friendly errors** - Show helpful error messages
+
+### Testing Considerations
+
+1. **Testable components** - Pure, predictable components
+2. **Test user behavior** - Not implementation details
+3. **Mock external dependencies** - APIs, context, etc.
+4. **Test error states** - Verify error handling works
+5. **Accessibility tests** - Test keyboard navigation, screen readers
+
+## Common Patterns
+
+### Compound Components
+
+```typescript
+interface TabsProps {
+ children: React.ReactNode
+ defaultValue: string
+}
+
+const TabsContext = createContext<{
+ value: string
+ setValue: (v: string) => void
+} | null>(null)
+
+const Tabs = ({ children, defaultValue }: TabsProps) => {
+ const [value, setValue] = useState(defaultValue)
+
+ return (
+ {children}
+)
+
+const TabsTrigger = ({ value, children }: { value: string, children: React.ReactNode }) => {
+ const context = useContext(TabsContext)
+ if (!context) throw new Error('TabsTrigger must be used within Tabs')
+
+ return (
+
+ )
+}
+
+const TabsContent = ({ value, children }: { value: string, children: React.ReactNode }) => {
+ const context = useContext(TabsContext)
+ if (!context) throw new Error('TabsContent must be used within Tabs')
+
+ if (context.value !== value) return null
+
+ return {children}
+}
+
+// Usage
+
+
,
+ document.body
+ )
+}
+
+// Usage
+const App = () => {
+ const [isOpen, setIsOpen] = useState(false)
+
+ return (
+ <>
+
+
+
+
+ {title &&
+ {children}
+ {title}
} + +Modal content goes here
+ +Loading...
,
+ endMessage = No more items
+}: InfiniteScrollProps
+ {items.map((item, index) => (
+
+ )
+}
+
+// Usage
+const PostsList = () => {
+ const fetchPosts = async (page: number) => {
+ const response = await fetch(`/api/posts?page=${page}`)
+ return response.json()
+ }
+
+ return (
+
+ {renderItem(item, index)}
+
+ ))}
+
+
+ {loading && loader}
+ {!loading && !hasMore && endMessage}
+
+
+ setQuery(e.target.value)}
+ placeholder="Search products..."
+ />
+
+ {loading &&
+ )
+}
+```
+
+## Example 7: Tabs Component
+
+```typescript
+import { createContext, useContext, useState, useId } from 'react'
+
+interface TabsContextType {
+ activeTab: string
+ setActiveTab: (id: string) => void
+ tabsId: string
+}
+
+const TabsContext = createContext
+ {results.map(product => (
+
+ )}
+
+ {!loading && query && results.length === 0 && (
+ No results found for "{query}"
+ )} +
+ {children}
+
+
+ {children}
+
+)
+
+interface TabsTriggerProps {
+ value: string
+ children: React.ReactNode
+ className?: string
+}
+
+const TabsTrigger = ({ value, children, className }: TabsTriggerProps) => {
+ const { activeTab, setActiveTab, tabsId } = useTabs()
+ const isActive = activeTab === value
+
+ return (
+
+ )
+}
+
+interface TabsContentProps {
+ value: string
+ children: React.ReactNode
+ className?: string
+}
+
+const TabsContent = ({ value, children, className }: TabsContentProps) => {
+ const { activeTab, tabsId } = useTabs()
+
+ if (activeTab !== value) return null
+
+ return (
+
+ {children}
+
+ )
+}
+
+// Export compound component
+export { Tabs, TabsList, TabsTrigger, TabsContent }
+
+// Usage
+const App = () => (
+ Profile Content
+Settings Content
+Notifications Content
+
+
+ )
+ }
+
+ return this.props.children
+ }
+}
+
+// Usage
+const App = () => (
+ Something went wrong
+
+
+
+ Error details
+{this.state.error.message}
+
+
+ )}
+ onError={(error, errorInfo) => {
+ // Send to error tracking service
+ console.error('Error logged:', error, errorInfo)
+ }}
+ >
+ Oops! Something went wrong
+{error.message}
+ +
+
+
+
+
+ )
+}
+```
+
+## Example 10: Optimistic Updates with useOptimistic
+
+```typescript
+'use client'
+
+import { useOptimistic } from 'react'
+import { likePost, unlikePost } from './actions'
+
+interface Post {
+ id: string
+ content: string
+ likes: number
+ isLiked: boolean
+}
+
+const PostCard = ({ post }: { post: Post }) => {
+ const [optimisticPost, addOptimistic] = useOptimistic(
+ post,
+ (currentPost, update: Partial
+
+ )
+}
+```
+
+## References
+
+These examples demonstrate:
+- Custom hooks for reusable logic
+- Form handling with validation
+- Portal usage for modals
+- Infinite scroll with Intersection Observer
+- Context for global state
+- Debouncing for performance
+- Compound components pattern
+- Error boundaries
+- LocalStorage integration
+- Optimistic updates (React 19)
+
diff --git a/.claude/skills/react/references/hooks-quick-reference.md b/.claude/skills/react/references/hooks-quick-reference.md
new file mode 100644
index 0000000..26e8f59
--- /dev/null
+++ b/.claude/skills/react/references/hooks-quick-reference.md
@@ -0,0 +1,291 @@
+# React Hooks Quick Reference
+
+## State Hooks
+
+### useState
+```typescript
+const [state, setState] = useState{optimisticPost.content}
+ +{processData(data)}
+})
+
+// Custom comparison
+const MemoizedComponent = memo(
+ ({ user }: Props) => -
+ {sortedFilteredItems.map(item => (
+
- {item.name} + ))} +
{data}
+}
+
+// Prevent memoization
+'use no memo'
+const SimpleComponent = ({ text }: Props) => {
+ return {text}
+}
+```
+
+## State Management Optimization
+
+### State Colocation
+
+Keep state as close as possible to where it's used:
+
+```typescript
+// Bad - state too high
+const App = () => {
+ const [showModal, setShowModal] = useState(false)
+
+ return (
+ <>
+
+
+ )
+}
+```
+
+### Pagination
+
+```typescript
+const PaginatedList = ({ items }: Props) => {
+ const [page, setPage] = useState(1)
+ const itemsPerPage = 20
+
+ const paginatedItems = useMemo(() => {
+ const start = (page - 1) * itemsPerPage
+ const end = start + itemsPerPage
+ return items.slice(start, end)
+ }, [items, page, itemsPerPage])
+
+ return (
+ <>
+ {paginatedItems.map(item => (
+
+ {virtualizer.getVirtualItems().map(virtualItem => (
+
+
+
+ ))}
+
+ {!isLoaded && 
setIsLoaded(true)}
+ className={isLoaded ? 'opacity-100' : 'opacity-0'}
+ />
+
+ )
+}
+```
+
+### Next.js Image Component
+
+```typescript
+import Image from 'next/image'
+
+const OptimizedImage = () => (
+
+
+ )
+}
+
+export default ProductsPage
+```
+
+### Server Component Rules
+
+**Can do:**
+- Access databases and APIs directly
+- Use server-only modules (fs, path, etc.)
+- Keep secrets secure (API keys, tokens)
+- Reduce client bundle size
+- Use async/await at top level
+
+**Cannot do:**
+- Use hooks (useState, useEffect, etc.)
+- Use browser APIs (window, document)
+- Attach event handlers (onClick, etc.)
+- Use Context
+
+### Mixing Server and Client Components
+
+```typescript
+// Server Component (default)
+const Page = async () => {
+ const data = await fetchData()
+
+ return (
+ Products
+ {products.map(product => ( +
+
+ )
+}
+
+// Client Component
+'use client'
+
+import { useState } from 'react'
+
+const ClientComponent = ({ initialData }) => {
+ const [count, setCount] = useState(0)
+
+ return (
+
+ )
+}
+```
+
+### Server Component Patterns
+
+#### Data Fetching
+```typescript
+// app/user/[id]/page.tsx
+interface PageProps {
+ params: { id: string }
+}
+
+const UserPage = async ({ params }: PageProps) => {
+ const user = await db.user.findUnique({
+ where: { id: params.id }
+ })
+
+ if (!user) {
+ notFound() // Next.js 404
+ }
+
+ return
+
+ )
+}
+```
+
+## Data Mutations & Revalidation
+
+### revalidatePath
+Invalidate cached data for a path:
+
+```typescript
+'use server'
+
+import { revalidatePath } from 'next/cache'
+
+export async function createPost(formData: FormData) {
+ await db.post.create({ data: {...} })
+
+ // Revalidate the posts page
+ revalidatePath('/posts')
+
+ // Revalidate with layout
+ revalidatePath('/posts', 'layout')
+}
+```
+
+### revalidateTag
+Invalidate cached data by tag:
+
+```typescript
+'use server'
+
+import { revalidateTag } from 'next/cache'
+
+export async function updateProduct(id: string, data: ProductData) {
+ await db.product.update({ where: { id }, data })
+
+ // Revalidate all queries tagged with 'products'
+ revalidateTag('products')
+}
+```
+
+### redirect
+Redirect after mutation:
+
+```typescript
+'use server'
+
+import { redirect } from 'next/navigation'
+
+export async function createPost(formData: FormData) {
+ const post = await db.post.create({ data: {...} })
+
+ // Redirect to the new post
+ redirect(`/posts/${post.id}`)
+}
+```
+
+## Caching with Server Components
+
+### cache Function
+Deduplicate requests within a render:
+
+```typescript
+import { cache } from 'react'
+
+export const getUser = cache(async (id: string) => {
+ return await db.user.findUnique({ where: { id } })
+})
+
+// Called multiple times but only fetches once per render
+const Page = async () => {
+ const user1 = await getUser('123')
+ const user2 = await getUser('123') // Uses cached result
+
+ return {post.content}
+ +...
+}
+```
+
+### Next.js fetch Caching
+```typescript
+// Cached by default
+const data = await fetch('https://api.example.com/data')
+
+// Revalidate every 60 seconds
+const data = await fetch('https://api.example.com/data', {
+ next: { revalidate: 60 }
+})
+
+// Never cache
+const data = await fetch('https://api.example.com/data', {
+ cache: 'no-store'
+})
+
+// Tag for revalidation
+const data = await fetch('https://api.example.com/data', {
+ next: { tags: ['products'] }
+})
+```
+
+## Best Practices
+
+### 1. Component Placement
+- Keep interactive components client-side
+- Use server components for data fetching
+- Place 'use client' as deep as possible in tree
+
+### 2. Data Fetching
+- Fetch in parallel when possible
+- Use Suspense for streaming
+- Cache expensive operations
+
+### 3. Server Functions
+- Validate all inputs
+- Check authentication/authorization
+- Handle errors gracefully
+- Return serializable data only
+
+### 4. Performance
+- Minimize client JavaScript
+- Use streaming for slow queries
+- Implement proper caching
+- Optimize database queries
+
+### 5. Security
+- Never expose secrets to client
+- Validate server function inputs
+- Use environment variables
+- Implement rate limiting
+
+## Common Patterns
+
+### Layout with Dynamic Data
+```typescript
+// app/layout.tsx
+const RootLayout = async ({ children }: { children: React.ReactNode }) => {
+ const user = await getCurrentUser()
+
+ return (
+
+
+
+
+ )
+}
+```
+
+### Search with Server Functions
+```typescript
+'use client'
+
+import { searchProducts } from './actions'
+import { useDeferredValue, useState, useEffect } from 'react'
+
+const SearchPage = () => {
+ const [query, setQuery] = useState('')
+ const [results, setResults] = useState([])
+ const deferredQuery = useDeferredValue(query)
+
+ useEffect(() => {
+ if (deferredQuery) {
+ searchProducts(deferredQuery).then(setResults)
+ }
+ }, [deferredQuery])
+
+ return (
+ <>
+ setQuery(e.target.value)}
+ />
+ Something went wrong!
+{error.message}
+ +
+ {label && }
+
+ {error && {error}}
+ {helperText && {helperText}}
+
+ )
+}
+
+// Generic component
+interface ListProps{emptyMessage}
+ }
+
+ return (
+ -
+ {items.map((item, index) => (
+
- {renderItem(item, index)} + ))} +
Loading...
+ if (error) return Error: {error.message}
+
+ return <>{children({ retry })}
+}
+
+// ============================================================================
+// Hooks Patterns
+// ============================================================================
+
+// useState with explicit type
+function useCounter(initialValue: number = 0) {
+ const [count, setCount] = useState
+
+
+
+ )
+}
+
+function Timer() {
+ // useRef for mutable value
+ const countRef = useRef
+
+
+
+ )
+}
+
+// ============================================================================
+// Generic Component Patterns
+// ============================================================================
+
+// Select component with generic options
+interface SelectProps| {col.header} | + ))} +
|---|
| + {col.render ? col.render(row[col.key], row) : String(row[col.key])} + | + ))} +
( + Component: React.ComponentType
, +): React.FC
{ + return ({ isLoading, ...props }: WithLoadingProps & P) => { + if (isLoading) { + return
Loading...
+ }
+
+ return -
+ {users.map((user) => (
+
- {user.name} + ))} +