El Projecte | Sobre nosaltres | Contribuir | Donacions | Llicència
HOME Els meus cursos Finalitzats
◄ Anterior
◄

Instal·lació i Configuració de l'Entorn

Següent ►
►

Ja sabem què és Node.js i per què encaixa amb una plataforma com Escena Viva. Toca instal·lar-lo. Podria semblar un tràmit —descarregar un instal·lador i següent, següent, següent— però la manera com instal·lis Node.js condiciona la resta de la teva vida com a desenvolupador: si demà un client exigeix la versió 22 i un altre la 24, si el teu equip ha de reproduir exactament el teu entorn, o si et trobes amb el clàssic error de permisos en instal·lar una eina global.

En aquesta lliçó instal·larem Node.js de la manera correcta (amb un gestor de versions), verificarem que tot funciona, configurarem l'editor i crearem l'estructura inicial de la carpeta escena-viva/, que ens acompanyarà fins al final del curs.

Contingut

  1. Les tres maneres d'instal·lar Node.js
  2. Instal·lació amb nvm a Linux i macOS
  3. Instal·lació a Windows: nvm-windows i fnm
  4. Verificació: què s'instal·la juntament amb Node
  5. Triar versió per a un projecte real: LTS vs Current
  6. El fitxer .nvmrc del projecte
  7. Configuració de l'editor i del terminal
  8. Creació de la carpeta del projecte Escena Viva
  9. Permisos: per què no has de fer servir mai sudo npm install -g

  1. Les tres maneres d'instal·lar Node.js

Mètode Com funciona Avantatges Inconvenients Recomanat?
Instal·lador oficial (nodejs.org) Descarregues un .msi, .pkg o binari i l'instal·les al sistema Molt senzill; serveix per provar en 2 minuts Una sola versió alhora; instal·la en directoris del sistema (origen de problemes de permisos); actualitzar és reinstal·lar Només per a una prova ràpida
Gestor de paquets del sistema (apt, dnf, brew, winget, choco) Node s'instal·la com qualsevol altre programa del sistema Integrat amb les actualitzacions del sistema Les distribucions solen anar endarrerides en versions; de vegades empaqueten npm per separat; canviar de versió és dolorós Acceptable en servidors gestionats, no al teu equip de desenvolupament
Gestor de versions (nvm, fnm, Volta, nvm-windows) Instal·la diverses versions de Node a la teva carpeta personal i commuta entre elles Diverses versions convivint; canvi instantani; sense sudo; versió per projecte via .nvmrc Un pas extra d'instal·lació inicial Sí. És l'opció d'aquesta lliçó.

La raó de fons per preferir un gestor de versions és senzilla: els projectes reals tenen cicles de vida diferents. L'API antiga d'Escena Viva pot estar en Node 22 mentre el nou panell d'organitzadors es desenvolupa en Node 24. Sense un gestor de versions, això t'obliga a desinstal·lar i reinstal·lar constantment.

Comparativa dels gestors més habituals:

Gestor Plataformes Llenguatge Velocitat Nota
nvm Linux, macOS, WSL script de shell Mitjana El més estès; l'estàndard de facto
nvm-windows Windows Go Mitjana Projecte diferent de nvm, ordres semblants però no idèntiques
fnm Linux, macOS, Windows Rust Molt alta Compatible amb .nvmrc; excel·lent alternativa moderna
Volta Linux, macOS, Windows Rust Alta Fixa la versió a package.json i l'aplica automàticament

En aquest curs farem servir nvm com a referència (i fnm o nvm-windows a Windows), perquè .nvmrc és un fitxer que entenen tots ells.

  1. Instal·lació amb nvm a Linux i macOS

Pas 1: instal·lar nvm

# Descarrega i installa nvm a la teva carpeta personal (~/.nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

L'script afegeix unes línies al teu fitxer de configuració de shell (~/.bashrc, ~/.zshrc o ~/.profile) que carreguen nvm en obrir el terminal. Tanca i torna a obrir el terminal, o recarrega'l:

# Recarrega la configuracio del shell sense tancar el terminal
source ~/.bashrc     # si fas servir bash
source ~/.zshrc      # si fas servir zsh

Comprova que nvm respon:

command -v nvm
# Ha d'imprimir: nvm

Si imprimeix buit, l'script no s'ha carregat. Revisa que les línies de nvm siguin al fitxer de configuració que el teu terminal llegeix realment (a macOS amb zsh és ~/.zshrc).

Pas 2: instal·lar l'última versió LTS

# Installa l'ultima versio amb suport a llarg termini
nvm install --lts

nvm descarrega el binari, el col·loca a ~/.nvm/versions/node/ i l'activa a la sessió actual.

# Veure totes les versions installades al teu equip
nvm ls

Sortida d'exemple:

->     v24.5.0
default -> lts/* (-> v24.5.0)
node -> stable (-> v24.5.0)
lts/* -> lts/krypton (-> v24.5.0)

Pas 3: fixar la versió per defecte

Sense aquest pas, cada terminal nou s'obrirà sense cap versió activa.

# Que tot terminal nou faci servir l'ultima LTS
nvm alias default 'lts/*'

Pas 4: commutar entre versions

nvm install 22          # Installar tambe la linia 22 (LTS en manteniment)
nvm use 22              # Activar-la en aquest terminal
node -v                 # v22.x.y
nvm use --lts           # Tornar a la LTS activa
node -v                 # v24.x.y

Resum d'ordres de nvm:

Ordre Què fa
nvm install --lts Instal·la l'última versió LTS
nvm install 24.5.0 Instal·la una versió exacta
nvm use 24 Activa la 24 més recent instal·lada, només en aquest terminal
nvm use Llegeix .nvmrc del directori actual i activa aquesta versió
nvm ls Llista les versions instal·lades
nvm ls-remote --lts Llista les LTS disponibles per descarregar
nvm alias default 'lts/*' Defineix la versió per defecte dels terminals nous
nvm uninstall 20 Elimina una versió que ja no necessites
nvm current Mostra la versió activa

  1. Instal·lació a Windows: nvm-windows i fnm

A Windows, el nvm de Linux no funciona (és un script de shell). Tens dues bones opcions.

Opció A: nvm-windows

Descarrega nvm-setup.exe des del projecte coreybutler/nvm-windows i executa'l. Després, a PowerShell com a administrador el primer cop (nvm-windows crea un enllaç simbòlic a C:\Program Files\nodejs):

nvm install lts
nvm use 24.5.0
node -v

Diferències respecte a nvm de Linux que convé conèixer:

  • No admet nvm alias default; la versió activa és global, no per terminal.
  • nvm use no llegeix .nvmrc automàticament.
  • Requereix permisos d'administrador per commutar.

Opció B: fnm (recomanada si comences de zero)

fnm funciona igual a Windows, Linux i macOS, és molt ràpid i sí que llegeix .nvmrc.

# Amb winget (inclos a Windows modern)
winget install Schniz.fnm

# Installar l'ultima LTS i activar-la
fnm install --lts
fnm use --lts
fnm default lts-latest

Perquè fnm canviï de versió automàticament en entrar en una carpeta amb .nvmrc, afegeix al teu perfil de PowerShell (notepad $PROFILE):

fnm env --use-on-cd | Out-String | Invoke-Expression

Opció C: WSL

Si desenvolupes per a servidors Linux, l'experiència més fidel és fer servir WSL 2 (Windows Subsystem for Linux) i instal·lar-hi nvm a dins seguint l'apartat 2. Evita molts problemes de rutes, permisos i finals de línia.

Avís: no barregis instal·lacions. Si ja tenies Node instal·lat amb l'instal·lador oficial o amb Chocolatey, desinstal·la'l abans de fer servir un gestor de versions. Dues instal·lacions competint al PATH produeixen errors desconcertants («tinc la 24 però node -v diu 18»).

  1. Verificació: què s'instal·la juntament amb Node

Obre un terminal nou i executa:

node -v     # v24.5.0
npm -v      # 11.x.y
npx -v      # 11.x.y

Si tots tres responen, la instal·lació és correcta. Això és el que has obtingut:

Eina Què és Exemple d'ús
node L'intèrpret: executa fitxers .js i obre el REPL node src/cataleg.js
npm Gestor de paquets: instal·la dependències i executa scripts npm install express
npx Executa un paquet sense instal·lar-lo permanentment npx cowsay hola
corepack Gestor de gestors: activa yarn o pnpm en la versió que demani el projecte corepack enable pnpm

Sobre corepack: ve inclòs amb Node però desactivat. Serveix perquè, si un projecte declara que fa servir [email protected], tu no l'hagis d'instal·lar a mà. S'activa així:

corepack enable

En aquest curs farem servir npm, que és el que porta Node per defecte. El detall d'npm i package.json és l'objecte del Mòdul 5; aquí només verifiquem que existeix.

Una comprovació addicional útil: executar codi directament des del terminal.

node -e "console.log('Escena Viva llest a Node', process.version)"
Escena Viva llest a Node v24.5.0

  1. Triar versió per a un projecte real: LTS vs Current

Recordem la regla que vam veure a la lliçó anterior i portem-la a una decisió concreta:

Situació Versió recomanada Raó
Projecte nou que anirà a producció Última Active LTS Estabilitat, suport de biblioteques i de proveïdors d'allotjament
Projecte heretat en producció La LTS que ja fa servir, amb pla de migració No barregis canvi de versió amb canvi funcional
Provar una novetat del llenguatge Current en una carpeta a part Mai al projecte principal
Curs o aprenentatge Última Active LTS És el que trobaràs a la feina

Per a Escena Viva triem la línia 24.x (Active LTS). I, molt important, ho deixem escrit al repositori perquè no depengui de la memòria de ningú.

  1. El fitxer .nvmrc del projecte

.nvmrc és un fitxer de text pla, a l'arrel del projecte, amb una sola línia: la versió de Node que el projecte necessita. L'entenen nvm, fnm, Volta i la majoria de sistemes d'integració contínua.

# Des de l'arrel del projecte, escriu la versio activa a .nvmrc
node -v > .nvmrc

Contingut resultant:

v24.5.0

També és vàlid i més flexible escriure'l a mà amb la línia major, per rebre pedaços sense tocar el fitxer:

lts/krypton

o simplement:

24

A partir d'ara, qualsevol persona que cloni el repositori d'Escena Viva només ha de fer:

cd escena-viva
nvm use          # Llegeix .nvmrc i activa la versio correcta
Found '/home/usuari/escena-viva/.nvmrc' with version <24>
Now using node v24.5.0 (npm v11.4.2)

Truc molt recomanable: configura el teu shell perquè executi nvm use automàticament en entrar en una carpeta amb .nvmrc. Amb fnm n'hi ha prou amb la línia --use-on-cd que hem vist abans; amb nvm, la documentació oficial inclou una funció cd per a bash i zsh que fa el mateix.

  1. Configuració de l'editor i del terminal

Visual Studio Code

VS Code és l'editor més habitual a l'ecosistema Node, i funciona sense configuració. Aquestes extensions marquen la diferència:

Extensió Per a què serveix
ESLint Detecta errors i mals hàbits mentre escrius
Prettier Formata el codi automàticament en desar
npm Intellisense Autocompleta noms de mòduls als require/import
DotENV Acoloreix fitxers .env (els farem servir al Mòdul 11)
REST Client o Thunder Client Prova els teus endpoints HTTP sense sortir de l'editor (Mòduls 4 i 6)
Error Lens Mostra l'error a la mateixa línia, no només al panell
MongoDB for VS Code Útil a partir del Mòdul 7

Ajustos recomanats per al projecte. Crea escena-viva/.vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "files.eol": "\n",
  "files.trimTrailingWhitespace": true,
  "javascript.preferences.quoteStyle": "single",
  "terminal.integrated.defaultProfile.windows": "PowerShell"
}

"files.eol": "\n" mereix una explicació: força finals de línia d'estil Unix. Si treballes a Windows i desplegues a Linux (el normal), això evita diferències absurdes al control de versions i errors als scripts.

Execució integrada

Tens tres maneres d'executar un script des de VS Code:

  1. Terminal integrat (Ctrl+Ñ o Ctrl+`` ): escriu node src/cataleg.js. És la forma que farem servir al curs.
  2. Botó «Run»: amb un fitxer .js obert, F5 engega el depurador de Node integrat.
  3. launch.json: configuració reutilitzable. La veurem amb detall a Depuració d'Aplicacions Node.js.

El terminal

Recomanacions pràctiques:

  • Linux/macOS: bash o zsh, indistintament. Afegeix el canvi automàtic de versió amb .nvmrc.
  • Windows: fes servir Windows Terminal amb PowerShell 7, o directament WSL. Evita cmd.exe.
  • Aprèn dues dreceres que faràs servir cada dia: Ctrl+C per aturar un procés en marxa (un servidor, per exemple) i la fletxa amunt per repetir l'ordre anterior.

  1. Creació de la carpeta del projecte Escena Viva

Crearem l'esquelet del projecte. Tria una carpeta de treball (per exemple ~/projectes) i executa:

# Crear l'estructura inicial d'Escena Viva
mkdir -p escena-viva/src
mkdir -p escena-viva/dades
mkdir -p escena-viva/informes
cd escena-viva

A Windows amb PowerShell:

New-Item -ItemType Directory -Path escena-viva\src, escena-viva\dades, escena-viva\informes -Force
Set-Location escena-viva

Fixem la versió de Node del projecte i arrenquem el control de versions:

# Versio de Node del projecte
node -v > .nvmrc

# Repositori git (opcional i molt recomanable)
git init

Creem també un .gitignore mínim. Encara que de moment no instal·larem dependències, val més prevenir:

printf 'node_modules/\n.env\ninformes/*.csv\n*.log\n' > .gitignore

Estructura resultant:

escena-viva/
├── .gitignore        # Que no es puja al repositori
├── .nvmrc            # Versio de Node del projecte
├── dades/            # Fitxers de dades (esdeveniments.json, vendes.csv)
├── informes/         # Sortides generades pel programa
└── src/              # Codi font JavaScript

Comprova que tot és al seu lloc:

ls -la

Sobre package.json: quan executis npm init -y tindràs un fitxer package.json que descriu el projecte i les seves dependències. Encara no el necessitem: els primers programes del curs funcionen només amb el que porta Node. L'estudiarem a fons al Mòdul 5.

  1. Permisos: per què no has de fer servir mai sudo npm install -g

Aquest és l'error de configuració més habitual en principiants, i mereix el seu propi apartat.

El símptoma

Instal·les Node amb l'instal·lador oficial o amb apt. Node queda a /usr/local o /usr, que pertany a root. Intentes instal·lar una eina global:

npm install -g nodemon
npm error code EACCES
npm error syscall mkdir
npm error path /usr/lib/node_modules/nodemon
npm error errno -13
npm error Error: EACCES: permission denied

La reacció instintiva és anteposar sudo. No ho facis.

Per què és mala idea

Problema Conseqüència
Executes scripts de tercers com a root Un paquet maliciós o compromès té control total de la teva màquina; molts paquets executen scripts postinstall
Es creen fitxers propietat de root a la teva memòria cau Errors EACCES posteriors fins i tot en instal·lacions normals, i una memòria cau ~/.npm corrupta
Barreges àmbits de sistema i d'usuari Actualitzar o desinstal·lar es torna impredictible

La solució correcta

Fer servir un gestor de versions. Amb nvm o fnm, Node i els paquets globals viuen a la teva carpeta personal (~/.nvm/versions/node/v24.5.0/lib/node_modules), on ja tens permisos. L'error EACCES simplement deixa d'existir:

npm install -g nodemon      # Sense sudo, sense errors

Si per alguna raó has de conservar una instal·lació de sistema, l'alternativa oficial és canviar el prefix global a la teva carpeta personal:

# Crear una carpeta propia per als paquets globals
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

# Afegir-la al PATH (a ~/.bashrc o ~/.zshrc)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Si ja has fet el desastre i tens fitxers de root a la memòria cau, es repara així:

sudo chown -R $(whoami) ~/.npm

Regla d'or: al teu equip de desenvolupament, npm no hauria de necessitar sudo mai. Si el necessita, el problema és en com vas instal·lar Node, no en npm.

Errors Comuns i Consells

Error 1: command not found: nvm després d'instal·lar-lo. L'script de nvm es carrega des del fitxer de configuració del shell. Si fas servir zsh però l'instal·lador va escriure a ~/.bashrc, no es carregarà. Obre el fitxer correcte i comprova que conté les línies export NVM_DIR=... i el source de nvm.sh. Després, obre un terminal nou.

Error 2: node -v retorna una versió diferent de la que acabes d'activar. Gairebé sempre hi ha dues instal·lacions competint. Diagnostica-ho amb:

which -a node     # Linux/macOS: mostra TOTES les rutes de node al PATH
where.exe node    # Windows

Si apareix /usr/bin/node abans que la ruta de ~/.nvm, desinstal·la la versió del sistema.

Error 3: cada terminal nou no té Node. Falta nvm alias default 'lts/*'.

Error 4: nvm use diu que no troba .nvmrc. Ets en un directori que no és l'arrel del projecte. nvm use busca .nvmrc al directori actual i als seus pares, no en subcarpetes germanes.

Error 5: instal·lar Node des del gestor del sistema a Ubuntu i trobar-se amb una versió antiquíssima. Els repositoris de les distribucions estables solen anar molt endarrerits. Comprova sempre amb node -v quina versió ha entrat realment.

Consell 1: fixa la versió també al servidor. El .nvmrc no només serveix en local; els sistemes de CI i moltes PaaS el llegeixen (Mòdul 11).

Consell 2: documenta l'arrencada. Encara que de moment no tinguem README, apunta en algun lloc les tres ordres necessàries per treballar al projecte: nvm use, npm install, npm start. El teu jo futur t'ho agrairà.

Consell 3: no acumulis versions. Executa nvm ls de tant en tant i desinstal·la les que ja no fa servir cap projecte; cadascuna ocupa desenes de megabytes.

Exercicis

Exercici 1: instal·lació verificada

  1. Instal·la Node.js amb nvm (o fnm/nvm-windows si ets a Windows).
  2. Instal·la dues versions: l'última LTS i la línia 22.
  3. Fixa la LTS com a versió per defecte.
  4. Escriu les ordres que faries servir per comprovar, des de zero en un terminal nou, que tot està bé: versió de Node, d'npm, d'npx, i la llista de versions instal·lades.

Exercici 2: l'esquelet d'Escena Viva

Crea la carpeta escena-viva/ amb:

  • Subcarpetes src/, dades/ i informes/.
  • Un fitxer .nvmrc amb la versió LTS que has instal·lat.
  • Un .gitignore que exclogui node_modules/, .env i els fitxers .log.

Després, escriu la seqüència d'ordres que executaria un company acabat d'arribar per situar-se al projecte amb la versió de Node correcta, i comprova que nvm use (o fnm use) respon llegint el .nvmrc.

Exercici 3: diagnòstic d'un entorn trencat

Una companya de l'equip d'Escena Viva t'escriu: «He instal·lat nvm i he fet nvm install --lts, però quan obro un terminal nou node -v em diu v18.19.0. A més, si provo npm install -g nodemon em dona EACCES i només funciona amb sudo.»

  1. Quin és el diagnòstic més probable?
  2. Quina ordre li demanaries d'executar per confirmar-ho?
  3. Redacta els passos de la solució.

Solucions

Solució 1

# 1 i 2. Installacio de dues versions
nvm install --lts        # Installa l'ultima LTS (24.x)
nvm install 22           # Installa l'ultima 22.x

# 3. Versio per defecte
nvm alias default 'lts/*'

# 4. Verificacio en un terminal NOU
node -v      # v24.x.y  -> ha de ser la LTS, no la 22
npm -v       # 11.x.y
npx -v       # 11.x.y
nvm ls       # Ha de llistar v22.x.y i v24.x.y, amb default -> lts/*

Comprovació addicional que el canvi funciona:

nvm use 22 && node -v     # v22.x.y
nvm use --lts && node -v  # v24.x.y

Solució 2

# Crear estructura
mkdir -p escena-viva/src escena-viva/dades escena-viva/informes
cd escena-viva

# Fixar versio del projecte
node -v > .nvmrc
cat .nvmrc                # v24.5.0

# Ignorats de git
printf 'node_modules/\n.env\n*.log\n' > .gitignore
git init

Seqüència per al company acabat d'arribar:

git clone <url-del-repositori> escena-viva
cd escena-viva
nvm install     # Installa la versio de .nvmrc si no la te
nvm use         # L'activa en aquest terminal
node -v         # Ha de coincidir amb el contingut de .nvmrc

Nota: nvm use falla si la versió del .nvmrc no està instal·lada; per això l'nvm install previ (sense arguments, també llegeix .nvmrc).

Solució 3

  1. Diagnòstic: hi ha una instal·lació prèvia de Node (de l'instal·lador oficial o del gestor de paquets del sistema) en un directori del sistema, i apareix abans que nvm al PATH. Aquesta instal·lació és de root, cosa que explica alhora la versió inesperada (v18) i l'error EACCES en instal·lar paquets globals.

  2. Ordre de confirmació:

which -a node
# Sortida esperada, amb la del sistema primer:
# /usr/bin/node
# /home/usuari/.nvm/versions/node/v24.5.0/bin/node

També ajuda npm config get prefix: si retorna /usr o /usr/local, confirma el diagnòstic.

  1. Solució:
# a) Desinstallar la versio del sistema (exemple a Debian/Ubuntu)
sudo apt remove --purge nodejs npm
sudo apt autoremove

# b) Reparar la memoria cau d'npm si es va fer servir sudo alguna vegada
sudo chown -R $(whoami) ~/.npm

# c) Obrir un terminal NOU i verificar
which -a node    # Nomes ha d'apareixer la ruta sota ~/.nvm
node -v          # La LTS installada amb nvm
npm install -g nodemon    # Ara funciona SENSE sudo

Si per política de l'empresa no pot desinstal·lar la versió del sistema, l'alternativa és assegurar-se que la línia de nvm a ~/.bashrc s'executa al final del fitxer, perquè la seva ruta quedi primera al PATH.

Conclusió

Ja tens un entorn de desenvolupament professional. Hem vist que hi ha tres maneres d'instal·lar Node.js i per què un gestor de versions (nvm, fnm o nvm-windows) és l'única que suporta bé la realitat de treballar amb diversos projectes: permet instal·lar diverses versions, commutar-hi a l'instant i —detall gens menor— elimina d'arrel els problemes de permisos que porten a la mala pràctica de sudo npm install -g.

Has instal·lat l'última Active LTS, has comprovat que node, npm, npx i corepack responen, has configurat l'editor amb les extensions que faràs servir durant el curs i has creat la carpeta escena-viva/ amb els seus directoris src/, dades/ i informes/, un .gitignore i un .nvmrc que documenta la versió del projecte per a tot l'equip.

La carpeta està creada però buida. A la lliçó següent, El Teu Primer Programa en Node.js, escriurem src/cataleg.js: el primer programa real d'Escena Viva, que defineix el catàleg d'esdeveniments del Teatro Almendra, la Sala Bóveda i l'Auditorio Ribera, el mostra formatat per consola i aprèn a rebre arguments des de la línia d'ordres.

◄ Anterior
◄
Següent ►
►

Curs de Node.js: De Principiant a Avançat

Mòdul 1: Introducció a Node.js

Mòdul 2: Conceptes Bàsics

Mòdul 3: Sistema de Fitxers i E/S

Mòdul 4: HTTP i Servidors Web

Mòdul 5: NPM i Gestió de Paquets

Mòdul 6: Framework Express.js

Mòdul 7: Bases de Dades i ORMs

Mòdul 8: Autenticació i Autorització

Mòdul 9: Proves i Depuració

Mòdul 10: Temes Avançats

Mòdul 11: Desplegament i DevOps

Mòdul 12: Projectes del Món Real

El Projecte | Sobre nosaltres | Contribuir | Donacions | Llicència
© Copyright 2026. Tots els drets reservats