Déployer SvelteKit avec adapter-node : build, port et domaine

SvelteKit ne produit pas le même artefact avec tous ses adaptateurs. Pour une application qui doit répondre côté serveur, @sveltejs/adapter-node crée un serveur Node autonome. Si toutes les routes peuvent être générées à l’avance, adapter-static publie des fichiers ; auto dépend de la plateforme cible et ne constitue pas un format universel pour tous les hébergeurs.

Ce guide porte sur adapter-node et les vérifications à effectuer avant de déployer votre dépôt Git avec Projects. Consultez les forfaits et limites actuels pour vérifier que les ressources et le processus persistant sont adaptés.

Vérifier les routes avant de choisir un adaptateur

Repérez les pages qui utilisent +page.server, +server, des hooks serveur, des sessions ou des données modifiées à chaque requête. Ces routes ont besoin d’un runtime en production. La documentation des adaptateurs SvelteKit explique que chaque adaptateur prépare l’application pour une cible différente ; le guide adapter-node décrit le serveur Node.

Si toutes les pages peuvent être pré-générées, comparez adapter-static et vérifiez ses exigences de routes et de fallback. Ne supprimez pas de hooks ou d’endpoints pour faire compiler le projet s’ils sont nécessaires à l’application.

Configurer la sortie Node

Installez l’adaptateur comme dépendance de développement. Avec SvelteKit 3 (et les versions 2.62 ou ultérieures), configurez-le dans le plugin SvelteKit de vite.config.js ; c’est la forme actuelle testée avec un projet minimal :

import adapter from '@sveltejs/adapter-node';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [sveltekit({ adapter: adapter() })]
});

Les projets plus anciens peuvent définir l’adaptateur dans svelte.config.js ; vérifiez la version installée et suivez son guide de migration officiel avant de déplacer la configuration.

Conservez le fichier de verrouillage du dépôt et son script de build. Pour un projet npm, la séquence habituelle est :

npm ci
npm run build
HOST=127.0.0.1 PORT=3000 node build

L’adaptateur crée build/ et le serveur accepte HOST et PORT. En local, testez l’accueil, les routes dynamiques, les endpoints et une URL inexistante. Si un proxy se trouve devant, configurez l’origine publique ou les en-têtes transmis de façon cohérente ; une URL externe incorrecte peut fausser les redirections et les liens absolus.

Protéger les variables et déployer depuis Git

SvelteKit ne rend pas toutes les variables d’environnement publiques par défaut : vérifiez les imports employés par le code. Les variables de $env/static/public ou $env/dynamic/public sont livrées au navigateur et ne doivent pas contenir de secrets. Gardez les identifiants privés dans la configuration du service.

Dans Projects, connectez le dépôt, choisissez la branche et vérifiez le runtime Node, l’installation, le build et la commande de démarrage node build. Si le forfait ou la détection du projet ne permet pas ce processus tel quel, utilisez le parcours de conteneur documenté pour l’offre choisie. Un build de développement ou npm run preview ne prouve pas que le serveur de production fonctionne.

Testez d’abord le domaine temporaire : rendu serveur, navigation directe, formulaires, connexion, appels API, fichiers, journaux et redémarrage du processus. Configurez le domaine final après ces essais, puis vérifiez HTTPS et les URL de callback. Si l’app sert uniquement des fichiers pré-générés, comparez le coût opérationnel avec Sites avant de garder un serveur actif.

Test local (9 octobre 2026) : un projet minimal SvelteKit 3.0.1 avec adapter-node 6.0.0 a passé svelte-check sans erreur ni avertissement et npm run build ; HOST=127.0.0.1 PORT=3000 node build 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.

Sources : adaptateurs SvelteKit, adapter-node, variables d’environnement, migration vers SvelteKit 3 et Projects.