overmind-devtools-client/README.md

Overmind devtool

# Overmind DevTools Client

## Introduction

There are three packages related to `overmind-devtools` experience:

- [overmind-devtools-client](../overmind-devtools-client/) - "core" package that provides UI ("web client")
- [overmind-devtools](../overmind-devtools/README.md) - standalone, electron application
- [overmind-devtools-vscode](../overmind-devtools-vscode/) - VSCode extension

`overmind-devtools-client` is a core application that can be hosted by available "hosts": `overmind-devtools` and `overmind-devtools-vscode`.

![overmind-devtools-packages](./docs/assets/overmind-devtools-packages.png)

This means that this package (a reminder: we're now in `overmind-devtools-client` package of the monorepo) is **crucial** for the other two.

In case you want to improve devtools experience (UI, UX, etc.), focus on this package specifically.

## Using the DevTools Web Client

### Starting the DevTools

To run the DevTools web client locally:

```bash
# Navigate to the package directory
cd overmind/packages/overmind-devtools-client

# Start both the WebSocket and the DevTools server
npm start
```

This starts:

- The WebSocket server on port 3031 (for communication with Overmind apps)
- The web client at <http://localhost:8080> (or another port if 8080 is in use)

### Connecting Your Application

In your Overmind application, configure it to connect to the DevTools:

```javascript
import { createOvermind } from 'overmind'
import { config } from './overmind'

// Connect to the DevTools WebSocket server on port 3031
const overmind = createOvermind(config, {
  devtools: 'localhost:3031'
})
```

For default port (3031), you can simply use:

```javascript
const overmind = createOvermind(config, {
  devtools: true
})
```

### DevTools Features

The Overmind DevTools provide several powerful features organized into tabs:

#### 1. State Tab

- View and inspect your entire application state
- Expand/collapse nested objects and arrays
- Edit values directly in the DevTools

#### 2. Actions Tab

- See all executed actions in chronological order
- Inspect payloads, mutations, and effects for each action
- Review sequences of operations within actions
- Execute actions directly from the DevTools
- Try different payloads without modifying application code

#### 3. Transitions Tab

- Track state machine transitions in your application
- View transition history with from/to states and event types
- Inspect payloads associated with transitions
- Select between different state machines

#### 4. Charts Tab (optional)

- Visualize state charts defined in your application
- The tab is only available if the app is using `overmind-statechart`

#### 5. Components Tab

- Track React components using Overmind state
- Monitor component update counts and path dependencies
- Identify performance bottlenecks from unnecessary renders

#### 6. History Tab

- See a chronological history of mutations, flushes, and effects
- Track how state changes over time

#### 7. Flushes Tab

- Track state mutations and their effects on components
- See which components updated after each state change

#### 8. Console Tab (Development only)

- Debug internal DevTools messages and state
- Only available in development mode

#### Removing features

The `Charts`, `Transitions`, `Components` and `Flushes` tabs are optional and
can be removed by setting the feature to `false` when initializing the DevTools.
You can also remove the `Run Actions` tool if you don't want to allow executing
actions from the DevTools `Actions` tab.

```javascript
if (this.devtools) {
  this.devtools.send({
    type: 'init', // or 're_init'
    data: {
      state: this.state,
      features: {
        charts: false,
        transitions: false,
        components: false,
        flushes: false,
        runActions: false
      }
    }
  })
}
```

This can be useful if you want to integrate the DevTools in a different state management library than Overmind.

### Changing the Port

You can use a custom port for the WebSocket server by setting the `OV_DEV_PORT` environment variable:

```bash
# Start both the WebSocket server and web client on port 3033
OV_DEV_PORT=3033 npm start
```

This will:

1. Start the WebSocket server on port 3033
2. Configure the web client to automatically connect to port 3033

Then connect your app to that same port:

```javascript
// In your application
const overmind = createOvermind(config, {
  devtools: 'localhost:3033'
})
```

The port is displayed in the DevTools UI, under the "Devtool port" section in the runtime configuration panel.

### Troubleshooting

If you're having connection issues:

1. **Cannot connect to WebSocket server**
   - Check if the server is running (you should see "Overmind DevTools WebSocket server running on port 3031" in the console)
   - Verify no other application is using the port
   - Try specifying a different port using the OV_DEV_PORT environment variable

2. **No data appears in DevTools**
   - Ensure your Overmind app is configured with the correct devtools option
   - Check browser console for any errors
   - Make sure the port in your app configuration matches the port used by the DevTools server

3. **Components not appearing**
   - Make sure you're using the overmind-react package correctly
   - Verify components are consuming state via useAppState()

4. **State machines not showing in Transitions tab**
   - Ensure you're using Overmind state machines properly
   - Check that state transitions are triggered in your application

## Local Development

You can open Chrome DevTools from the application menu: Select **Application > Open Chrome DevTools**.

**HINT**: you can also use the DevTools Electron app for local development by running [overmind-devtools](../overmind-devtools/README.md).