Skip to content

Document path-to-regexp migration #1316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
euoia wants to merge 5 commits into from
Closed

Document path-to-regexp migration #1316

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b795a3e
Remove references to alpha, simplify intro
euoia Jan 3, 2022
0ec09ea
Migration docs based on pillarjs/router/pull/102/files
euoia Jan 3, 2022
9795c43
Revert accidental changes to Gemfile
euoia Jan 3, 2022
14ee279
Add pillarjs/router changes from 2.0.0-beta.1
euoia Jan 5, 2022
0b1e712
Remove references to Express v3
euoia Jan 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 15 additions & 8 deletions en/guide/migrating-5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,22 +9,20 @@ redirect_from: "/guide/migrating-5.html"

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

Express 5.0 is still in the alpha 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 the basic API remains the same, there are still breaking changes; in other words an existing Express 4 program might not work if you update it to use Express 5.

Express 5 is not very different from Express 4: The changes to the API are not as significant as from 3.0 to 4.0. Although the basic API remains the same, there are still breaking changes; in other words an existing Express 4 program might not work if you update it to use Express 5.

To install the latest alpha and to preview Express 5, enter the following command in your application root directory:
To install Express 5, execute the following command in your application directory:

```console
$ npm install express@>=5.0.0-alpha.8 --save
$ npm install --save express@>=5.0.0
```

You can then run your automated tests to see what fails, and fix problems according to the updates listed below. After addressing test failures, run your app to see what errors occur. You'll find out right away if the app uses any methods or properties that are not supported.
You can then run your tests to see what fails, and fix problems according to the updates listed below. After addressing test failures, run your app to see what errors occur. You'll find out right away if the app uses any methods or properties that are not supported.

<h2 id="changes">Changes in Express 5</h2>

Here is the list of changes (as of the alpha 2 release ) that will affect you as a user of Express.
See the [pull request](https://github.com/expressjs/express/pull/2237) for a list of all the planned features.
Here is the list of changes that will affect you as a user of Express.
See [this pull request](https://github.com/expressjs/express/pull/2237) for a more detailed list of all features.

**Removed methods and properties**

Expand Down Expand Up @@ -116,6 +114,14 @@ The `res.sendfile()` function has been replaced by a camel-cased version `res.se

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.

The new version of the router contains **breaking changes** to the way paths are parsed:
Copy link

@nfantone nfantone Jan 3, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are great, but we should also include and list changes from 2.0.0-beta.1. In a nutshell, these are:

  • New ?, *, and + parameter modifiers (e.g.: /users/:user+ now matches /users/1, /users/1/2, etc. but not /users)
  • Special * path segment behavior removed. This means that * is no longer a valid path and /foo/*/bar now matches a literal '*'. For the previous behaviour, a (.*) matching group should be used instead.
  • Regular expressions can only be used in a matching group (e.g.: /users/\\d+ is now invalid and should be written as /users/(\\d+)).

Copy link
Contributor Author

@euoia euoia Jan 4, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, fantastic, I'll update the documentation.

I guess it might be worth stating that Express 5 uses path-to-regexp 6, and linking to the documentation for that. Similar to this page (see "Express uses path-to-regexp"):
http://expressjs.com/en/guide/routing.html#route-paths

Which leads a bit deeper down the rabbit hole - that page itself should possibly be updated, but is not versioned. Any suggestions on how to proceed?

I suppose it may also be worth forking http://forbeslindesay.github.io/express-route-tester/ in order to create a version for Express 5.

Copy link

@nfantone nfantone Jan 4, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 to all.

that page itself should possibly be updated, but is not versioned. Any suggestions on how to proceed?

None from my side. Core maintainers should help us here!

Copy link
Contributor Author

@euoia euoia Jan 5, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The migration guide has been updated with 14ee27 - @nfantone please have a look and let me know if it's okay.

@dougwilson how should we update the routing guide? If we follow the error handling guide (which is also unversioned) there's a section "Starting in Express v5..." - perhaps we could do that?

I think my preference would be to have separate documentation for version 5 versus version 4, but obviously that's a larger undertaking.


1. It is now possible to use named capturing groups in paths using `RegExp`, for example `/\/(?<group>.+)/` would result in `req.params.group` being populated.
2. Custom prefix and suffix groups are now supported using `{}`, for example `/:entity{-:action}?` would match `/user` and `/user-delete`.
3. Unbalanced patterns now produce an error. For example `/test(foo` previously worked, but now the opening parenthesis `(` must be escaped to match the previous behavior: `/test\\(foo`.
4. As with parentheses, curly brackets also require escaping. That is, `/user{:id}` no longer matches `/user{42}` as before unless written as `/user\\{:id\\}`.


<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 @@ -124,6 +130,7 @@ In Express 4, the `req.host` function incorrectly stripped off the port number i

In Express 4.7 and Express 5 onwards, the query parser option can accept `false` to disable query string parsing when you want to use your own function for query string parsing logic.


<h3>Improvements</h3>

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