React Skills

React Skills for LlamaFarm Designer

Best practices and patterns for React 18 development in the Designer subsystem.

Tech Stack

• React 18.2 with StrictMode
• TypeScript 5.2+ for type safety
• TanStack Query v5 for server state management
• React Router v7 for client-side routing
• TailwindCSS with tailwind-merge and clsx for styling
• Radix UI primitives for accessible components
• Vite for build tooling
• Vitest + React Testing Library for testing

Directory Structure

designer/src/
  api/          # API service functions
  components/   # React components (feature-organized)
  contexts/     # React context providers
  hooks/        # Custom hooks
  lib/          # Utility functions (cn, etc.)
  types/        # TypeScript type definitions
  utils/        # Helper functions
  test/         # Test utilities and mocks

Core Patterns

Component Composition

• Use composition over inheritance
• Prefer small, focused components
• Use forwardRef for components that wrap DOM elements
• Apply displayName to forwardRef components for DevTools

State Management

• Local UI state: useState, useReducer
• Server state: TanStack Query (useQuery, useMutation)
• Shared UI state: React Context with custom hooks
• Form state: Controlled components with validation

Hooks

• Follow Rules of Hooks (top-level, consistent order)
• Create custom hooks for reusable logic
• Use query key factories for TanStack Query
• Memoize expensive computations with useMemo
• Stabilize callbacks with useCallback

Styling

• Use cn() from lib/utils to merge Tailwind classes
• Use cva (class-variance-authority) for component variants
• Follow dark mode conventions with dark: prefix

Related Guides

• components.md - Component patterns
• hooks.md - Hook patterns and rules
• state.md - State management patterns
• performance.md - Performance optimization
• security.md - Security best practices

Quick Reference

// Utility for merging Tailwind classes
import { cn } from '@/lib/utils'
cn('base-class', condition && 'conditional-class', className)

// Query key factory pattern
export const projectKeys = {
  all: ['projects'] as const,
  lists: () => [...projectKeys.all, 'list'] as const,
  list: (ns: string) => [...projectKeys.lists(), ns] as const,
}

// Context with validation hook
const MyContext = createContext<MyContextType | undefined>(undefined)
export function useMyContext() {
  const ctx = useContext(MyContext)
  if (!ctx) throw new Error('useMyContext must be within MyProvider')
  return ctx
}

Testing

import { renderWithProviders } from '@/test/utils'
import { screen } from '@testing-library/react'

test('renders component', () => {
  renderWithProviders(<MyComponent />)
  expect(screen.getByText('Hello')).toBeInTheDocument()
})

React Component Patterns

Guidelines for building maintainable, accessible React components.

Component Structure

Function Components

Always use function components with TypeScript interfaces:

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
}

export function Button({ variant = 'primary', size = 'md', className, ...props }: ButtonProps) {
  return (
    <button
      className={cn(buttonVariants({ variant, size }), className)}
      {...props}
    />
  )
}

forwardRef Components

Use forwardRef when wrapping DOM elements or Radix primitives:

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, asChild = false, ...props }, ref) => {
    const Comp = asChild ? Slot : 'button'
    return (
      <Comp
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    )
  }
)
Button.displayName = 'Button'

Checklist Items

1. Components Must Use TypeScript Interfaces

2. forwardRef Components Need displayName

3. Spread Props Last

4. Use Composition Over Conditionals

5. Avoid Inline Function Definitions in JSX

6. Use cn() for Class Merging

7. Accessible Interactive Elements

8. Key Props on List Items

Component Variants with CVA

Use class-variance-authority for component variants:

import { cva, type VariantProps } from 'class-variance-authority'

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-8 px-3 text-xs',
        lg: 'h-11 px-8',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
)

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

Compound Components

For complex components, use the compound component pattern:

const Tabs = ({ children }: { children: React.ReactNode }) => (
  <div className="tabs">{children}</div>
)

const TabList = ({ children }: { children: React.ReactNode }) => (
  <div role="tablist">{children}</div>
)

const TabPanel = ({ children }: { children: React.ReactNode }) => (
  <div role="tabpanel">{children}</div>
)

Tabs.List = TabList
Tabs.Panel = TabPanel

// Usage
<Tabs>
  <Tabs.List>...</Tabs.List>
  <Tabs.Panel>...</Tabs.Panel>
</Tabs>

Provider Composition

Compose providers from the outside in (outermost wraps everything):

// main.tsx - correct order
<React.StrictMode>
  <QueryClientProvider client={queryClient}>
    <ThemeProvider>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </ThemeProvider>
  </QueryClientProvider>
</React.StrictMode>

React Hooks Patterns

Guidelines for writing and using React hooks effectively.

Rules of Hooks

1. Only call hooks at the top level - Never inside loops, conditions, or nested functions 2. Only call hooks from React functions - Components or custom hooks only 3. Use the `use` prefix - Custom hooks must start with use

Custom Hook Patterns

Basic Custom Hook

export function useMediaQuery(query: string): boolean {
  const [matches, setMatches] = useState(false)

  useEffect(() => {
    const mql = window.matchMedia(query)
    const onChange = (e: MediaQueryListEvent) => setMatches(e.matches)

    setMatches(mql.matches)
    mql.addEventListener('change', onChange)
    return () => mql.removeEventListener('change', onChange)
  }, [query])

  return matches
}

Composed Hooks

export function useIsMobile(): boolean {
  return useMediaQuery('(max-width: 767px)')
}

Checklist Items

1. Hooks Called at Top Level

2. Custom Hooks Use use Prefix

3. useEffect Has Cleanup

4. useEffect Dependencies Are Complete

5. useCallback for Handler Props

6. useMemo for Expensive Computations

7. useState Initializer for Expensive Initial Values

8. useRef for Mutable Values That Don't Trigger Rerenders

TanStack Query Hook Patterns

Query Key Factories

export const projectKeys = {
  all: ['projects'] as const,
  lists: () => [...projectKeys.all, 'list'] as const,
  list: (namespace: string) => [...projectKeys.lists(), namespace] as const,
  details: () => [...projectKeys.all, 'detail'] as const,
  detail: (namespace: string, id: string) =>
    [...projectKeys.details(), namespace, id] as const,
}

Query Hook

export function useProjects(namespace: string) {
  return useQuery({
    queryKey: projectKeys.list(namespace),
    queryFn: () => projectService.listProjects(namespace),
    enabled: !!namespace,
    staleTime: 5 * 60 * 1000,
    retry: 1,
  })
}

Mutation Hook

export function useCreateProject() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: ({ namespace, request }) =>
      projectService.createProject(namespace, request),
    onSuccess: (data, variables) => {
      queryClient.invalidateQueries({
        queryKey: projectKeys.list(variables.namespace)
      })
      queryClient.setQueryData(
        projectKeys.detail(variables.namespace, data.project.name),
        { project: data.project }
      )
    },
    onError: (error) => {
      console.error('Failed to create project:', error)
    },
  })
}

Context Hook Pattern

const ThemeContext = createContext<ThemeContextType | undefined>(undefined)

export function useTheme() {
  const context = useContext(ThemeContext)
  if (context === undefined) {
    throw new Error('useTheme must be used within a ThemeProvider')
  }
  return context
}

Cleanup Patterns

Timer Cleanup

useEffect(() => {
  const timer = setTimeout(() => {
    setExpired(true)
  }, 5000)

  return () => clearTimeout(timer)
}, [])

Event Listener Cleanup

useEffect(() => {
  const handleResize = () => setWidth(window.innerWidth)
  window.addEventListener('resize', handleResize)
  return () => window.removeEventListener('resize', handleResize)
}, [])

AbortController for Fetch

useEffect(() => {
  const controller = new AbortController()

  fetch(url, { signal: controller.signal })
    .then(res => res.json())
    .then(setData)
    .catch(err => {
      if (err.name !== 'AbortError') throw err
    })

  return () => controller.abort()
}, [url])

RAF Cleanup

useEffect(() => {
  const rafRef = { current: null as number | null }

  const animate = () => {
    // animation logic
    rafRef.current = requestAnimationFrame(animate)
  }
  rafRef.current = requestAnimationFrame(animate)

  return () => {
    if (rafRef.current) cancelAnimationFrame(rafRef.current)
  }
}, [])

React Performance Optimization

Guidelines for optimizing React application performance.

Core Principles

1. Measure first - Use React DevTools Profiler before optimizing 2. Avoid premature optimization - Only optimize when there's a measurable problem 3. Minimize rerenders - Prevent unnecessary component updates 4. Code split - Load code only when needed

Memoization Patterns

useMemo for Expensive Computations

const { thinking, contentWithoutThinking } = useMemo(
  () => parseMessageContentMemo(content, type, message.id),
  [content, type, message.id]
)

useCallback for Stable References

const handleSendClick = useCallback(async () => {
  const messageContent = inputValue.trim()
  if (!canSend || !messageContent) return

  setWantsAutoScroll(true)
  const success = await sendMessage(messageContent)
  if (success) updateInput('')
}, [inputValue, canSend, sendMessage, updateInput])

React.memo for Pure Components

const Message = React.memo(function Message({ message }: MessageProps) {
  // Component only rerenders if message prop changes
  return <div>{message.content}</div>
})

Checklist Items

1. Expensive Computations Are Memoized

2. Callbacks Passed to Children Are Stable

3. Context Values Are Memoized

4. Large Lists Use Virtualization

5. Images Are Lazy Loaded

6. Code Splitting at Route Level

Current State: The Designer currently uses static imports for all routes. This is a future optimization opportunity for large bundles.

7. Avoid Inline Object/Array Literals in JSX

8. useTransition for Non-Urgent Updates

Lazy Loading Patterns

React.lazy with Suspense

const Dashboard = React.lazy(() => import('./components/Dashboard'))
const Models = React.lazy(() => import('./components/Models'))

function App() {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/models" element={<Models />} />
      </Routes>
    </Suspense>
  )
}

Named Exports with Lazy

const Dashboard = React.lazy(() =>
  import('./components/Dashboard').then(module => ({
    default: module.Dashboard
  }))
)

Scroll Performance

RAF Debouncing

const rafRef = useRef<number | null>(null)

const handleScroll = useCallback(() => {
  if (rafRef.current) {
    cancelAnimationFrame(rafRef.current)
  }

  rafRef.current = requestAnimationFrame(() => {
    const atBottom = checkIfAtBottom()
    setIsUserAtBottom(atBottom)
  })
}, [checkIfAtBottom])

useEffect(() => {
  return () => {
    if (rafRef.current) {
      cancelAnimationFrame(rafRef.current)
    }
  }
}, [])

Smooth Scrolling

useEffect(() => {
  if (wantsAutoScroll && listRef.current) {
    listRef.current.scrollTo({
      top: listRef.current.scrollHeight,
      behavior: 'auto', // 'auto' prevents jank during streaming
    })
  }
}, [messages, wantsAutoScroll])

Avoiding Unnecessary Rerenders

Split Context by Update Frequency

// Separate frequently-changing state from stable state
const ThemeContext = createContext<Theme>('light')
const ThemeActionsContext = createContext<ThemeActions>(null!)

// Components that only need actions don't rerender on theme change
function ThemeToggle() {
  const { toggleTheme } = useContext(ThemeActionsContext)
  return <button onClick={toggleTheme}>Toggle</button>
}

Stable Callback References

// Bad - creates new function on every render
<Button onClick={() => handleClick(id)} />

// Good - stable reference
const handleItemClick = useCallback((id: string) => {
  // handle click
}, [])

<Button onClick={() => handleItemClick(id)} />

// Best - if child is memoized
const handleItemClick = useCallback(() => {
  handleClick(id)
}, [id, handleClick])

<MemoizedButton onClick={handleItemClick} />

Bundle Size Optimization

Import Only What You Need

// Bad - imports entire library
import * as _ from 'lodash'

// Good - tree-shakeable imports
import debounce from 'lodash/debounce'

// Best - use native alternatives when possible
const debounce = (fn: Function, ms: number) => {
  let timer: NodeJS.Timeout
  return (...args: any[]) => {
    clearTimeout(timer)
    timer = setTimeout(() => fn(...args), ms)
  }
}

Analyze Bundle

# Use rollup-plugin-visualizer (already in devDependencies)
nx build designer --mode=analyze

React Security Best Practices

Guidelines for preventing XSS, injection attacks, and other security vulnerabilities.

Core Principles

1. Never trust user input - Sanitize all data from users, URLs, and external sources 2. Escape by default - React escapes JSX by default, but edge cases exist 3. Validate navigation state - URL params and location.state can be manipulated 4. Use allowlists - Prefer allowlists over blocklists for validation

XSS Prevention

React's Built-in Protection

React automatically escapes values in JSX:

// Safe - React escapes the content
const userInput = '<script>alert("xss")</script>'
return <div>{userInput}</div> // Renders as text, not HTML

dangerouslySetInnerHTML

Avoid unless absolutely necessary:

// DANGEROUS - only use with sanitized content
<div dangerouslySetInnerHTML={{ __html: sanitizedHtml }} />

If you must use it, sanitize with a library like DOMPurify or rehype-sanitize.

Checklist Items

1. No Unsanitized dangerouslySetInnerHTML

2. URL Parameters Are Validated

3. Navigation State Is Validated

4. URLs Are Protocol-Validated

5. User Content Has Length Limits

6. Sensitive Data Not in URL

7. External Links Use rel="noopener"

8. Form Actions Are Protected

Sanitization Utilities

Config Value Sanitization

const MAX_CONFIG_VALUE_LENGTH = 100

export const sanitizeConfigValue = (value: unknown): string => {
  if (!value) return 'Not set'

  const str = String(value)
    .replace(/[<>'"]/g, '') // Remove HTML/script injection characters
    .trim()

  return str.length > MAX_CONFIG_VALUE_LENGTH
    ? str.substring(0, MAX_CONFIG_VALUE_LENGTH) + '...'
    : str
}

URL Validation

export const isValidAndSafeURL = (urlString: string): boolean => {
  try {
    const url = new URL(urlString)

    // Only allow http and https protocols
    if (!['http:', 'https:'].includes(url.protocol)) {
      return false
    }

    // Warn about localhost/private IPs in production
    const hostname = url.hostname.toLowerCase()
    const isLocalhost = hostname === 'localhost' ||
                       hostname === '127.0.0.1' ||
                       hostname.startsWith('192.168.') ||
                       hostname.startsWith('10.') ||
                       hostname.startsWith('172.')

    if (import.meta.env.PROD && isLocalhost) {
      console.warn('Localhost/private IP detected in production:', hostname)
    }

    return true
  } catch {
    return false
  }
}

Navigation State Validation

export const validateNavigationState = (state: unknown): {
  database: string
  strategyName: string
  strategyType: string
  currentConfig: Record<string, any>
  isDefault: boolean
} => {
  const s = state as any

  // Validate database name (alphanumeric and underscores only)
  const database = typeof s?.database === 'string' &&
                   /^[a-zA-Z0-9_]+$/.test(s.database)
    ? s.database
    : 'main_database'

  // Validate strategy name (alphanumeric, hyphens, underscores)
  const strategyName = typeof s?.strategyName === 'string' &&
                       /^[a-zA-Z0-9_-]+$/.test(s.strategyName)
    ? s.strategyName
    : ''

  // Validate against allowlist
  const allowedTypes = ['BasicStrategy', 'AdvancedStrategy']
  const strategyType = typeof s?.strategyType === 'string' &&
                       allowedTypes.includes(s.strategyType)
    ? s.strategyType
    : 'BasicStrategy'

  // Validate config is an object (contents still untrusted)
  const currentConfig = s?.currentConfig &&
                        typeof s.currentConfig === 'object' &&
                        !Array.isArray(s.currentConfig)
    ? s.currentConfig
    : {}

  const isDefault = typeof s?.isDefault === 'boolean' ? s.isDefault : false

  return { database, strategyName, strategyType, currentConfig, isDefault }
}

Filter Key/Value Sanitization

const MAX_FILTER_KEY_LENGTH = 50
const MAX_FILTER_VALUE_LENGTH = 200

export const sanitizeFilterKey = (key: string): string => {
  return key.replace(/[^a-zA-Z0-9_-]/g, '').substring(0, MAX_FILTER_KEY_LENGTH)
}

export const sanitizeFilterValue = (value: string): string => {
  return value
    .replace(/[<>'"\\]/g, '')
    .trim()
    .substring(0, MAX_FILTER_VALUE_LENGTH)
}

Markdown Rendering

Use rehype-sanitize when rendering user-provided markdown:

import ReactMarkdown from 'react-markdown'
import rehypeSanitize from 'rehype-sanitize'
import remarkGfm from 'remark-gfm'

function SafeMarkdown({ content }: { content: string }) {
  return (
    <ReactMarkdown
      remarkPlugins={[remarkGfm]}
      rehypePlugins={[rehypeSanitize]}
    >
      {content}
    </ReactMarkdown>
  )
}

Reserved Names

Prevent system name collisions:

export const RESERVED_NAMES = [
  'default',
  'null',
  'undefined',
  'none',
  'system',
  'admin',
  'root',
  'all',
  'any',
]

export const validateName = (name: string): string | null => {
  const trimmed = name.trim()

  if (!trimmed) return 'Name is required'

  if (RESERVED_NAMES.includes(trimmed.toLowerCase())) {
    return `"${trimmed}" is a reserved name`
  }

  if (!/^[a-zA-Z0-9_-]+$/.test(trimmed)) {
    return 'Cannot contain special characters'
  }

  if (trimmed.length > 100) {
    return 'Name must be 100 characters or less'
  }

  return null
}

Clipboard API Security

async function copyToClipboard(text: string) {
  try {
    // Sanitize before copying
    const sanitized = text.replace(/[<>]/g, '')
    await navigator.clipboard.writeText(sanitized)
    return true
  } catch (err) {
    console.error('Failed to copy:', err)
    return false
  }
}

State Management Patterns

Guidelines for managing state in React applications with TanStack Query and Context.

State Categories

TanStack Query Patterns

QueryClient Configuration

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60_000,           // 1 minute
      gcTime: 5 * 60_000,          // 5 minutes (was cacheTime)
      retry: 2,
      retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30_000),
      refetchOnWindowFocus: false,
      refetchOnMount: true,
      refetchOnReconnect: true,
    },
    mutations: {
      retry: 1,
    },
  },
})

Query Key Factory Pattern

export const chatCompletionsKeys = {
  all: ['chatCompletions'] as const,
  completions: (namespace: string, projectId: string) =>
    [...chatCompletionsKeys.all, namespace, projectId] as const,
  session: (namespace: string, projectId: string, sessionId: string) =>
    [...chatCompletionsKeys.completions(namespace, projectId), 'session', sessionId] as const,
}

Checklist Items

1. Server State Uses TanStack Query

2. Query Keys Use Factory Pattern

3. Mutations Invalidate Related Queries

4. Queries Have Proper enabled Condition

5. Context Providers Have Proper Memoization

6. Context Has Validation Hook

7. Avoid Prop Drilling

8. Optimistic Updates for Mutations

Context Provider Pattern

type Theme = 'light' | 'dark'

interface ThemeContextType {
  theme: Theme
  toggleTheme: () => void
  setTheme: (theme: Theme) => void
}

const ThemeContext = createContext<ThemeContextType | undefined>(undefined)

export function useTheme() {
  const context = useContext(ThemeContext)
  if (context === undefined) {
    throw new Error('useTheme must be used within a ThemeProvider')
  }
  return context
}

export function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setThemeState] = useState<Theme>(() => {
    const saved = localStorage.getItem('theme') as Theme
    if (saved) return saved
    return window.matchMedia('(prefers-color-scheme: dark)').matches
      ? 'dark'
      : 'light'
  })

  const setTheme = useCallback((newTheme: Theme) => {
    setThemeState(newTheme)
    localStorage.setItem('theme', newTheme)
  }, [])

  const toggleTheme = useCallback(() => {
    setTheme(theme === 'light' ? 'dark' : 'light')
  }, [theme, setTheme])

  const value = useMemo(
    () => ({ theme, toggleTheme, setTheme }),
    [theme, toggleTheme, setTheme]
  )

  return (
    <ThemeContext.Provider value={value}>
      {children}
    </ThemeContext.Provider>
  )
}

Test QueryClient Pattern

function createTestQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        retry: false,
        gcTime: 0,
        staleTime: 0,
      },
      mutations: {
        retry: false,
      },
    },
  })
}

function AllTheProviders({ children }: { children: React.ReactNode }) {
  // Memoize to prevent recreation on re-renders
  const [queryClient] = useState(() => createTestQueryClient())

  return (
    <QueryClientProvider client={queryClient}>
      <ThemeProvider>
        <BrowserRouter>{children}</BrowserRouter>
      </ThemeProvider>
    </QueryClientProvider>
  )
}

Combined Mutation Hooks

For related mutations, expose a unified interface:

export function useProjectMutations() {
  const createMutation = useCreateProject()
  const updateMutation = useUpdateProject()
  const deleteMutation = useDeleteProject()

  return {
    create: createMutation,
    update: updateMutation,
    delete: deleteMutation,
    isLoading:
      createMutation.isPending ||
      updateMutation.isPending ||
      deleteMutation.isPending,
    error:
      createMutation.error ||
      updateMutation.error ||
      deleteMutation.error,
  }
}