Héberger Nuxt en SSR : build Node et vérifications

Nuxt peut générer des fichiers statiques ou exécuter un serveur Node.js. Le choix dépend de la façon dont votre application gère les routes, les données et le code serveur. Ne passez pas au mode statique pour simplifier l’hébergement si cela supprime des fonctions nécessaires à votre site.

Ce guide prépare la sortie Node de Nitro et indique les points à vérifier lors de la connexion à Hostbrid Projects. Projects prend en charge les services Node et les conteneurs selon le forfait et les ressources disponibles ; consultez les forfaits et tarifs actuels avant de choisir. Ce guide ne garantit pas que tous les modules Nuxt fonctionneront sans adaptation.

Choisir entre rendu statique et serveur

nuxi generate pré-génère les routes compatibles et place les fichiers publics dans .output/public. Un serveur Node convient aux pages rendues à chaque requête, aux endpoints serveur ou aux fonctions qui dépendent de Nitro. Nuxt décrit les deux possibilités dans son guide officiel de déploiement.

Vérifiez nuxt.config, package.json, les modules et les routes utilisant defineEventHandler avant de changer de mode. Si le projet a besoin d’un rendu par requête, de cookies ou de secrets disponibles uniquement côté serveur, ne remplacez pas SSR par du HTML statique sans tester chaque fonction.

Générer et tester le serveur Node

Conservez le fichier de verrouillage et utilisez le gestionnaire qui l’a créé. Pour un projet npm :

npm ci
npm run build
NODE_ENV=production node .output/server/index.mjs

Le preset node-server de Nitro crée le point d’entrée .output/server/index.mjs ; Nuxt indique que le port par défaut est 3000 et que PORT et HOST sont configurables. En local, lancez PORT=3000 HOST=127.0.0.1 NODE_ENV=production node .output/server/index.mjs, puis vérifiez l’accueil, une route dynamique et une URL inexistante. Utilisez le vrai script build de votre package.json ; s’il exécute une autre commande, comprenez pourquoi avant de reprendre ces instructions.

Garder les variables privées

Nuxt sépare runtimeConfig privé de runtimeConfig.public. Les variables NUXT_PUBLIC_* sont accessibles au navigateur : elles ne doivent contenir ni mot de passe, ni clé de fournisseur, ni jeton administrateur. Définissez les secrets dans la configuration privée du service, jamais dans Git ou dans le code livré au navigateur. Le guide Nuxt sur la configuration d’exécution explique le lien avec les variables d’environnement.

Déployer et vérifier les routes

Connectez le dépôt à Projects, choisissez la bonne branche et définissez le build, la commande de démarrage et le runtime selon le projet et le forfait. Si le preset ne correspond pas à l’artefact Nitro, fournissez un Dockerfile qui exécute npm ci, npm run build et node .output/server/index.mjs, puis configurez le port exposé par le conteneur. Ne copiez pas une configuration générique sans contrôler la version de Node et le package.json du dépôt.

Commencez par le domaine temporaire. Vérifiez le SSR, les routes avec ou sans barre finale, les fichiers statiques, les formulaires, l’authentification, les appels API et les journaux. Configurez ensuite le domaine définitif et recommencez les tests en HTTPS. Si seules des pages pré-générées sont nécessaires, comparez la sortie statique avec Sites et évitez de maintenir un processus inutile.

Vérification locale (9 octobre 2026) : une app Nuxt 4.6.0 minimale a été compilée avec le preset node-server ; node .output/server/index.mjs a servi l’accueil en HTTP 200 et une route inexistante en HTTP 404. Cet exemple n’a pas été déployé sur un compte Projects et la compatibilité de modules tiers n’a pas été testée.

Références : déploiement Nuxt, configuration d’exécution, Projects et forfaits actuels.