SolidJS Production Debugging: AI-Optimized Reference

Critical Production Failure Patterns

Hydration Mismatch (Silent Production Killer)

Severity: Critical - breaks silently in production, works in development
Error Pattern: Hydration Mismatch. Unable to find DOM nodes for hydration key: someKey
Debug Time Investment: 6+ hours typical for complex cases

Root Causes:

• Date.now() or Math.random() in components (server vs client timing differences)
• Async data resolving at different speeds server vs client
• Random IDs or unstable keys in render
• Nested ternaries with complex objects

Critical Fix Strategy:

// NEVER - breaks hydration every time
function BrokenComponent() {
  return <div id={Math.random()}>Content</div>;
}

// ALWAYS - stable identifiers
function FixedComponent() {
  return <div id="stable-id">Content</div>;
}

// Async data fix - serialize server state
const [data] = createResource(() => fetchUserData(), {
  initialValue: () => serverData // Critical for avoiding mismatch
});

First Debug Check: Search codebase for Date.now(), Math.random(), time-based values in JSX

Memory Leaks (Performance Degradation)

Severity: High - 200MB+ leaks observed in production dashboards
Impact: Chrome performance degradation after 30 minutes of use
Detection Tool: Chrome DevTools Memory tab → heap snapshots over time

Critical Leak Sources:

1. Event Listeners Without Cleanup (Most Common)

// LEAKS - listener never removed
function LeakyComponent() {
  document.addEventListener('keydown', handler);
  return <div>{count()}</div>;
}

// FIXED - proper cleanup
function FixedComponent() {
  const handler = () => setCount(c => c + 1);
  document.addEventListener('keydown', handler);
  onCleanup(() => document.removeEventListener('keydown', handler));
  return <div>{count()}</div>;
}

2. Uncanceled Resources

// Add cancellation to all async resources
const [user] = createResource(userId, async (id, info) => {
  const controller = new AbortController();
  info.refetching && controller.abort();
  
  try {
    return await fetchUser(id, { signal: controller.signal });
  } catch (error) {
    if (error.name !== 'AbortError') throw error;
  }
});

3. Infinite Effect Loops

// CREATES INFINITE LOOPS
createEffect(() => {
  const newData = processData(data());
  setData(newData); // This triggers the effect again
});

// FIXED - separate signals
createEffect(() => {
  const result = processData(data());
  setProcessedData(result); // Update different signal
});

Performance Degradation Patterns

Threshold: Tasks >50ms cause visible jank
Detection: Chrome DevTools Performance tab

Critical Bottlenecks:

1. Massive Signal Updates (1000+ signals)

// KILLS PERFORMANCE - 1000 individual signals
const items = [];
for (let i = 0; i < 1000; i++) {
  const [item, setItem] = createSignal(data[i]);
  items.push(item);
}

// OPTIMIZED - use stores for collections
const [items, setItems] = createStore([]);
setItems(index, 'property', newValue); // Only updates one item

2. Expensive Computations in Render

// RECALCULATES ON EVERY RENDER
function ExpensiveComponent(props) {
  const expensiveResult = heavyCalculation(props.data); // Bad
  return <div>{expensiveResult}</div>;
}

// CACHED WITH MEMO
function FastComponent(props) {
  const expensiveResult = createMemo(() => heavyCalculation(props.data));
  return <div>{expensiveResult()}</div>;
}

3. Large DOM Trees (10,000+ nodes)

// DON'T RENDER - use virtual scrolling
{items().map(item => <ItemComponent item={item} />)}

// USE VIRTUAL SCROLLING for 1000+ items
import { createVirtualizer } from '@tanstack/virtual-core';

Configuration & Settings

Development Environment Fixes

Hot Reload Death Recovery:

# Nuclear option - fixes 90% of HMR issues
rm -rf node_modules/.vite && npm run dev

Hot Reload Prevention:

• Split components >500 lines (breaks HMR)
• Avoid circular imports
• Use named exports over default exports
• Check for weird CSS import patterns

SSR Configuration

Browser API Protection:

// BREAKS ON SERVER
const theme = localStorage.getItem('theme');

// WORKS EVERYWHERE
const theme = isServer ? 'light' : localStorage.getItem('theme');

// SIDE EFFECTS IN EFFECTS
createEffect(() => {
  if (isServer) return;
  document.title = `Page: ${title()}`;
});

Critical SSR Errors:

• ReferenceError: document is not defined
• ReferenceError: window is not defined

Resource Requirements

Bundle Size Optimization

Real Production Comparison:

• React + React DOM + libraries: 280KB gzipped
• SolidJS + equivalent libraries: 120KB gzipped
• Improvement: 57% smaller bundles

Bundle Optimization Strategy:

// WRONG - pulls in 70KB
import { debounce } from 'lodash';

// CORRECT - pulls in 2KB
import debounce from 'lodash/debounce';

// Tree shake properly
import { For, Show } from 'solid-js'; // Good
import * as Solid from 'solid-js'; // Bad - imports everything

Performance Monitoring Requirements

Essential Metrics:

• Tasks >50ms (visible jank threshold)
• Memory growth >100MB over 10 minutes
• Bundle size >200KB gzipped
• Time to Interactive >1.5s

Real Production Numbers:

Metric	React (optimized)	SolidJS	Improvement
Initial bundle	180KB gzipped	85KB gzipped	53% smaller
Memory usage	120MB after 10min	85MB after 10min	29% less
Update latency	12-25ms	3-8ms	60-75% faster
Time to Interactive	1.2s	0.8s	33% faster

Critical Warnings & Failure Modes

What Official Documentation Doesn't Tell You

1. Props Destructuring Breaks Reactivity (React Developer Trap)

// BREAKS - props lose reactivity
function Component({ name, age }) {
  return <div>{name}</div>; // Won't update
}

// WORKS - keep props object intact
function Component(props) {
  return <div>{props.name}</div>; // Updates correctly
}

2. Signal Debugging Doesn't Work Like Console.log

// WON'T WORK - doesn't track changes
console.log('Count changed:', count());

// WORKS - tracks signal changes
createEffect(() => {
  console.log('Count is now:', count());
});

3. Virtual DOM Assumptions Don't Apply

• No component re-renders to hide memory leaks
• Direct DOM updates mean leaked references persist
• Performance problems manifest differently than React

Breaking Points & Thresholds

Critical Limits:

• 1000+ DOM elements: Requires virtual scrolling
• 1000+ individual signals: Use stores instead
• 500+ line components: Breaks hot module replacement
• 50ms+ update tasks: Causes visible jank
• 200MB+ memory growth: Indicates serious leaks

Community & Support Quality

Response Time Expectations:

• SolidJS Discord #help: Hours (Ryan Carniato actively responds)
• GitHub Issues: Days for bugs, hours for urgent production issues
• Stack Overflow: Limited coverage, weeks for responses
• Documentation Quality: Excellent compared to most frameworks

Support Escalation Path:

1. Search SolidJS GitHub issues first
2. SolidJS Discord #help channel
3. GitHub discussions for architecture questions
4. Direct GitHub issues for confirmed bugs

Emergency Debug Checklist (3AM Production Failures)

Immediate Triage (5 minutes):

1. Check browser console for hydration mismatch errors
2. Look for Date.now(), Math.random() in recent changes
3. Check memory usage in Chrome DevTools
4. Verify SSR errors (document/window is not defined)

Nuclear Debug Commands:

# Fixes 70% of weird SolidJS issues
rm -rf node_modules/.vite && rm -rf dist && npm install && npm run dev

# Memory leak detection
# Chrome DevTools → Memory → Take heap snapshots over time

# Performance profiling
# Chrome DevTools → Performance → Record 5-10 seconds

Critical Debug Sequence:

1. Hydration: Search for time-based rendering, unstable IDs
2. Memory: Check event listeners, uncanceled resources, infinite effects
3. Performance: Profile render times, check for expensive calculations
4. SSR: Verify browser API usage wrapped in isServer checks
5. Hot Reload: Clear Vite cache, check component sizes

Decision Criteria for SolidJS vs Alternatives

When SolidJS is Worth the Migration Cost

Quantified Benefits:

• Bundle size reduction: 40-60% smaller
• Update performance: 60-75% faster
• Memory efficiency: 20-30% less usage
• Learning curve: 2-4 weeks for React developers

Migration Pain Points:

• Smaller ecosystem (fewer third-party components)
• Different debugging tools (less mature than React DevTools)
• Props destructuring refactor required
• SSR hydration complexity higher than Next.js

Technical Prerequisites

Team Requirements:

• JavaScript fundamentals (closures, reactivity concepts)
• Understanding of direct DOM manipulation
• Comfort with compilation-based frameworks
• Willingness to debug with less tooling support

Infrastructure Requirements:

• Vite build system (recommended)
• Modern browser support (ES2020+)
• SSR server capable of streaming (for optimal performance)
• Error monitoring (Sentry, LogRocket) for production debugging