Intégrer Next.js dans une API Express déployée sur Vercel

Intégrer Next.js dans une API Express déployée sur Vercel est une approche de plus en plus répandue pour bâtir des projets fullstack cohérents : un seul dépôt, un seul déploiement, et la puissance du rendu hybride de Next.js côté serveur. Ce tutoriel, deuxième volet de notre série, vous guide pas à pas pour ajouter Next.js à une base Express existante, en évitant les pièges courants.

Ce guide fait suite à la Phase 1 de notre guide qui couvre la création d'une API Express de zéro. Si vous débutez, commencez par là.

---

Prérequis et contexte

Avant de vous lancer, vérifiez que vous disposez bien des éléments suivants :

• Node.js installé (version 18+ recommandée pour Next.js 14)
• Connaissances de base en JavaScript et en principes d'API REST
• Un compte Vercel (gratuit pour commencer)

Pourquoi combiner Express et Next.js ? Express gère vos routes API métier avec une flexibilité totale (middlewares, authentification, logique serveur), tandis que Next.js prend en charge le rendu des pages React côté serveur ou en statique. Ensemble, ils forment une stack fullstack sans friction supplémentaire.

Deux articles de référence pour aller plus loin dans cette architecture :

• Créer une API personnalisée Express déployée sur Vercel
• Implémentation du pattern MVC

---

Étape 1 : Cloner le projet de départ

Commencez par récupérer le dépôt de départ. Il contient une API Express minimale sans couche Next.js, ce qui nous sert de base propre.

git clone https://github.com/Drylead/starter-basic-api-js
cd starter-basic-api-js

Piège fréquent : ne pas se placer dans le bon répertoire avant d'installer les dépendances. Vérifiez toujours que vous êtes bien dans starter-basic-api-js avant de poursuivre.

---

Étape 2 : Configuration des dépendances

Nous installons Next.js, React et React DOM, et nous supprimons body-parser — ce paquet est superflu depuis Express 4.16+ qui embarque nativement express.json() et express.urlencoded().

// Paramètrage le projet
npm install # ou `yarn install`
// Installation du paquet NextJS 
npm install next # ou `yarn add next`
// Installation du paquet React
npm install react # ou `yarn add react`
// Installation du paquet React DOM 
npm install react-dom # ou `yarn add react-dom`
// Suppression du paquet Body-parser 
npm uninstall body-parser # ou `yarn remove body-parser`

Pourquoi supprimer body-parser ? Depuis Express 4.16, les méthodes express.json() et express.urlencoded() sont intégrées au framework. Garder body-parser crée un doublon inutile et peut provoquer des conflits sur la lecture du corps de la requête.

---

Étape 3 : Intégrer Next.js dans le fichier principal

C'est l'étape clé. Nous modifions index.js pour initialiser l'application Next.js en amont du serveur Express. Le principe : app.prepare() installe le moteur de rendu Next.js, puis Express prend le relais pour gérer les routes API.

const express = require('express');
const cors = require('cors');
const next = require('next');

const dev = process.env.NODE_ENV !== 'production';
const app = next({ dev });
const handle = app.getRequestHandler();

const Datas = require('./datas.json');
const PORT = process.env.PORT || 3000;

app.prepare().then(() => {
    const server = express();

    const corsOptions = {
        origin: ['*'],
        optionsSuccessStatus: 200,
    };

    server.use(cors(corsOptions));

    server.use(express.json());
    server.use(express.urlencoded({ extended: true }));

    // Point de terminaison racine
    server.get('/', (req, res) => {
        res.send('Hello world');
    });
    // Point de terminaison pour récupérer tous les éléments
    server.get('/items', (req, res) => {
        if (!Datas || Datas.length === 0) {
            return res.status(500).json({ message: 'Erreur technique' });
        }
        res.json(Datas);
    });


    // Point de terminaison pour récupérer un élément spécifique par son identifiant
    server.get('/items/:id([0-9]+)', (req, res) => {
        const id = parseInt(req.params.id, 10);
        if (isNaN(id)) {
            return res.status(400).json({ message: 'Identifiant invalide' });
        }
        const item = Datas.find(data => data.id === id);
        if (!item) {
            return res.status(404).json({ message: 'Élément non trouvé' });
        }
        res.json(item);
    });

    server.listen(PORT, (err) => {
        if (err) throw err;
        console.log(`🚀 Server ready at: http://localhost:${PORT} ⭐️`);
    });
});

Dans cet exemple, app.prepare() permet de s'assurer que tout est prêt avant de démarrer, et Express permet de gérer des routes et des middlewares personnalisés. Cette préparation préalable améliore les performances au démarrage de l'application et garantit que toutes les ressources sont bien disponibles lorsque le serveur est prêt.

Points d'attention sur ce code :

• La variable dev est positionnée sur true si NODE_ENV n'est pas production. Vercel injecte automatiquement NODE_ENV=production lors du déploiement — veillez à ne pas l'écraser dans votre configuration.
• handle est le gestionnaire par défaut de Next.js. Si vous souhaitez que Next.js serve certaines pages React, ajoutez server.all('*', (req, res) => handle(req, res)) après vos routes Express. Sans cela, Next.js ne servira aucune page côté navigateur.
• Le CORS origin: ['*'] est acceptable en développement, mais en production, restreignez les origines autorisées aux domaines réels de votre application.

---

Étape 4 : Déployer sur Vercel

Vercel détecte automatiquement les projets Next.js. Le déploiement s'enclenche à chaque push sur la branche configurée (généralement main).

Si c'est votre premier déploiement :

1. Connectez-vous sur vercel.com et importez votre dépôt GitHub.
2. Vercel détecte Next.js et configure le build automatiquement.
3. Les variables d'environnement (comme NODE_ENV) sont injectées au runtime — pas besoin de fichier .env en production.

Une fois déployé, testez vos endpoints directement via l'URL Vercel générée :

• GET /items → retourne la liste complète
• GET /items/1 → retourne l'élément avec l'identifiant 1

Retrouvez l'exemple complet sur GitHub (branche version_nextjs).

---

Pourquoi utiliser un serveur personnalisé ?

Utiliser un serveur personnalisé avec Next.js et Express offre plusieurs avantages selon les besoins de l'application :

1. Gestion de routes avancées — Express permet des patterns de routes plus complexes que le système de fichiers de Next.js, avec des expressions régulières comme :id([0-9]+).
2. Intégration de middlewares personnalisés — authentification JWT, rate limiting, logging structuré : tout s'insère proprement dans la chaîne Express.
3. Optimisation des performances — app.prepare() initialise le moteur de rendu une seule fois au démarrage, réduisant la latence des premières requêtes.
4. Intégration avec des services externes — connexion à une base de données, webhooks, tâches planifiées : Express offre un environnement serveur complet, non limité aux routes Next.js.

Limite importante : Vercel recommande d'éviter les serveurs Express personnalisés sur son infrastructure pour les projets purement Next.js, car cela contourne certaines optimisations edge natives. Cette architecture est particulièrement adaptée lorsque vous avez besoin d'une vraie couche API indépendante du frontend.

---

FAQ

Q : Peut-on utiliser TypeScript à la place de JavaScript dans ce projet ?

Oui. Renommez index.js en index.ts, ajoutez @types/node, @types/express et @types/react à vos dépendances de développement, et configurez un tsconfig.json. Next.js supporte TypeScript nativement et générera sa propre configuration tsconfig si aucune n'existe.

Q : Pourquoi mon API fonctionne en local mais renvoie une erreur 500 sur Vercel ?

Les causes les plus fréquentes sont : une variable d'environnement non déclarée dans le tableau de bord Vercel, un fichier de données (datas.json) absent du dépôt (listé dans .gitignore), ou une dépendance manquante dans package.json. Consultez les logs de déploiement Vercel pour identifier l'erreur exacte.

Q : Comment ajouter une base de données à cette architecture ?

Connectez votre client de base de données (PostgreSQL, MySQL, MongoDB) dans app.prepare().then(...) avant de démarrer le serveur. Les connexions sont ainsi initialisées une seule fois. Sur Vercel, privilégiez des services compatibles serverless comme PlanetScale, Neon ou MongoDB Atlas pour éviter les problèmes de connexions persistantes.

---

Vous souhaitez aller plus loin et appliquer le pattern MVC à cette architecture ? Le prochain volet de la série couvre la structuration en modèles, contrôleurs et services. Si vous préférez déléguer la création ou la maintenance de votre application web, l'équipe Drylead peut vous accompagner sur votre projet.

Pour aller plus loin

• Création site Node ExpressJS : API performante
• Création site Strapi : CMS headless performant
• Création site Next.js SEO