# Debugging and Inspection

## Debugging with agents

For many debugging tasks, the fastest path is to use an agent that already knows the
`@data-client/vue` debugging workflow.

Install the [`data-client-vue` skill](https://skills.sh/reactive/data-client/data-client-vue)
in your coding agent, then ask it to inspect the current page or app state.

### How agent debugging works

In dev mode, [DevToolsManager](https://dataclient.io/vue/api/DevToolsManager.md) exposes live `Controller` instances so an agent can inspect
cache state, endpoint metadata, and dispatched actions directly from the running app.

Technically, those controllers are stored on [`globalThis.__DC_CONTROLLERS__`](https://dataclient.io/vue/api/DevToolsManager.md#controllers), which is a
browser-global `Map`. You can think of it as a temporary dev-mode registry that lets tools
and agents look up the active `DataClientPlugin` stores for the current page.

At a high level, the agent can:

- discover the active `DataClientPlugin` controllers
- read normalized or denormalized cache state
- inspect recent fetches, responses, errors, and invalidations
- correlate store changes with browser network activity
- trigger safe controller operations like invalidation or expiration for investigation

This is useful when you want a quick answer to questions like "why didn't this refetch?",
"what is in the cache right now?", or "which action updated this entity?" without manually
clicking through each inspector panel.

The skill drives this through [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp).

## Manual debugging

If you prefer to inspect everything yourself, the browser devtools workflow below remains
the standard manual path.

### Installation

Add the browser extension for
[chrome extension](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en)
or
[firefox extension](https://addons.mozilla.org/en-US/firefox/addon/reduxdevtools/)

### Open dev tools

![redux-devtools browser button](/img/devtools-browser-button.png)

After installing and loading your site in [dev-mode](https://vite.dev/guide/env-and-mode), click the redux-devtool logo in the location bar.

Clicking that will open the inspector, which allows you to observe dispatched actions,
their effect on the store's state as well as current store state.

![browser-devtools](/img/devtool-action.png "Reactive Data Client devtools")

The [Controller](https://dataclient.io/vue/api/Controller.md) dispatches actions, making that page useful for understanding
what actions you see. Here we observe common actions of [fetch](https://dataclient.io/vue/api/Controller.md#fetch)
and [setResponse](https://dataclient.io/vue/api/Controller.md#setResponse).

> **Note**
>
> By default the devtool integration will filter duplicate [fetch](https://dataclient.io/vue/api/Controller.md#fetch) actions.
> This can be changed with [skipLogging](https://dataclient.io/vue/api/DevToolsManager.md#skiplogging) option.

### Control flow

Data Client uses the [flux store](https://facebookarchive.github.io/flux/docs/in-depth-overview/) pattern, making debugging
straightforward as each change is traceable and descriptive.

> [More about control flow](https://dataclient.io/vue/concepts/managers.md)

### State Inspection

Whens [schemas](https://dataclient.io/rest/api/schema.md) are used, responses are [normalized](https://dataclient.io/vue/concepts/normalization.md) into `entities`
and `endpoints` tables. This enables automatic performance advantages over simpler key-value fetch caches; especially
beneficial with dynamic (changing) data. This also eliminates data-inconsistency bugs.

![Dev tools state inspector](/img/devtool-state.png "Reactive Data Client devtools state inspector")

Click on the **'state'**
tab in devtools to see the store's entire state. This can be useful to determine exactly where data is. There is
also a 'meta' section of the cache for information like when the request took place (useful for [TTL](https://dataclient.io/vue/concepts/expiry-policy.md)).

### State Diff

For monitoring a particular fetch response, it might be more useful to see how the store updates.
Click on the 'Diff' tab to see what changed.

![Dev tools diff inspector](/img/devtool-diff.png "Reactive Data Client devtools diff")

Here we toggled the 'completed' status of a todo using an [optimistic update](https://dataclient.io/rest/guides/optimistic-updates.md).

### Action Tracing

Tracing is not enabled by default as it is very computationally expensive. However, it can be very useful
in tracking down where [actions](https://dataclient.io/vue/api/Actions.md) are dispatched from. Customize [DevToolsManager](https://dataclient.io/vue/api/DevToolsManager.md)
by setting the trace option to `true` with [getDefaultManagers](https://dataclient.io/vue/api/getDefaultManagers.md):

```ts title="main.ts"
import { createApp } from 'vue';
import { DataClientPlugin, getDefaultManagers } from '@data-client/vue';
import App from './App.vue';

const managers = getDefaultManagers({
  devToolsManager: { trace: true },
});

const app = createApp(App);
app.use(DataClientPlugin, { managers });
app.mount('#app');
```