Preact Debugging and DevTools — Profiling 3kB Applications

Learn how to debug Preact applications using Preact DevTools, browser tools, and performance profiling techniques for the 3kB framework.

In this lesson, you'll install and use Preact DevTools, debug component rendering, profile performance, and troubleshoot common Preact issues.

What You'll Learn

How to install Preact DevTools, inspect component trees, profile re-renders, debug hooks, and optimize Preact application performance.

Why It Matters

Debugging tools help you understand what your application is doing, why components re-render, and where performance bottlenecks hide. Proper debugging saves hours of guesswork.

Real-World Use

The Doda Browser extension team uses Preact DevTools to profile tab switching performance, identifying that unnecessary re-renders in the tab list caused jank when switching between 50+ open tabs.

flowchart LR
    A[Application] --> B[Preact DevTools]
    A --> C[Browser DevTools]
    B --> D[Component Tree]
    B --> E[Signals Inspector]
    B --> F[Profiler]
    C --> G[Console]
    C --> H[Network]
    C --> I[Performance]
    style A fill:#673ab8,color:#fff
    style B fill:#4a148c,color:#fff

Installing Preact DevTools

Preact DevTools is a browser extension for Chrome and Firefox:

# DevTools are automatically enabled when you import preact/debug
npm install preact

In your application entry point, add the debug import:

import 'preact/debug'; // Must be imported BEFORE your components
import { render } from 'preact';
import App from './App';

render(<App />, document.getElementById('app'));

The preact/debug module activates DevTools integration and provides warnings for common mistakes.

Component Tree Inspection

Once DevTools is active, you can inspect the component tree:

function UserCard({ user }) {
  return (
    <div class="card">
      <Avatar src={user.avatar} />
      <h3>{user.name}</h3>
      <p>{user.email}</p>
    </div>
  );
}

function UserList({ users }) {
  return (
    <div>
      {users.map(user => (
        <UserCard key={user.id} user={user} />
      ))}
    </div>
  );
}

Output: In the DevTools Components tab, you see UserList as a parent with UserCard children. Selecting a UserCard shows its props (user.id, user.name, user.email) and hooks state.

Profiling Re-renders

Identify unnecessary re-renders with the profiler:

import 'preact/debug';

function ExpensiveList({ items }) {
  // Profiler shows when and why this component re-renders
  console.log('ExpensiveList rendered at:', Date.now());

  return (
    <ul>
      {items.map(item => (
        <ExpensiveItem key={item.id} item={item} />
      ))}
    </ul>
  );
}

In the DevTools Profiler tab, start recording and interact with your app. The flame chart shows each component's render duration and why it re-rendered (props change, state change, or parent re-render).

Debugging Hooks

Preact DevTools shows hook state for each component:

function Counter() {
  const [count, setCount] = useState(0);
  const [step, setStep] = useState(1);

  const doubled = useMemo(() => count * 2, [count]);

  useEffect(() => {
    document.title = `Count: ${count}`;
  }, [count]);

  return (
    <div>
      <p>Count: {count} (doubled: {doubled})</p>
      <button onClick={() => setCount(c => c + step)}>+</button>
    </div>
  );
}

Output: In DevTools, selecting the Counter component shows all hooks in order: State: 0, State: 1, Memo: 0, Effect. You can inspect each hook's current value.

Debugging Signals

When using @preact/signals, the DevTools signal inspector shows signal values:

import { signal, computed, effect } from '@preact/signals';

const todos = signal([]);
const filter = signal('all');

const filteredTodos = computed(() => {
  if (filter.value === 'all') return todos.value;
  return todos.value.filter(t => t.done === (filter.value === 'done'));
});

effect(() => {
  console.log(`Filtered count: ${filteredTodos.value.length}`);
});

Output: The DevTools Signals tab lists all signals with their current values. Selecting a signal shows which components and effects depend on it.

Console Warnings

preact/debug adds helpful console warnings:

// Warning: Using className instead of class
<div className="container">Bad</div>
// Console: "Warning: "className" is not a Preact prop. Did you mean "class"?"

// Warning: Missing key in list
items.map(item => <div>{item}</div>)
// Console: "Warning: Not all list items have a "key" prop"

These warnings catch common mistakes during development and help you write correct Preact code.

Common Mistakes

1. Forgetting to import preact/debug: Without it, DevTools integration doesn't activate and console warnings are silent.
2. Profiling in production mode: DevTools and debug warnings only work in development mode. Production builds strip debug code.
3. Not using browser DevTools for DOM inspection: Preact DevTools shows the component tree. Use browser DevTools Elements tab to inspect the actual DOM output.
4. Ignoring console warnings: Preact debug warnings point to real issues. Treat them as errors during development.
5. Profiling without understanding the flame chart: The profiler shows render duration. A long render isn't necessarily bad — focus on unnecessary re-renders (components that render but produce the same output).

Practice Questions

1. How do you enable Preact DevTools? Answer: Import preact/debug at the top of your entry point. Install the browser extension for Chrome or Firefox.

2. What information does the Components tab show? Answer: The component tree structure, props, state, hooks values, and context for each selected component.

3. How does the Profiler help identify performance issues? Answer: It records component renders in a flame chart, showing render duration, cause (props/state/context change), and component identity.

4. What are common Preact-specific warnings from preact/debug? Answer: Using className instead of class, missing key props in lists, using ReactDOM APIs, and calling hooks conditionally.

Challenge

Create a Preact app with at least 10 components and 5 signal-based state values. Use the Profiler to identify unnecessary re-renders, then optimize with memo, signals, or useMemo.

Mini Project

Build a moderately complex Preact app (todo list with filters, search, and categories). Use Preact DevTools to profile its performance, identify the top 3 re-render causes, and optimize them.

FAQ

What's Next

Learn about Preact Size Optimization to minimize your Preact bundle for production deployment.