Documentazione React: come leggerla senza perdersi

“React docs” e “react documentation” portano allo stesso indirizzo, react.dev, la documentazione ufficiale divisa in guide, riferimento API e comunità.

Tre sezioni, tre usi

• Learn React: un percorso guidato che costruisce un gioco e spiega stato, effetti ed eventi dall'inizio.
• Reference: la firma di ogni hook e di ogni componente, con i casi limite dichiarati pagina per pagina.
• Community: conferenze, corsi e risorse esterne, senza garanzia di versione.

Prima controlla la versione

npm ls react react-dom
npm view react version

La documentazione su react.dev descrive la versione stabile più recente, oggi la 19. Se il progetto è fermo a una 17 o 18, alcune pagine parlano di API che non hai: per quelle versioni esiste la documentazione storica su legacy.reactjs.org, con licenza MIT per il codice e contenuti CC BY 4.0.

Come si legge una pagina di riferimento

Parti dalla firma: parametri, valori di ritorno e tipo. Poi leggi il riquadro delle trappole, che elenca gli errori frequenti meglio di qualsiasi tutorial. Solo dopo guarda gli esempi, e verifica se usano hook o API presenti nella tua versione. Le pagine di riferimento sono brevi proprio perché non raccontano un progetto completo.

Cosa la documentazione non dice

Non dice quanto pesa un componente nel tuo bundle, non dice se una libreria di terze parti è compatibile e non misura le prestazioni della tua pagina. La documentazione descrive il contratto delle API, non il comportamento del tuo prodotto: per i numeri servono una build misurata e un profilo del browser.

Un record vivo

Nel catalogo EneUI la documentazione diventa interfaccia: navigation-menu e sidebar sono componenti React su primitive Radix con licenza MIT. Per esplorare per categoria parti da 111.985 componenti.

La limitazione

Non esiste una documentazione versionata per ogni release: react.dev segue la versione stabile e le versioni vecchie restano su un sito separato, che non riceve aggiornamenti. In più i risultati di ricerca mescolano risposte di dieci anni fa a domande di oggi, quindi la data della risposta conta più del numero di voti.

Dove continuare

Scrivere documentazione per i propri componenti è in come documentare i componenti; il modello di distribuzione del codice è in che cos'è shadcn/ui; il confronto fra le primitive headless è in Radix, Base UI e React Aria.