Una guida per creare una codebase scalabile e manutenibile
In un'applicazione React Native, organizzare la codebase è fondamentale per la manutenibilità e la scalabilità. Il modo in cui strutturi file e cartelle può influire molto sulla facilità con cui lavorerai sulla codebase in futuro.
Questo articolo esplora la struttura delle cartelle per funzionalità (feature based) per un'applicazione React Native e lo scopo di ogni cartella.
La cartella src
La cartella src è la directory radice di tutto il codice sorgente dell'applicazione. Al suo interno trovi diverse sottocartelle, ognuna con uno scopo specifico.
Types
Nella cartella types definisci i tipi globali dell'applicazione. Questo include i tipi dei moduli, le definizioni delle interfacce e qualsiasi altro tipo personalizzato che ti serve in tutta l'applicazione.
Avere un posto centrale per tutti i tipi rende più facile gestirli e mantenerli man mano che l'applicazione cresce. Inoltre garantisce che i tipi siano usati in modo coerente in tutte le funzionalità, riducendo il rischio di bug legati ai tipi e rendendo più facile individuarli quando capitano.
Lib
Nella cartella lib puoi tenere i file specifici dell'applicazione usati globalmente in tutta l'app. Per esempio l'istanza di axios per le chiamate API, i servizi di gestione degli errori, le costanti, la configurazione del query client di react-query e così via.
Tenere questi file in un posto centralizzato li rende più facili da mantenere e garantisce che siano coerenti in tutta l'applicazione.
Components
Nella cartella components tieni tutti i componenti riutilizzabili. Questi componenti devono essere isolati e non legati a una funzionalità o a un dominio in particolare. Esempi di questo tipo di componenti sono header, pulsanti ed elementi di lista.
Tenerli separati dai componenti specifici delle funzionalità rende più facile gestirli e riutilizzarli in tutta l'applicazione e riduce la duplicazione nel codice.
Hooks
Nella cartella hooks tieni gli hook personalizzati usati in tutta l'applicazione. Un hook è un tipo speciale di funzione in React che permette di riutilizzare logica con state tra i componenti.
Avere tutti gli hook personalizzati **riutilizzabili o usati in più punti **in un posto centralizzato rende più facile gestirli e mantenerli, oltre a ridurre il rischio di duplicazione del codice e a rendere più facile condividere gli hook tra diverse parti dell'applicazione.
Localization
Nella cartella localization tieni tutti i file legati all'internazionalizzazione dell'applicazione. Questo include i file delle lingue, le costanti di stringa e qualsiasi altra risorsa necessaria per supportare più lingue nell'applicazione.
Avere questi file in un posto centralizzato rende più facile gestirli e mantenerli, oltre a ridurre il rischio di duplicazione del codice e a rendere più semplice supportare più lingue nell'applicazione.
Navigation
Nella cartella navigation tieni tutto il codice legato alla navigazione dell'applicazione. Questo include gli stack, i tipi, le route e qualsiasi altro componente o funzione necessario per la navigazione.
Avere tutto il codice di navigazione in un posto centralizzato rende più facile gestirlo e mantenerlo, oltre a ridurre il rischio di duplicazione del codice e a rendere più facile condividere le funzioni di navigazione tra diverse parti dell'applicazione.
Services
Nella cartella services tieni tutto il codice legato all'infrastruttura sottostante dell'applicazione. Questo include il codice per le notifiche push, il monitoraggio degli errori e qualsiasi altro servizio che fornisce le funzioni di base dell'applicazione.
Theme
Nella cartella theme conviene mettere gli stili dell'app, per esempio il tema scuro/chiaro. Tenere gli stili e i file del tema in un unico posto rende più facile gestire e aggiornare l'aspetto dell'app quando serve.
Utils
Le funzioni di utilità possono essere una parte importante della tua applicazione React Native, perché permettono di riutilizzare codice in più parti dell'applicazione. La cartella utils è un ottimo posto dove tenere le funzioni di utilità usate in tutta l'applicazione. Centralizzandole in un unico posto, sono facili da trovare e da usare in altre parti del codice. Per esempio: funzioni di utilità legate al layout di react-native.
Features
Quando si costruiscono applicazioni complesse, è essenziale avere una struttura delle cartelle chiara e concisa che racchiuda tutto il codice in un unico posto. Una cartella features aiuta a ottenerlo, perché separa le diverse funzionalità dell'applicazione in categorie distinte. Così gli sviluppatori possono trovare in fretta una funzionalità specifica e modificarla senza toccare altre parti dell'applicazione.
Inoltre, man mano che l'applicazione cresce e si aggiungono funzionalità, la struttura delle cartelle resta ordinata, e per i nuovi sviluppatori è più facile entrare nel progetto e capire come funziona l'applicazione. La netta separazione delle responsabilità aiuta anche a ridurre il rischio di bug e migliora le prestazioni complessive dell'applicazione.
Ecco come potrebbe essere una cartella auth:
src/
├── ...
└── features/
├── auth/
| ├── api/
| ├── helpers/
| ├── hooks/
| ├── screens/
| ├── services/
| └── store/
└── ... (other features)
L'importanza della cartella features sta nella sua capacità di dividere la codebase in parti più piccole e più gestibili. Ogni funzionalità ha le sue sottocartelle specifiche, come api, helpers (o utils), hooks, screens, services e store. Così è più facile capire come funziona ogni funzionalità e come interagiscono tra loro.
La cartella api contiene tutto il codice legato alle API specifico dell'autenticazione. Così è più facile gestire le chiamate API e tenerle in ordine.
La cartella helpers contiene metodi di supporto o funzioni di utilità specifici della funzionalità di autenticazione. Si possono usare solo all'interno della funzionalità di autenticazione e non devono essere condivisi con altre parti dell'applicazione.
La cartella hooks contiene gli hook legati specificamente all'autenticazione. Dato che React dipende molto dagli hook, questo rende più facile gestirli e tenerli in ordine.
La cartella screens contiene tutte le schermate della funzionalità di autenticazione. Tra le altre, la schermata di login, quella di registrazione e quella per la password dimenticata.
La cartella services contiene i servizi specifici della funzionalità di autenticazione. Per esempio, potresti avere un servizio di autenticazione che si occupa di gestire login e registrazioni degli utenti.
Infine, la cartella store contiene il codice di state management specifico della funzionalità di autenticazione. Può essere uno store Redux, uno store Zustand o qualsiasi altra libreria di state management tu preferisca.
Dividendo l'applicazione in parti più piccole e ordinate, diventa molto più facile gestire il codice e modificarlo quando serve. Aiuta anche a mantenere il codice pulito e leggibile, così è più facile per gli altri sviluppatori capirlo e lavorarci.
Esempio di struttura della cartella della funzionalità auth
src/
└── features/
└── auth/
├── api/
| ├── login.ts
| ├── signup.ts
| └── refresh-token.ts
├── helpers/
| ├── validateToken.ts
| └── dataTransformer.ts
├── screens/
| ├── Login.tsx
| └── Signup.tsx
├── services/
| └── validation.ts
└── store/
└── auth.ts
La cartella auth è la sottocartella dedicata alla funzionalità di autenticazione dell'applicazione. I file in questa cartella gestiscono tutto ciò che riguarda autenticazione e autorizzazione, dalle API di login e registrazione fino alle schermate con cui interagisce l'utente.
La cartella api contiene le API della funzionalità di autenticazione, come i file login.ts e signup.ts, che gestiscono richieste e risposte per il login e la registrazione dell'utente. Il file refresh-token.ts gestisce il rinnovo del token.
La cartella helpers contiene le funzioni di supporto usate nel processo di autenticazione. Per esempio, il file validateToken.ts serve a validare il token, e il file dataTransformer.ts trasforma i dati inviati alle API di autenticazione e ricevuti da esse.
La cartella screens contiene i componenti UI con cui interagisce l'utente. Per esempio, i file Login.tsx e Signup.tsx contengono i componenti UI con cui l'utente fa rispettivamente il login e la registrazione.
La cartella hooks contiene gli hook personalizzati legati all'autenticazione. Per esempio, i file useLoginAction.ts e useSignupForm.ts contengono hook che aiutano a gestire lo state e le azioni dei form di login e di registrazione, rispettivamente.
La cartella services contiene i servizi legati all'autenticazione, come il file validation.ts, che contiene le funzioni per validare l'input dell'utente.
La cartella store contiene lo state management legato all'autenticazione. Il file auth.ts contiene lo state e le azioni legati all'autenticazione, usando una libreria di state management come Zustand, Redux o un'altra.
ATTENZIONE
È importante notare che le convenzioni sui nomi di cartelle e file possono variare da progetto a progetto e da sviluppatore a sviluppatore. Quello che conta è la struttura e l'organizzazione delle cartelle, non i nomi esatti usati per ognuna. Per esempio, la cartella utils nella radice dell'app potrebbe chiamarsi anche helpers o utilities, oppure invece di screens si potrebbe usare pages o qualcos'altro che abbia senso per il progetto specifico. L'obiettivo è avere una struttura chiara e coerente che aiuti gli sviluppatori a capire l'organizzazione del codice e renda più facile mantenere e far crescere l'applicazione.
Struttura per tipo e struttura per funzionalità a confronto
Un altro metodo molto diffuso per organizzare la codebase di un progetto è la struttura delle cartelle per tipo, che ha i suoi pro e contro. Nella sezione seguente confrontiamo visivamente queste due strutture.
Confronto
Feature-based folder structure:
src/
└── features/
├── auth/
| ├── api/
| │ ├── register.tsx
| │ ├── login.tsx
| │ ├── types.tsx
| │ └── helpers.tsx
| ├── helpers/
| ├── hooks/
| └── screens/
| │ ├── LoginScreen.tsx
| │ ├── SignupScreen.tsx
| │ ├── WelcomeScreen.tsx
| │ └── HomeScreen.tsx
| ├── services/
| └── store/
├── todo/
| └── screens/
| │ └── TodoListScreen.tsx
| ├── services/
| └── store/
└── ... (other features)
Type-based folder structure:
src/
├── screens/
| ├── LoginScreen.tsx
| ├── SignupScreen.tsx
| ├── TodoListScreen.tsx
| ├── WelcomeScreen.tsx
| └── HomeScreen.tsx
├── api/
| └── auth/
| ├── register.ts
| ├── login.ts
| ├── types.ts
| └── helpers.ts
Come si vede qui sopra, nella struttura per tipo le schermate sono separate dalle chiamate API e dagli helper, e questo può rendere più difficile capire la codebase. Nota come, nella struttura per tipo, potremmo finire per mettere nella stessa cartella schermate che non c'entrano niente tra loro, come LoginScreen.tsx e TodoListScreen.tsx. Inoltre può rendere più difficile mantenere il codice, perché il codice correlato non è raggruppato in un unico posto. Nella struttura per funzionalità, invece, tutto il codice legato all'autenticazione, comprese schermate, chiamate API, helper e servizi, è raggruppato in un'unica cartella auth. Così è più facile capire la codebase, perché tutto il codice correlato si trova in un solo posto. Questo approccio permette un migliore incapsulamento del codice e rende il progetto scalabile e flessibile per i cambiamenti futuri.
Il quadro finale con una struttura per funzionalità
Ecco come apparirebbe alla fine la struttura per funzionalità, con file di esempio:
Feature-based folder structure:
src/
├── components/
│ ├── Button.tsx
│ └── Header.tsx
├── hooks/
│ └── useHeader.ts
├── localization/
│ ├── languages.ts
│ └── locales.ts
├── lib/
│ ├── axios-instance.ts
│ └── constants.ts
├── navigation/
│ ├── root-navigator.tsx
│ └── auth-stack.tsx
├── services/
│ ├── notification.ts
│ └── logging.ts
├── theme/
│ └── index.ts
├── types/
│ ├── env.d.ts
│ └── react-augment.d.ts
├── utils/
│ └── layout.ts
└── features/
├── auth/
│ ├── api/
│ │ ├── login.ts
│ │ ├── signup.ts
│ │ └── refresh-token.ts
│ ├── helpers/
│ │ ├── validateToken.ts
│ │ └── dataTransformer.ts
│ ├── hooks/
│ │ ├── useLoginAction.ts
│ │ └── useSignupForm.ts
│ ├── screens/
│ │ ├── Login.tsx
│ │ └── Signup.tsx
│ ├── services/
│ │ └── validation.ts
│ └── store/
│ └── auth.ts (zustand, redux, jotai etc.)
└── ... (other features)
I file aggiunti alle varie cartelle qui sopra (per esempio button.tsx e header.tsx nella cartella components, useHeader.ts nella cartella hooks, ecc.) servono solo da esempio e non vanno presi come accurati al 100%. Li ho inclusi per dare una rappresentazione visiva della struttura delle cartelle e aiutare a capire meglio l'organizzazione della codebase. L'implementazione reale può variare in base ai requisiti specifici del progetto. Questo articolo si concentra sulla struttura per funzionalità e su come può aiutare a costruire una codebase scalabile e ordinata, non sui dettagli dei singoli file.
Conclusione
Secondo me, la struttura delle cartelle per funzionalità è un approccio utile per organizzare progetti React/React Native. Dividendo il codice in funzionalità separate, trovo più facile mantenere, capire e sviluppare l'applicazione. Questa struttura permette un migliore incapsulamento del codice e rende il progetto scalabile e flessibile per i cambiamenti futuri. Certo, non è una soluzione valida per tutti, e la struttura esatta può variare in base alle dimensioni e alla complessità del progetto. L'idea chiave però è mantenere una separazione netta tra le diverse funzionalità e i rispettivi componenti, servizi e dati. Nella mia esperienza, questa struttura mi ha aiutato a costruire e mantenere progetti ben organizzati, in grado di reggere la crescita e i cambiamenti nel tempo. Volevo condividere questo approccio con chi potrebbe trovarlo utile a sua volta.
Pubblicato su
Questo articolo è pubblicato anche su: