Publicar SvelteKit amb adapter-node: build, port i domini

SvelteKit no genera el mateix artefacte amb tots els adaptadors. Si una app ha de respondre al servidor, @sveltejs/adapter-node crea un servidor Node autònom. Si totes les rutes es poden generar per endavant, adapter-static publica fitxers; auto depèn de la plataforma de destinació i no és un format universal per a qualsevol allotjament.

Aquesta guia se centra en adapter-node i en les comprovacions per desplegar una aplicació pròpia des de Git amb Projects. Revisa els plans i límits actuals per confirmar que els recursos i el procés persistent hi encaixen.

Revisa les rutes abans de triar adaptador

Identifica les pàgines que fan servir +page.server, +server, hooks de servidor, sessions o dades que canvien a cada petició. Necessiten un runtime en producció. La documentació d’adaptadors de SvelteKit explica que cada adaptador prepara l’app per a una destinació diferent; la guia d’adapter-node descriu el servidor Node.

Si totes les pàgines es poden prerenderitzar, compara adapter-static i comprova els requisits de rutes i fallback. No esborris hooks ni endpoints només per aconseguir que compili si l’app els necessita.

Configura la sortida Node

Instal·la l’adaptador com a dependència de desenvolupament. A SvelteKit 3 (i versions 2.62 o posteriors), configura’l al connector de SvelteKit dins de vite.config.js; aquesta és la forma actual que hem provat amb un projecte mínim:

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

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

Els projectes antics poden tenir l’adaptador a svelte.config.js; comprova la versió instal·lada i segueix la seva guia oficial de migració abans de moure la configuració.

Conserva el fitxer de bloqueig del repositori i l’script de build que ja tingui. En un projecte npm, la seqüència habitual és:

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

L’adaptador crea build/ i el servidor accepta HOST i PORT. En local comprova la portada, les rutes dinàmiques, els endpoints i una URL inexistent. Si hi ha un proxy al davant, configura l’origen públic o les capçaleres reenviades d’acord amb el desplegament; una URL externa incorrecta pot afectar redireccions i enllaços absoluts.

Protegeix les variables i publica des de Git

SvelteKit no fa públiques totes les variables d’entorn automàticament: revisa els imports del codi. Les variables de $env/static/public o $env/dynamic/public arriben al navegador; no hi posis secrets. Desa les credencials privades a la configuració del servei.

A Projects, connecta el repositori, selecciona la branca i revisa el runtime Node, les ordres d’instal·lació i build, i la comanda d’arrencada node build. Si el pla o la detecció del projecte no permeten executar aquest procés tal com està, utilitza el flux de contenidors documentat per a l’oferta triada. No donis per fet que una compilació de desenvolupament o npm run preview és el servidor de producció.

Prova primer el domini temporal: renderització de servidor, navegació directa, formularis, inici de sessió, crides a API, fitxers, registres i reinici del procés. Connecta el domini final quan passin aquestes comprovacions i valida HTTPS i les URL de callback. Si l’app només serveix fitxers prerenderitzats, compara el cost operatiu amb Sites abans de mantenir un servidor actiu.

Prova local (9 d’octubre de 2026): un projecte mínim de SvelteKit 3.0.1 amb adapter-node 6.0.0 va passar svelte-check sense errors ni avisos i va compilar amb npm run build; HOST=127.0.0.1 PORT=3000 node build va servir la portada amb HTTP 200 i una ruta inexistent amb HTTP 404. No s’ha publicat aquesta mostra en un compte de Projects.

Fonts: adaptadors de SvelteKit, adapter-node, variables d’entorn, migració a SvelteKit 3 i Projects.