DevTools

Installazione

I DevTools sono un pacchetto separato:

npm install @tanstack/react-query-devtools

Setup

Aggiungi il componente ReactQueryDevtools nel tree della tua app, tipicamente accanto al QueryClientProvider:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <div>La tua app qui</div>
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

I DevTools vengono automaticamente esclusi dalla build di produzione tramite tree-shaking: non devi preoccuparti di rimuoverli manualmente.

Opzioni del Componente

<ReactQueryDevtools
  initialIsOpen={false}       // Parte chiuso
  buttonPosition="bottom-right" // Posizione del bottone: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
  position="bottom"            // Posizione del pannello: 'top' | 'bottom' | 'left' | 'right'
/>

Cosa Puoi Ispezionare

Lista delle Query

Il pannello principale mostra tutte le query nella cache con il loro stato:

• Fresh (verde) — I dati sono freschi e non necessitano di refetch
• Stale (giallo) — I dati sono obsoleti e verranno refetchati al prossimo trigger
• Fetching (blu) — La query sta caricando dati
• Paused (grigio) — La query è in pausa (es. offline)
• Inactive (grigio scuro) — La query non ha più observer attivi

Dettaglio Query

Cliccando su una query puoi vedere:

• Query Key — La chiave completa della query
• Status — Stato corrente (loading, error, success)
• Data — I dati nella cache (visualizzabili in formato JSON)
• Last Updated — Timestamp dell’ultimo aggiornamento
• Observer Count — Quanti componenti stanno usando questa query
• staleTime / gcTime — Configurazione cache della query

Azioni Disponibili

Per ogni query puoi:

• Refetch — Forza un refetch manuale
• Invalidate — Invalida la query (la marca come stale)
• Reset — Resetta la query al suo stato iniziale
• Remove — Rimuovi la query dalla cache

DevTools Embedded

Se preferisci i DevTools integrati nella tua UI (senza il bottone floating):

import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools';

function DebugPanel() {
  return (
    <div style={{ height: '300px' }}>
      <ReactQueryDevtoolsPanel />
    </div>
  );
}

DevTools in Produzione

Se hai bisogno dei DevTools anche in produzione (es. per debug), puoi usare il lazy loading:

import React from 'react';

const ReactQueryDevtoolsProduction = React.lazy(() =>
  import('@tanstack/react-query-devtools/build/modern/production.js').then(
    (d) => ({ default: d.ReactQueryDevtools })
  )
);

function App() {
  const [showDevtools, setShowDevtools] = React.useState(false);

  React.useEffect(() => {
    // Attiva con: window.toggleDevtools()
    window.toggleDevtools = () => setShowDevtools((prev) => !prev);
  }, []);

  return (
    <QueryClientProvider client={queryClient}>
      <MyApp />
      <ReactQueryDevtools initialIsOpen />
      {showDevtools && (
        <React.Suspense fallback={null}>
          <ReactQueryDevtoolsProduction />
        </React.Suspense>
      )}
    </QueryClientProvider>
  );
}

Best Practice

1. Tieni i DevTools aperti durante lo sviluppo — ti aiutano a capire il ciclo di vita delle query
2. Monitora le query inactive — troppe query inactive possono indicare problemi di memoria
3. Controlla gli observer count — se è 0 ma la query è ancora attiva, potrebbe esserci un leak
4. Usa il refetch manuale per testare il comportamento di errore e retry
5. Non includere manualmente in produzione — il tree-shaking li rimuove automaticamente