> ## 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
})
```

Navigate away from a screen and check if all nodes are unregistered. If the count in `(5)` doesn't drop to zero when expected, you might have a memory leak.

<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>