Express : installation et premier serveur

Express est le framework web minimaliste de référence pour Node.js : routes, middlewares, API JSON, fichiers statiques. Cette rubrique décrit Express 5, la version courante. Les exemples utilisent des noms génériques (monapi, port 3000).

Prérequis

Express 5 demande Node.js 18 ou plus récent. Voir Node.js : installation et Node.js : gérer les versions.

node --version
npm --version

Créer un projet

mkdir monapi && cd monapi
npm init -y
npm install express

Dans package.json, activer les modules ES (import) et ajouter les scripts :

{
  "name": "monapi",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node src/serveur.js",
    "dev": "node --watch src/serveur.js"
  }
}

node --watch redémarre le serveur à chaque modification de fichier : aucun outil supplémentaire n’est nécessaire en développement.

Premier serveur

src/serveur.js :

import express from 'express';

const app = express();
const port = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.send('Bonjour depuis Express');
});

app.get('/sante', (req, res) => {
  res.json({ statut: 'ok' });
});

app.listen(port, '127.0.0.1', () => {
  console.log(`Serveur en écoute sur http://127.0.0.1:${port}`);
});

npm run dev
curl http://127.0.0.1:3000/
curl http://127.0.0.1:3000/sante

Écouter sur 127.0.0.1 rend le serveur inaccessible de l’extérieur : un reverse proxy local le publie (voir Sécurité et production).

Séparer l’application et le démarrage

Pour faciliter les tests, exporter l’application sans l’écouter :

src/app.js :

import express from 'express';

export const app = express();
app.get('/sante', (req, res) => res.json({ statut: 'ok' }));

src/serveur.js :

import { app } from './app.js';

const port = Number(process.env.PORT) || 3000;
app.listen(port, '127.0.0.1', () => console.log(`Écoute sur ${port}`));

Structure conseillée

monapi/
├── package.json
├── src/
│   ├── app.js
│   ├── serveur.js
│   ├── routes/
│   │   └── clients.js
│   ├── middlewares/
│   │   └── erreurs.js
│   └── services/
├── public/              # fichiers statiques
├── views/               # modèles de pages (optionnel)
└── .env                 # non versionné

.gitignore :

node_modules/
.env

Configuration par l’environnement

export PORT=3000
export NODE_ENV=production
node src/serveur.js

Avec Node.js 20.6 ou plus, charger un fichier .env sans dépendance :

node --env-file=.env src/serveur.js

.env :

PORT=3000
NODE_ENV=development

Ne jamais versionner .env quand il contient des secrets.

Changements d’Express 4 à Express 5

Migrer une application Express 4 demande de vérifier :

Syntaxe des chemins : le caractère * seul n’est plus valide, il faut nommer le joker (/*splat), et le paramètre optionnel s’écrit {/:id} au lieu de /:id?.
Erreurs asynchrones : une promesse rejetée (ou une fonction async qui lève une erreur) dans un gestionnaire est transmise automatiquement au gestionnaire d’erreurs ; le try/catch avec next(err) n’est plus obligatoire.
req.body vaut undefined quand aucun analyseur de corps (express.json()) n’a été appliqué (il valait {}).
Supprimés : app.del() (utiliser app.delete()), req.param() (utiliser req.params, req.body ou req.query), res.redirect('back'), res.send(statut) (utiliser res.sendStatus(statut)).
express.urlencoded : l’option extended vaut false par défaut.

Le guide officiel de migration (expressjs.com/en/guide/migrating-5.html) détaille tous les changements.

Dépannage

Symptôme	Piste
`Cannot use import statement outside a module`	Ajouter `"type": "module"` dans `package.json`, ou utiliser `require`
`Error [ERR_MODULE_NOT_FOUND]`	En ES modules, l’extension est obligatoire dans les imports relatifs (`./app.js`)
`listen EADDRINUSE: address already in use`	Port occupé : `sudo ss -tlnp \| grep 3000`
`Cannot GET /chemin`	Route inexistante ou mauvaise méthode HTTP
Le navigateur n’atteint pas le serveur	Écoute sur `127.0.0.1` : normal depuis une autre machine
`TypeError: Missing parameter name` au démarrage	Chemin au format Express 4 (`*`, `/:id?`) dans Express 5

Ubuntu 24.04 et 26.04 : différences à connaître

Express fonctionne de la même façon sur les deux versions ; seule compte la version de Node.js installée. Le paquet d’Ubuntu (node-express) n’est pas utilisé : installer Express avec npm dans le projet.

Pour aller plus loin

Documentation : expressjs.com
Suite : Routes