Migrando para o Express 5

Visão Geral

O Express 5 não é muito diferente do Express 4: As mudanças na API não são tão significantes quanto as do 3.0 para o 4.0. Apesar de a API básica permanecer a mesma, ainda existem mudanças disruptivas; em outras palavras um programa do Express 4 existente pode não funcionar se você atualizá-lo para usar o 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"

É possível em seguida executar seus testes automatizados para verificar o que falha, e corrigir os problemas de acordo com as atualizações abaixo. Após endereçar as falhas nos testes, execute o seu aplicativo para verificar quais erros ocorrem. Você descobrirá imediatamente se o aplicativo utiliza quaisquer métodos ou propriedades que não são suportados.

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.

Mudanças no Express 5

Métodos e propriedades removidas

• app.del()
• app.param(fn)
• Nomes de métodos pluralizados
• Vírgula no início no argumento nome para o 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

Melhorias

• 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

Mudadas

• res.render()
• Brotli encoding support

Métodos e propriedades removidas

Se estiver usando qualquer um desses métodos ou propriedades no seu aplicativo, ele irá quebrar. Portanto, será necessário alterar o seu aplicativo após fazer a atualização para a versão 5.

app.del()

O Express 5 não suporta mais a função app.del(). Se você usas esta função um erro será lançado. Para registrar rotas HTTP DELETE, use a função app.delete() ao invés disso.

Inicialmente del era usada ao invés de delete, porque delete é uma palavra-chave reservada no JavaScript. Entretanto, a partir do ECMAScript 6, delete e outras palavras-chave reservadas podem legalmente ser usadas como nomes de propriedades.

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)

A assinatura app.param(fn) foi usada para modificar o comportamento da função app.param(name, fn). Ela foi descontinuada desde a v4.11.0, e o Express 5 não a suporta mais de nenhuma forma.

Nomes de métodos pluralizados

Os seguintes nomes de métodos podem ser pluralizados. No Express 4, o uso dos métodos antigos resultava em um aviso de descontinuação. O Express 5 não os suporta mais de forma nenhuma: Express 5 no longer supports them at all:

req.acceptsLanguage() é substituído por req.acceptsLanguages().

req.acceptsCharset() é substituído por req.acceptsCharsets().

req.acceptsEncoding() é substituído por 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')

  // ...
})

Dois pontos no começo (:) do nome do app.param(name, fn)

Um caractere de dois pontos (:) no início do nome para a função app.param(name, fn) é um remanescente do Express 3, e para fins de compatibilidade com versões anteriores, o Express 4 suportava-o com um aviso de descontinuação. O Express 5 irá silenciosamente ignorá-lo e usar o nome do parâmetro sem prefixá-lo com os dois pontos.

Isso não deve afetar o seu código se você seguiu a documentação do Express 4 do app.param, já que ela não menciona os dois pontos no início.

req.param(name)

Este é um método potencialmente confuso e perigoso de recuperação de dados de formulário foi removido. Você precisará agora especificamente olhar para o nome do parâmetro enviado no objeto 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)

O Express 5 não suporta mais a assinatura res.json(obj, status). Ao invés disso, configure o status e então encadeie-o ao método res.json() assim: 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)

O Express 5 não suporta mais a assinatura res.jsonp(obj, status). Ao invés disso, configure o status e então encadeie-o ao método res.jsonp() assim: 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)

O Express 5 não suporta mais a assinatura res.send(obj, status). Ao invés disso, configure o status e então encadeie-o ao método res.send() assim: 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)

O Express 5 não suporta mais a assinatura res.send(status), onde status é um número. Ao invés disso, use a função res.sendStatus(statusCode), que configura o código do status do cabeçalho de resposta HTTP e envia a versão de texto do código: “Não Encontrado”, “Erro Interno de Servidor”, e assim por diante. Se precisar enviar um número usando a função res.send(), coloque o número entre aspas para converte-lo para um sequência de caracteres, para que o Express não o interprete como uma tentativa de usar a assinatura antiga não suportada.

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()

A função res.sendfile() foi substituída pela versão em formato camel-case res.sendFile() no 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. Ela foi descontinuada desde a v4.11.0, e o Express 5 não a suporta mais de nenhuma forma.

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

Mudadas

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. Por exemplo:

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. Por exemplo:

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

O objeto app.router, que foi removido no Express 4, está de volta no Express 5. Na nove versão, este objeto é apenas uma referência para o roteador Express base, diferentemente do Express 3, onde um aplicativo tinha que carregá-lo explicitamente.

req.body

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

req.host

No Express 4, a função req.host incorretamente removia o número da porta caso estivesse presente. No Express 5 o número da porta é mantido.

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

Melhorias

res.render()

Este método agora impinge comportamento assíncrono para todos os mecanismos de visualização, evitando erros causados pelos mecanismos de visualização que tinham uma implementação síncrona e que violavam a interface recomendada.

Brotli encoding support

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