In questo tutorial, partiremo da una nuova SvelteKit app e passeremo allo sviluppo mobile nativo con Capacitor. Puoi anche aggiungere Capgo Native Navigation and Transitions per un feeling nativo, e usare tailwind-capacitor per le safe areas.
Capacitor ti permette di convertire facilmente la tua web app SvelteKit in un'app mobile nativa, senza dover apportare modifiche sostanziali o imparare nuove skill come React Native.
Segui questa guida passo dopo passo per trasformare la tua app SvelteKit in un'app mobile con Capacitor, con opzioni per Capgo Native Navigation, Transitions e guida al layout iOS.
Informazioni su Capacitor
CapacitorJS cambia le regole del gioco! Può essere integrato senza sforzo in qualsiasi progetto web, avvolgendo la tua applicazione in una webview nativa e generando progetti Xcode e Android Studio. I suoi plugin permettono di accedere alle funzioni native del dispositivo, come la fotocamera, tramite un bridge JavaScript.
Capacitor ti permette di creare una fantastica app mobile nativa senza configurazioni complicate o curve di apprendimento ripide. Il suo API leggero e le funzionalità ottimizzate lo rendono facile da integrare nel tuo progetto. Rimarrai stupito di quanto sia semplice ottenere un'app nativa completa con Capacitor!
Preparazione della tua app SvelteKit
Per creare una nuova app SvelteKit, esegui il seguente comando:
npm create svelte@latest my-app
cd my-app
npm install
npm run buildDopo aver eseguito il comando build dovresti vedere una nuova dist cartella nella root del tuo progetto.
Questa cartella verrà utilizzata da Capacitor in seguito, ma per ora dobbiamo configurarla correttamente.
Aggiungere Capacitor alla tua app SvelteKit
Per impacchettare qualsiasi web app in un container mobile nativo, dobbiamo seguire alcuni passaggi iniziali. Successivamente, basterà eseguire un singolo sync comando.
Per prima cosa, installa Capacitor CLI come dipendenza di sviluppo e configuralo nel tuo progetto. Durante il setup, puoi premere “invio” per accettare i valori predefiniti di nome e bundle ID.
Successivamente, installa il pacchetto core e i pacchetti necessari per le piattaforme iOS e Android.
Infine, aggiungi le piattaforme e Capacitor creerà le cartelle per ogni piattaforma nella root del tuo progetto:
# 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 androidA questo punto, dovresti vedere nuove ios e android cartelle nel tuo progetto SvelteKit.
Sono veri progetti native!
Per accedere al progetto Android in seguito, devi installare Android Studio. Per iOS, ti serve un Mac e dovresti installare Xcode.
Inoltre, dovresti cercare il file capacitor.config.ts nel tuo progetto, che contiene alcune impostazioni base di Capacitor usate durante la sync. L'unica cosa a cui prestare attenzione è webDir, che deve puntare al risultato del tuo comando di build. Al momento è errato.
Per risolvere, apri il file capacitor.config.ts file e aggiorna il webDir:
import { CapacitorConfig } from '@capacitor/cli'
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'build',
}
export default configOra che abbiamo aggiornato le impostazioni di Capacitor, trasformiamo il progetto SvelteKit in un'applicazione statica scaricando il pacchetto dell'adapter statico corretto:
npm i -D @sveltejs/adapter-staticUna volta installato il pacchetto, dovremo modificare il svelte.config.js passando dall'adapter automatico a quello statico:
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 configCon l' svelte.config.js aggiornato, dovremo aggiungere un'opzione prerender creando un file +layout.js per la pagina src/routes e basta aggiungere la seguente export in +layout.js:
export const prerender = trueDopo aver aggiunto e aggiornato la +layout.js pagina, dovremo aggiungere le piattaforme mobile e ricostruire il progetto per creare la build cartella
Puoi farlo eseguendo i seguenti comandi:
npm run build
npx cap syncIl primo comando npm run build genererà la build del tuo progetto SvelteKit e copierà la build statica, mentre il secondo comando npx cap sync sincronizzerà tutti i code web nelle posizioni corrette delle piattaforme native per visualizzarli nell'app.
Inoltre, il comando sync potrebbe aggiornare le piattaforme native e installare i plugin, quindi quando installi nuovi plugin Capacitor, è il momento di eseguire npx cap sync di nuovo.
Senza accorgertene, hai completato il processo: ora vediamo l'app su un dispositivo!
Build e Deploy di App Native
Per sviluppare app iOS, devi avere Xcode installato, mentre per le app Android ti serve Android Studio installato. Inoltre, se intendi distribuire la tua app sugli store, devi iscriverti all'Apple Developer Program per iOS e alla Google Play Console per Android.
Se sei alle prime armi con lo sviluppo mobile nativo, puoi usare Capacitor CLI per aprire facilmente entrambi i progetti nativi:
npx cap open ios
npx cap open androidUna volta configurati i tuoi progetti nativi, distribuire l'app su un dispositivo connesso è semplicissimo. In Android Studio, ti basta attendere che tutto sia pronto per deployare l'app senza modificare alcuna impostazione. Ecco un esempio:
In Xcode, devi configurare il tuo account di signing per distribuire l'app su un dispositivo reale invece che solo sul simulatore. Se non l'hai mai fatto, Xcode ti guida nel processo (ma anche qui devi essere iscritto al Developer Program). Dopo, ti basta premere play per eseguire l'app sul dispositivo connesso, che puoi selezionare in alto. Ecco un esempio:
Complimenti! Hai distribuito con successo la tua web app SvelteKit su un dispositivo mobile. Ecco un esempio:
Ma aspetta, esiste anche un modo più veloce per farlo durante lo sviluppo...
Capacitor Live Reload
A questo punto sarai probabilmente abituato ad avere l'hot reload con tutti i framework moderni, e la buona notizia è che puoi avere la stessa funzionalità su un dispositivo mobile con il minimo sforzo!
Abilita l'accesso alla tua applicazione ospitata localmente con live reload sulla tua rete facendo caricare i contenuti all'app Capacitor tramite l'URL specifico.
Il primo passo è individuare il tuo indirizzo IP locale. Se usi un Mac, puoi trovarlo eseguendo questo comando nel terminale:
ipconfig getifaddr en0Su Windows, esegui:
ipconfigPoi cerca l'indirizzo IPv4.
Possiamo istruire Capacitor a caricare l'app direttamente dal server aggiungendo un'altra voce al nostro 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;Assicurati di usare l'IP e la porta corretti, come mostrato nell'esempio sopra.
Ora possiamo applicare queste modifiche copiandole nel nostro progetto nativo:
npx cap copyL'oggetto copy il comando è simile a sync, ma copierà solo le modifiche apportate alla cartella web e alla configurazione, senza aggiornare il progetto nativo.
Ora puoi distribuire la tua app tramite Android Studio o Xcode. Successivamente, se modifichi qualcosa nella tua app Svelte, l'app si ricaricherà automaticamente e mostrerà le modifiche!
Tieni presente che se installi nuovi plugin come la fotocamera, è comunque necessario un rebuild del progetto nativo. Questo perché i file nativi vengono modificati e l'operazione non può avvenire on the fly.
Nota che devi usare l'IP e la porta corretti nella configurazione. Il blocco code sopra mostra la porta predefinita di SvelteKit a scopo dimostrativo.
Utilizzo dei Capacitor Plugin
Vediamo come usare un plugin Capacitor in azione, come abbiamo menzionato in precedenza. Per farlo, possiamo installare un semplice plugin eseguendo:
npm i @capacitor/shareNon c'è nulla di speciale nel plugin Share, ma attiva il dialog di condivisione nativo! Per farlo, basta importare il pacchetto e chiamare la share() funzione dalla nostra app, quindi modifichiamo src/routes/index.svelte in questo modo:
<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>Come detto prima, quando installi nuovi plugin, devi eseguire un'operazione di sync e poi ridistribuire l'app sul dispositivo. Per farlo, esegui questo comando:
npx cap syncDopo aver premuto il tasto, potrai vedere il bellissimo dialog di condivisione nativo in azione!
In seguito, puoi rendere l'app più nativa su iOS e Android con la navigazione e le transizioni Capgo, risolvendo i comuni problemi di layout su iOS come l'overflow orizzontale o le safe area tagliate.
UI nativa con Capgo Native Navigation e Transitions
Ho lavorato per anni con Ionic per creare applicazioni cross-platform, ma integrarlo con SvelteKit è un workaround e raramente ne vale la pena quando hai già Tailwind CSS.
Per un feeling mobile nativo in un'app SvelteKit + Capacitor, usa i plugin Capgo invece di UI kit solo web come Konsta UI:
- @capgo/capacitor-native-navigation — navbar nativa, tab bar Liquid Glass su iOS e stile tab bar sfocata su Android. Il router di SvelteKit gestisce lo stato delle rotte; il plugin si occupa della UI nativa.
- @capgo/capacitor-transitions — transizioni di pagina in stile Ionic e swipe-back laterale su iOS nel layer WebView, senza adottare Ionic UI.
Installa entrambi:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigura la navigazione nativa con la modalità CSS inset, così il contenuto web rispetta le barre native:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Renderizza una tab bar Liquid Glass (iOS usa il rendering di sistema; Android usa un backdrop WebView sfocato):
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}`);
});Aggiungi transizioni di pagina native nel tuo 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>Avvolgi le pagine delle route in cap-router-outlet, cap-page, e cap-content, e chiama setDirection('forward') o setDirection('back') prima di navigare. Non duplicare header o footer web quando la navigazione nativa gestisce quelle superfici.
Guarda le guide complete: Usare @capgo/capacitor-native-navigation e Usare @capgo/capacitor-transitions.
Safe areas con Tailwind
Per le safe area del dispositivo in Tailwind CSS, usa @capgo/tailwind-capacitor (pubblicato come tailwind-capacitor su npm). Fornisce safe-areas utility e altri plugin Tailwind compatibili con Capacitor:
bun add -D tailwind-capacitorIn src/app.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Usa utility come pt-safe, pb-safe, e px-safe invece di inserire manualmente env(safe-area-inset-*) a mano. Il progetto è in attivo sviluppo — se manca qualcosa per il tuo setup SvelteKit, apri una PR su GitHub.
Risolvere problemi di layout su iOS (Viewport, Safe Area e Overflow orizzontale)
Se i contenuti appaiono tagliati, spostati o con scroll orizzontale su iOS, aggiungere solo overflow-x: hidden o modificare il tag viewport di solito non basta. Segui questi controlli in ordine.
Assicurati che il meta tag viewport sia applicato correttamente
In src/app.html, imposta il meta tag viewport in <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gestisci l'area sicura iOS da un unico wrapper root
Crea un unico app shell e applica il padding dell'area sicura lì — non in vari componenti annidati:
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);
}Avvolgi tutto il contenuto della pagina in .app-shell. Il padding dell'area sicura duplicato in header, modal e layout wrapper spesso fa sembrare l'interfaccia tagliata o troppo grande.
Con @capgo/tailwind-capacitor, puoi gestire lo stesso padding con utility come pt-safe pb-safe px-safe su quel singolo shell.
Imposta Capacitor iOS contentInset a never primo
In capacitor.config.ts, preferisci l'inset nativo disabilitato e lascia che il CSS (o la Native Navigation) contentInsetMode: 'css') gestisca la safe area:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Mescolare l'automatic content inset di Capacitor con il padding env(safe-area-inset-*) CSS è una causa comune di spaziature doppie.
Trova l'elemento che causa l'overflow
Il colpevole di solito è un elemento che usa 100vw, Tailwind w-screen, una larghezza fissa in pixel, o un grande min-width.
In Safari Web Inspector, esegui:
[...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,
}));Con Tailwind, sostituisci w-screen con w-full quando possibile. Molti problemi di overflow orizzontale derivano da 100vw / w-screen, padding della safe-area duplicato o un contenitore a larghezza fissa — non dal meta tag viewport stesso."
Conclusione
Capacitor è un'ottima opzione per creare applicazioni native partendo da un progetto web esistente, offrendo un modo semplice per condividere code e mantenere una UI coerente.
E con l'aggiunta di Capgo, è ancora più facile aggiungere i live updates alla tua app, garantendo agli utenti l'accesso immediato alle ultime funzionalità e bug fix.
Se vuoi scoprire come aggiungere Capgo alla tua app SvelteKit, leggi il prossimo articolo:
Scopri come Capgo può aiutarti a creare app migliori più velocemente, registrati per un account gratuito oggi stesso.
Continua da Building Mobile Apps with SvelteKit and Capacitor
Se stai usando Creare app mobile con SvelteKit e Capacitor per pianificare l'automazione CI/CD e connetterla a Capgo CI/CD per il workflow del prodotto in Capgo CI/CD, Capgo Native Build per il workflow del prodotto in Capgo Native Builds, Integrazioni Capgo per il workflow del prodotto in Integrazioni Capgo, Integrazione CI/CD per i dettagli di implementazione in CI/CD Integration, e Integrazione GitHub Actions per i dettagli di implementazione in GitHub Actions Integration.
