Escena Viva és ja 1.0.0, amb la seva etiqueta v1.0.0 a git, i el seu package.json està gairebé complet: nom, versió, main, engines, dependencies, devDependencies. Queda un buit, i és el que més es fa servir en el dia a dia: "scripts": { }. Aquest objecte buit és avui el motiu que, per arrencar el servidor, algú hagi de recordar node src/servidor/servidor.js; per llançar l'informe d'ocupació, node src/informes/ocupacio.js; i per a la canonada de vendes, una ruta que només coneix qui la va escriure.

En aquesta lliçó convertim scripts en la interfície única del projecte. Quan acabem, qualsevol persona que cloni el repositori podrà escriure npm run i veure la llista completa de coses que pot fer, sense obrir cap README ni preguntar a ningú. I de passada resoldrem la pregunta que va quedar pendent a la lliçó 05-02: per què "lint": "eslint src" funciona encara que no hagis instal·lat mai ESLint globalment.

1. Què és realment el camp scripts
2. Scripts predefinits davant de scripts personalitzats
3. Els scripts d'Escena Viva, un a un
4. El PATH estès: node_modules/.bin
5. Pas d'arguments amb --
6. Variables d'entorn dels scripts
7. Ganxos pre i post (i l'advertència de postinstall)
8. Encadenar ordres i sobreviure a Windows
9. ESLint i Prettier: què resol cadascun
10. Errors comuns i consells
11. Exercicis
12. Conclusió

scripts és un objecte on cada clau és un nom i cada valor és una línia de shell. Quan executes npm run <nom>, npm:

1. Busca la clau <nom> al package.json del directori actual.
2. Prepara un entorn especial (variables npm_* i un PATH ampliat, ja ho veurem).
3. Llança aquesta línia amb el shell del sistema (/bin/sh a POSIX, cmd.exe a Windows tret de configuració diferent).
4. Retorna el codi de sortida de l'ordre: 0 és èxit, qualsevol altre és fallada.

No hi ha màgia addicional. No és un llenguatge nou: és shell. El valuós no és el mecanisme, sinó la convenció: tothom espera trobar-hi les ordres del projecte.

npm reconeix un grapat de noms predefinits que es poden invocar sense la paraula run:

Tota la resta és personalitzat i exigeix npm run. És a dir: npm dev no existeix (npm intentarà interpretar-ho com una subordre seva i fallarà), cal escriure npm run dev.

Un detall històric que continua viu: si no defineixes start, npm busca server.js a l'arrel. Escena Viva té el seu servidor a src/servidor/servidor.js, així que el valor per defecte no ens serveix i l'hem de declarar explícitament. És el correcte de totes maneres: l'script explícit documenta el punt d'entrada.

Aquest és el package.json complet després d'aquesta lliçó:

Anem ordre a ordre.

Arrenca el servidor HTTP que vam construir al Mòdul 4. Coincideix amb el camp main, i això no és casualitat: main declara el punt d'entrada del paquet, start declara com s'executa el procés. Un servidor en producció s'aixeca amb npm start (o directament amb node, veges l'avís més avall).

--watch és un indicador natiu de Node (estable des de Node 22) que reinicia el procés quan canvia qualsevol fitxer del qual depengui el mòdul carregat. Durant anys això exigia instal·lar nodemon com a dependència de desenvolupament; avui no cal cap dependència externa, cosa que encaixa amb la filosofia d'Escena Viva: zero dependències allà on la plataforma ja serveix.

Diferències que convé conèixer:

Per al nostre cas, --watch sobra i basta. Si algun dia necessites vigilar també dades/esdeveniments.json, afegeix --watch-path=./dades.

La CLI del catàleg del Mòdul 1: imprimeix per stdout els tres esdeveniments amb les seves sessions. Posar-la a scripts la converteix en part de la interfície del projecte en comptes d'un fitxer solt que cal descobrir llegint l'arbre.

informe calcula l'ocupació (7 sessions, aforament 3000, 1811 venudes). vendes llança la canonada de streams que llegeix dades/vendes.csv i produeix l'agregat per sessió. Tots dos escriuen dades per stdout i diagnòstics per stderr, la convenció del curs, així que això continua funcionant:

El --silent és important aquí: sense ell, npm imprimeix dues línies de capçalera (> [email protected] informe i l'ordre) que s'esmunyirien dins del teu fitxer. npm les envia a stdout, no a stderr, així que si un script està pensat per redirigir-se, acostuma't a --silent (o la seva forma curta -s).

Aquesta és la promesa que vam fer a 05-02. ESLint no està instal·lat globalment i tanmateix l'script funcionarà tan bon punt afegeixis ESLint a devDependencies. L'explicació completa és a l'apartat 4.

--write reescriu els fitxers; --check només comprova i falla si alguna cosa no està formatada. El primer és per al desenvolupament, el segon per a la integració contínua, on mai no vols que una màquina modifiqui fitxers: vols que et digui que estan malament.

Fixa't en les cometes al voltant del patró. Sense elles, el shell POSIX expandiria src/**/*.js abans que Prettier el veiés, i el resultat dependria de la configuració de globstar del shell i del sistema operatiu. Amb cometes, el patró arriba intacte a Prettier, que l'expandeix ell mateix de forma idèntica a totes les plataformes. És un detall petit amb conseqüències reals.

Els dos punts de format:check no signifiquen res per a npm: és només una convenció visual per agrupar variants d'un mateix script. npm run format:check és un nom com qualsevol altre.

Un script de composició: no fa feina pròpia, encadena dos més. Aquest és el patró que convé interioritzar: scripts petits d'un sol propòsit, més scripts que els combinen. Si demà hi afegim comprovació de tipus, s'afegeix a la cadena sense tocar els altres.

Un test honest. Hi ha dues males alternatives:

• Deixar el test per defecte de npm (echo \"Error: no test specified\" && exit 1), que no diu res útil.
• Posar "test": "exit 0" perquè la CI passi en verd. Això és mentir: el semàfor verd deixa de significar alguna cosa.

El nostre script escriu el motiu per stderr i surt amb codi 1. La CI fallarà, que és exactament el que ha de passar en un projecte 1.0.0 sense proves, i el missatge diu on és la solució. Al Mòdul 9 aquest script passarà a ser node --test test/ i el vermell es tornarà verd amb raó.

Aquí hi ha la resposta promesa. Molts paquets declaren executables al seu propi package.json:

Quan npm instal·la un paquet amb camp bin, crea un enllaç a node_modules/.bin/. Després d'instal·lar Prettier, el projecte té:

I quan executes npm run <alguna-cosa>, npm anteposa aquest directori al PATH del procés fill. Pots comprovar-ho tu mateix:

Per això "format": "prettier --write ..." troba prettier sense instal·lació global i sense escriure ./node_modules/.bin/prettier. I per això "lint": "eslint src" funcionarà tan bon punt ESLint sigui a devDependencies.

Tres conseqüències pràctiques:

• La versió que s'executa és la del projecte, no la del sistema. Dos projectes amb Prettier 2 i Prettier 3 conviuen sense conflictes.
• No cal npx dins dels scripts. npx prettier funciona, però afegeix una resolució innecessària. Dins de scripts, escriu el binari a seques.
• Si una ordre falla amb command not found dins d'un script, gairebé sempre significa que falta el paquet a les dependències, no que falti una instal·lació global.

Això no fa el que sembla:

npm interpreta --sala com una opció seva (que no coneix) i no la passa a l'script. El separador -- marca la frontera:

Ara l'ordre executada és node src/cataleg.js --sala="Sala Boveda" i els arguments arriben a process.argv. Amb un script així:

El filtre funciona igual el llancis amb node directament o amb npm run ... --. Regla mnemotècnica: tot el que va abans de -- és per a npm; tot el que va després, per al teu programa.

npm injecta al procés fill un conjunt de variables derivades del manifest i de la configuració:

Un ús real: que el servidor registri la seva versió en arrencar sense haver de llegir el package.json en temps d'execució.

Compte amb la trampa: si algú arrenca amb node src/servidor/servidor.js en comptes de npm start, aquesta variable no existeix. Per això el ?? amb un valor de reserva. Mai no facis dependre la lògica de negoci d'una variable npm_*; fes-les servir només per a diagnòstics.

npm_lifecycle_event permet que un mateix fitxer es comporti diferent segons com l'hagin cridat, tot i que sol ser preferible tenir dos scripts explícits.

Les opcions de configuració també hi arriben. Si executes npm run informe --format=csv, npm exposa npm_config_format=csv. És un mecanisme real, però prefereix -- i process.argv: és explícit, portable i funciona quan executes l'script sense npm.

Per a qualsevol script x, npm executa automàticament prex abans i postx després, sempre que existeixin. Funciona amb els predefinits i amb els personalitzats:

Si el fitxer de dades no existeix, prestart falla, i npm no executa start. Una fallada primerenca i clara en lloc d'un servidor arrencat que peta a la primera petició.

Els ganxos més coneguts són els del cicle d'instal·lació:

postinstall és potent i per això és perillós. Quan instal·les un paquet, el seu postinstall s'executa a la teva màquina amb els teus permisos, sense preguntar-te res. Pot llegir el teu ~/.npmrc (on viu el teu token de npm), les teves variables d'entorn, les teves claus SSH.

Això no és teoria: és el vector habitual dels atacs a la cadena de subministrament. Un mantenidor amb el compte compromès publica una versió de pedaç amb un postinstall maliciós, i milers de màquines l'executen en hores.

Mesures immediates, que ampliarem a la lliçó 05-06:

• A CI i producció, npm ci --ignore-scripts quan el projecte ho toleri.
• Revisar els postinstall de les dependències noves abans d'acceptar-les.
• No desar secrets a l'entorn de la màquina que instal·la paquets.

Als teus propis scripts, postinstall està bé per a tasques del projecte (crear un directori, generar un fitxer derivat). El problema és el codi aliè, no el mecanisme.

Els operadors del shell funcionen tal qual:

&& és el que vols el 95 % de les vegades: encadena i s'atura a la primera fallada. || serveix per a valors de reserva: "informe": "node src/informes/ocupacio.js || echo 'informe no disponible' 1>&2".

La portabilitat és el problema real. Aquestes coses es trenquen a Windows:

Els nostres scripts d'Escena Viva són deliberadament portables: només invoquen node, eslint i prettier, i fan servir cometes dobles escapades. Si algun dia necessites variables d'entorn en línia:

Regla general: si un script comença a assemblar-se a un programa, escriu-lo com un programa a scripts/ i crida'l amb node. JavaScript és portable; el shell no.

Es confonen sovint i no competeixen:

La configuració moderna és simple: Prettier mana en el format, ESLint mana en la correcció, i es desactiven a ESLint les regles d'estil que xocarien amb Prettier. Amb el format fora de la conversa, les revisions de codi deixen de discutir cometes i parlen del que importa.

Per a Escena Viva, ESLint hi entraria així:

I l'script "lint": "eslint src" comença a funcionar sense res més, gràcies al PATH de l'apartat 4. La configuració de regles és un tema en si mateix i no la desenvolupem aquí: el rellevant per a aquesta lliçó és que l'eina s'invoca des de scripts i viu a devDependencies.

• Escriure npm dev. Només start, test, stop i restart prescindeixen de run. Per a la resta, npm run dev.
• Oblidar el -- en passar arguments. npm run cataleg --sala=X no arriba al teu programa; npm run cataleg -- --sala=X sí.
• Redirigir sense --silent. Les capçaleres de npm van a stdout i contaminen el fitxer de sortida.
• Posar "test": "exit 0". Un verd fals és pitjor que un vermell honest: destrueix la confiança en la CI.
• Scripts gegants de cinc ordres encadenades. Divideix en scripts petits i compon amb &&. Es depuren millor i es reutilitzen.
• Assumir bash. sh no és bash i cmd.exe no és cap dels dos. Si dubtes, mou la lògica a un fitxer .js.
• Dependre de npm_package_version a la lògica. Només existeix si es va arrencar amb npm. Fes-la servir per a diagnòstics, amb valor de reserva.
• Consell: executa npm run sense arguments en entrar en un projecte aliè. És la documentació més fiable que trobaràs, perquè si estigués desactualitzada, no funcionaria.
• Consell: anomena els scripts pel que fan per al negoci (informe, vendes, cataleg), no per l'eina que fan servir. L'eina canviarà; la intenció, no.

Afegeix a Escena Viva un script verificar-dades que comprovi que dades/esdeveniments.json existeix, és JSON vàlid i conté exactament 3 esdeveniments amb 7 sessions en total. Ha d'imprimir el resum per stdout i sortir amb codi 1 si alguna cosa falla. Enganxa'l perquè s'executi automàticament abans d'informe.

Modifica src/cataleg.js per acceptar --sala=<nom> i filtrar les sessions d'aquesta sala. Comprova que funciona tant amb node directe com amb npm run. Explica per què una de les dues formes necessita --.

Dissenya un script publicar-informes que executi comprovar, després informe i després vendes, aturant-se a la primera fallada. Després, revisa aquesta proposta d'un company i digues quines tres coses es trencaran a Windows:

El ganxo preinforme talla la cadena abans que informe intenti treballar amb dades corruptes.

La forma amb npm run necessita -- perquè npm consumeix els arguments que comencen per -- com a opcions pròpies. Amb node no hi ha intermediari: tot el que va després del fitxer va directe a process.argv.

Els tres problemes de la proposta del company a Windows:

1. rm -rf no existeix a cmd.exe; cal fer servir node -e "fs.rmSync('sortida', { recursive: true, force: true })" o rimraf.
2. NODE_ENV=prod ordre no és sintaxi vàlida a cmd.exe; requereix cross-env.
3. mkdir sortida falla si el directori ja existeix amb comportament diferent segons el shell; convé fs.mkdirSync(..., { recursive: true }).

A més, la redirecció > sense --silent ficaria les capçaleres de npm dins de sortida/ocupacio.txt.

El package.json d'Escena Viva ja no té buits. scripts és avui la interfície única del projecte: npm start aixeca el servidor, npm run dev el recarrega amb node --watch sense dependre de ningú, npm run cataleg, npm run informe i npm run vendes exposen la feina dels mòduls 1 i 3, npm run comprovar compon linting i format, i npm test falla amb un missatge honest que apunta al Mòdul 9.

Pel camí has entès el mecanisme que ho sosté: npm executa shell amb un PATH que comença a node_modules/.bin, i per això les eines del projecte s'invoquen pel seu nom sense instal·lació global. Saps separar els arguments de npm dels teus amb --, aprofitar npm_package_version per a diagnòstics, encadenar amb && sense sacrificar la portabilitat, i desconfiar del postinstall del codi aliè.

A la lliçó següent, Creació i Publicació de Paquets, canviem de banda del taulell. Fins ara hem consumit paquets; ara en publicarem un. Extraurem src/utils/format.js —amb formatarPreu, formatarData i generarCodiEntrada— a un paquet propi, @escena-viva/format, i veurem com es decideix què és API pública amb exports, què es puja realment amb files, com es comprova el tarball amb npm pack abans que sigui tard, i per què despublicar un paquet és gairebé impossible.