Abans d'escriure el primer component de TaskFlow necessites preparar l'entorn de treball: instal·lar les eines bàsiques, crear un projecte amb una estructura assenyada i comprovar que tot funciona servint una pàgina al navegador. Aquesta lliçó és purament pràctica i està pensada per a qui parteix de zero: al final tindràs una carpeta de projecte a punt, amb el paquet lit instal·lat, un servidor de desenvolupament funcionant i l'editor configurat per treballar còmodament amb plantilles de Lit.

1. Instal·lar Node.js
2. Crear el projecte amb Vite (plantilla de Lit)
3. Alternativa: npm init @open-wc
4. Instal·lar el paquet lit
5. Estructura de carpetes recomanada
6. Servir el projecte en local
7. Extensions d'editor útils
8. JavaScript o TypeScript: la decisió d'aquest curs

Lit en si mateix és una biblioteca que s'executa al navegador i no necessita cap entorn especial per funcionar. Tot i això, per al flux de treball modern de desenvolupament —gestionar dependències, aixecar un servidor de desenvolupament amb recàrrega automàtica, empaquetar el projecte— s'utilitza Node.js juntament amb el seu gestor de paquets, npm.

Passos:

1. Descarrega i instal·la la versió LTS (de suport prolongat) de Node.js des de nodejs.org. A Linux també pots usar el gestor de paquets de la teva distribució o un gestor de versions com nvm.
2. Comprova la instal·lació obrint un terminal i executant:

Hauries de veure dos números de versió. Per a aquest curs, qualsevol versió de Node.js 18 o superior és suficient, ja que és el mínim que exigeixen les eines modernes de l'ecosistema (Vite, Lit 3.x).

Vite és una eina de desenvolupament molt popular pel seu arrencada gairebé instantània i la seva recàrrega en calent. Porta plantilles oficials per a diversos ecosistemes, entre ells Lit.

Per crear un projecte nou anomenat taskflow:

L'assistent crearà una carpeta taskflow amb un projecte d'exemple ja configurat per treballar amb Lit. A continuació, entra a la carpeta i instal·la les dependències:

I arrenca el servidor de desenvolupament:

Vite mostrarà una URL local (normalment http://localhost:5173). En obrir-la al navegador veuràs el component d'exemple que porta la plantilla, amb recàrrega automàtica cada vegada que desis un canvi al codi.

Nota: la plantilla lit de Vite usa TypeScript per defecte. Existeix també una plantilla lit-ts explícita i, si prefereixes JavaScript pur, pots partir de la plantilla vanilla i afegir lit manualment (s'explica a l'apartat 4). Més endavant en aquesta mateixa lliçó es comenta com triar entre JavaScript i TypeScript per seguir el curs.

Una altra via, mantinguda per la comunitat d'Open Web Components (un conjunt d'eines i recomanacions específicament pensades per a Web Components, no només per a Lit), és l'assistent @open-wc:

Aquest assistent pregunta de manera interactiva què es vol generar (una aplicació, un component publicable com a paquet...), si es desitja usar TypeScript, i si es volen incloure eines de linting, testing o demostracions. És una opció una mica més completa i orientada a qui va a publicar components reutilitzables com a paquets independents, mentre que la plantilla de Vite és més directa per començar una aplicació com més aviat millor.

Per als propòsits d'aquest curs, qualsevol de les dues vies és vàlida; els exemples assumiran una estructura de projecte creada amb Vite, per ser la més estesa i senzilla d'arrencar.

Si partiixes d'una plantilla en blanc (per exemple, la plantilla vanilla de Vite) o simplement vols saber què passa "per sota", instal·lar Lit manualment és tan senzill com:

Això afegeix lit a les dependències del package.json del projecte. A partir d'aquí, en qualsevol fitxer JavaScript o TypeScript del projecte es pot importar el necessari:

No cal cap configuració addicional de bundler: lit es distribueix com a mòduls ES estàndard, compatibles amb Vite i amb qualsevol eina moderna d'empaquetat.

Un projecte de Lit no imposa una estructura de carpetes concreta —a diferència d'alguns frameworks més opinats—, però convé adoptar una organització clara des del principi, especialment perquè TaskFlow creixerà amb diversos components al llarg del curs. Una estructura recomanada per a aquest curs és:

Idees clau d'aquesta organització:

• Cada component viu al seu propi fitxer, amb un nom que coincideix amb el nom de l'etiqueta HTML que defineix (task-card.js defineix <task-card>).
• La carpeta components/ agrupa tots els Web Components de l'aplicació, separats de la lògica d'arrencada (main.js).
• A mesura que el curs avanci, aquesta estructura s'anirà ampliant (per exemple, amb una carpeta per a controladors reactius o per a proves), però la idea de "un component, un fitxer" es mantindrà durant tot el curs.

Durant el desenvolupament, els components de Lit s'executen directament al navegador, per la qual cosa n'hi ha prou amb un servidor que serveixi els fitxers estàtics del projecte. Ja s'ha vist que Vite ofereix això amb npm run dev, però convé entendre què fa exactament aquesta comanda:

• Arrenca un servidor HTTP local (no cal configurar Apache, Nginx ni res semblant).
• Serveix index.html i resol els mòduls ES (import ... from 'lit') al vol, sense necessitat de generar abans un bundle.
• Observa els canvis als fitxers del projecte i refresca automàticament el navegador (o fins i tot actualitza el mòdul concret sense recarregar tota la pàgina, gràcies al "Hot Module Replacement").

Per generar una versió optimitzada per a producció (minificada, amb els mòduls empaquetats), Vite ofereix també:

El resultat es genera en una carpeta dist/. El procés d'empaquetat per a producció, amb més detall sobre optimització i publicació, s'estudia al mòdul d'integració i desplegament; per ara n'hi ha prou de saber que existeix aquesta segona comanda.

Treballar amb les plantilles de Lit —blocs d'HTML incrustats dins de JavaScript mitjançant la funció html— és molt més còmode amb el suport adequat de l'editor. Si uses Visual Studio Code (l'editor més habitual a l'ecosistema), aquestes són les extensions recomanades:

lit-plugin es recolza internament en una eina anomenada lit-analyzer, que també existeix com a comanda de línia d'ordres i es pot integrar a la integració contínua per detectar errors a les plantilles (per exemple, atributs mal escrits) abans d'arribar a producció. Tornarem sobre eines de qualitat de codi al mòdul de proves i bones pràctiques.

Lit està escrit en TypeScript i ofereix una integració excel·lent amb ell (tipat de propietats, autocompletat de plantilles, decoradors amb tipus comprovats). Tot i això, TypeScript no és obligatori: Lit funciona igual de bé amb JavaScript pur.

Existeixen dues maneres habituals de declarar una classe de component a Lit:

• Amb decoradors (@customElement, @property, @state...): és la sintaxi més concisa i la que usa la documentació oficial per defecte. Els decoradors són una proposta de JavaScript que, a dia d'avui, requereix una eina de compilació que els suporti (TypeScript, o Babel amb el plugin corresponent en projectes JavaScript). Vite ja porta aquesta capacitat configurada a la seva plantilla de Lit.
• Sense decoradors, amb static properties: una forma alternativa, totalment equivalent en resultat, pensada per a projectes en JavaScript pla que no vulguin dependre d'un pas de compilació amb suport de decoradors. És més verbosa però no requereix cap configuració addicional.

Aquest curs usarà JavaScript, mostrant totes dues variants (decoradors i static properties) allà on tingui sentit comparar, perquè puguis triar la que millor s'ajusti als teus propis projectes. La primera vegada que aparegui aquesta disjuntiva amb detall serà a la propera lliçó, en construir el primer component real.

• Usar una versió antiga de Node.js: si npm create vite@latest falla amb errors estranys, el primer que cal comprovar és la versió de Node.js instal·lada. Actualitzar-la sol resoldre el problema.
• Oblidar npm install després de clonar o crear el projecte: sense aquest pas, el paquet lit (i la resta de dependències) no estaran disponibles i el projecte no arrencarà.
• Barrejar sintaxi de decoradors sense la configuració de compilació adequada: si es copien exemples amb @customElement en un projecte que no té configurat el suport de decoradors, apareixeran errors de sintaxi. La plantilla de Vite per a Lit ja ve preparada; si es parteix de zero convé comprovar-ho abans.
• Confondre el servidor de desenvolupament amb un servidor de producció: npm run dev no està pensat per servir trànsit real; per a producció es genera primer el build i es serveix el contingut estàtic resultant.

1. Instal·la Node.js si encara no el tens, i comprova les versions de node i npm des del terminal.
2. Crea un projecte nou anomenat taskflow fent servir la plantilla de Lit de Vite, instal·la les dependències i arrenca'l en mode desenvolupament. Comprova que el pots obrir al navegador.
3. Dins del projecte just creat, crea la carpeta src/components/ i un fitxer buit task-card.js dins seu, seguint l'estructura de carpetes recomanada en aquesta lliçó.

1. La comprovació es fa amb:

Si tots dos comandaments retornen un número de versió (per exemple v20.11.0 i 10.2.4), la instal·lació és correcta.

Després de l'últim comandament, el terminal mostrarà una URL local (per exemple http://localhost:5173); en obrir-la al navegador s'ha de veure la pàgina d'exemple de la plantilla de Lit.

A Windows, sense touch disponible per defecte, n'hi ha prou de crear el fitxer buit des de l'editor de codi desant-lo en aquesta ruta.

En aquesta lliçó has preparat tot el terreny necessari per començar a programar: Node.js instal·lat, un projecte TaskFlow creat amb Vite (o alternativament amb @open-wc), el paquet lit disponible, una estructura de carpetes pensada per créixer i un editor configurat amb suport específic per a les plantilles de Lit. També has vist que aquest curs usarà JavaScript, alternant entre la sintaxi de decoradors i static properties segons convingui.

Amb l'entorn ja a punt, a la lliçó següent deixaràs de configurar i començaràs a programar: crearàs el teu primer component Lit real i, amb ell, la primera versió —totalment estàtica— de <task-card>, la peça fonamental de TaskFlow.