Using Refine Devtools

Refine Devtools is a powerful development tool that helps you debug, monitor, and optimize your Refine applications. It provides insights into queries, mutations, resource usage, and more.

Overview

Refine Devtools offers:

Query monitoring: Track all data fetching operations
Mutation tracking: Monitor create, update, and delete operations
Resource inspector: View registered resources and their configurations
Performance metrics: Analyze application performance
State inspection: Debug application state
Network activity: Monitor API calls and responses

Devtools only works in development mode and has no overhead on production builds. It’s automatically excluded from production bundles.

Installation

Install the devtools packages:

npm install @refinedev/devtools @refinedev/cli

Or use the CLI to initialize devtools:

npm run refine devtools init

This command will:

Install required packages
Add devtools components to your app
Configure the devtools server

Basic Setup

Wrap your application with DevtoolsProvider and add the DevtoolsPanel:

import { Refine } from "@refinedev/core";
import { DevtoolsProvider, DevtoolsPanel } from "@refinedev/devtools";

const App = () => {
  return (
    <DevtoolsProvider>
      <Refine
        dataProvider={dataProvider(API_URL)}
        resources={[
          {
            name: "posts",
            list: "/posts",
          },
        ]}
      >
        {/* Your app content */}
        <DevtoolsPanel />
      </Refine>
    </DevtoolsProvider>
  );
};

Features

Query Monitoring

The devtools automatically track all queries made through Refine hooks:

import { useList, useOne } from "@refinedev/core";

const PostList = () => {
  // These queries will appear in the devtools
  const { data: posts } = useList({ resource: "posts" });
  const { data: post } = useOne({ resource: "posts", id: 1 });
  
  // View in devtools:
  // - Query keys
  // - Cache status
  // - Data
  // - Loading states
  // - Error states
};

Mutation Tracking

Monitor all create, update, and delete operations:

import { useCreate, useUpdate, useDelete } from "@refinedev/core";

const PostForm = () => {
  const { mutate: create } = useCreate();
  const { mutate: update } = useUpdate();
  const { mutate: deleteOne } = useDelete();
  
  // All mutations are tracked in devtools with:
  // - Request payload
  // - Response data
  // - Status
  // - Timing information
};

Resource Inspector

View all registered resources and their configurations:

const resources = [
  {
    name: "posts",
    list: "/posts",
    create: "/posts/create",
    edit: "/posts/edit/:id",
    show: "/posts/show/:id",
    meta: {
      canDelete: true,
      label: "Blog Posts",
    },
  },
];

// Devtools will show:
// - Resource names
// - Available actions
// - Route configurations
// - Metadata

Performance Metrics

Analyze your application’s performance:

Query execution times
Mutation durations
Cache hit rates
Network request timings
Component render counts

Network Activity

Monitor all API calls:

// Devtools tracks:
// - Request URL
// - HTTP method
// - Request headers
// - Request body
// - Response status
// - Response data
// - Response time

Configuration

Custom Server URL

For dockerized apps or custom domains:

import { DevtoolsProvider } from "@refinedev/devtools";

const App = () => {
  return (
    <DevtoolsProvider url="http://custom-devtools-domain.com">
      <Refine>{/* ... */}</Refine>
    </DevtoolsProvider>
  );
};

Custom Port

Change the devtools server port:

# Using environment variable
REFINE_DEVTOOLS_PORT=5002 npm run dev

# Or in your CLI command
refine dev --devtools-port=5002

Docker Setup

When running your app and devtools in separate Docker containers:

# docker-compose.yml
version: "3.8"

services:
  app:
    build: ./app
    ports:
      - "3000:3000"
    environment:
      - REFINE_DEVTOOLS_URL=http://devtools:5001
    networks:
      - refine-network

  devtools:
    build: ./devtools
    ports:
      - "5001:5001"
    networks:
      - refine-network

networks:
  refine-network:
    driver: bridge

// app/App.tsx
import { DevtoolsProvider } from "@refinedev/devtools";

const App = () => {
  return (
    <DevtoolsProvider url="http://devtools.local">
      <Refine>{/* ... */}</Refine>
    </DevtoolsProvider>
  );
};

Update your /etc/hosts:

127.0.0.1 devtools.local
127.0.0.1 app.local

Using the Devtools Panel

Opening the Panel

The devtools panel can be opened by:

Clicking the floating devtools button (bottom-right corner)
Using the keyboard shortcut: Ctrl + Shift + D (Windows/Linux) or Cmd + Shift + D (Mac)

Panel Sections

Queries Tab

View all active queries:

Query key and identifier
Current status (loading, success, error)
Cached data
Last updated timestamp
Refetch button
Clear cache button

Mutations Tab

Track mutation operations:

Mutation type (create, update, delete)
Resource name
Request payload
Response data
Status and timing

Resources Tab

Inspect registered resources:

Resource name and identifier
Available actions (list, create, edit, show, delete)
Route paths
Metadata and options

Network Tab

Monitor network requests:

Request URL and method
Status code
Response time
Request/response headers
Payload and response body

Performance Tab

Analyze performance metrics:

Query execution times
Cache hit/miss ratios
Average response times
Slowest queries
Most frequent queries

Debugging with Devtools

Inspecting Query Data

Click on any query to view:

{
  queryKey: ["posts", "list", {...}],
  status: "success",
  data: [
    { id: 1, title: "Post 1" },
    { id: 2, title: "Post 2" },
  ],
  dataUpdatedAt: 1234567890,
  isFetching: false,
}

Manually Refetching Queries

Use the refetch button to manually trigger a query:

// Useful for testing:
// - Cache invalidation
// - Data freshness
// - Error scenarios

Clearing Cache

Clear specific query caches to test stale data handling:

// Clear individual query
// Clear all queries for a resource
// Clear entire cache

Mutation Replay

Replay mutations for debugging:

// Useful for:
// - Testing error handling
// - Verifying optimistic updates
// - Debugging side effects

Best Practices

Keep devtools open during development: Monitor queries and mutations in real-time
Check cache behavior: Ensure queries are cached appropriately
Monitor performance: Identify slow queries and optimize them
Test error scenarios: Use devtools to simulate and debug errors
Verify resource configuration: Check that resources are registered correctly
Review network activity: Ensure API calls are efficient
Use performance metrics: Identify bottlenecks and optimization opportunities

Troubleshooting

Devtools Not Appearing

Ensure DevtoolsProvider wraps your app
Check that DevtoolsPanel is rendered
Verify you’re in development mode
Check browser console for errors

Connection Issues

Verify the devtools server is running
Check the port configuration
Ensure no firewall is blocking the connection
Try accessing http://localhost:5001 directly

Performance Issues

The devtools can impact performance in apps with many queries
Consider disabling for specific performance testing
Use production build for accurate performance measurements

Docker/Network Issues

Verify network configuration in docker-compose
Check service names and ports
Ensure environment variables are set correctly
Test connectivity between containers

Enterprise Edition Features

The Enterprise Edition offers additional devtools features:

Custom port configuration: Use environment variables
Custom domain support: Run devtools on a separate domain
Advanced monitoring: Additional metrics and insights
Team collaboration: Share devtools sessions

Getting Started

Core Concepts

Guides

Advanced

Migration

​Overview

​Installation

​Basic Setup

​Features

​Query Monitoring

​Mutation Tracking

​Resource Inspector

​Performance Metrics

​Network Activity

​Configuration

​Custom Server URL

​Custom Port

​Docker Setup

​Using the Devtools Panel

​Opening the Panel

​Panel Sections

​Queries Tab

​Mutations Tab

​Resources Tab

​Network Tab

​Performance Tab

​Debugging with Devtools

​Inspecting Query Data

​Manually Refetching Queries

​Clearing Cache

​Mutation Replay

​Best Practices

​Troubleshooting

​Devtools Not Appearing

​Connection Issues

​Performance Issues

​Docker/Network Issues

​Enterprise Edition Features

​Further Reading

Build docs developers (and LLMs) love

Overview

Installation

Basic Setup

Features

Query Monitoring

Mutation Tracking

Resource Inspector

Performance Metrics

Network Activity

Configuration

Custom Server URL

Custom Port

Docker Setup

Using the Devtools Panel

Opening the Panel

Panel Sections

Queries Tab

Mutations Tab

Resources Tab

Network Tab

Performance Tab

Debugging with Devtools

Inspecting Query Data

Manually Refetching Queries

Clearing Cache

Mutation Replay

Best Practices

Troubleshooting

Devtools Not Appearing

Connection Issues

Performance Issues

Docker/Network Issues

Enterprise Edition Features

Further Reading