overmind-devtools-client

Overmind DevTools Client

Introduction

There are three packages related to overmind-devtools experience:

• overmind-devtools-client - "core" package that provides UI ("web client")
• overmind-devtools - standalone, electron application
• 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.

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:

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

# Start both the WebSocket server and web client
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:

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:

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

4. Charts Tab

• Visualize state charts defined in your application

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

Changing the Port

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

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

This will:

• Start the WebSocket server on port 3033
• Configure the web client to automatically connect to port 3033

Then connect your app to that same port:

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

• 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

• 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

• Components not appearing

  • Make sure you're using the overmind-react package correctly
  • Verify components are consuming state via useAppState()

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

This package bundle (bundle.js) is further used by the companion "host" packages (mentioned before).

Hence, make sure you've built this package before developing the related packages.

HINT: you can also use the DevTools Electron app for local development by running overmind-devtools.