En ce tutoriel, nous allons commencer par une nouvelle SvelteKit app and transition to native mobile development using Capacitor. You can also add Capgo Native Navigation and Transitions for a native mobile feel, and use tailwind-capacitor for safe areas.
Capacitor allows you to easily convert your SvelteKit web application into a native mobile app without the need for significant modifications or learning a new skill like React Native.
Follow this step-by-step guide to transform your SvelteKit app into a mobile app using Capacitor, with optional Capgo Native Navigation, Transitions, and iOS layout guidance.
À propos de Capacitor
CapacitorJS est un véritable changement de cap ! Il peut être intégré de manière aisée dans tout projet web, en enveloppant votre application dans une vue web native et en générant des projets Xcode et Android Studio natifs pour vous. Ses plugins vous donnent accès aux fonctionnalités de l'appareil natif comme la caméra via un pont JavaScript.
Capacitor vous permet de créer une application mobile native fantastique sans aucune configuration compliquée ou courbe d'apprentissage abrupte. Sa couche API et sa fonctionnalité épurée rendent facile son intégration dans votre projet. Vous serez émerveillé par la simplicité avec laquelle vous pouvez obtenir une application mobile native fonctionnelle avec Capacitor !
Préparation de votre application SvelteKit
Pour créer une nouvelle application SvelteKit, exécutez la commande suivante :
npm create svelte@latest my-app
cd my-app
npm install
npm run buildAprès avoir exécuté la build commande, vous devriez voir un nouveau dist dossier à la racine de votre projet.
Ce dossier sera utilisé par Capacitor plus tard, mais pour l'instant, nous devons le configurer correctement.
Intégration de Capacitor à votre application SvelteKit
Pour emballer tout projet web dans un conteneur mobile natif, nous devons suivre quelques étapes initiales. Ensuite, il suffit de lancer une seule sync commande.
Premièrement, installez le Capacitor CLI comme dépendance de développement et configurez-le dans votre projet. Lors de la configuration, vous pouvez appuyer sur « entrée » pour accepter les valeurs par défaut pour le nom et l'ID de l'application.
Ensuite, installez le package de base et les packages pertinents pour les plateformes iOS et Android.
Finalement, ajoutez les plateformes, et Capacitor créera des dossiers pour chaque plateforme à la racine de votre projet :
# 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À ce stade, vous devriez voir de nouveaux ios et android dossiers dans votre projet SvelteKit.
Ces sont des projets natifs réels !
Pour accéder au projet Android ultérieurement, vous devez installer Android Studio Pour iOS, vous avez besoin d'un Mac et devriez installer Xcode.
De plus, vous devriez trouver un fichier capacitor.config.ts dans votre projet, qui contient certaines configurations de base Capacitor utilisées lors de la synchronisation. La seule chose dont vous devez vous soucier est le webDir, qui doit pointer vers le résultat de votre commande de build. Actuellement, il est incorrect.
Pour corriger cela, ouvrez le fichier capacitor.config.ts fichier et mettez à jour le webDir:
import { CapacitorConfig } from '@capacitor/cli'
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'build',
}
export default configUne fois que nous avons mis à jour nos paramètres de Capacitor, changeons notre projet Sveltekit en application statique en téléchargeant le bon package d'adaptateur statique.
npm i -D @sveltejs/adapter-staticAprès l'installation du package, nous devrons modifier svelte.config.js de l'adaptateur automatique en statique :
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 configAvec le svelte.config.js mis à jour, nous devrons ajouter une prerender une option en créant un src/routes layout.js pour And ajoutez simplement l'export suivant à +layout.js:
export const prerender = trueAprès avoir ajouté et mis à jour la +layout.js page, nous devrons ajouter nos plateformes mobiles, reconstruire notre projet pour créer le build folder
Vous pouvez le faire en exécutant les commandes suivantes :
npm run build
npx cap syncLa première commande npm run build Il construira votre projet SvelteKit et copiera la mise en page statique, tandis que la deuxième commande npx cap sync syncronisera tous les web code dans les bons endroits des plateformes natives afin qu'ils soient affichés dans une application.
syncra les web __CAPGO_KEEP_0__ dans les bons endroits des plateformes natives afin qu'elles puissent être affichées dans une application. Capacitor pluginsEnfin, il est temps de relancer npx cap sync Encore.
Sans vous en rendre compte, vous avez maintenant terminé le processus, alors voyons l'application sur un appareil !
Construire et déployer des applications natives
Pour développer des applications iOS, vous devez avoir Xcode installé, et pour les applications Android, vous devez avoir Android Studio installé. De plus, si vous prévoyez distribuer votre application sur l'app store, vous devez vous inscrire au programme Apple Developer pour iOS et au Google Play Console pour Android.
Si vous êtes nouveau dans le développement mobile natif, vous pouvez utiliser le Capacitor CLI pour ouvrir facilement les projets natifs :
npx cap open ios
npx cap open androidUne fois que vous avez configuré vos projets natifs, déployer votre application sur un appareil connecté est facile. Dans Android Studio, il suffit d'attendre que tout soit prêt, et vous pouvez déployer votre application sur un appareil connecté sans modifier les paramètres. Voici un exemple :
Dans Xcode, vous devez configurer votre compte de signature pour déployer votre application sur un appareil réel au lieu du simulateur. Si vous n'avez pas déjà effectué cela, Xcode vous guide à travers le processus (mais encore une fois, vous devez être inscrit au programme de développeurs). Une fois cela fait, vous pouvez simplement appuyer sur play pour exécuter l'application sur votre appareil connecté, que vous pouvez sélectionner en haut. Voici un exemple :
Félicitations ! Vous avez réussi à déployer votre application web SvelteKit sur un appareil mobile. Voici un exemple :
Mais attendez, il existe également une méthode plus rapide pour procéder pendant le développement…
Capacitor Live Reload
À ce stade, vous êtes probablement habitué à avoir la mise à jour en temps réel avec tous les frameworks modernes, et la bonne nouvelle est que vous pouvez avoir la même fonctionnalité sur un appareil mobile avec un minimum d'efforts !
Activer l'accès à votre application hébergée localement avec rechargement en direct sur votre réseau en ayant l'application Capacitor charger le contenu à partir de l'URL spécifique.
Le premier pas consiste à déterminer votre adresse IP locale. Si vous utilisez un Mac, vous pouvez trouver cela en exécutant la commande suivante dans le terminal :
ipconfig getifaddr en0Sur Windows, exécutez :
ipconfigRecherchez ensuite l'adresse IPv4.
On peut instruire Capacitor à charger l'application directement depuis le serveur en ajoutant une autre entrée à notre fichier : capacitor.config.ts file:
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;l'adresse IP et le port corrects comme montré dans l'exemple ci-dessus.comme illustré dans l'exemple ci-dessus.
Maintenant, nous pouvons appliquer ces modifications en les copiant vers notre projet natif :
npx cap copyThe copy le command est similaire à sync, mais cela ne se produira que copiez simplement les modifications apportées au dossier web et la configuration, sans mettre à jour le projet natif.
Vous pouvez maintenant déployer votre application une fois de plus à l'aide d'Android Studio ou Xcode. Après cela, si vous modifiez quelque chose dans votre application Svelte, l'application se rechargera automatiquement et affichera les modifications !
Tenez compte que si vous installez de nouveaux plugins comme la caméra, il est encore nécessaire de reconstruire votre projet natif. C'est parce que les fichiers natifs sont modifiés, et cela ne peut pas être fait en temps réel.
Notez que vous devez utiliser l'IP et le port corrects dans votre configuration. Le bloc code ci-dessus montre le port par défaut de SvelteKit pour des fins de démonstration.
Utilisation des plugins Capacitor
Examinons maintenant comment utiliser un plugin Capacitor en action, que nous avons mentionné quelques fois avant. Pour cela, nous pouvons installer un plugin simple en exécutant :
npm i @capacitor/shareRien de particulièrement original dans le Partager plugin, mais cela ouvre la boîte de dialogue de partage native ! Pour cela, nous n'avons besoin désormais que d'importer le package et d'appeler la share() fonction de notre application, donc changeons donc le src/routes/index.svelte en ceci :
<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>Comme mentionné précédemment, lors de l'installation de nouveaux plugins, nous devons effectuer une opération de synchronisation et puis redéployer l'application sur notre appareil. Pour cela, exécutez la commande suivante :
npx cap syncAprès avoir cliqué sur le bouton, vous pouvez voir le dialogue de partage natif en action !
Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas.
Interface utilisateur naturelle avec Capgo Navigation native et transitions
J'ai travaillé pendant des années avec Ionic pour construire des applications cross-plateformes, mais l'intégration de SvelteKit avec elle est hacky et rarement justifiée lorsque vous avez déjà Tailwind CSS.
Pour un sentiment natif mobile dans une application SvelteKit + Capacitor , utilisez les plugins Capgo au lieu des kits UI web uniquement comme Konsta UI :
- @capgo/capacitor-navigation native — barre de navigation native, Liquid Glass barre de tab sur iOS, et un style de barre de tab flou sur Android. Votre routeur SvelteKit conserve l'état de la route ; le plugin gère la barre de chrome native.
- @capgo/capacitor-transitions — Transition de page Ionic et swipe arrière sur iOS dans la couche WebView, sans adopter l'interface utilisateur Ionic.
Installez les deux :
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigurez la navigation native avec le mode d'insertion CSS pour que le contenu web respecte les barres natives :
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Afficher une barre d'onglets Liquid Glass (iOS utilise la mise en page système ; Android utilise un arrière-plan flou WebView) :
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}`);
});Add native page transitions in your app shell:
<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>Enveloppez les pages routées dans cap-router-outlet, cap-pageet cap-content, et appelez setDirection('forward') ou setDirection('back') Avant de naviguer. N'ajoutez pas de titres ou de pieds de page web si la navigation native les gère déjà.
Voir les guides complets : Utiliser @capgo/capacitor-navigation native and Utilisation de @capgo/capacitor-transitions.
Utiliser @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions
Les zones de sécurité avec Tailwind @capgo/tailwind-capacitor @__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ tailwind-capacitor (publié comme sur npm). Il fournit safe-areas outils et autres plugins Tailwind compatibles avec Capacitor :
bun add -D tailwind-capacitorEn src/app.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilisez les outils tels que pt-safe, pb-safe, et px-safe au lieu de les répandre env(safe-area-inset-*) manuellement. Le projet est actuellement développé — si quelque chose manque pour votre configuration SvelteKit, ouvre une PR sur GitHub.
Résoudre les problèmes de mise en page iOS (Vueport, Zone de sécurité et débordement horizontal)
Si le contenu semble coupé, décalé ou déroulable horizontalement sur iOS, ajouter plus overflow-x: hidden ou modifier seul le tag viewport ne résout généralement pas le problème. Passons par ces vérifications dans l'ordre.
Assurez-vous que la balise meta de vueport est appliquée correctement
En src/app.htmlconfigurez la balise meta de viewport en <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gérez l'espace sûr d'iOS à partir d'un seul enveloppe racine
Créez un noyau d'application unique et appliquez-y un padding de zone de sécurité — pas dans plusieurs composants imbriqués :
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);
}Wrapper tout le contenu de la page à l'intérieur .app-shellLes marges de sécurité dupliquées dans les en-têtes, les modales et les enveloppes de mise en page rendent souvent l'interface utilisateur coupée ou trop grande.
Avec @capgo/tailwind-capacitorvous pouvez exprimer la même mise en forme avec des utilitaires comme pt-safe pb-safe px-safe sur cette coquille unique.
Configurez Capacitor iOS contentInset sur never first
Dans capacitor.config.ts, préférez l'insertion native désactivée et laissez CSS (ou la navigation native) contentInsetMode: 'css') gérer l'espace sûr :
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Mélanger les Capacitor’s retraits automatiques de contenu avec CSS env(safe-area-inset-*) la marge est une cause courante de double espacement.
Trouvez l'élément réellement débordant
Le coupable habituel est un élément utilisant 100vw, Tailwind w-screen, une largeur fixe en pixels, ou une large min-width.
Dans l'inspecteur Web Safari, exécutez :
[...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,
}));Avec Tailwind, remplacez w-screen par w-full lorsque possible. Beaucoup d'issues de débordement horizontal proviennent de 100vw / w-screenPas de duplication de la marge de sécurité de l'espace d'affichage ou d'un conteneur à largeur fixe — pas de la balise meta viewport elle-même.
Conclusion
Capacitor est une excellente option pour créer des applications natives en fonction d'un projet web existant, offrant une façon simple de partager code et de maintenir une interface utilisateur cohérente.
Et avec l'ajout de Capgo, il est même plus facile d'ajouter des mises à jour en temps réel à votre application, vous assurant que vos utilisateurs aient toujours accès aux dernières fonctionnalités et corrections de bogues.
Si vous souhaitez apprendre à ajouter Capgo à votre application SvelteKit, consultez l'article suivant.
Learn how Capgo can help you build better apps faster, inscrivez-vous à un compte gratuit aujourd'hui.
Continuez à partir de l'article Construire des applications mobiles avec SvelteKit et Capacitor
Si vous utilisez Building Mobile Apps with SvelteKit and Capacitor pour planifier l'automatisation de CI/CD, connectez-l’avec Capgo CI/CD pour le flux de travail du produit dans Capgo CI/CD, Capgo Bâtiments natifs Pour le workflow du produit dans les builds natives Capgo. Capgo Integrations pour le flux de travail du produit dans Capgo Intégrations, Intégration CI/CD pour les détails d'implémentation dans l'intégration CI/CD, et GitHub Actions Integration pour les détails d'implémentation dans GitHub Actions d'intégration.
