Scelta dello stack: JavaScript modulare o TypeScript leggero

Lo stack tecnico di questo laboratorio deve aiutare a vedere l’architettura, non coprirla.

Per questo partiamo da strumenti semplici:

• browser;
• HTML essenziale;
• JavaScript modulare oppure TypeScript leggero;
• dati in memoria all’inizio;
• localStorage o JSON più avanti;
• test minimi sulle regole principali.

Non partiamo da un framework perché in questa fase sarebbe troppo facile nascondere i problemi. Un framework può essere utile, ma se non sai ancora separare regole, casi d’uso e persistenza, rischia di diventare solo un posto più grande in cui mescolare tutto.

Obiettivo della lezione

Alla fine devi saper spiegare:

• quale stack userai nel laboratorio;
• perché lo stack deve restare semplice;
• che cosa significa usare moduli JavaScript;
• quando TypeScript può aiutare;
• perché non partiamo subito da React, Vue, Svelte o Angular;
• perché localStorage non è il dominio del progetto;
• come documentare una scelta tecnica nel README.

La scelta dello stack non è una gara a usare lo strumento più potente. È una decisione didattica: scegliamo ciò che ci permette di studiare meglio le responsabilità del codice.

La scelta consigliata

Per la maggior parte delle classi, la scelta consigliata è:

JavaScript modulare + browser + server locale semplice

Con questa combinazione puoi:

• dividere il codice in file;
• usare import ed export;
• vedere subito il risultato nel browser;
• evitare configurazioni troppo pesanti;
• concentrarti su dominio, casi d’uso, UI e persistenza.

Un possibile punto di partenza è:

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

Non è ancora la struttura definitiva. È il punto minimo per iniziare a ragionare.

Perché JavaScript modulare

JavaScript modulare permette di dividere il codice in file separati.

Esempio:

// src/stati.js
export const StatoStrumento = {
  DISPONIBILE: "disponibile",
  IN_PRESTITO: "in_prestito",
  GUASTO: "guasto",
  IN_MANUTENZIONE: "in_manutenzione",
};

// src/main.js
import { StatoStrumento } from "./stati.js";

console.log(StatoStrumento.DISPONIBILE);

Questa divisione è importante perché ci obbliga a decidere che cosa vive in un file e che cosa vive in un altro.

Separare i file non basta per avere una buona architettura. Puoi avere dieci file e comunque responsabilità confuse. Però i moduli sono un primo passo concreto: rendono visibili le dipendenze.

Quando scrivi:

import { StatoStrumento } from "./stati.js";

stai dicendo che un file dipende da un altro. Nel corso impareremo a chiederci se quella dipendenza ha senso.

Attenzione ai moduli nel browser

Con type="module" il browser tratta il file JavaScript come modulo:

<script type="module" src="./src/main.js"></script>

In alcuni ambienti aprire direttamente index.html con doppio click può creare problemi con gli import. Se succede, non è un errore di architettura: è un dettaglio del browser.

Soluzioni semplici:

• usare l’estensione Live Server dell’editor;
• usare un piccolo server statico locale;
• usare un ambiente già predisposto dal docente.

L’importante è non trasformare questa difficoltà nel centro del corso. Il server locale serve solo ad aprire correttamente il progetto.

Quando usare TypeScript leggero

TypeScript può essere utile se la classe ha già basi solide di JavaScript.

In questo percorso può aiutare per:

• descrivere la forma di uno strumento;
• evitare stati scritti male;
• chiarire gli input dei casi d’uso;
• rendere più leggibili i DTO;
• rendere più sicuri alcuni refactoring.

Esempio:

type StatoStrumento =
  | "disponibile"
  | "in_prestito"
  | "guasto"
  | "in_manutenzione";

type Strumento = {
  id: string;
  nome: string;
  categoria: string;
  stato: StatoStrumento;
};

Questo codice dice una cosa utile:

uno strumento non può avere uno stato qualsiasi

Però TypeScript non sostituisce il ragionamento architetturale. Puoi scrivere codice confuso anche con tipi perfetti. Se TypeScript rallenta troppo la classe, usa JavaScript modulare. Le idee principali del corso restano le stesse.

Perché non partiamo da un framework

Framework come React, Vue, Svelte o Angular sono strumenti validi. Qui però non sono necessari all’inizio.

Il rischio è che lo studente confonda:

• componente UI con caso d’uso;
• stato del componente con modello di dominio;
• chiamata a localStorage con logica applicativa;
• struttura del framework con architettura del progetto.

Esempio di confusione:

Ho messo la regola nel componente perché il pulsante è lì.

Questo ragionamento sembra pratico, ma è fragile. Il pulsante è solo un modo per attivare l’azione. La regola deve valere anche se l’azione viene attivata da un test, da una CLI o da una futura API.

Quando il progetto sarà più chiaro, potrai immaginare una UI costruita con un framework. Ma dominio e casi d’uso dovrebbero poter restare quasi uguali.

Browser, memoria e localStorage

Il browser è sufficiente per costruire una prima applicazione:

• mostra una lista;
• gestisce input utente;
• reagisce ai click;
• permette di usare DevTools;
• offre localStorage per salvare dati semplici.

All’inizio useremo dati in memoria:

const strumenti = [];

Questo significa che i dati spariscono quando ricarichi la pagina. Va bene così: nelle prime lezioni vogliamo concentrarci su responsabilità, regole e casi d’uso.

Più avanti useremo localStorage.

localStorage non è un database. È un archivio semplice integrato nel browser. Lo useremo per imparare un concetto più importante:

il modo in cui salvo i dati deve essere sostituibile

Se il dominio dipende da localStorage, abbiamo sbagliato confine. Il dominio deve parlare di strumenti, prestiti, stati e regole, non di API del browser.

Opzione A: JavaScript modulare

Usa questa opzione se vuoi partire subito senza configurazioni pesanti.

Struttura minima:

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

Vantaggi:

• immediata;
• adatta a principianti;
• poca configurazione;
• ottima per vedere import, export e responsabilità.

Limiti:

• meno controllo sui tipi;
• alcuni errori emergono solo durante l’esecuzione;
• serve disciplina sui nomi e sugli stati.

Questa è l’opzione consigliata se la classe deve concentrarsi soprattutto sul ragionamento.

Opzione B: TypeScript leggero

Usa questa opzione se la classe ha già un ambiente pronto o se il docente vuole lavorare anche sulla forma dei dati.

Struttura minima:

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

Vantaggi:

• stati e strutture dati più chiari;
• refactoring più sicuro;
• errori rilevati prima;
• input e output dei casi d’uso più espliciti.

Limiti:

• richiede configurazione;
• può spostare l’attenzione sul tooling;
• non è necessario per capire l’architettura di base.

La regola pratica è questa:

se il tooling occupa più tempo del problema, lo stack è troppo pesante per questa fase

Decisione tecnica da scrivere

Nel README aggiungi una sezione:

## Scelta dello stack

Scrivi una decisione breve:

## Scelta dello stack

Per iniziare useremo JavaScript modulare nel browser, senza framework.
Questa scelta ci permette di concentrarci sulla separazione delle responsabilità:
interfaccia, casi d'uso, dominio e salvataggio dati.

Useremo dati in memoria nelle prime lezioni e localStorage in una fase successiva.
Non introduciamo un database perché ora il problema principale non è salvare molti
dati, ma capire dove mettere il codice.

Questa sezione non deve essere lunga. Deve spiegare il perché.

Spiegazione guidata per studiare

Questa lezione va studiata come una decisione tecnica.

Una decisione tecnica non dice solo “useremo JavaScript”. Dice anche:

• perché lo useremo;
• quale problema risolve;
• quali alternative abbiamo escluso;
• quali limiti accettiamo.

Nel corso useremo spesso questa forma di ragionamento. Non basta scegliere uno strumento perché è famoso. Dobbiamo capire se aiuta il progetto in questo momento.

In questa fase lo strumento giusto è quello che lascia visibili i confini. Se un framework crea subito componenti, routing, stato globale e build complessa, rischia di spostare l’attenzione. Non perché sia sbagliato in assoluto, ma perché non è ciò che dobbiamo studiare adesso.

Esempio di ragionamento

Confronta queste due frasi:

Usiamo JavaScript perché è più facile.

Usiamo JavaScript modulare perché ci permette di dividere il codice in file,
vedere le dipendenze e concentrarci sulle responsabilità senza introdurre
un framework.

La seconda frase è migliore. Non si limita a nominare uno strumento: collega la scelta all’obiettivo del percorso.

Questa è una piccola decisione architetturale. Non riguarda solo la tecnologia, ma anche il modo in cui vogliamo imparare.

Micro-sfida

Scegli tra JavaScript modulare e TypeScript leggero.

Poi completa questa frase nel README:

Abbiamo scelto ________ perché ________.
Non useremo ancora ________ perché ________.

Esempio:

Abbiamo scelto JavaScript modulare perché la classe può partire subito senza
configurazione pesante. Non useremo ancora React perché vogliamo vedere
chiaramente dove stanno regole, casi d'uso e persistenza.

Prodotto da consegnare

Alla fine della lezione devi mostrare:

• la sezione Scelta dello stack nel README;
• la scelta tra JavaScript modulare e TypeScript leggero;
• una motivazione chiara della scelta;
• almeno un esempio di export;
• almeno un esempio di import;
• una frase che spieghi perché non introduciamo ancora framework.

Il prodotto non è un’applicazione più ricca. È una scelta tecnica scritta bene e coerente con il corso.

Domande di comprensione

Rispondi per iscritto:

• Perché lo stack deve aiutare a vedere l’architettura?
• Qual è il vantaggio principale di import ed export?
• Perché un framework può confondere le responsabilità all’inizio?
• Perché localStorage non appartiene al dominio?
• Quando TypeScript può essere utile?
• Quando invece può diventare un ostacolo?

Le risposte devono collegare la tecnologia al progetto del Registro.

Controllo finale

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

• ho scelto JavaScript modulare o TypeScript leggero;
• so spiegare perché non introduciamo subito un framework;
• so che localStorage non è il dominio;
• ho scritto la scelta dello stack nel README;
• so creare almeno un file con export e un file con import;
• ho capito che lo stack deve servire il percorso, non guidarlo.

Nel prossimo passo organizzeremo cartelle e file iniziali. Anche lì la regola sarà la stessa: abbastanza struttura da orientarsi, non così tanta da diventare decorazione.