Checklist ambiente: browser, editor, Git e localStorage

Prima di scrivere altro codice, conviene controllare l’ambiente.

Molti problemi nei laboratori non dipendono dall’architettura. Dipendono da dettagli pratici:

• il file non viene caricato;
• il browser blocca gli import JavaScript;
• la console mostra errori che nessuno legge;
• localStorage contiene dati vecchi;
• Git non è stato inizializzato;
• non esiste un punto funzionante a cui tornare.

Questa lezione serve a togliere attrito. Se l’ambiente è stabile, possiamo concentrarci sul problema vero: costruire un programma che funziona, osservarne la fragilità e poi migliorarlo.

Obiettivo della lezione

Alla fine devi saper:

• aprire il progetto nel browser;
• usare un server locale se gli import non funzionano;
• aprire DevTools e leggere la console;
• riconoscere errori comuni di caricamento;
• controllare localStorage;
• cancellare dati di test quando serve;
• aprire l’intera cartella nell’editor;
• fare un salvataggio iniziale con Git, se la classe lo usa;
• aggiornare il README con il metodo di avvio verificato.

Non serve diventare esperti di strumenti. Serve non restare bloccati su problemi evitabili.

Perché questa lezione conta

L’architettura non vive solo nei diagrammi. Vive anche nel modo in cui osservi il sistema.

Se la pagina è bianca e tu non apri la console, stai lavorando alla cieca. Se il codice non cambia perché stai leggendo dati vecchi da localStorage, potresti perdere mezz’ora a cercare un bug che non è nel codice. Se fai un refactoring senza salvare una versione funzionante, ogni errore diventa più costoso.

Questa checklist non è burocrazia. È una cintura di sicurezza per il laboratorio.

Browser e DevTools

Usa un browser moderno: Chrome, Edge, Firefox o Safari aggiornato.

Apri DevTools:

• tasto destro sulla pagina;
• Ispeziona;
• tab Console.

La console è il primo posto da guardare quando qualcosa non funziona.

Esempi di errori realistici:

Uncaught TypeError: Cannot read properties of null

oppure:

Failed to load module script

oppure:

The requested module './datiIniziali.js' does not provide an export named 'strumenti'

Non ignorare questi messaggi. Leggili con tre domande:

• quale file viene indicato?
• quale riga viene segnalata?
• l’errore riguarda HTML, import, dati o logica?

Imparare a leggere la console fa parte del lavoro architetturale: se non sai osservare il sistema, non puoi migliorarlo.

Aprire il progetto

Con JavaScript modulare, l’apertura diretta di index.html può funzionare in alcuni ambienti e creare problemi in altri.

Se vedi errori sugli import, usa un server locale.

Opzione semplice con Python:

python3 -m http.server 5173

Poi apri:

http://localhost:5173

Se hai già Node installato puoi usare un server statico equivalente, ma non introdurre un framework solo per servire una pagina.

Nel README scrivi il metodo che userai davvero in classe:

## Come si avvia

Dalla cartella del progetto:

```bash
python3 -m http.server 5173
```

Aprire `http://localhost:5173`.

Attenzione: se inserisci un esempio Markdown che contiene blocchi di codice, usa fence a quattro backtick nel README completo. In questa fase basta che il comando sia chiaro e verificato.

Editor

Apri la cartella del progetto nell’editor, non solo un singolo file.

Questo ti permette di vedere:

• struttura delle cartelle;
• file modificati;
• percorsi degli import;
• eventuali errori di sintassi;
• ricerca globale nel progetto;
• differenze rispetto all’ultima versione salvata.

Abituati a cercare parole precise:

• stato;
• prestito;
• localStorage;
• render;
• strumento;
• datiIniziali.

La ricerca è uno strumento di comprensione. Quando il progetto crescerà, non potrai orientarti solo ricordando dove hai scritto ogni pezzo.

File che devono esistere

Controlla che la struttura sia questa:

registro-laboratorio/
  README.md
  index.html
  src/
    main.js
    datiIniziali.js

Controlla anche che l’import in main.js sia coerente:

import { strumentiIniziali } from "./datiIniziali.js";

Il browser non corregge i nomi al posto tuo.

Se il file si chiama dati-iniziali.js, l’import deve usare ./dati-iniziali.js. Se il file esporta strumentiIniziali, non puoi importare strumenti senza rinominare correttamente.

Verifica minima della pagina

Prima di andare avanti, fai questa prova:

1. avvia o apri il progetto;
2. apri DevTools;
3. verifica che la console non mostri errori;
4. cambia il nome di uno strumento in src/datiIniziali.js;
5. ricarica la pagina;
6. controlla che il nuovo nome compaia.

Questa prova dice una cosa semplice: il browser sta caricando i file giusti.

Se il cambiamento non compare, non passare oltre. Controlla:

• stai modificando il file corretto?
• hai salvato il file?
• la pagina è stata ricaricata?
• c’è un errore in console?
• stai aprendo l’indirizzo giusto?

Git minimo

Git non è obbligatorio per capire l’architettura, ma è molto consigliato.

Inizializza il repository:

git init

Controlla lo stato:

git status

Fai un primo commit quando il progetto si avvia:

git add .
git commit -m "Avvia registro laboratorio"

Il commit non è un rito. È un punto a cui puoi tornare.

Nel corso faremo refactoring: cambieremo la struttura del codice senza voler cambiare il comportamento. Avere una versione funzionante salvata rende il refactoring meno rischioso.

Se la classe non usa Git, concorda almeno una regola:

prima di un refactoring importante si salva una copia funzionante del progetto

Non è elegante come Git, ma l’idea didattica resta: proteggere un punto stabile prima di cambiare struttura.

localStorage

localStorage è uno spazio di salvataggio nel browser. Lo useremo più avanti per sostituire la persistenza in memoria.

Per ora non devi ancora usarlo nel progetto. Devi solo sapere dove si trova e come controllarlo.

Apri DevTools e cerca:

• Application in Chrome o Edge;
• Storage in Firefox;
• sezione localStorage;
• origine del sito, per esempio http://localhost:5173.

Prova dalla console:

localStorage.setItem("registro-demo", "ciao");
localStorage.getItem("registro-demo");
localStorage.removeItem("registro-demo");

Questa non è ancora persistenza del Registro. È solo una verifica dello strumento.

Attenzione ai dati vecchi

Quando useremo localStorage, potrà succedere questo:

• modifichi i dati iniziali;
• ricarichi la pagina;
• la pagina sembra non cambiare;
• in realtà sta leggendo dati salvati in precedenza.

Per questo devi imparare a cancellare i dati di test.

Dalla console:

localStorage.clear();

Usalo con attenzione: cancella tutti i dati salvati per quell’origine.

Nel progetto finale non useremo clear() come soluzione normale. Qui serve solo per gestire l’ambiente di laboratorio.

Diagnosi rapida degli errori comuni

Sintomo	Possibile causa	Primo controllo
Pagina bianca	errore JavaScript	apri la Console
Import non trovato	percorso sbagliato	controlla nome file e maiuscole
Modulo bloccato	apertura da file locale	usa un server locale
Dati non aggiornati	dati vecchi in localStorage	controlla DevTools Storage
Click che non funziona	selettore sbagliato	verifica querySelector
La lista non appare	elemento #app mancante	controlla index.html
Il commit fallisce	Git non configurato	leggi il messaggio del terminale

Questa tabella non risolve tutto, ma aiuta a non andare a caso.

Attività guidata

Esegui questi controlli in ordine:

1. apri il progetto nell’editor;
2. avvia il progetto nel browser;
3. apri DevTools;
4. verifica che la console non abbia errori;
5. modifica un nome in datiIniziali.js;
6. ricarica la pagina;
7. verifica che il cambiamento compaia;
8. prova a scrivere e leggere una chiave in localStorage;
9. rimuovi la chiave di prova;
10. se usi Git, crea un primo commit;
11. aggiorna il README con il metodo di avvio verificato.

Non saltare i passaggi. Questa lezione serve proprio a evitare problemi invisibili.

Micro-sfida

Rompi volontariamente un import.

Per esempio, cambia:

import { strumentiIniziali } from "./datiIniziali.js";

in:

import { strumentiIniziali } from "./dati.js";

Ricarica la pagina e leggi l’errore in console.

Poi ripristina l’import corretto.

Risultato atteso: sai riconoscere un errore di percorso e sai tornare a una versione funzionante.

Prodotto da ottenere

Alla fine della lezione devi avere:

• progetto aperto correttamente nell’editor;
• pagina avviata nel browser;
• DevTools aperti almeno una volta;
• console controllata;
• metodo di avvio scritto nel README;
• prova di modifica dati completata;
• prova minima di localStorage completata;
• primo commit o copia funzionante salvata.

Domande di comprensione

Rispondi per iscritto:

• Perché la console va controllata prima di cercare il problema a caso?
• Che differenza c’è tra aprire index.html direttamente e usare un server locale?
• Perché localStorage può mostrare dati vecchi?
• Perché un commit prima del refactoring è utile?
• Qual è il primo controllo da fare se una modifica ai dati non appare nella pagina?

Controllo finale

La lezione è completata quando puoi dire sì a queste domande:

• so aprire il progetto nel browser;
• so aprire DevTools e leggere la console;
• so usare un server locale se i moduli non vengono caricati;
• so dove controllare localStorage;
• so cancellare dati di test se necessario;
• so riconoscere un import sbagliato;
• ho scritto nel README come si avvia il progetto;
• ho salvato una versione funzionante, con Git o con una procedura concordata.

Nel prossimo modulo costruiremo intenzionalmente un programma fragile. Ora che l’ambiente è pronto, potremo concentrarci sul problema vero: il codice che cresce senza una separazione chiara delle responsabilità.