Migration vers Express 5

Présentation

Express 5 n’est pas très différent d’Express 4 : les modifications apportées à l’API ne sont pas aussi importantes qu’entre les versions 3.0 et 4.0. Bien que l’API de base reste identique, des modifications radicales ont été apportées ; en d’autres termes, un programme Express 4 risque de ne pas fonctionner si vous le mettez à jour pour utiliser Express 5.

To install this version, you need to have a Node.js version 18 or higher. Then, execute the following command in your application directory:

npm install "express@5"

Vous pouvez alors exécuter les tests automatisés pour voir les échecs et corriger les problèmes en fonction des mises à jour répertoriées ci-dessous. Après avoir traité les échecs de test, exécutez votre application pour détecter les erreurs qui se produisent. Vous saurez tout de suite si l’application utilise des méthodes ou des propriétés.

Express 5 Codemods

To help you migrate your express server, we have created a set of codemods that will help you automatically update your code to the latest version of Express.

Run the following command for run all the codemods available:

npx @expressjs/codemod upgrade

If you want to run a specific codemod, you can run the following command:

npx @expressjs/codemod name-of-the-codemod

You can find the list of available codemods here.

Modifications dans Express 5

Méthodes et propriétés supprimées

• app.del()
• app.param(fn)
• Noms de méthodes au pluriel
• Signe deux-points de tête dans l'argument du nom pour app.param(name, fn)
• req.param(name)
• res.json(obj, status)
• res.jsonp(obj, status)
• res.redirect('back') and res.location('back')
• res.redirect(url, status)
• res.send(body, status)
• res.send(status)
• res.sendfile()
• router.param(fn)
• express.static.mime
• express:router debug logs

Améliorations

• Path route matching syntax
• Rejected promises handled from middleware and handlers
• express.urlencoded
• app.listen
• app.router
• req.body
• req.host
• req.query
• res.clearCookie
• res.status
• res.vary

Modifié

• res.render()
• Brotli encoding support

Méthodes et propriétés supprimées

Si vous utilisez une de ces méthodes ou propriétés dans votre application, elle tombera en panne. Vous devrez donc modifier votre application après la mise à jour vers la version 5.

app.del()

Express 5 ne prend plus en charge la fonction app.del(). Si vous utilisez cette fonction, une erreur est émise. Pour enregistrer des routes HTTP DELETE, utilisez la fonction app.delete() à la place.

Initialement, del était utilisé au lieu de delete car delete est un mot clé réservé dans JavaScript. Cependant, à partir d’ECMAScript 6, delete et les autres mots clés réservés peuvent être utilisés en toute légalité comme noms de propriété.

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.del('/user/:id', (req, res) => {
  res.send(`DELETE /user/${req.params.id}`)
})

// v5
app.delete('/user/:id', (req, res) => {
  res.send(`DELETE /user/${req.params.id}`)
})

app.param(fn)

La signature app.param(fn) servait à modifier le comportement de la fonction app.param(name, fn). Elle est obsolète depuis la version 4.11.0 et Express 5 ne la prend plus en charge.

Noms de méthodes au pluriel

Les noms de méthode suivants ont été mis au pluriel. Dans Express 4, l’utilisation des anciennes méthodes ont généré un avertissement d’obsolescence. Express 5 ne les prend plus du tout en charge :

req.acceptsLanguage() est remplacé par req.acceptsLanguages().

req.acceptsCharset() est remplacé par req.acceptsCharsets().

req.acceptsEncoding() est remplacé par req.acceptsEncodings().

npx @expressjs/codemod pluralized-methods

// v4
app.all('/', (req, res) => {
  req.acceptsCharset('utf-8')
  req.acceptsEncoding('br')
  req.acceptsLanguage('en')

  // ...
})

// v5
app.all('/', (req, res) => {
  req.acceptsCharsets('utf-8')
  req.acceptsEncodings('br')
  req.acceptsLanguages('en')

  // ...
})

Signe deux-points (:) de tête dans le nom de la fonction app.param(name, fn)

Le signe deux-points (:) de tête dans le nom de la fonction app.param(name, fn) est une subsistance d’Express 3 et, pour des raisons de compatibilité avec les versions antérieures, Express 4 la prenait en charge avec un avis sur l’obsolescence. Express 5 l’ignore automatiquement et utilise le paramètre de nom sans le préfixer d’un signe deux-points.

Cela n’affectera normalement pas votre code si vous lisez la documentation Express 4 d’app.param car cela ne mentionne pas le signe deux-points de tête.

req.param(name)

Cette méthode potentiellement déroutante et dangereuse d’extraction des données de formulaire a été supprimée. Vous devrez désormais rechercher spécifiquement le nom du paramètre soumis dans l’objet req.params, req.body ou req.query.

npx @expressjs/codemod req-param

// v4
app.post('/user', (req, res) => {
  const id = req.param('id')
  const body = req.param('body')
  const query = req.param('query')

  // ...
})

// v5
app.post('/user', (req, res) => {
  const id = req.params.id
  const body = req.body
  const query = req.query

  // ...
})

res.json(obj, status)

Express 5 ne prend plus en charge la signature res.json(obj, status). A la place, définissez le statut et enchaînez-le à la méthode res.json() comme suit : res.status(status).json(obj).

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.post('/user', (req, res) => {
  res.json({ name: 'Ruben' }, 201)
})

// v5
app.post('/user', (req, res) => {
  res.status(201).json({ name: 'Ruben' })
})

res.jsonp(obj, status)

Express 5 ne prend plus en charge la signature res.jsonp(obj, status). A la place, définissez le statut et enchaînez-le à la méthode res.jsonp() comme suit : res.status(status).jsonp(obj).

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.post('/user', (req, res) => {
  res.jsonp({ name: 'Ruben' }, 201)
})

// v5
app.post('/user', (req, res) => {
  res.status(201).jsonp({ name: 'Ruben' })
})

res.redirect(url, status)

Express 5 ne prend plus en charge la signature res.send(obj, status). A la place, définissez le statut et enchaînez-le à la méthode res.send() comme suit : res.status(status).send(obj).

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.get('/user', (req, res) => {
  res.redirect('/users', 301)
})

// v5
app.get('/user', (req, res) => {
  res.redirect(301, '/users')
})

res.redirect('back') and res.location('back')

Express 5 no longer supports the magic string back in the res.redirect() and res.location() methods. Instead, use the req.get('Referrer') || '/' value to redirect back to the previous page. In Express 4, the res.redirect('back') and res.location('back') methods were deprecated.

npx @expressjs/codemod magic-redirect

// v4
app.get('/user', (req, res) => {
  res.redirect('back')
})

// v5
app.get('/user', (req, res) => {
  res.redirect(req.get('Referrer') || '/')
})

res.send(body, status)

Express 5 no longer supports the signature res.send(obj, status). Instead, set the status and then chain it to the res.send() method like this: res.status(status).send(obj).

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.get('/user', (req, res) => {
  res.send({ name: 'Ruben' }, 200)
})

// v5
app.get('/user', (req, res) => {
  res.status(200).send({ name: 'Ruben' })
})

res.send(status)

Express 5 ne prend plus en charge la signature res.send(statut), où statut est un nombre. A la place, utilisez la fonction res.sendStatus(statusCode) qui définit le code de statut de l’en-tête de réponse HTTP et envoie la version texte du code: “Not Found”, “Internal Server Error”, etc. Si vous devez envoyer un nombre à l’aide de la fonction res.send(), mettez ce nombre entre guillemets pour qu’Express ne l’interprète pas comme une tentative d’utilisation de l’ancienne signature non prise en charge.

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.get('/user', (req, res) => {
  res.send(200)
})

// v5
app.get('/user', (req, res) => {
  res.sendStatus(200)
})

res.sendfile()

La fonction res.sendfile() a été remplacée par une version CamelCase res.sendFile() dans Express 5.

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.get('/user', (req, res) => {
  res.sendfile('/path/to/file')
})

// v5
app.get('/user', (req, res) => {
  res.sendFile('/path/to/file')
})

router.param(fn)

The router.param(fn) signature was used for modifying the behavior of the router.param(name, fn) function. Elle est obsolète depuis la version 4.11.0 et Express 5 ne la prend plus en charge.

express.static.mime

In Express 5, mime is no longer an exported property of the static field. Use the mime-types package to work with MIME type values.

// v4
express.static.mime.lookup('json')

// v5
const mime = require('mime-types')
mime.lookup('json')

express:router debug logs

In Express 5, router handling logic is performed by a dependency. Therefore, the debug logs for the router are no longer available under the express: namespace. In v4, the logs were available under the namespaces express:router, express:router:layer, and express:router:route. All of these were included under the namespace express:*. In v5.1+, the logs are available under the namespaces router, router:layer, and router:route. The logs from router:layer and router:route are included in the namespace router:*. To achieve the same detail of debug logging when using express:* in v4, use a conjunction of express:*, router, and router:*.

# v4
DEBUG=express:* node index.js

# v5
DEBUG=express:*,router,router:* node index.js

Modifié

Path route matching syntax

Path route matching syntax is when a string is supplied as the first parameter to the app.all(), app.use(), app.METHOD(), router.all(), router.METHOD(), and router.use() APIs. The following changes have been made to how the path string is matched to an incoming request:

• The wildcard * must have a name, matching the behavior of parameters :, use /*splat instead of /*

// v4
app.get('/*', async (req, res) => {
  res.send('ok')
})

// v5
app.get('/*splat', async (req, res) => {
  res.send('ok')
})

// v5
app.get('/{*splat}', async (req, res) => {
  res.send('ok')
})

• The optional character ? is no longer supported, use braces instead.

// v4
app.get('/:file.:ext?', async (req, res) => {
  res.send('ok')
})

// v5
app.get('/:file{.:ext}', async (req, res) => {
  res.send('ok')
})

• Regexp characters are not supported. Par exemple :

app.get('/[discussion|page]/:slug', async (req, res) => {
  res.status(200).send('ok')
})

should be changed to:

app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => {
  res.status(200).send('ok')
})

• Some characters have been reserved to avoid confusion during upgrade (()[]?+!), use \ to escape them.
• Parameter names now support valid JavaScript identifiers, or quoted like :"this".

Rejected promises handled from middleware and handlers

Request middleware and handlers that return rejected promises are now handled by forwarding the rejected value as an Error to the error handling middleware. This means that using async functions as middleware and handlers are easier than ever. When an error is thrown in an async function or a rejected promise is awaited inside an async function, those errors will be passed to the error handler as if calling next(err).

Details of how Express handles errors is covered in the error handling documentation.

express.urlencoded

The express.urlencoded method makes the extended option false by default.

app.listen

In Express 5, the app.listen method will invoke the user-provided callback function (if provided) when the server receives an error event. In Express 4, such errors would be thrown. This change shifts error-handling responsibility to the callback function in Express 5. If there is an error, it will be passed to the callback as an argument. Par exemple :

const server = app.listen(8080, '0.0.0.0', (error) => {
  if (error) {
    throw error // e.g. EADDRINUSE
  }
  console.log(`Listening on ${JSON.stringify(server.address())}`)
})

app.router

L’objet app.router, qui a été supprimé dans Express 4, est revenu dans Express 5. Dans la version, cet objet n’est qu’une référence dans le routeur Express de base, contrairement à Express 3, où une application devait le charger explicitement.

req.body

The req.body property returns undefined when the body has not been parsed. In Express 4, it returns {} by default.

req.host

Dans Express 4, la req.host retirait de manière incorrecte le numéro de port s’il était présent. Dans Express 5, ce numéro de port est conservé.

req.query

The req.query property is no longer a writable property and is instead a getter. The default query parser has been changed from “extended” to “simple”.

res.clearCookie

The res.clearCookie method ignores the maxAge and expires options provided by the user.

res.status

The res.status method only accepts integers in the range of 100 to 999, following the behavior defined by Node.js, and it returns an error when the status code is not an integer.

res.vary

The res.vary throws an error when the field argument is missing. In Express 4, if the argument was omitted, it gave a warning in the console

Améliorations

res.render()

Cette méthode impose désormais un comportement asynchrone pour tous les moteurs de vue. Cela évite les bogues générés par les moteurs de vue qui avaient une implémentation synchrone et qui ne prenaient pas en compte l’interface recommandée.

Brotli encoding support

Express 5 supports Brotli encoding for requests received from clients that support it.