Aller au contenu
English

Navigateur et outils de construction

  • Leçon 4
  • 55 min
  • Module 1 : Premiers pas avec le Web

Où nous en sommes

Dans les deux dernières leçons, nous avons écrit la première page et nous l'avons fait fonctionner avec JavaScript : elle charge dix billets et en envoie un nouveau. Mais un dossier de fichiers ne suffit pas pour un vrai projet : pas de versions exactes des paquets, pas de vérifications avant l'exécution, pas de construction de production. Dans cette leçon, nous passons la page à npm, Vite et TypeScript, et nous apprenons où s'exécute chaque morceau de code.

Ce que vous saurez faire

Passez de la première page aux outils d’un vrai projet. Ces outils comprennent npm pour les paquets, un serveur de développement, TypeScript pour les vérifications avant l’exécution, des tests et une construction de production. Sachez aussi où chaque morceau de code s’exécute, car le navigateur et le serveur suivent des règles différentes.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 55 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • ~/projects/ticket-desk avec bridge/, et l’API simulée en cours d’exécution dans le terminal 1.
  • Une connexion : npm install télécharge environ 64 Mo de paquets.

À la fin, votre dossier correspond à l’instantané end-of-m01.

Vous avez écrit bridge/index.html avec un seul élément de liste, « Loading… » (chargement…). La page affiche maintenant dix éléments. Où sont-ils donc? Pas dans le fichier : il n’a pas changé. Ils sont dans le DOM, l’arbre actuel des éléments de la page dans le navigateur, que app.js a modifié.

Les outils de développement du navigateur montrent cet arbre. Ouvrez http://127.0.0.1:8100/, ouvrez les outils de développement, puis sélectionnez l’onglet Elements (éléments) :

Les outils de développement de Chrome à côté de la première page. Le panneau Elements montre l'arbre : html, head, body avec la classe top, main avec la classe layout et un indicateur grid, puis le script app.js. En dessous, le volet Styles pour body montre la règle margin 0 de styles.css, ligne 14. La règle margin 8px du navigateur est barrée. Le volet montre aussi les propriétés personnalisées de :root dans styles.css, ligne 2, comme --ink #1d2733.
Le panneau Elements montre le DOM, replié au niveau de body. Le volet Styles montre l'origine de chaque règle : styles.css remplace la marge de 8px du navigateur. L’image est en anglais.

Ouvrez <main>, puis le deuxième <section>, puis <ul>, avec les petits triangles : la liste contient dix éléments <li>. Le panneau Elements montre le DOM dans son état actuel. View page source (afficher le code source de la page), accessible par un clic droit, montre le fichier envoyé par le serveur, avec « Loading… ». Dans l’onglet Console, vous pouvez interroger le DOM avec JavaScript. Tapez ceci, puis appuyez sur Entrée :

document.querySelectorAll('#tickets li').length

Il répond 10. Quand une page affiche quelque chose d’inattendu, regardez d’abord le DOM, puis les requêtes dans l’onglet Network (réseau). Le DOM indique ce que la page contient; l’onglet Network indique ce que le serveur a envoyé.

Le problème : un dossier de fichiers ne suffit pas pour grandir

Section intitulée « Le problème : un dossier de fichiers ne suffit pas pour grandir »

La première page fonctionne avec trois fichiers et aucun outil. Le vrai écran de Grace demande beaucoup plus : une liste de milliers de billets de soutien, une vue de billet, un brouillon en flux continu, des tests. Teodor énumère les problèmes qui apparaîtront s’ils continuent de la même façon :

  • Les erreurs apparaissent seulement à l’exécution du code. Écrivez ticket.subjet au lieu de ticket.subject, et la liste affiche undefined (non défini) au lieu d’un objet. Aucun message, aucun avertissement : c’est l’agent qui découvre l’erreur.
  • Le code d’autres personnes. Le module 2 utilise React, une bibliothèque d’environ 64 ko (compressée) que Teodor n’écrira pas. Chaque ordinateur de l’équipe doit télécharger une version précise.
  • La production est différente. Le vrai écran doit utiliser de petits fichiers qui se chargent vite, pas les fichiers tels que Teodor les écrit.

Une cuisinière dans une cuisine très occupée rencontre les mêmes problèmes. Elle note les marques et les quantités exactes dans ses recettes, pour qu’une autre personne puisse préparer le même plat. Elle goûte pendant la cuisson et présente le plat final autrement que dans la casserole. Les outils de cette leçon remplissent ces trois fonctions : npm conserve la liste exacte des ingrédients, le serveur de développement permet de goûter pendant le travail, et la construction présente le plat.

Un paquet est du code publié pour que d’autres personnes l’utilisent, comme Vite ou React. npm (son nom vient de « Node Package Manager », gestionnaire de paquets Node) télécharge des paquets depuis le registre npm, un magasin public, dans le dossier node_modules. Il lit la liste des paquets dans package.json, la description du projet.

Copiez ces fichiers de l’instantané end-of-m01 dans votre dossier ticket-desk : package.json, package-lock.json, .env.example, index.html, tsconfig.json, vite.config.ts, README.md (qui décrit maintenant aussi la page), et le dossier src. Dans le terminal 2, dans le dossier ticket-desk :

Fenêtre de terminal
S=../nextia-learning-labs/C22/snapshots/end-of-m01
cp $S/package.json $S/package-lock.json $S/.env.example $S/index.html $S/tsconfig.json $S/vite.config.ts $S/README.md .
cp -R $S/src .

Les commandes supposent que le dépôt des exercices se trouve à côté de ticket-desk, dans ~/projects. Lisez ensuite package.json :

package.json
{
"name": "ticket-desk",
"version": "0.1.0",
"private": true,
"description": "Larkfield's help-desk interface: the running project of the frontend course of Nextia Learning.",
"license": "MIT",
"type": "module",
"engines": {
"node": "^22.22.2 || >=24.15.0"
},
"scripts": {
"api": "node mock-api/server.mjs",
"dev": "vite",
"build": "tsc --noEmit && vite build",
"preview": "vite preview",
"typecheck": "tsc --noEmit",
"test": "node --test \"mock-api/*.test.mjs\" && vitest run"
},
"devDependencies": {
"typescript": "7.0.2",
"vite": "8.3.4",
"vitest": "5.0.3"
}
}

Trois parties comptent :

  • scripts (scripts) contient des noms courts pour les commandes. npm run dev exécute vite; npm test exécute les deux ensembles de tests. npm run api exécute node mock-api/server.mjs : vous pouvez désormais démarrer l’API simulée avec cette commande. Une nouvelle personne n’a pas besoin de connaître les longues commandes.
  • devDependencies (dépendances de développement) contient les paquets nécessaires pendant la construction du projet : TypeScript, Vite et Vitest. Chacun a une version exacte, comme 8.3.4, pour que chaque ordinateur reçoive le même code.
  • "type": "module" indique que les fichiers .js sont des modules, comme dans la dernière leçon.

Chacun des trois paquets a besoin d’autres paquets, qui en nécessitent encore d’autres. package-lock.json consigne la version exacte de chacun. Faites un commit (enregistrement dans le dépôt) des deux fichiers; ne modifiez jamais le fichier de verrouillage à la main.

Installez-les dans le terminal 2 :

Fenêtre de terminal
npm install

L’exécution de l’auteur a affiché ceci. L’ordinateur de l’équipe du cours avait les paquets dans le cache de npm; cela a donc pris moins d’une seconde. Votre première installation les télécharge et prend plus de temps :

added 38 packages, and audited 39 packages in 422ms
12 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
npm warn allow-scripts 1 package has install scripts not yet covered by allowScripts:
npm warn allow-scripts fsevents@2.3.3 (install: (install scripts present))
npm warn allow-scripts
npm warn allow-scripts Run `npm approve-scripts --allow-scripts-pending` to review, or `npm approve-scripts <pkg>` to allow.

Vous avez demandé trois paquets, et npm en a ajouté 38. C’est normal : Vite et Vitest apportent leurs outils auxiliaires. L’avertissement apparaît seulement sur macOS. fsevents est un outil auxiliaire de macOS qui indique à Vite qu’un fichier a changé. npm n’a pas exécuté son script d’installation, car personne ne l’a approuvé. Vite fonctionne sans lui : chaque commande de ce cours a été exécutée avec cet avertissement. Vous pouvez l’ignorer.

node_modules occupe maintenant 64 Mo. Il grossit à mesure que le cours ajoute des paquets, et on ne l’enregistre jamais dans un commit. .gitignore le mentionne, et npm install le recrée à partir du fichier de verrouillage.

La taille de node_modules à la fin de chaque module de ce cours, sur le Mac de l'équipe du cours. Le module 2 ajoute React et la bibliothèque de tests; le module 6 ajoute l'outil de tests de bout en bout.
Description textuelle du graphique

Un graphique à colonnes montre la taille de node_modules à la fin de chaque module. Elle atteint 64 Mo après le module 1, 107 après le module 2, 114 après les modules 3, 4 et 5, et 135 après le module 6. Les plus grandes hausses viennent de React et de ses outils de tests au module 2, puis de l’outil de tests de bout en bout au module 6. Aucun de ces mégaoctets n’arrive tel quel au navigateur : la construction prend seulement le code que la page utilise.

Pourquoi ne pas ouvrir index.html comme un fichier, en double-cliquant dessus? Parce qu’un navigateur charge les modules seulement depuis un serveur, et qu’il ne comprend pas TypeScript. Un serveur de développement est un petit serveur pour votre ordinateur pendant que vous travaillez. Il envoie les fichiers du projet au navigateur et transforme chaque fichier en un format que le navigateur comprend. Il recharge aussi la page quand vous enregistrez un fichier. Ce cours utilise Vite.

Démarrez-le dans un troisième terminal, le terminal 3. Le terminal 1 garde l’API simulée en cours d’exécution.

Fenêtre de terminal
npm run dev
VITE v8.3.4 ready in 100 ms
➜ Local: http://localhost:5173/
➜ Network: use --host to expose

Ouvrez http://localhost:5173/. Vous voyez la même page qu’avant, maintenant construite à partir de index.html et de src/main.ts, avec les styles communs du cours. src/main.ts reprend bridge/app.js en TypeScript : il charge les dix billets les plus récents et envoie le formulaire avec FormData et fetch. Ses requêtes se trouvent dans src/api.ts, et la section suivante examine ses types.

Le bureau des billets à localhost:5173 : le formulaire New ticket (nouveau billet) à gauche, et la liste des dix billets les plus récents à droite. Chaque billet occupe une ligne, comme T-80010: Return label for my order LK-300210 (Test Customer · other · open), soit une étiquette de retour pour la commande LK-300210, un client de test, la catégorie autre et l'état ouvert.
La même page, servie par le serveur de développement de Vite et écrite en TypeScript. La liste vient de l'API simulée sur un autre port. L’image est en anglais.

Deux serveurs fonctionnent maintenant sur votre ordinateur, avec des rôles différents. Vite envoie les fichiers de la page. L’API simulée envoie les données. En production, Vite ne s’exécute pas du tout : la construction crée des fichiers ordinaires que n’importe quel serveur Web peut envoyer.

TypeScript : trouver les erreurs avant l’exécution du code

Section intitulée « TypeScript : trouver les erreurs avant l’exécution du code »

Rappelez-vous l’erreur ticket.subjet : JavaScript donne undefined et continue. TypeScript est JavaScript avec des types : des notes qui décrivent la forme de chaque valeur. Un outil lit ces notes et vérifie le code avant son exécution. Les types des données de l’API se trouvent dans src/types.ts :

src/types.ts (the start)
export interface TicketSummary {
ticket_id: string;
customer_id: string;
customer_name: string;
subject: string;
team: string;
priority: number;
status: string;
created_at: string;
}

Une interface nomme les champs d’un objet et le type de chacun : string pour le texte, number pour les nombres. src/api.ts l’utilise : function ticketLine(ticket: TicketSummary): string dit « cette fonction reçoit un résumé de billet et renvoie du texte ».

Faites maintenant l’erreur volontairement. Dans src/api.ts, remplacez ticket.subject par ticket.subjet dans ticketLine, enregistrez, puis lancez la vérification des types :

Fenêtre de terminal
npx tsc --noEmit
src/api.ts(33,41): error TS2551: Property 'subjet' does not exist on type 'TicketSummary'. Did you mean 'subject'?

Le vérificateur donne le fichier, la ligne (33), la colonne (41) et même la correction. npx exécute un programme de node_modules; tsc est le vérificateur TypeScript, et --noEmit signifie « vérifier seulement ». Remettez le bon mot, et la vérification n’affiche rien : aucune erreur.

Les types existent seulement pour la vérification. Le navigateur ne les voit jamais : Vite les retire quand il envoie un fichier. TypeScript ne prend donc aucun temps dans le navigateur. Il vous demande un peu de temps de travail : vous écrivez les types et vous les gardez conformes au contrat de l’API.

Le projet a deux sortes de tests. Les 21 vérifications de l’API simulée s’exécutent avec Node.js. src/api.test.ts vérifie le code de la page avec Vitest, un exécuteur de tests pour les projets Vite. Voici l’un de ses tests :

src/api.test.ts (one test)
test('loadTickets fails with the status when the API answers an error', async () => {
vi.stubGlobal('fetch', async () => new Response('{}', { status: 503 }));
await expect(loadTickets(10)).rejects.toThrow('The API answered 503');
});

vi.stubGlobal remplace fetch par une version factice qui répond immédiatement 503; le test n’a donc pas besoin d’API. Exécutez tous les tests :

Fenêtre de terminal
npm test

La sortie énumère les 21 vérifications de l’API simulée, puis le résumé de Vitest :

ℹ tests 21
ℹ pass 21
...
Test Files 1 passed (1)
Tests 4 passed (4)

Construisez ensuite les fichiers pour la production :

Fenêtre de terminal
npm run build
vite v8.3.4 building client environment for production...
transforming...
✓ 6 modules transformed.
rendering chunks...
computing gzip size...
dist/index.html 1.38 kB │ gzip: 0.62 kB
dist/assets/index-Cq7Ckq9E.css 4.20 kB │ gzip: 1.48 kB
dist/assets/index-jgaqHoif.js 1.91 kB │ gzip: 0.98 kB
✓ built in 206ms
Un flux de gauche à droite. Les fichiers src/types.ts, src/api.ts, src/main.ts et src/styles.css passent à tsc --noEmit, qui vérifie les types sans écrire de fichier. Sans erreur, ils passent à vite build, qui retire les types, regroupe les fichiers et réduit leur taille. Une erreur mène à : corriger le code. vite build écrit dist/index.html 1,38 ko, dist/assets/index-hash.js 1,91 ko et dist/assets/index-hash.css 4,20 ko.
Ce que fait npm run build : d'abord la vérification des types, puis la construction de Vite. Une erreur de type arrête la construction.
Description textuelle du diagramme

npm run build exécute deux programmes. D’abord, tsc --noEmit vérifie les types de tous les fichiers dans src/; il n’écrit rien. S’il trouve une erreur, la construction s’arrête, et vous corrigez le code. Sinon, vite build retire les types, regroupe les modules dans un seul fichier JavaScript et réduit sa taille. Il écrit le résultat dans dist/ : un fichier HTML de 1,38 ko, un fichier JavaScript de 1,91 ko et un fichier CSS de 4,20 ko.

dist/ est ce qu’un vrai serveur Web enverrait. Le JavaScript occupe 1,91 ko, et 0,98 ko après gzip, la compression que les serveurs utilisent pendant le transfert. Les noms de fichiers contiennent une empreinte, un code calculé à partir du contenu, comme index-jgaqHoif.js. Quand le contenu change, le nom change, pour que le navigateur n’utilise jamais une ancienne copie. Le module 5 mesure ces fichiers quand l’application est beaucoup plus grande.

Regardez les premières lignes de src/api.ts :

src/api.ts (the start)
export const API_URL: string = import.meta.env.VITE_API_URL ?? 'http://127.0.0.1:8100';

La page vient de http://localhost:5173, et les données de http://127.0.0.1:8100. Ce sont deux origines : une origine combine le schéma, l’hôte et le port. Les chemins ne peuvent donc plus commencer par /, comme dans bridge/app.js : la page utilise l’adresse complète de l’API. import.meta.env.VITE_API_URL lit un paramètre dans un fichier .env, si vous en créez un à partir de .env.example; ?? donne la valeur par défaut quand il n’y en a pas.

Un navigateur ne laisse pas une page lire une réponse d’une autre origine, sauf si le serveur le permet. C’est la règle de même origine et CORS (Cross-Origin Resource Sharing, partage de ressources entre origines), de la leçon Accès depuis le navigateur et CORS. L’API simulée autorise http://localhost:5173 et http://localhost:4173. Observez cela depuis le terminal, avec un en-tête Origin (origine), comme le navigateur l’envoie :

Fenêtre de terminal
curl -i -X POST http://127.0.0.1:8100/v1/tickets -H "Content-Type: application/json" -H "Origin: http://localhost:5173" -d '{"customer_id": "C-0022", "subject": "Parcel lost", "body": "It did not arrive."}'
HTTP/1.1 202 Accepted
X-Request-ID: 2a596651-427e-45a5-b167-c14804cfbfb1
Access-Control-Allow-Origin: http://localhost:5173
Vary: Origin
Access-Control-Expose-Headers: Location, Retry-After, X-Request-ID, Idempotent-Replayed
Content-Type: application/json
Location: /v1/jobs/1
...
{"ticket_id":"T-500001","job_id":1,"state":"queued","status_url":"/v1/jobs/1","queued_ahead":0,"estimated_wait_seconds":3.7}

Dans Windows PowerShell, utilisez curl.exe et mettez le JSON dans un fichier, comme le montre Examiner une requête; les guillemets y fonctionnent différemment. Faites maintenant une requête depuis une origine que l’API n’autorise pas :

Fenêtre de terminal
curl -i "http://127.0.0.1:8100/v1/tickets?limit=1" -H "Origin: http://evil.example"
HTTP/1.1 200 OK
X-Request-ID: f87a16c3-f5bc-4254-885b-b61d37c128c7
Content-Type: application/json
...

L’API a répondu 200 avec les données, mais sans en-tête Access-Control-Allow-Origin (origine autorisée). curl affiche quand même les données; un navigateur les cacherait à la page. La vérification se fait donc dans le navigateur, pour protéger l’utilisateur, et non dans l’API. Le schéma place tous les éléments de ce module au bon endroit.

Trois zones. À gauche, le navigateur, en rouge et marqué public : l'utilisateur peut tout lire et modifier de ce côté. Il contient la page (HTML pour son contenu, CSS pour son apparence, JavaScript pour ses actions), le DOM, l'arbre actuel des éléments de la page, et un appel fetch vers http://127.0.0.1:8100/v1/tickets?limit=10 avec l'en-tête Origin http://localhost:5173. En haut à droite, le serveur de développement Vite à http://localhost:5173 envoie les fichiers index.html, src/main.ts en JavaScript et styles.css; npm run build crée les mêmes fichiers dans dist. En bas à droite, l'API simulée des billets, un serveur à http://127.0.0.1:8100 : les billets en JSON; elle vérifie à nouveau chaque requête; plus tard, les clés et les secrets restent ici. Flèche 1 du navigateur vers Vite : GET / et les fichiers. Flèche 2 du navigateur vers l'API : GET /v1/tickets, à travers une boîte rouge de vérification CORS. Flèche 3 en retour : JSON et Access-Control-Allow-Origin. Une note : l'API répond à chaque requête; le navigateur transmet la réponse à la page seulement si l'en-tête nomme l'origine de la page. curl n'effectue pas cette vérification; CORS protège donc l'utilisateur dans le navigateur, et non l'API.
La frontière navigateur–frontend–API. Tout dans le navigateur est public; le serveur conserve les données et les secrets, et vérifie chaque requête.
Description textuelle du diagramme

La zone de gauche est le navigateur, et tout ce qu’elle contient est public : HTML, CSS, JavaScript et DOM. Il communique avec deux serveurs. Vite envoie les fichiers de la page (en production, n’importe quel serveur Web envoie dist/). L’API simulée envoie les données. Le navigateur transmet une réponse de l’API à la page seulement si l’en-tête Access-Control-Allow-Origin nomme l’origine de la page : c’est la vérification CORS. L’API répond quand même; elle doit donc vérifier elle-même chaque requête.

Le même schéma répond à la question principale du module : quel code s’exécute où? HTML, CSS et JavaScript s’exécutent dans le navigateur. La personne qui utilise le navigateur peut lire chaque ligne, chaque paramètre VITE_ et chaque requête dans l’onglet Network. Une clé, un mot de passe ou toute règle à appliquer doit donc se trouver sur un serveur, jamais dans la page. .env.example le dit dès ses premières lignes : Vite place chaque valeur VITE_ dans le JavaScript que le navigateur télécharge. Une leçon ultérieure sur la sécurité du navigateur le montre avec une fausse clé.

Utilisez npm, un serveur de développement et TypeScript pour toute page qui dépasse quelques fichiers ou qu’une équipe partage. Le fichier de verrouillage donne les mêmes paquets à tout le monde. La vérification des types trouve une catégorie d’erreurs avant qu’un agent les découvre.

Ces outils ont un coût. node_modules occupe 64 Mo maintenant et 135 Mo à la fin du cours. Chaque paquet est du code d’autres personnes auxquelles vous faites confiance; npm install signale les vulnérabilités connues, ici found 0 (aucune trouvée). Et la construction est une étape de plus qui peut échouer. Pour une page avec un court script, la méthode bridge/, sans outils, convient bien.

Erreur courante

La page utilise un autre port et la liste ne fonctionne plus : une erreur CORS

Symptôme : le port 5173 est occupé. Teodor démarre donc Vite sur un autre port : npm run dev -- --port 5174. La page s’ouvre à http://localhost:5174/, mais la liste affiche :

Le bureau des billets à localhost:5174 : le formulaire New ticket (nouveau billet) à gauche. À droite, le titre Newest tickets (billets les plus récents) et le texte Could not load the tickets. Failed to fetch. (Impossible de charger les billets. Échec de la récupération.)
Vite charge la page, mais la requête pour la liste échoue. La page sait seulement qu'elle n'a reçu aucune réponse utilisable. L’image est en anglais.

L’onglet Console des outils de développement indique pourquoi :

Console
Access to fetch at 'http://127.0.0.1:8100/v1/tickets?limit=10' from origin 'http://localhost:5174' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
Failed to load resource: net::ERR_FAILED

Cause : l’API simulée autorise seulement http://localhost:5173 et http://localhost:4173. Un port différent correspond à une origine différente. La réponse n’a donc pas d’en-tête Access-Control-Allow-Origin pour cette origine, et le navigateur ne la transmet pas à la page. Pour le code de la page, cela ressemble exactement à une panne réseau : fetch rejette la promesse avec Failed to fetch (échec de la récupération).

Solution : utilisez le port 5173, ou autorisez la nouvelle origine. Au démarrage, l’API simulée lit les origines autorisées dans le paramètre CORS_ORIGINS. Arrêtez-la dans le terminal 1, puis redémarrez-la avec les deux origines :

Fenêtre de terminal
CORS_ORIGINS=http://localhost:5173,http://localhost:5174 node mock-api/server.mjs

Rechargez la page : les dix billets apparaissent. Autorisez seulement les origines que vous utilisez. Une vraie API garde cette liste courte, comme l’explique le cours sur les API.

Voici l’exemple détaillé du module : une petite page avec un formulaire qui appelle l’API simulée et affiche sa réponse. Suivez les étapes en gardant chaque valeur intermédiaire visible. Le formulaire lit un billet à partir de son identifiant.

  1. Créez bridge/find.html, une page avec un seul formulaire. Elle utilise le même fichier styles.css :

    bridge/find.html (the body)
    <main class="layout">
    <section aria-labelledby="find-heading" class="card">
    <h2 id="find-heading">Find a ticket</h2>
    <form id="find">
    <label for="ticket-id">Ticket ID</label>
    <input id="ticket-id" name="ticket_id" required pattern="T-[0-9]+" placeholder="T-80008" />
    <button type="submit">Find</button>
    </form>
    <p id="result" role="status"></p>
    </section>
    </main>
    <script type="module" src="find.js"></script>

    Le <head> est le même que dans index.html, avec le titre Find a ticket (trouver un billet).

  2. Créez bridge/find.js. Chaque console.log affiche une étape :

    bridge/find.js
    // Guided practice of Module 1: read one ticket by its ID and show it, or the API's error.
    const form = document.querySelector('#find');
    const result = document.querySelector('#result');
    form.addEventListener('submit', async (event) => {
    event.preventDefault();
    const id = new FormData(form).get('ticket_id');
    const url = `/v1/tickets/${encodeURIComponent(id)}`;
    console.log('1. request', url);
    result.textContent = 'Looking…';
    try {
    const response = await fetch(url);
    console.log('2. status', response.status);
    const body = await response.json();
    console.log('3. body', JSON.stringify(body).slice(0, 70) + '…');
    result.textContent = response.ok
    ? `${body.ticket_id}: ${body.subject} (${body.status}, ${body.messages.length} messages)`
    : `Not found: ${body.error.message}`;
    } catch (error) {
    result.textContent = `The API did not answer. Is it running? (${error.message})`;
    }
    });

    encodeURIComponent rend le texte saisi sûr pour son insertion dans une adresse.

  3. Ouvrez http://127.0.0.1:8100/find.html, ouvrez l’onglet Console, tapez T-80008, puis sélectionnez Find (trouver).

  4. Lisez les trois lignes dans la Console, puis la page.

L’exécution de l’équipe du cours a affiché ces lignes dans la Console :

Console
1. request /v1/tickets/T-80008
2. status 200
3. body {"ticket_id":"T-80008","customer_id":"C-81265","customer_name":"Tariq …
La page Find a ticket (trouver un billet) : le champ Ticket ID (identifiant du billet) contient T-80008. Le bouton Find (trouver) est suivi de la réponse T-80008: Hello, where is my order LK-581106? (open, 0 messages). (T-80008 : Bonjour, où est ma commande LK-581106? [ouvert, 0 message].)
La réponse de l'exemple détaillé pour T-80008. L’image est en anglais.

Étape par étape : la valeur du formulaire est devenue l’adresse /v1/tickets/T-80008. L’API a répondu 200. Le corps contient un billet, avec messages comme tableau. Ainsi, body.messages.length vaut 0. Tapez maintenant T-99999. Le statut est 404, response.ok vaut false (faux), et la page affiche Not found: There is no ticket T-99999. (Introuvable : le billet T-99999 n’existe pas.), le message de l’API elle-même. L’instantané end-of-m01 ne contient pas find.html et find.js : supprimez-les ou mettez-les de côté quand vous avez terminé.

Créez une deuxième page, bridge/reply.html, avec bridge/reply.js. Son formulaire contient un identifiant de billet et le texte d’une réponse. Il envoie POST /v1/tickets/{id}/messages avec le corps JSON {"author": "agent", "body": "…"}. En cas de succès (201), il affiche le message_id du nouveau message. En cas d’erreur, il affiche le message de l’API et les champs incorrects. Si l’API ne répond pas, il le signale. Testez trois cas et prédisez d’abord chaque réponse : une vraie réponse à T-80008, une réponse de trois espaces et une réponse à T-99999.

Afficher une solution

bridge/reply.html reprend find.html avec un deuxième champ : <label for="reply-body">Reply</label> et <textarea id="reply-body" name="body" required rows="3" maxlength="5000"></textarea>, un bouton Send reply (envoyer la réponse) et le script reply.js :

bridge/reply.js
const form = document.querySelector('#reply');
const result = document.querySelector('#result');
form.addEventListener('submit', async (event) => {
event.preventDefault();
const data = new FormData(form);
const id = data.get('ticket_id');
result.textContent = 'Sending…';
try {
const response = await fetch(`/v1/tickets/${encodeURIComponent(id)}/messages`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ author: 'agent', body: data.get('body') }),
});
const body = await response.json();
if (response.ok) {
result.textContent = `Saved as message ${body.message_id} on ${id}.`;
form.reset();
} else {
result.textContent = `Not saved: ${body.error.message} ${body.error.fields.length ? `Fields: ${body.error.fields.join(', ')}` : ''}`.trim();
}
} catch (error) {
result.textContent = `The API did not answer. Is it running? (${error.message})`;
}
});

L’exécution de l’équipe du cours a affiché ces réponses :

Billet et réponse La page affiche
T-80008, We are checking with the courier. (Nous vérifions auprès du transporteur.) Saved as message 332 on T-80008. (Enregistré comme message 332 sur T-80008.)
T-80008, trois espaces Not saved: The request is not valid. Fields: body (Non enregistré : la requête n’est pas valide. Champs : body)
T-99999, Hello (Bonjour) Not saved: There is no ticket T-99999. (Non enregistré : le billet T-99999 n’existe pas.)

Votre numéro de message peut être différent si vous avez envoyé d’autres messages avant. L’API simulée poursuit la numérotation à partir du plus grand numéro dans ses données. Après la première réponse, find.html affiche T-80008 avec 1 messages (1 message). Redémarrez l’API pour la réinitialiser. Vérifiez votre solution avec les trois mêmes cas, et aussi avec l’API arrêtée. Les pages de cet exercice ne sont pas dans l’instantané.

Vérifiez votre compréhension

Le panneau Elements (éléments) affiche dix éléments de liste, mais View page source (afficher le code source) en affiche un seul, Loading… (chargement…). Expliquez la différence.

Afficher la réponse

View page source affiche le fichier index.html tel que le serveur l’a envoyé, avec un seul élément. Le panneau Elements affiche le DOM : l’arbre actuel de la page dans le navigateur. app.js a remplacé l’élément « Loading… » par dix nouveaux éléments dans le DOM; le fichier n’a jamais changé. Quand une page semble incorrecte, le DOM représente ce que l’utilisateur voit.

Vérifiez votre compréhension

Prédisez : vous exécutez npm run build après une faute de frappe dans src/api.ts (ticket.subjet). Que se passe-t-il, et est-ce que dist/ change?

Afficher la réponse

La construction s’arrête à sa première étape. npm run build exécute tsc --noEmit && vite build, et tsc échoue avec error TS2551: Property 'subjet' does not exist on type 'TicketSummary'. Did you mean 'subject'? (erreur TS2551 : la propriété « subjet » n’existe pas sur le type « TicketSummary ». Vouliez-vous dire « subject »?). Le && exécute vite build seulement si la première commande réussit. Donc, dist/ n’est pas réécrit : il garde les fichiers de la dernière construction réussie, ou reste absent.

Vérifiez votre compréhension

curl récupère les billets de l'API simulée avec Origin : http://evil.example. Est-ce une faille de sécurité dans le paramètre CORS de l'API? Expliquez.

Afficher la réponse

Non. CORS est une règle que le navigateur suit pour protéger son utilisateur. Il cache la réponse à une page dont l’API n’a pas nommé l’origine. L’API répond quand même à chaque requête. curl ne suit pas cette règle, donc il affiche les données. CORS ne protège jamais les données contre un client extérieur au navigateur. Pour protéger les données, l’API doit vérifier qui les demande, avec l’authentification et l’autorisation, sur le serveur.

Vérifiez votre compréhension

Vérification de fin de module : expliquez quel code du bureau des billets s'exécute dans le navigateur, et lequel doit s'exécuter sur un serveur. Donnez un exemple de ce qui ne doit jamais être dans le navigateur, et expliquez pourquoi.

Afficher la réponse

Dans le navigateur : bridge/index.html, styles.css et app.js, ainsi que la page TypeScript après la construction par Vite (dist/). Le navigateur les télécharge, construit le DOM et exécute le JavaScript sur l’ordinateur de l’utilisateur. Sur un serveur : l’API simulée (mock-api/server.mjs, avec Node.js). Elle conserve les billets, vérifie chaque requête à nouveau et décide de la réponse. Un serveur Web envoie les fichiers (Vite pendant votre travail). L’utilisateur contrôle le navigateur : il peut lire chaque ligne du script, chaque valeur VITE_ et chaque requête dans l’onglet Network (réseau). Il peut aussi modifier ou contourner n’importe quelle vérification. Une clé d’API ou un mot de passe ne doit donc jamais être dans le navigateur. Une règle obligatoire, comme déterminer qui peut lire un billet, appartient au serveur, même si la page la vérifie aussi.

Récapitulatif

  • Le DOM est l’arbre actuel de la page dans le navigateur. Le panneau Elements l’affiche, et le panneau Network affiche les requêtes.
  • npm installe les paquets de package.json (TypeScript 7.0.2, Vite 8.3.4, Vitest 5.0.3) aux versions exactes de package-lock.json. Cela représente 38 paquets et 64 Mo, jamais enregistrés dans un commit.
  • Vite sert la page pendant votre travail (npm run dev, http://localhost:5173) et la construit pour la production (npm run build : 1,91 Ko de JavaScript, 0,98 Ko avec gzip).
  • TypeScript ajoute des types que tsc --noEmit vérifie avant l’exécution du code : ticket.subjet a produit error TS2551 (erreur TS2551). Le navigateur ne voit jamais les types.
  • La page et l’API ont des origines différentes. La vérification CORS du navigateur décide donc si la page peut lire une réponse. L’API répond quand même : CORS protège l’utilisateur, pas les données.

Le module 1 en un paragraphe. Vous avez exécuté l’API simulée de billets sur votre ordinateur avec Node.js. Vous lui avez demandé des billets avec curl et le navigateur. Vous avez écrit la première page avec du HTML sémantique, des champs étiquetés et une grille CSS adaptative. Vous l’avez rendue fonctionnelle avec JavaScript : objets et tableaux, fonctions, modules, événement de soumission et fetch avec await. La page charge dix billets et en envoie un nouveau (202, T-500001). Vous l’avez ensuite transférée vers npm, Vite et TypeScript, avec 25 tests réussis et une construction de 1,91 Ko. Vous pouvez maintenant dire où chaque partie s’exécute : la page dans le navigateur, accessible à tous. Les données et chaque règle obligatoire restent sur le serveur.

Ensuite, le module 2 construit l’interface à partir de composants React.

Leçon suivante : Bases de React