SolidJS Production Debugging: Fix the Shit That Actually Breaks

I've debugged SolidJS apps at 2AM more times than I care to admit. While everyone debates SolidJS 2.0, the real world runs on 1.x - and that's where the production disasters happen. Here are the clusterfucks that actually break in production and the fixes that work when Stack Overflow has zero answers.

Hydration Mismatch: The Silent Production Killer

Error: Hydration Mismatch. Unable to find DOM nodes for hydration key: someKey

This shit breaks silently in production but works fine locally. I've spent 6 hours debugging this exact error on a dashboard that worked perfectly in dev.

What causes it:

• Date/time rendering different on server vs client
• Random IDs or Math.random() in your components
• Async data that resolves differently between server and client
• Nested ternaries with complex objects

The nuclear fix that actually works:

// If you're using Date.now() or Math.random() in render, stop
// This breaks hydration every damn time
function BrokenComponent() {
  return <div id={Math.random()}>Content</div>; // Never do this
}

// Use stable IDs instead
function FixedComponent() {
  return <div id=\"stable-id\">Content</div>;
}

For async data hydration mismatch:

// This breaks because server and client finish at different times
const [data] = createResource(() => fetchUserData());

// This works - serialize the data correctly
const [data] = createResource(() => fetchUserData(), {
  initialValue: () => serverData // Pass server state to avoid mismatch
});

First thing to check: Are you using Date.now(), Math.random(), or any time-based values in your JSX? Remove them.

Memory Leaks: When Your Fast App Becomes Slow as Shit

SolidJS is supposed to be memory efficient, but you can still fuck it up. I found a 200MB memory leak in our dashboard that brought Chrome to its knees after 30 minutes of use. Use Chrome DevTools Memory tab to track these issues.

Common SolidJS memory leak sources:

1. Event listeners that don't clean up:

// This leaks - event listener never gets removed
function LeakyComponent() {
  const [count, setCount] = createSignal(0);
  
  document.addEventListener('keydown', () => {
    setCount(c => c + 1);
  });
  
  return <div>{count()}</div>;
}

// This works - cleanup in onCleanup
function FixedComponent() {
  const [count, setCount] = createSignal(0);
  
  const handler = () => setCount(c => c + 1);
  document.addEventListener('keydown', handler);
  
  onCleanup(() => {
    document.removeEventListener('keydown', handler);
  });
  
  return <div>{count()}</div>;
}

2. Uncanceled resources:

// This can leak if component unmounts during fetch
const [user] = createResource(userId, fetchUser);

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

3. Infinite createEffect loops:

// This creates infinite loops and memory issues
const [data, setData] = createSignal({});
const [processed, setProcessed] = createSignal({});

createEffect(() => {
  const newData = processData(data());
  setProcessed(newData);
  setData(newData); // This triggers the effect again - infinite loop
});

// Fix with proper dependency management
createEffect(() => {
  const result = processData(data());
  setProcessed(result);
}); // Don't update data inside the effect

Debug memory leaks:

1. Chrome DevTools → Memory tab → Take heap snapshot
2. Look for objects growing between snapshots (memory profiling guide)
3. Search for your component names in retained objects
4. Check if onCleanup functions are actually running

Performance Hell: When SolidJS Isn't Fast Enough

SolidJS is fast, but you can still make it slow. Here's how I found and fixed performance issues that made our real-time dashboard stutter. Use Chrome DevTools Performance tab to identify bottlenecks.

1. Massive signal updates:

// This kills performance - 1000 signals updating
const [items, setItems] = createSignal([]);

// Every item change triggers re-render of entire list
for (let i = 0; i < 1000; i++) {
  const [item, setItem] = createSignal(data[i]);
  items.push(item);
}

// Use stores for collections instead
const [items, setItems] = createStore([]);

// Update just one item - rest stay unchanged
setItems(index, 'property', newValue);

2. Expensive computations in render:

// This recalculates on every render
function ExpensiveComponent(props) {
  const expensiveResult = heavyCalculation(props.data); // Bad
  return <div>{expensiveResult}</div>;
}

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

3. DOM thrashing with large lists:

// Don't render 10,000 DOM nodes
{items().map(item => <ItemComponent item={item} />)}

// Use virtual scrolling for large lists ([TanStack Virtual docs](https://tanstack.com/virtual/latest))
import { createVirtualizer } from '@tanstack/virtual-core';

const virtualizer = createVirtualizer({
  count: items().length,
  getScrollElement: () => parentRef,
  estimateSize: () => 35,
});

Hot Reload Death: When Dev Server Becomes Useless

Hot reload breaks daily in SolidJS. Here's how to fix it without losing your state. Check Vite HMR troubleshooting for common issues:

When hot reload dies completely:

## Nuclear option - deletes all Vite cache
rm -rf node_modules/.vite
rm -rf node_modules/.cache
npm run dev

When specific files won't hot reload:

// Large components break HMR - split them up
// This 500-line component kills hot reload
function MassiveComponent() { /* 500 lines */ }

// Split into smaller components
function HeaderSection() { /* 50 lines */ }
function BodySection() { /* 100 lines */ }
function FooterSection() { /* 50 lines */ }

Hot reload debugging tricks:

• Check browser console for HMR errors
• Look for circular imports (these break HMR)
• Remove default exports temporarily (named exports reload better)
• Check if you're importing CSS files in weird ways

SSR Failures: When Your Server-Side App Dies

Error: ReferenceError: document is not defined or window is not defined

This happens when browser-specific code runs on the server. I've seen this break entire deployments.

Common culprits:

// This breaks SSR - no localStorage on server
const [theme, setTheme] = createSignal(localStorage.getItem('theme'));

// Fix with isServer check
const [theme, setTheme] = createSignal(isServer ? 'light' : localStorage.getItem('theme') || 'light');

// Or use clientOnly
function ThemeComponent() {
  return (
    <clientOnly>
      {() => {
        const savedTheme = localStorage.getItem('theme');
        return <div>Theme: {savedTheme}</div>;
      }}
    </clientOnly>
  );
}

Window/document access:

// Breaks on server
window.addEventListener('resize', handler);

// Fix with createEffect + isServer
createEffect(() => {
  if (isServer) return;
  window.addEventListener('resize', handler);
  onCleanup(() => window.removeEventListener('resize', handler));
});

Debugging Tools That Actually Help

1. Solid DevTools Chrome Extension

• Install from Chrome Web Store
• Shows reactivity graph and signal values
• Requires @solid-devtools/debugger package in dev

npm install -D @solid-devtools/debugger

2. Chrome DevTools Performance Tab

• Profile component render times
• Find expensive signal updates
• Identify memory leaks over time

3. Console debugging that works:

// Debug signal updates
const [count, setCount] = createSignal(0);
console.log('Count changed:', count()); // Won't work - doesn't track

// Track signal changes properly
createEffect(() => {
  console.log('Count is now:', count()); // Logs on every change
});

// Debug computations
const doubled = createMemo(() => {
  const result = count() * 2;
  console.log('Doubled computed:', result);
  return result;
});

The 3AM Debugging Checklist

When everything is fucked and you need to debug fast:

1. Check hydration: Look for Date.now(), Math.random(), time-based rendering
2. Check memory: Take heap snapshots, look for growing objects
3. Check infinite loops: Search for signals that update themselves in effects
4. Check SSR: Look for browser APIs used during server render
5. Check hot reload: Clear Vite cache, restart dev server
6. Check console: SolidJS logs are better than you think
7. Check network: Failed API calls cause weird component behavior

Nuclear debugging command:

rm -rf node_modules/.vite && rm -rf dist && npm install && npm run dev

This fixes 70% of weird SolidJS issues. When in doubt, nuke the cache.

SolidJS is supposed to be performant by default, but you can still fuck it up spectacularly. I've seen SolidJS apps that were slower than React because developers didn't understand the performance model. Here's how to fix the shit that actually matters.

The SolidJS Performance Model (Why It's Different)

SolidJS doesn't have a virtual DOM. Updates go directly to the DOM nodes that need changing. This is why it's fast, but it also means performance problems show up differently than in React.

What SolidJS optimizes for:

• Granular reactive updates (only changed values update)
• Minimal JavaScript execution during updates
• Direct DOM manipulation without diffing
• Small bundle sizes through compilation

What can still kill performance:

• Too many reactive primitives (thousands of signals)
• Expensive computations in render paths
• Large DOM trees (10,000+ nodes)
• Memory leaks from poor cleanup

Bundle Size Optimization: Beyond the Hype

Everyone talks about SolidJS bundle sizes, but you can still ship massive bundles if you're not careful.

Real bundle size comparison from our production app:

• React + React DOM + essential libraries: 280KB gzipped
• SolidJS + equivalent libraries: 120KB gzipped
• Difference: 57% smaller

How to keep bundles small:

// Don't import entire libraries
import { debounce } from 'lodash'; // Pulls in 70KB
import debounce from 'lodash/debounce'; // Pulls in 2KB

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

// Use dynamic imports for large components
const HeavyChart = lazy(() => import('./HeavyChart'));

Webpack Bundle Analyzer for Vite:

npm install -D vite-bundle-analyzer
npm run build -- --analyzer

This shows what's actually in your bundles. I found a 40KB unused date library this way.

Memory Optimization: The Hidden Performance Killer

Memory leaks in SolidJS are different from React. Components don't re-render, so leaked closures stick around forever.

Monitor memory usage:

// Add this to track memory in production
if (process.env.NODE_ENV === 'development') {
  setInterval(() => {
    console.log('Memory usage:', performance.memory?.usedJSHeapSize / 1024 / 1024, 'MB');
  }, 5000);
}

Common memory leak patterns:

1. Event listeners without cleanup:

function LeakyComponent() {
  createEffect(() => {
    const handler = () => console.log('resize');
    window.addEventListener('resize', handler);
    // Forgot onCleanup - this leaks
  });
}

function FixedComponent() {
  createEffect(() => {
    const handler = () => console.log('resize');
    window.addEventListener('resize', handler);
    onCleanup(() => window.removeEventListener('resize', handler));
  });
}

2. Timers that don't clear:

// Leaks memory every time component mounts
function TimerComponent() {
  const timer = setInterval(() => updateData(), 1000);
  // Timer keeps running after component unmounts
}

// Proper cleanup
function FixedTimerComponent() {
  const timer = setInterval(() => updateData(), 1000);
  onCleanup(() => clearInterval(timer));
}

3. Resources that don't cancel:

// Can leak if component unmounts during fetch
const [userData] = createResource(() => fetchUser());

// Proper cancellation
const [userData] = createResource(async (_, info) => {
  const controller = new AbortController();
  info.refetching && controller.abort();
  
  try {
    return await fetchUser({ signal: controller.signal });
  } catch (error) {
    if (error.name !== 'AbortError') throw error;
  }
});

Render Performance: When Updates Are Still Slow

SolidJS updates are fast, but you can still make them slow with bad patterns.

Performance killers:

1. Expensive calculations in render:

// This recalculates on every signal change
function SlowComponent() {
  const expensiveValue = heavyCalculation(data(), settings(), filters());
  return <div>{expensiveValue}</div>;
}

// Cache expensive calculations
function FastComponent() {
  const expensiveValue = createMemo(() => 
    heavyCalculation(data(), settings(), filters())
  );
  return <div>{expensiveValue()}</div>;
}

Real-world example: We had a dashboard that recalculated statistics on every data point update (2,000+ calculations per second). Wrapping in createMemo reduced update time from 45ms to 3ms - the difference between janky scrolling and buttery smooth interactions.

2. Creating signals in render:

// Don't create signals dynamically
function BadComponent() {
  const items = data().map(item => createSignal(item)); // Creates new signals every render
  return <div>{/* ... */}</div>;
}

// Use stores for dynamic collections
function GoodComponent() {
  const [items, setItems] = createStore(data());
  return <div>{/* ... */}</div>;
}

3. Massive DOM trees:

// Don't render everything at once
{items().map(item => <ItemComponent key={item.id} item={item} />)}

// Virtualize large lists
import { createVirtualizer } from '@tanstack/solid-virtual';

const virtualizer = createVirtualizer({
  count: items().length,
  getScrollElement: () => scrollElement,
  estimateSize: () => 50,
});

// Only render visible items
virtualizer.getVirtualItems().map(virtualItem => (
  <ItemComponent 
    key={virtualItem.key}
    item={items()[virtualItem.index]} 
  />
))

Server-Side Rendering Performance

SSR in SolidJS can be blazing fast or painfully slow depending on how you handle data fetching. Check SolidStart SSR docs and server-side rendering guide.

Async rendering patterns:

// This blocks SSR until all data loads
const [userData] = createResource(() => fetchUser());
const [postsData] = createResource(() => fetchPosts());
const [commentsData] = createResource(() => fetchComments());

// This renders immediately with loading states
const [userData] = createResource(() => fetchUser(), { initialValue: null });
const [postsData] = createResource(() => fetchPosts(), { initialValue: [] });
const [commentsData] = createResource(() => fetchComments(), { initialValue: [] });

Streaming SSR optimization:

// Enable streaming in SolidStart
export default defineConfig({
  solid: {
    ssr: true,
    streaming: true, // Streams content as it becomes available
  },
});

Preload critical data:

// In route data functions - loads before component renders
export function routeData() {
  return {
    user: createResource(() => fetchUser()),
    settings: createResource(() => fetchSettings()),
  };
}

Production Performance Monitoring

You need real metrics, not gut feelings about performance. Use Core Web Vitals and performance monitoring tools for accurate measurements.

Essential monitoring:

// Track Core Web Vitals
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.entryType === 'navigation') {
      console.log('LCP:', entry.loadEventEnd - entry.loadEventStart);
    }
    if (entry.entryType === 'largest-contentful-paint') {
      console.log('LCP:', entry.startTime);
    }
  });
});

observer.observe({ entryTypes: ['navigation', 'largest-contentful-paint'] });

Bundle analysis:

// Add to vite.config.js for bundle analysis ([Vite build options](https://vitejs.dev/config/build-options.html))
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: (id) => {
          if (id.includes('node_modules')) return 'vendor';
          if (id.includes('charts')) return 'charts';
        },
      },
    },
  },
});

Real Performance Numbers from Production

Here are actual metrics from migrating a React dashboard to SolidJS:

Test methodology: Dashboard with 500+ data points updating every 2 seconds, tested on Chrome DevTools with slow 3G throttling.

Performance Anti-patterns to Avoid

1. Over-signaling:

// Don't create signals for everything
function OverEngineeredComponent() {
  const [firstName, setFirstName] = createSignal('');
  const [lastName, setLastName] = createSignal('');
  const [email, setEmail] = createSignal('');
  const [phone, setPhone] = createSignal('');
  // ... 20 more signals
}

// Use a store for related data
function CleanComponent() {
  const [user, setUser] = createStore({
    firstName: '',
    lastName: '',
    email: '',
    phone: '',
    // ... all related data
  });
}

2. Unnecessary memoization:

// Don't memo everything
const expensiveThing = createMemo(() => props.value * 2); // Bad - simple operation
const cheapThing = createMemo(() => formatDate(date())); // Bad - already optimized

// Only memo actually expensive operations  
const reallyExpensiveThing = createMemo(() => {
  return heavyDataProcessing(largeDataset(), complexFilters());
});

3. Improper resource management:

// Don't create resources in effects
createEffect(() => {
  const [data] = createResource(() => fetchData()); // Bad - creates new resource every time
});

// Create resources at component level
const [data] = createResource(() => fetchData());

The Performance Debugging Process

When your SolidJS app is slow:

1. Chrome DevTools Performance tab - Record 5-10 seconds, look for:

   • Long tasks (>50ms)
   • Excessive garbage collection
   • High CPU usage during updates

2. Memory tab - Take snapshots over time:

   • Growing heap size indicates leaks
   • Search for your component names in retained objects

3. Network tab - Check for:

   • Unnecessary API calls
   • Large bundle sizes
   • Uncached resources

4. Solid DevTools - View reactivity graph:

   • Excessive signal updates
   • Circular dependencies
   • Unused computations

The nuclear performance fix: When everything else fails, try this:

rm -rf node_modules/.vite
rm -rf dist  
npm install
npm run build

Sometimes Vite's cache gets corrupted and causes performance issues that don't show up in development.

Performance Is About User Experience

Remember: SolidJS performance optimization is about real user impact, not benchmark numbers. A 10ms improvement that users don't notice isn't worth weeks of optimization work.

Focus on:

• Faster initial loading (bundle size, SSR)
• Smooth interactions (no janky updates)
• Lower memory usage (better mobile experience)
• Reliable performance (no memory leaks)