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

Configuració de l'entorn de desenvolupament

Següent ►
►

Treballar seriosament amb React requereix un petit ecosistema d'eines: un entorn d'execució de JavaScript fora del navegador (Node.js), un gestor de paquets (npm), una eina de construcció que transformi el teu codi i et doni un servidor de desenvolupament ràpid (Vite), un editor ben configurat i una extensió de navegador per inspeccionar components. En aquesta lliçó muntaràs aquest entorn de cap a cap i crearàs el projecte CicloUrbano que faràs servir durant tot el curs. Quan acabis tindràs una aplicació funcionant al navegador i entendràs què fa cada fitxer generat.

Contingut

  1. Requisits previs: Node.js i npm
  2. L'editor i les seves extensions
  3. Crear el projecte de CicloUrbano amb Vite
  4. Recorregut per l'estructura de carpetes
  5. Els scripts de npm: dev, build, preview
  6. Recàrrega en calent (Hot Module Replacement)
  7. React DevTools al navegador
  8. Per què Vite i no Create React App

  1. Requisits previs: Node.js i npm

React s'escriu amb una sintaxi (JSX) que els navegadors no entenen directament i es distribueix en paquets que cal descarregar. Totes dues coses necessiten Node.js, l'entorn que permet executar JavaScript fora del navegador, i npm (Node Package Manager), que s'instal·la juntament amb Node.

Quina versió instal·lar

Fes servir sempre una versió LTS (Long Term Support): són les versions parelles (20, 22, 24...) amb suport prolongat i les que les eines donen per bones. Vite requereix Node 20.19 o superior. Descarrega-la de nodejs.org o, encara millor, instal·la un gestor de versions com nvm (macOS/Linux) o fnm (multiplataforma), que et permet tenir diverses versions i canviar entre elles per projecte.

Comprovar que tot està al seu lloc

Obre un terminal i executa:

node --version
npm --version

Sortida esperada (els números concrets variaran, però el format és aquest):

v22.14.0
10.9.2

Si l'ordre no es reconeix, Node no està instal·lat o no és al PATH; reinicia el terminal després d'instal·lar-lo. Si la versió de Node és inferior a 20, actualitza-la abans de continuar: més endavant veuràs errors confusos.

Un apunt sobre gestors de paquets

Gestor Ordre d'instal·lació Notes
npm npm install Ve amb Node. És el que farem servir durant tot el curs
pnpm pnpm install Més ràpid i estalvia disc en compartir dependències entre projectes
yarn yarn Alternativa històrica, encara molt usada en projectes existents

Els tres resolen el mateix problema i les ordres són gairebé intercanviables. Farem servir npm perquè no cal instal·lar res més.

  1. L'editor i les seves extensions

L'editor recomanat és Visual Studio Code, gratuït i amb el millor suport per a React. Aquestes extensions aporten una millora real en el dia a dia:

Extensió Per a què serveix
ESLint Marca errors i males pràctiques mentre escrius (hooks mal usats, variables sense utilitzar, key que falten)
Prettier Formata el codi automàticament en desar: s'acaben les discussions sobre cometes i indentació
ES7+ React/Redux/React-Native snippets Dreceres com rafce que generen l'esquelet d'un component de funció
Auto Rename Tag En renombrar una etiqueta d'obertura en JSX, renombra la de tancament
Error Lens Mostra el missatge d'error a la mateixa línia, sense haver de passar-hi el ratolí per sobre

Una configuració molt recomanable és activar el formatatge en desar. A VS Code, Ctrl+, → cerca «format on save» → marca-ho. O directament a .vscode/settings.json dins del projecte:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

  1. Crear el projecte de CicloUrbano amb Vite

Vite (es pronuncia «vit», ràpid en francès) és l'eina de construcció estàndard avui per a projectes React. Fa dues coses: durant el desenvolupament aixeca un servidor gairebé instantani que serveix el teu codi, i per a producció genera els fitxers optimitzats que pujaràs a l'allotjament.

Situa't a la carpeta on guardes els teus projectes i executa:

npm create vite@latest ciclourbano -- --template react

Desglossem aquesta ordre, perquè els guions dobles confonen molta gent:

  • npm create vite@latest descarrega i executa l'assistent de creació de Vite en la seva darrera versió, sense instal·lar-lo permanentment.
  • ciclourbano és el nom de la carpeta del projecte.
  • El -- separa els arguments de npm dels arguments de l'assistent. Sense ell, npm intentaria interpretar --template com una opció seva.
  • --template react tria la plantilla de React amb JavaScript. (Si volguessis TypeScript seria react-ts; ho veuràs a la lliçó 10-04, però en aquest curs fem servir JavaScript).

Sortida esperada:

Scaffolding project in /home/tu-usuario/proyectos/ciclourbano...

Done. Now run:

  cd ciclourbano
  npm install
  npm run dev

Segueix aquestes tres instruccions:

cd ciclourbano
npm install

npm install llegeix package.json, descarrega les dependències a la carpeta node_modules/ i crea package-lock.json. Triga entre uns segons i un minut segons la teva connexió:

added 152 packages, and audited 153 packages in 12s
found 0 vulnerabilities

I arrenca el servidor de desenvolupament:

npm run dev
  VITE v7.0.0  ready in 187 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Obre http://localhost:5173/ al navegador: veuràs la pàgina de benvinguda de Vite + React amb un comptador. Deixa aquest procés en marxa al seu terminal mentre treballes; per aturar-lo, Ctrl+C.

Si el port 5173 està ocupat, Vite farà servir el 5174, el 5175, etc. Fixa't sempre en la URL que imprimeix la consola.

  1. Recorregut per l'estructura de carpetes

Això és el que Vite ha generat:

ciclourbano/
├── node_modules/          <- dependències descarregades (mai es toca ni es puja a git)
├── public/                <- fitxers estàtics servits tal qual
│   └── vite.svg
├── src/                   <- EL TEU codi: aquí treballaràs sempre
│   ├── assets/
│   │   └── react.svg
│   ├── App.css
│   ├── App.jsx            <- component arrel de l'aplicació
│   ├── index.css          <- estils globals
│   └── main.jsx           <- punt d'entrada de JavaScript
├── .gitignore
├── eslint.config.js
├── index.html             <- pàgina HTML real que serveix el navegador
├── package.json
├── package-lock.json
├── README.md
└── vite.config.js

index.html: el punt de partida real

En un projecte Vite, l'HTML no està amagat dins de la configuració: és un fitxer de primer nivell i és el veritable punt d'entrada.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite + React</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

Dues línies són les importants:

  • <div id="root"></div> és el contenidor buit on React muntarà tota l'aplicació. Tot el que veuràs en pantalla acabarà dins d'aquest div.
  • <script type="module" src="/src/main.jsx"> carrega el teu codi com a mòdul ES. És el fil que enllaça l'HTML amb React.

Aprofita per personalitzar-lo ara, ja que és el teu projecte:

<html lang="ca">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>CicloUrbano — Lloguer de bicicletes urbanes</title>
  </head>

src/main.jsx: on arrenca React

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './index.css';
import App from './App.jsx';

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <App />
  </StrictMode>
);

És el fitxer que connecta React amb el div#root de l'HTML. L'analitzarem línia a línia a la lliçó següent; de moment queda't amb la idea que aquí comença tot.

La resta de peces

Fitxer / carpeta Per a què serveix
src/App.jsx Component arrel. D'ell penja l'arbre complet de components de CicloUrbano
src/index.css Estils globals: tipografia base, colors, reinici de marges
src/App.css Estils del component App (al Mòdul 2 veuràs estratègies millors)
src/assets/ Imatges i recursos que importes des del codi; Vite els optimitza i els afegeix un hash en construir
public/ Recursos servits tal qual, sense processar, a l'arrel del lloc: public/logo.png se serveix com a /logo.png. Fes-la servir per a favicon.ico, robots.txt o descàrregues
package.json Nom del projecte, dependències i scripts executables
package-lock.json Versions exactes instal·lades. Es puja a git perquè tot l'equip instal·li el mateix
vite.config.js Configuració de Vite (plugins, àlies, port, proxy)
eslint.config.js Regles d'anàlisi estàtica del codi
.gitignore Llista del que git ha d'ignorar; inclou node_modules/ i dist/
node_modules/ Dependències descarregades. Pesa molt, es regenera amb npm install i mai es puja a git

Diferència clau entre src/assets/ i public/: el que hi ha a assets passa pel procés de construcció (s'optimitza, es reanomena amb un hash per cachejar bé i, si no s'utilitza, s'elimina); el que hi ha a public es copia sense tocar-lo i el seu nom no canvia.

vite.config.js

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()]
});

És mínim a propòsit. El plugin @vitejs/plugin-react és el que ensenya a Vite a transformar JSX i el que habilita la recàrrega en calent de components. Si més endavant necessites un àlies de rutes o un proxy cap a una API, es configura aquí.

Com encaixen les peces

flowchart TD
    A[El navegador demana index.html] --> B["index.html conté div#root<br/>i carrega /src/main.jsx"]
    B --> C[main.jsx: createRoot + render]
    C --> D[App.jsx: component arrel]
    D --> E[Components de CicloUrbano<br/>src/components/]
    F[Vite: servidor de desenvolupament] -.transforma JSX al vol.-> B

  1. Els scripts de npm: dev, build, preview

Obre'l tu mateix, package.json:

{
  "name": "ciclourbano",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^19.1.0",
    "react-dom": "^19.1.0"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^4.4.0",
    "eslint": "^9.25.0",
    "vite": "^7.0.0"
  }
}
Script Ordre Què fa Quan el fas servir
dev npm run dev Aixeca el servidor de desenvolupament amb recàrrega en calent a localhost:5173 Tota l'estona mentre programes
build npm run build Genera la versió de producció optimitzada a dist/ Abans de desplegar
preview npm run preview Serveix localment el que hi ha a dist/ per comprovar-ho Després de build, per validar abans de pujar
lint npm run lint Analitza el codi buscant errors i males pràctiques Abans de confirmar canvis a git

Prova el cicle complet ara:

npm run build
vite v7.0.0 building for production...
✓ 34 modules transformed.
dist/index.html                   0.46 kB │ gzip:  0.30 kB
dist/assets/index-DiwrgTda.css    1.39 kB │ gzip:  0.72 kB
dist/assets/index-C9n2Xk4p.js   143.41 kB │ gzip: 46.12 kB
✓ built in 612 ms
npm run preview
  ➜  Local:   http://localhost:4173/

Observa dos detalls importants: preview fa servir un port diferent (4173) perquè no el confonguis amb el de desenvolupament, i els fitxers de dist/ porten un hash al nom (index-C9n2Xk4p.js). Aquest hash canvia quan canvia el contingut, cosa que permet al navegador cachejar agressivament sense servir mai una versió antiga.

Sobre dependencies enfront de devDependencies: les primeres acaben al paquet que arriba al navegador (react, react-dom); les segones només es fan servir a la teva màquina per construir i analitzar el codi (vite, eslint). Per això el resultat de build pesa molt menys que node_modules/.

  1. Recàrrega en calent (Hot Module Replacement)

El HMR (Hot Module Replacement, substitució de mòduls en calent) és la raó per la qual el desenvolupament amb Vite resulta tan còmode. Quan deses un fitxer, Vite no recarrega la pàgina sencera: envia per WebSocket només el mòdul que ha canviat i React el substitueix en viu.

La diferència pràctica és enorme:

Recàrrega completa HMR
Temps fins a veure el canvi 1-3 segons Desenes de mil·lisegons
Estat de l'aplicació Es perd: tornes a l'inici Es conserva
Desplaçament i focus Es reinicien Es mantenen

L'«estat es conserva» és el que més agrairàs: si has omplert mig formulari de reserva de CicloUrbano i ajustes un color al CSS, continues veient el formulari emplenat.

Prova-ho. Amb npm run dev en marxa, obre src/App.jsx, canvia qualsevol text visible i desa. El navegador s'actualitza sol, sense parpelleig. A la consola de Vite veuràs:

9:41:23 [vite] hmr update /src/App.jsx

Hi ha casos en què l'HMR no pot aplicar el canvi i recarrega la pàgina sencera: en modificar vite.config.js, en tocar index.html, o quan canvies l'estructura d'un mòdul de manera que Vite no pot reconciliar-la. És normal.

  1. React DevTools al navegador

React DevTools és l'extensió oficial que permet inspeccionar la teva aplicació en termes de React —components, props, estat— en lloc de en termes de nodes HTML.

Instal·lació

  • Chrome / Edge: cerca «React Developer Tools» a la Chrome Web Store i instal·la-la.
  • Firefox: busca-la a addons.mozilla.org.
  • Safari o altres: es pot fer servir la versió independent amb npx react-devtools.

Un cop instal·lada, obre http://localhost:5173, prem F12 i veuràs dues pestanyes noves: Components i Profiler.

Què mostra la pestanya Components

  • L'arbre de components amb els seus noms reals (App, LlistaBicicletes, TargetaBicicleta), en lloc d'un embolic de div. Aquesta és la raó principal per instal·lar-la.
  • Props i estat del component seleccionat, al panell dret, i editables al vol per provar casos sense tocar el codi.
  • El component pare que el renderitza i la ruta completa fins a l'arrel.
  • Un selector (icona de fletxa) per clicar un element de la pàgina i saltar al seu component.

Comprova que funciona: obre Components i veuràs App a l'arbre, i dins seu StrictMode. Encara hi ha poc a veure, però a partir de la lliçó 01-03 aquesta pestanya serà la teva eina de diagnòstic principal.

La pestanya Profiler mesura el rendiment dels renders. És una eina excel·lent, però requereix entendre abans com renderitza React; s'estudia a la lliçó Mesurar el rendiment amb React DevTools Profiler.

  1. Per què Vite i no Create React App

Durant anys, la manera estàndard de crear un projecte React va ser create-react-app (CRA). Avui no l'has de fer servir:

  • Està descontinuat. La documentació oficial de React el va retirar de les seves recomanacions el 2023 i el paquet va deixar de mantenir-se activament. Instal·lar-lo avui mostra avisos de dependències obsoletes.
  • És lent. CRA fa servir webpack amb Babel i empaqueta tota l'aplicació abans de poder servir res: arrencar un projecte mitjà podia trigar 30 segons o més, i cada canvi diversos segons. Vite serveix els mòduls ES nativament i fa servir esbuild (escrit en Go) per a les dependències: arrenca en menys d'un segon amb independència de la mida del projecte.
  • És opac. La seva configuració està amagada darrere de react-scripts, i personalitzar-la obligava a fer eject (una operació irreversible que aboca centenars de línies de configuració al teu repositori) o a pedaços externs. vite.config.js són cinc línies llegibles.
Create React App Vite
Estat Descontinuat Actiu i estàndard de facto
Arrencada del servidor Desenes de segons Menys d'un segon
Actualització després d'un canvi Segons Mil·lisegons
Configuració Amagada; eject irreversible Fitxer curt i editable
Construcció de producció webpack Rollup, amb divisió de codi inclosa

Que CRA aparegui en tutorials antics és el millor senyal per desconfiar de la seva actualitat: si un tutorial fa servir create-react-app, probablement també faci servir components de classe i API anteriors als hooks. Menciona'l només com a context històric.

Errors habituals i consells

  • Executar npm run dev fora de la carpeta del projecte. Dona npm error Missing script: "dev". Comprova amb pwd (o ls package.json) que estàs dins de ciclourbano/.
  • Oblidar el -- a l'ordre de creació. npm create vite@latest ciclourbano --template react no passa la plantilla a l'assistent i aquest et preguntarà interactivament. No és un error greu, però convé saber per què passa.
  • Pujar node_modules/ a git. Són desenes de milers de fitxers. El .gitignore que genera Vite ja l'exclou; no l'esborris. Si algú clona el repositori, amb npm install el reconstrueix.
  • Editar fitxers dins de node_modules/. Qualsevol canvi allà desapareixerà en la instal·lació següent. Si necessites modificar una dependència, hi ha eines específiques (patch-package), però gairebé mai és la solució correcta.
  • Node en una versió massa antiga. És la causa número u d'errors incomprensibles en instal·lar o arrencar. Verifica sempre node --version abans de demanar ajuda.
  • Tancar el terminal on corre npm run dev i esperar que la web continuï funcionant. El servidor de desenvolupament és aquest procés; si el mates, localhost:5173 deixa de respondre.
  • Confondre el port de dev amb el de preview. El 5173 serveix el teu codi en desenvolupament, el 4173 serveix el contingut de dist/. Si edites i no veus canvis, comprova en quin port estàs.
  • Consell: afegeix el projecte a git des del primer dia (git init, git add ., git commit -m "Projecte inicial de CicloUrbano"). Poder tornar a un punt que funcionava val un món mentre aprens.

Exercicis

Exercici 1

Crea el projecte de CicloUrbano seguint els passos de la lliçó i, a continuació:

  1. Canvia el <title> de index.html a CicloUrbano — Lloguer de bicicletes urbanes i l'atribut lang a ca.
  2. Amb el servidor de desenvolupament en marxa, modifica qualsevol text de src/App.jsx i comprova que el canvi apareix sense recarregar la pàgina.
  3. Executa la construcció de producció i serveix-la localment. Anota quin port fa servir i quina mida té el fitxer JavaScript generat.

Exercici 2

Classifica cadascun d'aquests fitxers o carpetes en una de tres categories: (A) l'edito habitualment, (B) existeix però gairebé mai el toco, (C) mai l'edito a mà.

src/App.jsx · node_modules/ · package.json · package-lock.json · index.html · vite.config.js · src/components/ · dist/

Exercici 3

Col·loca dues imatges al projecte: logo-ciclourbano.svg a public/ i bicicleta-urbana.svg a src/assets/. Explica amb quina ruta referenciaries cadascuna i què li passa a cada fitxer en executar npm run build.

Solucions

Solució 1.

npm create vite@latest ciclourbano -- --template react
cd ciclourbano
npm install
npm run dev

Edita index.html:

<html lang="ca">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>CicloUrbano — Lloguer de bicicletes urbanes</title>
  </head>

En desar src/App.jsx amb un text diferent, el navegador s'actualitza en mil·lisegons sense perdre l'estat (si havies premut el comptador d'exemple, manté el seu valor): això és l'HMR en acció. La consola de Vite imprimeix [vite] hmr update /src/App.jsx.

Pel tercer punt:

npm run build
npm run preview

preview serveix a http://localhost:4173/. El fitxer JavaScript rondarà els 140-150 kB (uns 45 kB comprimits amb gzip), que és essencialment el pes de React i React DOM.

Solució 2.

Fitxer / carpeta Categoria Motiu
src/App.jsx A És el teu component arrel; el toques constantment
src/components/ A Aquí viuran tots els components de CicloUrbano
package.json B Es modifica en afegir scripts; les dependències les gestiona npm install
index.html B Títol, idioma, favicon i metadades; després gairebé no es toca
vite.config.js B Només quan necessitis un àlies, un proxy o un plugin
node_modules/ C Generada per npm; qualsevol canvi es perd
package-lock.json C La gestiona npm; es confirma a git però no s'edita a mà
dist/ C Sortida de npm run build; es regenera i ni tan sols es puja a git

Solució 3.

  • public/logo-ciclourbano.svg se serveix tal qual des de l'arrel del lloc. Es referencia amb una ruta absoluta i el seu nom no canvia mai:

    <img src="/logo-ciclourbano.svg" alt="CicloUrbano" />

    Després de npm run build apareix a dist/logo-ciclourbano.svg amb el mateix nom. És l'opció correcta quan la ruta ha de ser estable i predictible (favicon, robots.txt, imatges referenciades des de fora).

  • src/assets/bicicleta-urbana.svg s'importa des del codi:

    import bicicletaUrbana from './assets/bicicleta-urbana.svg';

<img src={bicicletaUrbana} alt="Bicicleta urbana" />

    En construir, Vite el processa, el reanomena amb un hash (dist/assets/bicicleta-urbana-B7kX2p1q.svg) i substitueix la referència. Avantatges: memòria cau òptima al navegador, error en temps de construcció si la ruta està mal escrita, i eliminació automàtica si el fitxer deixa de fer-se servir.

Conclusió

Ja tens un entorn de desenvolupament professional: Node.js LTS i npm verificats, un editor amb ESLint i Prettier, el projecte CicloUrbano creat amb Vite, el servidor de desenvolupament en marxa amb recàrrega en calent i React DevTools instal·lat al navegador. També saps què fa cada fitxer generat, en què es diferencien src/assets/ i public/, per a què serveix cada script de npm i per què Vite ha substituït Create React App.

Fins ara només has executat codi d'altri. A la lliçó següent, Hola món en React, netejaràs la plantilla d'exemple, entendràs línia a línia com main.jsx munta l'aplicació al DOM i escriuràs els teus dos primers components propis: Benvinguda i TargetaBicicleta.

◄ Anterior
◄
Següent ►
►

Curs de React

Mòdul 1: Introducció a React

Mòdul 2: Components de React

Mòdul 3: Treballar amb Esdeveniments

Mòdul 4: Conceptes Avançats de Components

Mòdul 5: Hooks de React

Mòdul 6: Enrutament a React

Mòdul 7: Gestió de l'Estat

Mòdul 8: Optimització del Rendiment

Mòdul 9: Proves a React

Mòdul 10: Temes Avançats

Mòdul 11: Projecte: Construir una Aplicació Completa

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