Mobile Apps mit SvelteKit und Capacitor bauen

In diesem Tutorial starten wir mit einer neuen SvelteKit App und wechseln zur nativen mobilen Entwicklung mit Capacitor. Du kannst zudem Capgo Native Navigation und Transitions für ein natives Feeling hinzufügen und tailwind-capacitor für Safe Areas nutzen.

Capacitor ermöglicht es dir, deine SvelteKit Web-App ganz einfach in eine native mobile App zu verwandeln, ohne große Änderungen vorzunehmen oder neue Skills wie React Native lernen zu müssen.

Folge dieser Schritt-für-Schritt-Anleitung, um deine SvelteKit-App mit Capacitor in eine mobile App zu verwandeln – inklusive optionaler Capgo Native Navigation, Transitions und iOS-Layout-Hilfen.

Über Capacitor

CapacitorJS ist ein Game-Changer! Es lässt sich mühelos in jedes Web-Projekt integrieren, indem es deine Anwendung in einen nativen Webview einbettet und Xcode- sowie Android Studio-Projekte für dich generiert. Die Plugins bieten über eine JavaScript-Bridge Zugriff auf native Gerätefunktionen wie die Kamera.

Capacitor ermöglicht es dir, eine fantastische native Mobile App ohne komplizierte Setup-Phasen oder steile Lernkurven zu erstellen. Das schlanke API und die optimierte Funktionalität machen die Integration in dein Projekt zum Kinderspiel. Du wirst staunen, wie einfach es ist, mit Capacitor eine voll funktionsfähige native App zu bauen!

Deine SvelteKit-App vorbereiten

Um eine neue SvelteKit-App zu erstellen, führe diesen Befehl aus:

npm create svelte@latest my-app
cd my-app
npm install
npm run build

Nachdem du den build Befehl ausgeführt hast, solltest du einen neuen dist Ordner im Root deines Projekts sehen.

Dieser Ordner wird später von Capacitor verwendet, aber zuerst müssen wir ihn korrekt einrichten.

Capacitor zu deiner SvelteKit-App hinzufügen

Um eine Web-App in einen nativen Mobile-Container zu verpacken, sind ein paar erste Schritte nötig. Danach ist es so einfach wie das Ausführen eines einzigen sync Befehl.

Installiere zuerst Capacitor CLI als Dev-Dependency installieren und im Projekt einrichten. Während des Setups kannst du einfach „Enter“ drücken, um die Standardwerte für Name und Bundle ID zu übernehmen.

Installiere als Nächstes das Core-Package sowie die passenden Packages für iOS und Android.

Füge schließlich die Plattformen hinzu, und Capacitor erstellt für jede Plattform einen Ordner im Root deines Projekts:

# Install the Capacitor CLI locally
npm install -D @capacitor/cli

# Initialize Capacitor in your SvelteKit project
npx cap init

# Install the required packages
npm install @capacitor/core @capacitor/ios @capacitor/android

# Add the native platforms
npx cap add ios
npx cap add android

An dieser Stelle solltest du neue iOS und Android Ordner in deinem SvelteKit-Projekt sehen.

Das sind echte Native-Projekte!

Um später auf das Android-Projekt zuzugreifen, musst du Folgendes installieren: Android Studioinstallieren. Für iOS brauchst du einen Mac und solltest Xcode.

installieren. Außerdem solltest du einen capacitor.config.ts Datei in deinem Projekt, die grundlegende Capacitor Einstellungen für den Sync enthält. Du musst nur auf folgendes achten: webDir, das auf das Ergebnis deines Build-Befehls zeigen muss. Aktuell ist es falsch konfiguriert.

Um das zu beheben, öffne die capacitor.config.ts -Datei und aktualisiere das webDir:

import { CapacitorConfig } from '@capacitor/cli'

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'build',
}

export default config

Nachdem wir unsere Capacitor Einstellungen aktualisiert haben, wandeln wir unser SvelteKit-Projekt in eine statische Anwendung um, indem wir das passende statische Adapter-Paket herunterladen:

npm i -D @sveltejs/adapter-static

Sobald das Paket installiert ist, müssen wir die svelte.config.js Datei vom Auto-Adapter auf statisch umstellen:

import adapter from '@sveltejs/adapter-static'
import { vitePreprocess } from '@sveltejs/kit/vite'

/** @type {import('@sveltejs/kit').Config} */
const config = {
// Consult https://kit.svelte.dev/docs/integrations#preprocessors
// for more information about preprocessors
  preprocess: vitePreprocess(),

  kit: {
    // adapter-auto only supports some environments, see https://kit.svelte.dev/docs/adapter-auto for a list.
    // If your environment is not supported or you settled on a specific environment, switch out the adapter.
    // See https://kit.svelte.dev/docs/adapters for more information about adapters.
    adapter: adapter({
      // default options are shown. On some platforms
      // these options are set automatically — see below
      pages: 'build',
      assets: 'build',
      fallback: null,
      precompress: false,
      strict: true
    })
  }
}

export default config

Mit dem svelte.config.js aktualisierten Adapter müssen wir eine prerender Option hinzufügen, indem wir eine +layout.js Seite zu src/routes und füge einfach den folgenden Export zu +layout.js:

export const prerender = true

Nach dem Hinzufügen und Aktualisieren von +layout.js Um die mobilen Plattformen hinzuzufügen, müssen wir unser Projekt neu bauen, um den Build Ordner

Das kannst du mit den folgenden Befehlen machen:

npm run build
npx cap sync

Der erste Befehl npm run build baut dein SvelteKit-Projekt und kopiert den statischen Build, während der zweite Befehl npx cap sync alle Web-code an die richtigen Stellen der nativen Plattformen synchronisiert, damit sie in einer App angezeigt werden können.

Zudem kann der sync-Befehl die nativen Plattformen aktualisieren und Plugins installieren. Wenn du also neue Capacitor Pluginsinstallierst, ist es Zeit für npx cap sync erneut aus.

Ohne es zu merken, hast du den Prozess abgeschlossen. Schauen wir uns die App nun auf einem Gerät an!

Native Apps bauen und deployen

Um iOS-Apps zu entwickeln, musst du Xcode installiert haben. Für Android-Apps benötigst du Android Studio als Installation. Wenn du deine App zudem in den App Store bringen willst, musst du dich für das Apple Developer Program (iOS) bzw. die Google Play Console (Android) anmelden.

Falls du neu in der nativen Mobile-Entwicklung bist, kannst du das Capacitor CLI nutzen, um beide nativen Projekte einfach zu öffnen:

npx cap open ios
npx cap open android

Sobald deine nativen Projekte eingerichtet sind, ist das Deployment auf ein verbundenes Gerät ganz einfach. In Android Studio musst du nur warten, bis alles bereit ist, und kannst deine App ohne weitere Einstellungen deployen. Hier ist ein Beispiel:

In Xcode musst du dein Signing-Account einrichten, um deine App auf einem echten Gerät statt nur im Simulator zu deployen. Falls du das noch nie gemacht hast, führt dich Xcode durch den Prozess (du musst dafür allerdings im Developer Program angemeldet sein). Danach kannst du einfach auf Play drücken, um die App auf deinem verbundenen Gerät zu starten, das du oben auswählen kannst. Hier ein Beispiel:

Glückwunsch! Du hast deine SvelteKit Web-App erfolgreich auf einem mobilen Gerät deployed. Hier ist ein Beispiel:

Aber Moment, es gibt während der Entwicklung auch einen schnelleren Weg…

Capacitor Live Reload

Mittlerweile bist du wahrscheinlich an Hot Reload bei allen modernen Frameworks gewöhnt, und die gute Nachricht ist: Du kannst dieselbe Funktionalität auf einem mobilen Gerät mit minimalem Aufwand nutzen!

Aktiviere den Zugriff auf deine lokal gehostete App mit Live Reload in deinem Netzwerk indem die Capacitor App den Inhalt von der spezifischen URL lädt.

Der erste Schritt ist es, deine lokale IP-Adresse herauszufinden. Wenn du einen Mac nutzt, kannst du dies mit folgendem Befehl im Terminal ermitteln:

ipconfig getifaddr en0

Unter Windows ausführen:

ipconfig

Suche dann nach der IPv4-Adresse.

Wir können Capacitor anweisen, die App direkt vom Server zu laden, indem wir einen weiteren Eintrag in unsere capacitor.config.ts Datei:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:3000',
    cleartext: true
  }
};

export default config;

Achte darauf, die richtige IP und den Port zu verwenden, wie im obigen Beispiel gezeigt.

Jetzt können wir diese Änderungen anwenden, indem wir sie in unser natives Projekt kopieren:

npx cap copy

Der copy Befehl ist ähnlich wie sync, aber es werden nur Kopiere die Änderungen aus dem Web-Ordner rüber und die Konfiguration übernommen, ohne das native Projekt zu aktualisieren.

Du kannst deine App nun noch einmal über Android Studio oder Xcode deployen. Wenn du danach etwas in deiner Svelte-App änderst, wird die App automatisch neu geladen und zeigt die Änderungen an!

Beachte bitte, dass die Installation neuer Plugins, wie etwa der Kamera, weiterhin einen Rebuild deines nativen Projekts erfordert. Da hierbei native Dateien geändert werden, kann dies nicht on the fly geschehen.

Achte darauf, die richtige IP und den Port in deiner Konfiguration zu verwenden. Der code Block oben zeigt den Standard-SvelteKit-Port zu Demonstrationszwecken.

Capacitor Plugins verwenden

Schauen wir uns an, wie ein Capacitor Plugin in der Praxis funktioniert, das wir bereits erwähnt haben. Dazu können wir ein einfaches Plugin mit folgendem Befehl installieren:

npm i @capacitor/share

Es gibt nichts Besonderes am Share-Plugin, aber es öffnet den nativen Share-Dialog! Dafür müssen wir nur noch das Package importieren und die share() Funktion aus unserer App aufrufen, also ändern wir die src/routes/index.svelte wie folgt:

<script>
  import { Share } from '@capacitor/share';

  async function share() {
    await Share.share({
      title: 'Open Youtube',
      text: 'Check new video on youtube',
      url: 'https://www.youtube.com',
      dialogTitle: 'Share with friends'
    });
  }
</script>

<h1>Welcome to SvelteKit and Capacitor!</h1>
<button on:click={share}>Share now!</button>

Wie bereits erwähnt, müssen wir nach der Installation neuer Plugins einen Sync durchführen und die App anschließend neu auf das Gerät deployen. Nutze dazu diesen Befehl:

npx cap sync

Nach dem Klick auf den Button siehst du den nativen Share-Dialog in Aktion!

Als Nächstes kannst du die App auf iOS und Android mit Capgo Navigation und Transitions nativer wirken lassen und typische iOS-Layoutprobleme beheben, die horizontalen Overflow oder abgeschnittene Safe Areas verursachen.

Native-Feeling-UI mit Capgo Native Navigation und Transitions

Ich arbeite schon seit Jahren mit Ionic um plattformübergreifende Apps zu bauen, aber die Integration mit SvelteKit ist oft umständlich und lohnt sich kaum, wenn man bereits Tailwind CSS.

Für ein natives Mobile-Feeling in einer SvelteKit + Capacitor App solltest du Capgo Plugins statt reiner Web-UI-Kits wie Konsta UI nutzen:

• @capgo/capacitor-native-navigation — native Navbar, Liquid Glass Tab Bar auf iOS und ein Blur-Effekt für die Tab Bar auf Android. Dein SvelteKit Router verwaltet den Route-State; das Plugin übernimmt das native Chrome.
• @capgo/capacitor-transitions — Page Transitions im Ionic-Stil und iOS Edge Swipe-Back in der WebView-Ebene, ohne das Ionic UI zu übernehmen.

Beides installieren:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Konfiguriere die native Navigation mit dem CSS Inset Mode, damit Web-Content die nativen Bars berücksichtigt:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Rendere eine Liquid Glass Tab Bar (iOS nutzt systemeigenes Rendering; Android nutzt einen geblurrten WebView-Hintergrund):

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'labeled',
  icons: true,
  colors: { dynamic: true },
  tabs: [
    { id: 'home', title: 'Home', icon: { svg: '...' } },
    { id: 'settings', title: 'Settings', icon: { svg: '...' } },
  ],
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  goto(`/${id}`);
});

Füge native Page Transitions in deine App Shell ein:

<script>
  import { goto } from '$app/navigation';
  import { routerOutlet, page, setDirection } from '@capgo/capacitor-transitions/svelte';
  import '@capgo/capacitor-transitions';

  function openSettings() {
    setDirection('forward');
    goto('/settings');
  }
</script>

<cap-router-outlet use:routerOutlet>
  <cap-page use:page>
    <cap-content slot="content">
      <slot />
    </cap-content>
  </cap-page>
</cap-router-outlet>

Umschließe geroutete Seiten mit cap-router-outlet, cap-page, und cap-content, und rufe setDirection('forward') oder setDirection('back') bevor du navigierst. Dupliziere keine Web-Header oder -Footer, wenn die native Navigation diese Bereiche bereits übernimmt.

Hier findest du die vollständigen Guides: Verwendung von @capgo/capacitor-native-navigation und Verwendung von @capgo/capacitor-transitions.

Safe Areas mit Tailwind

Für Device Safe Areas in Tailwind CSS verwende @capgo/tailwind-capacitor (veröffentlicht als tailwind-capacitor auf npm). Es bietet safe-areas Utilities und andere Capacitor-freundliche Tailwind-Plugins:

bun add -D tailwind-capacitor

Unter src/app.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Nutze Utilities wie pt-safe, pb-safe, und px-safe anstatt alles manuell env(safe-area-inset-*) von Hand. Das Projekt wird aktiv weiterentwickelt – falls etwas für dein SvelteKit-Setup fehlt, eröffne einen PR auf GitHub.

iOS-Layoutprobleme beheben (Viewport, Safe Area und horizontaler Overflow)

Wenn Inhalte auf iOS abgeschnitten, verschoben oder horizontal scrollbar wirken, hilft es meist nicht, mehr overflow-x: hidden hinzuzufügen oder nur das Viewport-Tag zu ändern. Gehe diese Checks der Reihe nach durch.

Stelle sicher, dass das Viewport-Meta-Tag korrekt angewendet wird

Unter src/app.html, setze das Viewport-Meta-Tag in <head>:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

iOS Safe Area nur von einem Root-Wrapper aus handhaben

Erstelle eine einzige App-Shell und wende dort das Safe-Area-Padding an – nicht in mehreren verschachtelten Komponenten:

html,
body,
body {
  width: 100%;
  min-height: 100%;
  margin: 0;
  padding: 0;
  overflow-x: hidden;
}

* {
  box-sizing: border-box;
}

.app-shell {
  min-height: 100dvh;
  width: 100%;
  padding-top: env(safe-area-inset-top);
  padding-right: env(safe-area-inset-right);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
}

Umschließe den gesamten Seiteninhalt mit .app-shellDoppeltes Safe-Area-Padding in Headern, Modals und Layout-Wrappern lässt das UI oft abgeschnitten oder zu groß wirken.

Mit @capgo/tailwind-capacitor, kannst du dasselbe Padding mit Utilities wie pt-safe pb-safe px-safe in dieser einen Shell ausdrücken.

Setze Capacitor iOS contentInset zu never zuerst

Unter capacitor.config.ts, deaktiviere lieber native Insets und überlasse CSS (oder der Native Navigation contentInsetMode: 'css') die Safe Area:

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'build',
  ios: {
    contentInset: 'never',
  },
};

Kombination von Capacitor’s automatischen Content Insets mit CSS env(safe-area-inset-*) Padding ist eine häufige Ursache für doppelte Abstände.

Das tatsächlich überlaufende Element finden

Der übliche Übeltäter ist ein Element mit 100vw, Tailwind w-screen, einer festen Pixelbreite oder einem großen min-width.

Im Safari Web Inspector ausführen:

[...document.querySelectorAll('*')]
  .filter(el => el.scrollWidth > document.documentElement.clientWidth)
  .map(el => ({
    el,
    tag: el.tagName,
    class: el.className,
    scrollWidth: el.scrollWidth,
    clientWidth: document.documentElement.clientWidth,
  }));

Mit Tailwind ersetzen w-screen mit w-full wann immer möglich. Viele Probleme mit horizontalem Overflow entstehen durch 100vw / w-screen, doppeltes Safe-Area-Padding oder einen Container mit fester Breite – nicht durch das Viewport-Meta-Tag selbst.

Fazit

Capacitor ist eine hervorragende Option, um native Apps auf Basis eines bestehenden Webprojekts zu bauen, da es einen einfachen Weg bietet, code zu teilen und ein konsistentes UI zu pflegen.

Und mit der Ergänzung von Capgo, wird es noch einfacher, Live Updates in deine App einzubinden, damit deine Nutzer immer Zugriff auf die neuesten Features und Bugfixes haben.

Wenn du lernen möchtest, wie du Capgo in deine SvelteKit-App einbindest, schau dir den nächsten Artikel an:

Erfahren Sie, wie Capgo Ihnen hilft, schneller bessere Apps zu bauen, Registrieren Sie sich für ein kostenloses Konto noch heute.

Weiterlesen: Mobile Apps mit SvelteKit und Capacitor bauen

Wenn du es nutzt Mobile Apps mit SvelteKit und Capacitor bauen um CI/CD-Automatisierung zu planen, verbinde es mit Capgo CI/CD für den Produkt-Workflow in Capgo CI/CD, Capgo Native Builds optimieren für den Produkt-Workflow in Capgo Native Builds, Capgo Integrationen für den Produkt-Workflow in Capgo Integrations, CI/CD-Integration für die Implementierungsdetails in der CI/CD-Integration und GitHub Actions-Integration für die Implementierungsdetails in der GitHub Actions-Integration.