Construisez un serveur Express 5 pas à pas : routes, middleware, corps JSON, fichiers statiques et gestionnaire d'erreurs, avec un générateur de serveur de départ et les changements de la v4 à la v5.
Express est un petit framework web pour Node.js. Installez-le avec npm install express, créez une application avec express(), ajoutez des routes comme app.get('/', handler), et démarrez-la avec app.listen(3000). Les middlewares comme express.json() s'exécutent avant vos routes, et un gestionnaire d'erreurs à quatre arguments se place en dernier.
La plupart des tutoriels Express montrent encore du code de la version 4 qui casse ou génère des avertissements en version 5, désormais installée par défaut. Ce guide utilise Express 5 de bout en bout, génère un serveur de départ avec les éléments que vous cochez, et se termine par un tableau des changements qui piègent les gens lors de la mise à jour d'un ancien projet.
Cochez les fonctionnalités voulues dans le générateur : corps JSON, fichiers statiques, un router, une page 404 et un gestionnaire d'erreurs.
Choisissez ES modules ou CommonJS selon votre package.json.
Copiez le fichier dans index.js, lancez npm install express, puis node index.js.
Lisez les sections ci-dessous pour comprendre le rôle de chaque partie et les différences entre la version 5 et la 4.
L'ordre compte : Express exécute les middlewares et les routes dans l'ordre où vous les enregistrez, donc les parseurs de corps passent en premier et le gestionnaire d'erreurs en dernier.
Dans Express 5, une route async qui lève une erreur ou est rejetée est transmise automatiquement à votre gestionnaire d'erreurs. Vous n'avez plus besoin d'envelopper chaque fonction async.
Utilisez path.join(__dirname, 'public') ou un chemin absolu pour les fichiers statiques, afin que le serveur fonctionne quel que soit le dossier depuis lequel vous le lancez.
Définissez NODE_ENV=production en production. Le gestionnaire d'erreurs intégré arrête alors d'envoyer les stack traces aux visiteurs.
Questions fréquentes
Quelle version de Node.js faut-il pour Express 5 ?
Express 5 nécessite Node.js 18 ou plus récent. Si vous êtes bloqué sur une version plus ancienne de Node, restez sur Express 4 jusqu'à ce que vous puissiez mettre à jour le runtime.
Pourquoi req.body vaut-il undefined ?
Aucun parseur de corps ne s'est exécuté pour cette requête. Ajoutez app.use(express.json()) pour le JSON ou express.urlencoded() pour les envois de formulaire avant vos routes, et assurez-vous que le client envoie un en-tête Content-Type correspondant. Dans Express 5, un corps non analysé vaut undefined et non un objet vide.
Comment écrire une route attrape-tout dans Express 5 ?
Les jokers doivent maintenant être nommés. Utilisez app.get('/*splat', handler) au lieu de '/*'. Pour inclure aussi le chemin racine, entourez-le d'accolades : '/{*splat}'.
Que fait next() ?
Il passe la requête au middleware ou à la route correspondante suivante. Appelez next() pour continuer, next(err) pour sauter vers les gestionnaires d'erreurs, ou envoyez une réponse pour arrêter la chaîne. Oublier les deux laisse la requête en suspens.
Faut-il encore utiliser body-parser ?
Pas pour le JSON et les données de formulaire. express.json() et express.urlencoded() sont intégrés. Notez que dans Express 5, l'option extended du parseur urlencoded vaut false par défaut.
Routes et paramètres
Une route, c'est une méthode, un chemin et un handler. Les segments nommés comme :id se lisent dans req.params, les query strings dans req.query, et le corps analysé dans req.body.
Répondez avec res.json() pour des données, res.send() pour du texte ou du HTML, et chaînez res.status(404) avant l'un ou l'autre pour définir le code. Express 5 n'accepte dans res.status() que des nombres entiers de 100 à 999.
Le middleware en un paragraphe
Un middleware est une fonction de req, res et next qui s'exécute avant le handler de la route. Il peut lire ou modifier la requête, terminer la réponse, ou appeler next(). La journalisation, les vérifications d'authentification, les en-têtes CORS et l'analyse du corps sont tous des middlewares, montés avec app.use() pour tous les chemins ou passés à une seule route.
Mettre en place un projet
Installer et lancer
Créez un dossier, initialisez package.json, déclarez-le comme projet ES module et installez Express.
Les routes dans leur propre fichier
Un router est une mini-application. Montez-le sous un préfixe pour que chaque chemin à l'intérieur soit relatif à celui-ci.
Les erreurs async atteignent le gestionnaire d'erreurs
Dans Express 5, une promesse rejetée dans une route est transmise pour vous. Le handler à quatre arguments, enregistré en dernier, la transforme en réponse.
D'Express 4 à 5 : ce qui a changé
Express fournit des codemods pour beaucoup de ces changements : npx codemod@latest @expressjs/v5-migration-recipe.
Code Express 4 et son remplacement en Express 5
Express 4
Express 5
Remarque
app.get('/*', ...)
app.get('/*splat', ...)
Les jokers doivent être nommés
'/:file.:ext?'
'/:file{.:ext}'
Les parties facultatives utilisent des accolades
app.del()
app.delete()
Supprimé
req.param('id')
req.params.id, req.body ou req.query
Supprimé
res.sendfile()
res.sendFile()
Supprimé
res.json(obj, 201)
res.status(201).json(obj)
Le statut n'est plus un second argument
res.redirect('back')
res.redirect(req.get('Referrer') || '/')
Le 'back' magique a été supprimé
req.body vaut {} sans analyse
req.body vaut undefined
Vérifiez avant de lire
urlencoded extended: true
extended: false par défaut
Définissez-le si vous avez besoin d'objets imbriqués