🎯 Best Practices - Elerama Frontend

Questo documento raccoglie tutte le best practices aggiornate del progetto.

---

📡 Data Fetching

✅ USA TanStack Query (Raccomandato)

Per tutte le chiamate API, usa TanStack Query:

// ✅ RACCOMANDATO - TanStack Query
import { useCompaniesList } from "@/hooks/api/auth/useAuthApi";

const { data, isLoading, error, refetch } = useCompaniesList();
// Nessun useEffect, nessun useRef necessario!
// Cache automatica (5 min), de-duplicazione, StrictMode safe

Vantaggi:

• ✅ Cache automatica (5 minuti default, configurabile)
• ✅ StrictMode safe - De-duplicazione automatica delle richieste
• ✅ Zero boilerplate - Nessun useEffect/useRef necessario
• ✅ Invalidazioni coordinate - Mutations aggiornano automaticamente le query correlate
• ✅ Override flessibile - Configurazione personalizzabile per ogni hook

❌ NON Usare useRef per Fetch

Con TanStack Query, NON serve più useRef per prevenire doppi fetch in StrictMode:

// ❌ VECCHIO - Pattern deprecato
const hasFetchedRef = useRef(false);

useEffect(() => {
    if (!hasFetchedRef.current) {
        hasFetchedRef.current = true;
        fetchData();
    }
}, []);

// ✅ NUOVO - TanStack Query gestisce tutto automaticamente
const { data } = useCompaniesList();

Quando usare useRef:

• ✅ BroadcastChannel (non-fetch use cases)
• ✅ Riferimenti DOM (const inputRef = useRef<HTMLInputElement>(null))
• ✅ Valori che non devono causare re-render
• ❌ MAI per prevenire doppi fetch con TanStack Query

📚 Documentazione TanStack Query

• Guida Completa - Documentazione dettagliata (configurazione, hooks, best practices, troubleshooting)

---

📦 Import Policy

❌ NO Barrel Files

NON creare mai file index.ts per re-export. Usa sempre import diretti:

// ✅ Corretto - Import diretto
import { useLogin } from "@/hooks/api/auth/useAuthApi";
import { authQueryKeys } from "@/hooks/api/auth/auth.query-keys";
import { invalidateAuthQueries } from "@/hooks/api/auth/auth.query-helpers";

// ❌ Sbagliato - Barrel file non esiste
import { useLogin } from "@/hooks/api/auth"; // ❌ No index.ts

Motivazione: Import diretti garantiscono:

• Tracciabilità del codice
• Chiarezza delle dipendenze
• Migliore tree-shaking
• Nessuna ambiguità

---

🔐 Route Protection

Protezione Base (Solo Autenticazione)

import { createProtectedLoader } from "@/lib/auth/loaders";

// ✅ Una riga per proteggere
export const clientLoader = createProtectedLoader();

export default function Dashboard() {
    return <div>Contenuto protetto</div>;
}

Protezione con Settings (Autenticazione + Dati Utente)

import { createProtectedLoader } from "@/lib/auth/loaders";

// ✅ Verifica autenticazione + presenza settings
// Se i settings non sono presenti, reindirizza a /welcome
export const clientLoader = createProtectedLoader({ requireSettings: true });

export default function Profile() {
    const userSettings = useAuthStore((state) => state.userSettings);
    // Qui sei sicuro che userSettings non è null
    return <div>Profilo</div>;
}

Route Guest-Only (Solo Non Autenticati)

import { createGuestLoader } from "@/lib/auth/loaders";

// ✅ Reindirizza utenti già autenticati
export const clientLoader = createGuestLoader();

export default function Login() {
    return <div>Login</div>;
}

Route Pubbliche (Accessibili a Tutti)

// ✅ Nessun clientLoader = accessibile a tutti
export default function About() {
    return <div>Chi Siamo</div>;
}

📚 Documentazione: Autenticazione

---

⚛️ React Compiler

Non Usare Memoizzazione di Default

React Compiler ottimizza automaticamente. NON usare useCallback, useMemo, React.memo di default:

// ❌ Non necessario - React Compiler ottimizza automaticamente
const handleClick = useCallback(() => {
    console.log("Clicked");
}, []);

// ✅ Lascia fare al Compiler
const handleClick = () => {
    console.log("Clicked");
};

Usa Memoizzazione SOLO Quando Necessario

USE ONLY when:

1. Funzioni usate come dipendenze di useEffect
2. Props passate a componenti third-party non compilati
3. Scenari critici identificati con profiling
4. Valori di Context che non devono causare re-render

// ✅ OK - useEffect dependency
const fetchData = useCallback(async () => {
    // API call
}, [dependency]);

useEffect(() => {
    fetchData();
}, [fetchData]);

📚 Documentazione: react-compiler-verification.md

---

🧪 Testing

Test con TanStack Query

Wrappa i test con QueryClientProvider:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { renderHook, waitFor } from "@testing-library/react";

test("useCompaniesList dovrebbe caricare le aziende", async () => {
    const queryClient = new QueryClient({
        defaultOptions: {
            queries: { retry: false },
        },
    });

    const { result } = renderHook(() => useCompaniesList(), {
        wrapper: ({ children }) => (
            <QueryClientProvider client={queryClient}>
                {children}
            </QueryClientProvider>
        ),
    });

    await waitFor(() => expect(result.current.isSuccess).toBe(true));
    expect(result.current.data).toBeDefined();
});

📚 Documentazione: testing.md

---

🎨 Component Patterns

Esempio Completo: Pagina con Data Fetching

import { createProtectedLoader } from "@/lib/auth/loaders";
import { AuthenticatedLayout } from "@/components/layout/authenticated-layout";
import { useCompaniesList } from "@/hooks/api/auth/useAuthApi";

// ✅ Protezione route
export const clientLoader = createProtectedLoader();

export default function Companies() {
    // ✅ TanStack Query - cache automatica
    const { data, isLoading, error, refetch } = useCompaniesList();

    if (isLoading) {
        return (
            <AuthenticatedLayout>
                <div>Caricamento...</div>
            </AuthenticatedLayout>
        );
    }

    if (error) {
        return (
            <AuthenticatedLayout>
                <div>
                    <p>Errore: {error.message}</p>
                    <button onClick={() => refetch()}>Riprova</button>
                </div>
            </AuthenticatedLayout>
        );
    }

    const companies = data?.data || [];

    return (
        <AuthenticatedLayout>
            <div className="p-8">
                <h1 className="text-3xl font-bold mb-4">Aziende</h1>
                <ul className="space-y-2">
                    {companies.map((company) => (
                        <li key={company.id} className="p-4 border rounded">
                            {company.name}
                        </li>
                    ))}
                </ul>
            </div>
        </AuthenticatedLayout>
    );
}

---

🔄 Sincronizzazione Multi-Tab

Zustand Persist (Storage Events)

Sincronizzazione automatica dello stato tra tab tramite localStorage:

import { useAuthStore } from "@/store/auth/auth.store";

// Accesso ottimizzato con selector
const isAuthenticated = useAuthStore((state) => state.isAuthenticated);
const userSettings = useAuthStore((state) => state.userSettings);

BroadcastChannel (Navigazione)

Per azioni che richiedono navigazione coordinata tra tab:

import { useBroadcastChannel } from "@/hooks/iframe/useBroadcastChannel";

const { sendMessage } = useBroadcastChannel("auth", (message) => {
    if (message.type === "logout") {
        navigate("/");
    }
});

// Logout con broadcast alle altre tab
const handleLogout = () => {
    authStore.getState().logout();
    sendMessage({ type: "logout" });
    navigate("/");
};

📚 Documentazione: useBroadcastChannel.md

---

📝 Documentation Policy

❌ NON Creare

• Documenti di riepilogo per bug fix
• Spiegazioni di singole modifiche
• Change logs manuali

✅ Aggiorna Sempre

• Documentazione esistente quando le feature cambiano
• Test quando il codice cambia
• README quando cambia la struttura del progetto

---

🚀 Quick Checklist

Quando crei una nuova feature:

• [ ] Route protection: Usa createProtectedLoader() se necessario
• [ ] Data fetching: Usa TanStack Query hooks
• [ ] NO useRef per fetch: TanStack Query gestisce StrictMode
• [ ] Import diretti: NO barrel files (index.ts)
• [ ] NO memoizzazione: Lascia fare a React Compiler (salvo casi specifici)
• [ ] Test coverage: Scrivi test con QueryClientProvider wrapper
• [ ] TypeScript strict: Tutti i tipi devono essere espliciti
• [ ] Update docs: Aggiorna documentazione esistente se necessario

---

📚 Link Utili

• Autenticazione
• TanStack Query Guide
• Quick Start Guide
• React Compiler Verification
• Testing Guide
• Zustand Store

---

Ultima revisione: 2025-11-10 Versione TanStack Query: v5.90.7 React: 19 React Router: 7.9