Migration vers Express 4

Présentation

Express 4 est un changement novateur d’Express 3. Cela signifie qu’une application Express 3 existante ne fonctionnera pas si vous mettez à jour la version Express dans les dépendances.

Cet article couvre :

• Modifications dans Express 4.
• Un exemple de migration d'une application Express 3 vers Express 4.
• Mise à niveau vers le générateur d'applications Express 4.

Modifications dans Express 4

De nombreuses modifications importantes ont été faites dans Express 4 :

• Modification du système principal et middleware d'Express. Les dépendances Connect et des middleware intégrés ont été supprimées, vous devez donc ajouter les middleware vous-même.
• Modifications du système de routage.
• Autres modifications diverses.

Voir aussi :

• Nouvelles fonctions dans la version 4.x.
• Migration de la version 3.x vers 4.x.

Modification du système principal et middleware d'Express

Express 4 ne dépend plus de Connect, et supprime tous les middleware intégrés de son noyau, sauf la fonction express.static. Cela signifie qu’Express est désormais un canevas Web de routage et de middleware indépendant et que les versions et éditions d’Express ne sont pas affectées par les mises à jour de middleware.

Sans middleware intégré, vous devez explicitement ajouter tous les middleware requis pour exécuter votre application. Procédez comme suit :

1. Installez le module : npm install --save <module-name>
2. Dans votre application, demandez le module : require('module-name')
3. Utilisez le module en fonction de cette documentation: app.use( ... )

La table suivante répertorie le middelware Express 3 et ces équivalents dans Express 4.

Vous trouverez ici la liste complète du middleware Express 4.

Dans la plupart des cas, il vous suffit de remplacer l’ancienne version du middelware 3 par son équivalent Express 4. Pour plus d’informations, consultez la documentation relative au module dans GitHub.

app.use accepte les paramètres

Dans la version 4 vous pouvez utilisez un paramètre variable pour définir le chemin vers lequel les fonctions middleware sont chargées, puis lire la valeur de ce paramètre dans le gestionnaire de routage. Par exemple :

app.use('/book/:id', function (req, res, next) {
  console.log('ID:', req.params.id)
  next()
})

Le système de routage

Les applications chargent dorénavant les middleware de routage de manière implicite, ce qui fait que vous n’avez plus à vous soucier de l’ordre dans lequel les middleware sont chargés par rapport au middleware router.

La façon de définir des routes n’a pas changé mais le système de routage possède deux nouvelles fonctions pour vous aider à organiser vos routes :

• Une nouvelle méthode, app.route(), permettant de créer des gestionnaires de routage sous forme de chaîne pour un chemin de routage.
• Une nouvelle classe, express.Router, permettant de créer des gestionnaires de routage modulaires pouvant être montés.

méthode app.route()

La nouvelle méthode app.route() vous permet de créer des gestionnaires de routage sous forme de chaîne pour un chemin de routage. Etant donné que le chemin est spécifié à une seul emplacement, la création de routes modulaires est utile car elle réduit la redondance et les erreurs. Pour plus d’informations sur les routes, voir la documentation Router().

Voici quelques exemples de gestionnaires de chemin de chaînage définis à l’aide de la fonction app.route().

app.route('/book')
  .get(function (req, res) {
    res.send('Get a random book')
  })
  .post(function (req, res) {
    res.send('Add a book')
  })
  .put(function (req, res) {
    res.send('Update the book')
  })

classe express.Router

L’autre fonction qui aide à organiser les routes est une nouvelle classe, express.Router, que vous pouvez utiliser pour créer des gestionnaires de routage modulaires pouvant être montés. Une instance Router est un middleware et un système de routage complet ; pour cette raison, elle est souvent appelée “mini-app”.

L’exemple suivant créé une routeur en tant que module, charge un middleware dans celui-ci, définit des routes et monte le module sur un chemin dans l’application principale.

Par exemple, créez un fichier de routage nommé birds.js dans le répertoire app, avec le contenu suivant :

var express = require('express')
var router = express.Router()

// middleware specific to this router
router.use(function timeLog (req, res, next) {
  console.log('Time: ', Date.now())
  next()
})
// define the home page route
router.get('/', function (req, res) {
  res.send('Birds home page')
})
// define the about route
router.get('/about', function (req, res) {
  res.send('About birds')
})

module.exports = router

Puis, chargez le module de routage dans l’application :

var birds = require('./birds')

/// ...

app.use('/birds', birds)

L’application pourra gérer des demandes dans les chemins /birds et /birds/about, et appellera le middleware timeLog spécifique à la route.

Autres modifications

Le tableau suivant répertorie les autres modifications mineures mais importantes dans Express 4 :

Exemple de migration d'application

Voici un exemple de migration d’une application Express 3 vers Express 4. Les fichiers qui nous intéressent sont app.js et package.json.

Application de la version 3

app.js

Examinons une application Express v.3 avec le fichier app.js suivant :

var express = require('express')
var routes = require('./routes')
var user = require('./routes/user')
var http = require('http')
var path = require('path')

var app = express()

// all environments
app.set('port', process.env.PORT || 3000)
app.set('views', path.join(__dirname, 'views'))
app.set('view engine', 'pug')
app.use(express.favicon())
app.use(express.logger('dev'))
app.use(express.methodOverride())
app.use(express.session({ secret: 'your secret here' }))
app.use(express.bodyParser())
app.use(app.router)
app.use(express.static(path.join(__dirname, 'public')))

// development only
if (app.get('env') === 'development') {
  app.use(express.errorHandler())
}

app.get('/', routes.index)
app.get('/users', user.list)

http.createServer(app).listen(app.get('port'), function () {
  console.log('Express server listening on port ' + app.get('port'))
})

package.json

Voici à quoi ressemble le fichier package.json qui accompagne la version 3 :

{
  "name": "application-name",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "3.12.0",
    "pug": "*"
  }
}

Processus

Commencez le processus de migration en installant le middleware requis pour l’application Express 4 et en mettant à jour Express et Pug vers leur version la plus récente respective à l’aide de la commande suivante :

$ npm install serve-favicon morgan method-override express-session body-parser multer errorhandler express@latest pug@latest --save

Apportez les modifications suivantes à app.js :

1. Les fonctions Express Middleware intégrées express.favicon, express.logger, express.methodOverride, express.session, express.bodyParser et express.errorHandler ne sont plus disponibles sur l’objet express. Vous devez installer leurs fonctions alternatives manuellement et les charger dans l’application.

2. Vous ne devez plus charger la fonction app.router. Il ne s’agit pas d’un objet d’application Express 4 valide. Supprimez le code app.use(app.router);.

3. Assurez-vous que les fonctions middleware sont chargées dans l’ordre correct - chargez errorHandler après avoir chargé les routes d’application.

Application de la version 4

package.json

Le fait d’exécuter la commande npm ci-dessus mettra à jour package.json comme suit :

{
  "name": "application-name",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "body-parser": "^1.5.2",
    "errorhandler": "^1.1.1",
    "express": "^4.8.0",
    "express-session": "^1.7.2",
    "pug": "^2.0.0-beta6",
    "method-override": "^2.1.2",
    "morgan": "^1.2.2",
    "multer": "^0.1.3",
    "serve-favicon": "^2.0.1"
  }
}

app.js

Puis, supprimez le code non valide, chargez les middleware requis et procédez aux autres changements, le cas échéant. Voici à quoi ressemble le fichier app.js :

var http = require('http')
var express = require('express')
var routes = require('./routes')
var user = require('./routes/user')
var path = require('path')

var favicon = require('serve-favicon')
var logger = require('morgan')
var methodOverride = require('method-override')
var session = require('express-session')
var bodyParser = require('body-parser')
var multer = require('multer')
var errorHandler = require('errorhandler')

var app = express()

// all environments
app.set('port', process.env.PORT || 3000)
app.set('views', path.join(__dirname, 'views'))
app.set('view engine', 'pug')
app.use(favicon(path.join(__dirname, '/public/favicon.ico')))
app.use(logger('dev'))
app.use(methodOverride())
app.use(session({
  resave: true,
  saveUninitialized: true,
  secret: 'uwotm8'
}))
app.use(bodyParser.json())
app.use(bodyParser.urlencoded({ extended: true }))
app.use(multer())
app.use(express.static(path.join(__dirname, 'public')))

app.get('/', routes.index)
app.get('/users', user.list)

// error handling middleware should be loaded after the loading the routes
if (app.get('env') === 'development') {
  app.use(errorHandler())
}

var server = http.createServer(app)
server.listen(app.get('port'), () => {
  console.log('Express server listening on port ' + app.get('port'))
})

app.listen(app.get('port'), function () {
  console.log('Express server listening on port ' + app.get('port'))
})

Exécutez l'application

Le processus de migration est terminé et l’application est désormais une application Express 4. Pour confirmer, démarrez l’application en utilisant la commande suivante :

$ node .

Chargez http://localhost:3000 et voyez comment la page d’accueil est générée par Express 4.

Mise à niveau vers le générateur d'applications Express 4

L’outil de ligne de commande qui permet de générer une application Express est toujours express, mais pour effectuer la mise à niveau vers la nouvelle version, vous devez désinstaller le générateur d’applications Express 3 puis installer la nouvelle version d’express-generator.

Installation

Si le générateur d’applications Express 3 est installé sur votre système, vous devez le désinstaller :

$ npm uninstall -g express

En fonction de la configuration de vos privilèges de fichier et de répertoire, vous devrez exécuter cette commande avec sudo.A présent, installez le nouveau générateur :

$ npm install -g express-generator

En fonction de la configuration de vos privilèges de fichier et de répertoire, vous devrez exécuter cette commande avec sudo.

Désormais, la commande express sur votre système est mise à jour vers le générateur Express 4.

Modifications du générateur d'applications

Les options et les syntaxe de commande restent généralement identiques, avec les exceptions suivantes :

• L’option --sessions a été supprimée.
• L’option --jshtml a été supprimée.
• L’option --hogan a été ajoutée à la prise en charge de Hogan.js.

Exemple

Exécutez la commande suivante pour créer une application Express 4 :

$ express app4

Si vous examinez le contenu du fichier app4/app.js, vous remarquerez que toutes les fonctions middleware (sauf express.static) qui sont requises pour l’application sont chargées en tant que modules indépendants, et le middleware router n’est plus chargé explicitement dans l’application.

Vous noterez également que le fichier app.js est désormais un module Node.js, contrairement à l’application autonome qui a été générée par l’ancien générateur.

Après avoir installé les dépendances, démarrez l’application en utilisant la commande suivante :

$ npm start

Si vous examinez le script de démarrage npm dans le fichier package.json, vous remarquerez dorénavant que la commande qui démarre l’application est node ./bin/www alors qu’il s’agissait de node app.js dans Express 3.

Puisque le fichier app.js qui a été généré par le générateur Express 4 est désormais un module Node.js, il ne peut plus être démarré indépendamment en tant qu’application (sauf si vous modifiez le code). Le module doit être chargé dans un fichier Node.js et démarré via le fichier Node.js. Dans cet exemple, le fichier Node.js est ./bin/www.

Ni le répertoire bin ni le fichier www sans extension n’est obligatoire pour créer une application Express ou démarrer celle-ci. Ce ne sont ici que des suggestions faites par le générateur, donc n’hésitez pas à les modifier si besoin.

Pour se débarrasser du répertoire www et garder la présentation d’Express 3, supprimez la ligne module.exports = app; à la fin du fichier app.js, puis collez le code suivant à la place :

app.set('port', process.env.PORT || 3000)

var server = app.listen(app.get('port'), function () {
  debug('Express server listening on port ' + server.address().port)
})

Assurez-vous d’avoir chargé le module debug en haut du fichier app.js à l’aide du code suivant :

var debug = require('debug')('app4')

Ensuite, modifiez "start": "node ./bin/www" dans le fichier package.json en "start": "node app.js".

Vous avez à présent déplacé la fonctionnalité depuis ./bin/www de nouveau dans app.js. Cette modification n’est pas recommandée, mais l’exercice vous aide à comprendre le mode de fonctionnement du fichier ./bin/www et la raison pour laquelle le fichier app.js ne se lance plus seul.