Skip to content

Commit

Permalink
Update migration guide (#1610)
Browse files Browse the repository at this point in the history
* add `res.query` and `res.redirect`
* add `express.urlencoded` and `req.body`
* add `res.clearCookie` and `res.status`
* update introduction page
* add `res.redirect('back')` and `res.location('back')`
* bring changes from #1317
* add `brotli` support
* adapt router matching syntax
  • Loading branch information
bjohansebas authored Oct 6, 2024
1 parent 6f59979 commit 5bbc22a
Showing 1 changed file with 61 additions and 12 deletions.
73 changes: 61 additions & 12 deletions en/guide/migrating-5.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ redirect_from: "/guide/migrating-5.html"

<h2 id="overview">Overview</h2>

Express 5.0 is still in the beta release stage, but here is a preview of the changes that will be in the release and how to migrate your Express 4 app to Express 5.
Express 5 is not very different from Express 4; although it maintains the same basic API, there are still changes that break compatibility with the previous version. Therefore, an application built with Express 4 might not work if you update it to use Express 5.

To install the latest beta and to preview Express 5, enter the following command in your application root directory:
To install this version, you need to have a Node.js version 18 or higher. Then, execute the following command in your application directory:

```console
$ npm install "express@>={{ site.data.express.next_version }}" --save
Expand All @@ -31,6 +31,8 @@ You can then run your automated tests to see what fails, and fix problems accord
<li><a href="#req.param">req.param(name)</a></li>
<li><a href="#res.json">res.json(obj, status)</a></li>
<li><a href="#res.jsonp">res.jsonp(obj, status)</a></li>
<li><a href="#magic-redirect">res.redirect('back') and res.location('back')</a></li>
<li><a href="#res.redirect">res.redirect(url, status)</a></li>
<li><a href="#res.send.body">res.send(body, status)</a></li>
<li><a href="#res.send.status">res.send(status)</a></li>
<li><a href="#res.sendfile">res.sendfile()</a></li>
Expand All @@ -41,15 +43,21 @@ You can then run your automated tests to see what fails, and fix problems accord
<ul class="doclist">
<li><a href="#path-syntax">Path route matching syntax</a></li>
<li><a href="#rejected-promises">Rejected promises handled from middleware and handlers</a></li>
<li><a href="#express.urlencoded">express.urlencoded</a></li>
<li><a href="#app.router">app.router</a></li>
<li><a href="#req.body">req.body</a></li>
<li><a href="#req.host">req.host</a></li>
<li><a href="#req.query">req.query</a></li>
<li><a href="#res.clearCookie">res.clearCookie</a></li>
<li><a href="#res.status">res.status</a></li>
<li><a href="#res.vary">res.vary</a></li>
</ul>

**Improvements**

<ul class="doclist">
<li><a href="#res.render">res.render()</a></li>
<li><a href="#brotli-support">Brotli encoding support</a></li>
</ul>

<h3>Removed methods and properties</h3>
Expand Down Expand Up @@ -94,13 +102,22 @@ Express 5 no longer supports the signature `res.json(obj, status)`. Instead, set

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

<h4 id="res.redirect">res.redirect(url, status)</h4>

Express 5 no longer supports the signature `res.redirect(url, status)`. Instead, use the following signature: `res.redirect(status, url)`.


<h4 id="magic-redirect">res.redirect('back') and res.location('back')</h4>

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.

<h4 id="res.send.body">res.send(body, status)</h4>

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)`.

<h4 id="res.send.status">res.send(status)</h4>

Express 5 no longer supports the signature <code>res.send(<em>status</em>)</code>, where _`status`_ is a number. Instead, use the `res.sendStatus(statusCode)` function, which sets the HTTP response header status code and sends the text version of the code: "Not Found", "Internal Server Error", and so on.
Express 5 no longer supports the signature `res.send(status)`, where `status` is a number. Instead, use the `res.sendStatus(statusCode)` function, which sets the HTTP response header status code and sends the text version of the code: "Not Found", "Internal Server Error", and so on.
If you need to send a number by using the `res.send()` function, quote the number to convert it to a string, so that Express does not interpret it as an attempt to use the unsupported old signature.

<h4 id="res.sendfile">res.sendfile()</h4>
Expand All @@ -113,26 +130,42 @@ The `res.sendfile()` function has been replaced by a camel-cased version `res.se

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:

- Add new `?`, `*`, and `+` parameter modifiers.
- Matching group expressions are only RegExp syntax.
* `(*)` is no longer valid and must be written as `(.*)`, for example.
- Named matching groups no longer available by position in `req.params`.
* `/:foo(.*)` only captures as `req.params.foo` and not available as `req.params[0]`.
- Regular expressions can only be used in a matching group.
* `/\\d+` is no longer valid and must be written as `/(\\d+)`.
- Special `*` path segment behavior removed.
* `/foo/*/bar` will match a literal `*` as the middle segment.
- The wildcard `*` must have a name, matching the behavior of parameters `:`, use `/*splat` instead of `/*`
- The optional character `?` is no longer supported, use braces instead: `/:file{.:ext}`.
- Regexp characters are not supported. For example:
```js
app.get('/[discussion|page]/:slug', async (req, res) => {
res.status(200).send('ok')
})
```
should be changed to:
```js
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"`.

<h4 id="rejected-promises">Rejected promises handled from middleware and handlers</h4>

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 `await`ed 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](/en/guide/error-handling.html).

<h4 id="express.urlencoded">express.urlencoded</h4>

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

<h4 id="app.router">app.router</h4>

The `app.router` object, which was removed in Express 4, has made a comeback in Express 5. In the new version, this object is a just a reference to the base Express router, unlike in Express 3, where an app had to explicitly load it.

<h4 id="req.body">req.body</h4>

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

<h4 id="req.host">req.host</h4>

In Express 4, the `req.host` function incorrectly stripped off the port number if it was present. In Express 5, the port number is maintained.
Expand All @@ -141,8 +174,24 @@ In Express 4, the `req.host` function incorrectly stripped off the port number i

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".

<h4 id="res.clearCookie">res.clearCookie</h4>

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

<h4 id="res.status">res.status</h4>

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.

<h4 id="res.query">res.vary</h4>

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

<h3>Improvements</h3>

<h4 id="res.render">res.render()</h4>

This method now enforces asynchronous behavior for all view engines, avoiding bugs caused by view engines that had a synchronous implementation and that violated the recommended interface.

<h4 id="brotli-support">Brotli encoding support</h4>

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

0 comments on commit 5bbc22a

Please sign in to comment.