> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uniwind.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Shadow Tree Diagnostics

> Debug and monitor Shadow Tree updates in real-time

## Overview

<Tip>
  Diagnostics are designed for development only. They help you understand what's happening under the hood when Uniwind Pro updates your styles.
</Tip>

Ever wondered what Uniwind Pro is doing behind the scenes? The Diagnostics API gives you a window into the Shadow Tree. See exactly when components register, unregister, and how styles flow through the C++ engine.

## Enabling Diagnostics

```tsx theme={null}
import { enableDiagnostics } from 'uniwind/diagnostics'

enableDiagnostics({
    reportMounts: true,
    reportUnmounts: true,
    reportUpdates: true,
})
```

Once enabled, you'll see this confirmation in your console:

```bash theme={null}
Uniwind: 🛠️ Diagnostics enabled!
```

## What You Can Track

### Component Mounts

When `reportMounts` is enabled, you'll see every component that registers with the Shadow Tree:

```bash theme={null}
Uniwind (5): 🟢 ShadowNodeRegistered for tag 42 and className: "flex flex-1 items-center"
```

| Part | Meaning |
| - | - |
| `(5)` | Total shadow nodes currently registered |
| `🟢` | A new node was added |
| `tag 42` | React Native's internal view identifier |
| `className` | The Tailwind classes applied to this component |

### Component Unmounts

When `reportUnmounts` is enabled, you'll see components leaving the Shadow Tree:

```bash theme={null}
Uniwind (4): 🟡 ShadowNodeUnregistered for tag 42
```

The count decreases as components are removed. Useful for detecting memory leaks or unexpected unmounts.

### Style Updates

This is where it gets interesting. When `reportUpdates` is enabled, you'll see exactly what styles are being applied and how:

```bash theme={null}
Uniwind 🌳 Performed shadow tree update for 198 nodes:
▶ 🔥 C++ updates (195):
    View (42) { backgroundColor: "#FF5733", opacity: 0.95 }
    Text (43) { color: "#FFFFFF", fontSize: 16 }
    // ... and 193 more nodes
▼ ✨ Native updates (3):
    Switch (978) { tintColor: "#0000FF", onTintColor: "#0000FF" }
    // ... and 2 more nodes
```

Updates are grouped into collapsible sections:

| Icon | Type | Description |
| - | - | - |
| 🔥 | C++ updates | Styles applied directly via the Shadow Tree, zero re-renders |
| ✨ | Native updates | Props updated directly on Native Views (Swift/Kotlin) |

## Configuration Options

| Option | Type | Default | Description |
| - | - | - | - |
| `reportMounts` | `boolean` | `false` | Log when components register with the Shadow Tree |
| `reportUnmounts` | `boolean` | `false` | Log when components unregister from the Shadow Tree |
| `reportUpdates` | `boolean` | `false` | Log style updates with detailed property changes |

<Info>
  Enable only what you need. Logging everything on a complex screen can get noisy.
</Info>

## Common Use Cases

### Debugging Theme Switches

Enable `reportUpdates` to see all styles that change when switching themes:

```tsx theme={null}
enableDiagnostics({ reportUpdates: true })
```

Then trigger a theme change and watch the console. You'll see every component that updates and exactly what properties changed.

### Detecting Memory Leaks

All styled views are stored in C++. Enable mount tracking to verify components are properly cleaned up:

```tsx theme={null}
enableDiagnostics({
    reportMounts: true,
    reportUnmounts: true
})
```

Unmount a screen (for example, pop it from a stack) and check that its nodes are unregistered. If the count in `(5)` doesn't drop as expected after a real unmount, you might have a memory leak.

<Note>
  Screens that stay mounted keep their nodes registered. This includes inactive tabs, screens frozen by `react-freeze`, and content suspended by React, so they keep receiving theme updates. Switching away from a tab won't lower the count, and that's expected.
</Note>

<Info>
  If you suspect a memory leak in Uniwind Pro, [create an issue](https://github.com/uni-stack/uniwind/issues/new?template=pro-bug-report.yml) with the diagnostics output attached.
</Info>

### Verifying Zero Re-renders

Both C++ updates (🔥) and Native updates (✨) are applied without triggering React re-renders. If you see your styles in these logs, Uniwind Pro is working as expected.

## Platform Support

| Platform | Support |
| - | - |
| iOS | Full diagnostics |
| Android | Full diagnostics |
| Web | No-op (function exists but produces no output) |

<Warning>
  Diagnostics only work on native platforms. On web, the `enableDiagnostics` function is a stub that does nothing.
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="Shadow Tree Updates" icon="bolt" href="/pro/shadow-tree-updates">
    Learn how Uniwind Pro updates styles without re-renders
  </Card>

  <Card title="Theme Transitions" icon="wand-magic-sparkles" href="/pro/theme-transitions">
    Add smooth animated transitions between themes
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.