📚 Documentazione del Progetto

Caricamento automatico dei settings
Protezione route con requireSettings (verifica autenticazione + presenza settings)
Type guards per validazione
Accesso ai settings nei componenti

react-compiler-verification.md

Guida alla verifica di React Compiler:

Cosa ottimizza React Compiler
Pagina di test interattiva (/test-compiler)
Test con React DevTools Profiler
Analisi del bundle compilato
Metriche di successo e troubleshooting
Best practices con React Compiler

modules.md

Sistema di gestione moduli ERP:

Sidebar con lista moduli
Route dinamica per caricamento moduli
Iframe integration
Encoding/decoding dei path
Apertura in nuova tab

useBroadcastChannel.md

Documentazione dell'hook useBroadcastChannel:

Come funziona BroadcastChannel API
Esempi pratici di utilizzo
Confronto con storage events
Best practices

Comunicazione Iframe - Topbar Menu:

Hook useTopbarMenu
Chiamate da iframe a parent per aggiornare il menu
Type declarations
Test e best practices

iframe-messages-communication.md

Comunicazione Iframe - Messages:

Hook useTopbarMessages
Store Zustand per persistenza stato
Gestione contatore messaggi non letti
Chiamate da iframe (readMessage, addMessage, setMessages)
Comportamento del modal automatico
Sincronizzazione cross-tab
Migrazione dal legacy Messages.js

Comunicazione Iframe - Navigation:

Hook useIframeNavigation
Navigazione dell'applicazione React dall'iframe
Chiamate da iframe per navigare (navigateTo)
Validazione e normalizzazione del path
Esempi di utilizzo e casi d'uso
Integrazione con React Router

iframe-toast-communication.md

Comunicazione Iframe - Toast:

Hook useToastBridge
Mostrare notifiche toast dall'iframe
Chiamate da iframe (show, success, info, warning, error, dismiss)
Varianti stilistiche dei toast
Esempi di utilizzo in PHP/JavaScript

error-boundary.md

Documentazione degli Error Boundary:

Come gestire gli errori a livello di route
Componente RouteErrorBoundary riutilizzabile
Errori HTTP (404, 401, 403, 500)
Personalizzazione e best practices

testing.md

Testing con Vitest:

Configurazione Vitest e React Testing Library
Test dei componenti
Test delle API
Coverage reports

zustand-migration.md (Archivio)

Migrazione a Zustand (storico):

Obiettivo della migrazione
File creati e modificati
Confronto prima/dopo
Benefici ottenuti

🚀 Inizio Rapido

Creare una Pagina Protetta con Data Fetching

Registra la route in app/routes.ts:
typescript
```
route("dashboard", "routes/dashboard.tsx")
```
1

Crea il file della route in app/routes/dashboard.tsx:

typescript

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

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

export default function Dashboard() {
    // ✅ TanStack Query - nessun useEffect/useRef necessario!
    const { data, isLoading } = useCompaniesList();

    return (
        <AuthenticatedLayout>
            <div>Dashboard con dati</div>
        </AuthenticatedLayout>
    );
}

Una riga per proteggere, nessun flash di contenuto, zero boilerplate per fetch!

🎯 Concetti Chiave

Autenticazione

Factory functions: createProtectedLoader() e createGuestLoader()
Protezione pre-render: clientLoader blocca PRIMA del render
Zero flash: Nessun contenuto non autorizzato visibile
Type-safe: TypeScript verifica tutto
Multi-tab sync: Funziona automaticamente

Data Fetching (TanStack Query)

✅ USA TanStack Query per chiamate API (raccomandato)
❌ NO useRef per fetch - TanStack Query de-duplica automaticamente
Cache automatica: 5 minuti default, configurabile
StrictMode safe: Gestione automatica doppi render in dev
Import diretti: NO barrel files (index.ts)

📁 Struttura del Progetto

app/
├── routes.ts                       # Configurazione route
├── lib/
│   ├── api.ts                      # Utility API (apiRequest, ApiError)
│   ├── query-client.ts             # QueryClient TanStack Query
│   └── auth/
│       ├── auth.ts                 # Servizio di autenticazione
│       └── loaders.ts              # Factory functions (createProtectedLoader, createGuestLoader)
├── store/
│   ├── auth/
│   │   └── auth.store.ts           # Zustand store autenticazione
│   ├── cart/
│   │   └── cart.store.ts           # Zustand store carrello
│   └── messages/
│       └── messages.store.ts       # Zustand store messaggi
├── api/
│   └── auth/
│       └── auth.api.ts             # Funzioni API autenticazione
├── schemas/
│   ├── api.schema.ts               # Schema base API
│   └── auth/
│       └── auth.schema.ts          # Schema autenticazione
├── hooks/
│   ├── api/
│   │   └── auth/
│   │       └── useAuthApi.ts       # TanStack Query hooks per autenticazione
│   ├── ui/
│   │   ├── useTopbarCart.ts        # Comunicazione carrello con iframe
│   │   └── useTopbarMessages.ts    # Comunicazione messaggi con iframe
│   ├── sync/
│   │   ├── useBroadcastChannel.ts  # Hook per sincronizzazione multi-tab
│   │   ├── useAuthSyncListener.ts  # Sync autenticazione tra tab
│   │   ├── useCartSyncListener.ts  # Sync carrello tra tab
│   │   └── useMessagesSyncListener.ts # Sync messaggi tra tab
│   └── iframe/
│       └── useIframeNavigation.ts  # Navigazione dall'iframe
├── components/
│   └── layout/
│       ├── authenticated-layout.tsx # Layout per pagine protette
│       ├── sidebar/                # Componenti sidebar
│       │   ├── app-sidebar.tsx
│       │   ├── nav-modules.tsx
│       │   └── nav-user.tsx
│       └── topbar/                 # Componenti topbar
│           ├── cart.tsx
│           ├── messages.tsx
│           └── nav-actions.tsx
└── routes/
    ├── auth/
    │   ├── login.tsx               # + createGuestLoader()
    │   └── companies.tsx           # + createProtectedLoader()
    ├── welcome.tsx                 # + createProtectedLoader({ loadSettings: true })
    └── r.$path.tsx                 # Route moduli con iframe

💡 Workflow Tipico

Pianifica - Decidi quali route servono
Registra - Aggiungile alla configurazione route in routes.ts
Proteggi - Aggiungi clientLoader dove necessario
Implementa - Scrivi il componente della pagina
Testa - Il sistema gestisce autenticazione e sincronizzazione

🔗 Collegamenti Utili

❓ FAQ

Q: Devo aggiungere codice di autenticazione nelle route? A: Solo una riga: export const clientLoader = createProtectedLoader();

Q: Come faccio a sapere quali route sono protette? A: Cerca createProtectedLoader() nei file delle route.

Q: Funziona la sincronizzazione tra tab? A: Sì, automaticamente tramite AuthSyncListener.

Q: Posso avere route accessibili a tutti? A: Sì, semplicemente non aggiungere clientLoader.

📚 Documentazione del Progetto

🎯 BEST PRACTICES ⭐

📖 Contenuti

Autenticazione

quick-start.md

📡 TanStack Query (Data Fetching)

tanstack-query-guide.md

zustand-auth.md

user-settings.md

react-compiler-verification.md

modules.md

useBroadcastChannel.md

iframe-topbar-communication.md

iframe-messages-communication.md

iframe-navigation.md

iframe-toast-communication.md

error-boundary.md

testing.md

zustand-migration.md (Archivio)

🚀 Inizio Rapido

Creare una Pagina Protetta con Data Fetching

🎯 Concetti Chiave

Autenticazione

Data Fetching (TanStack Query)

📁 Struttura del Progetto

💡 Workflow Tipico

🔗 Collegamenti Utili

❓ FAQ

📚 Documentazione del Progetto ​

🎯 BEST PRACTICES ⭐ ​

📖 Contenuti ​

📡 TanStack Query (Data Fetching) ​

zustand-migration.md (Archivio) ​

🚀 Inizio Rapido ​

Creare una Pagina Protetta con Data Fetching ​

🎯 Concetti Chiave ​

Autenticazione ​

Data Fetching (TanStack Query) ​

📁 Struttura del Progetto ​

💡 Workflow Tipico ​

🔗 Collegamenti Utili ​

❓ FAQ ​

📚 Documentazione del Progetto

🎯 BEST PRACTICES ⭐

📖 Contenuti

📡 TanStack Query (Data Fetching)

zustand-migration.md (Archivio)

🚀 Inizio Rapido

Creare una Pagina Protetta con Data Fetching

🎯 Concetti Chiave

Autenticazione

Data Fetching (TanStack Query)

📁 Struttura del Progetto

💡 Workflow Tipico

🔗 Collegamenti Utili

❓ FAQ