Adapter: Hosting konfigurieren

Wo der Adapter konfiguriert wird

In svelte.config.js legst du fest, welcher Adapter zum Einsatz kommt:

import adapter from '@sveltejs/adapter-auto';

export default {
    kit: {
        adapter: adapter(),
    },
};

Wechselst du den Hoster, ersetzt du den import und ggf. die adapter()-Optionen. Mehr ist nicht zu tun — vorausgesetzt, dein App-Code nutzt keine adapter-spezifischen Features.

adapter-auto — der Default

Beim Anlegen mit npx sv create ist standardmäßig @sveltejs/adapter-auto eingestellt. Wie der Name verrät: Er erkennt automatisch, in welcher Umgebung du baust, und wählt den passenden konkreten Adapter.

So funktioniert die Erkennung:

• Build auf Vercel? → adapter-vercel
• Build auf Netlify? → adapter-netlify
• Build auf Cloudflare Pages? → adapter-cloudflare
• Sonst auf einer Plattform mit erkannten Umgebungsvariablen → entsprechender Adapter

Vorteil: Du kommittest deinen Code, der CI baut und sofort funktioniert es. Nachteil: Bei lokalen Builds (npm run build ohne CI) erkennt der Auto-Adapter nichts und kann nicht zur richtigen Strategie greifen — du brauchst dann einen expliziten Adapter.

Empfehlung: Für kleine Side-Projects oder zum Ausprobieren ist adapter-auto praktisch. Für echte Produktivprojekte den konkreten Adapter explizit setzen — dann gibt es keine Überraschungen.

adapter-node — eigener Node-Server

Der Standard-Adapter für selbst gehostete Node-Setups. Nach dem Build hast du ein Verzeichnis build/ mit einem fertigen Node.js-Server, den du mit node build startest.

npm install -D @sveltejs/adapter-node

import adapter from '@sveltejs/adapter-node';

export default {
    kit: {
        adapter: adapter({
            out: 'build',           // Default
            precompress: true,      // Brotli + gzip beim Build
            envPrefix: 'PUBLIC_',   // Welche Env-Vars im Bundle landen
        }),
    },
};

Wann passt das?

• Eigener VPS (Hetzner, Linode, etc.) mit Node-Runtime.
• Docker-basierte Deployments — du baust ein Image, das node build startet.
• Hosting-Plattformen wie Render, Railway, Fly.io, die Node-Apps laufen lassen.

Der Adapter respektiert die Standard-Umgebungsvariable PORT — gut für Container-Deployments. Mit HOST lässt sich das Bind-Interface festlegen.

adapter-static — komplett statisch

Dieser Adapter erzeugt eine rein statische Site — fertige HTML-Dateien plus Assets, ohne Node-Server. Perfekt für Marketing-Seiten, Blogs, Dokumentationen.

npm install -D @sveltejs/adapter-static

import adapter from '@sveltejs/adapter-static';

export default {
    kit: {
        adapter: adapter({
            pages: 'build',        // Output-Verzeichnis
            assets: 'build',
            fallback: undefined,   // optional für SPA-Modus
            precompress: false,
            strict: true,          // Fehler bei nicht-prerenderbaren Routen
        }),
    },
};

Wichtige Voraussetzung: Alle Routen müssen prerenderbar sein. Du setzt im Root-Layout export const prerender = true und sorgst dafür, dass keine Route etwas macht, das nicht zur Build-Zeit funktioniert (Form Actions, Auth-Cookies lesen etc.).

Hosting-Optionen für statisch gebaute Apps:

• GitHub Pages — kostenlos, perfekt für Open-Source-Doku.
• Cloudflare Pages, Netlify, Vercel Static Hosting — sehr schnell, globales CDN.
• Eigener Web-Server — die Dateien einfach in den Document-Root kopieren.

SPA-Modus mit fallback

Wenn du eine reine SPA ohne Server willst (z. B. einen authenticated-only Bereich, der hinter einem CDN liegt), kannst du fallback: 'index.html' setzen. Dann erzeugt SvelteKit eine einzelne Index-Datei, und alle URLs werden auf sie geroutet — die App startet im Browser und übernimmt das Routing dort.

adapter-vercel — für Vercel-Hosting

Vercel ist eine sehr beliebte Hosting-Plattform mit Serverless- und Edge-Functions. Der adapter-vercel baut SvelteKit direkt in Vercels Function-Format.

npm install -D @sveltejs/adapter-vercel

import adapter from '@sveltejs/adapter-vercel';

export default {
    kit: {
        adapter: adapter({
            runtime: 'nodejs20.x',     // oder 'edge' für Edge Functions
            regions: ['fra1', 'iad1'], // Vercel-Regionen
        }),
    },
};

Vorteile:

• Edge Functions für extrem niedrige Latenz weltweit (mit runtime: 'edge').
• Incremental Static Regeneration (ISR) über die config.isr-Page-Option.
• Vercel-Domain kostenlos, eigene Domain einbindbar.
• Preview-Deployments für jeden Pull Request.

Nachteil: Vendor-Lock-in. Wer ohne Adapter-Wechsel weg will, kann das technisch jederzeit, aber Vercel-spezifische Features (ISR, Edge-Konfig) gehen nicht 1:1 mit zu anderen Hostern.

adapter-cloudflare — für Cloudflare Workers / Pages

Cloudflare Pages mit dem adapter-cloudflare ist eine sehr schnelle, günstige Option. Der Code läuft in Cloudflare Workers — einer Edge-Runtime auf der ganzen Welt.

npm install -D @sveltejs/adapter-cloudflare

import adapter from '@sveltejs/adapter-cloudflare';

export default {
    kit: {
        adapter: adapter({
            routes: {
                include: ['/*'],
                exclude: ['<all>'],
            },
        }),
    },
};

Wichtig zu wissen: Cloudflare Workers sind nicht Node. Sie laufen in einer abgespeckten V8-Runtime ohne fs, ohne klassische Node-Module, ohne lange Laufzeit. Wenn du Node-spezifische Bibliotheken nutzt (etwa pg für Postgres), funktionieren sie hier nicht. Lösung: Cloudflare-eigene Datenbanken (D1, KV) oder externe APIs.

Stärken: Sehr schnelle Antwortzeiten durch Edge-Computing, kostengünstig (großzügige Free-Tier), gut für globale Apps.

Adapter-Vergleich

Häufige Stolperfallen

Adapter-Wechsel ohne Re-Test. Wenn du von adapter-node auf adapter-cloudflare wechselst und deine App node:fs nutzt, fällt der Build durch — Cloudflare Workers haben keinen Filesystem-Zugriff. Auch andere Node-spezifische APIs (Buffer, manche crypto-Funktionen) haben in Edge-Runtimes nicht die gleiche Verfügbarkeit. Vor jedem Adapter-Wechsel lokal testen mit dem Ziel-Adapter.

adapter-static mit nicht-prerenderbaren Routen. Der Build bricht ab. Der Trick: Im Root-Layout prerender = true setzen — und dann jede Route prüfen, die das nicht erfüllt (Form Actions, Cookie-basierte Auth in Loads). Entweder umbauen oder mit prerender = false markieren, falls möglich.

adapter-auto lokal verwendet. Lokal weiß der Auto-Adapter nicht, was du nutzen willst. Er fällt auf eine Default-Strategie zurück, die in Production möglicherweise anders aussieht. Wer lokal testen will, setzt explizit adapter-node (für Container-Deploys) oder adapter-static.

Environment-Variablen in der Edge-Runtime. Cloudflare Workers haben kein process.env. SvelteKit hat dafür eigene Module: $env/static/private und $env/dynamic/private — die funktionieren in allen Adaptern. Wer process.env.SECRET direkt liest, fliegt im Edge-Build auf die Nase.

Build-Output-Verzeichnis verwechselt. Jeder Adapter hat seinen eigenen Output. adapter-static schreibt nach build/ (default), adapter-vercel ins von Vercel erwartete .vercel/-Format. Wer das build/-Verzeichnis manuell auf einen Server kopiert, aber den Vercel-Adapter nutzt, deployt die falsche Struktur.

Cookies verhalten sich pro Adapter unterschiedlich. Bei lokalen Tests funktioniert ein einfaches event.cookies.set('session', ...) immer. In Production, gerade bei Edge-Adaptern, brauchst du oft secure: true und sameSite: 'lax'. Default-Cookies können anders gesetzt werden, je nach Adapter — die SvelteKit-Doku-Seite zum Adapter listet die jeweiligen Defaults.

Form Actions auf statischen Hosts. adapter-static deaktiviert Server-Logik vollständig. Form Actions funktionieren nicht. Wer einen reinen Marketing-Build mit einem Kontakt-Formular braucht, muss das Form-Action zu einer separaten API auslagern (eigener Endpoint auf einem anderen Hoster oder bei einem Form-Service wie Formspree).

Adapter-Doku liest sich oft schwer. Jeder Adapter hat eigene Optionen, die in der jeweiligen npm-Page stehen — nicht in der SvelteKit-Hauptdoku. Bei spezifischen Fragen (ISR-Frist bei Vercel, Wrangler-Setup bei Cloudflare) ist die Adapter-Repository-README die richtige Quelle.

Weiterführende Ressourcen

Externe Quellen

• Adapters – svelte.dev
• adapter-node
• adapter-static
• adapter-vercel
• adapter-cloudflare

Verwandte Artikel

• Render-Modi pro Route konfigurieren
• Prerendering im Detail
• Streaming-Responses
• Setup mit SvelteKit