In questo tutorial, partiremo da una nuova SvelteKit app React 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 modifiche drastiche o la necessità di imparare nuovi framework come React Native.
Segui questa guida passo dopo passo per trasformare la tua app SvelteKit in un'app mobile usando Capacitor, con Capgo Native Navigation, Transitions e linee guida sul layout iOS opzionali.
Informazioni su Capacitor
CapacitorJS cambia le regole del gioco! Si integra senza sforzo in qualsiasi progetto web, avvolgendo la tua applicazione in una webview nativa e generando per te i progetti Xcode e Android Studio. I suoi plugin danno accesso alle funzionalità native del dispositivo, come la fotocamera, tramite un bridge JavaScript.
Con Capacitor puoi creare una fantastica app mobile nativa senza configurazioni complicate né ripide curve di apprendimento. Il suo API leggero e le funzionalità essenziali lo rendono facile da integrare nel tuo progetto. Rimarrai stupito di quanto sia semplice ottenere un'app nativa completa con Capacitor!
Preparare la tua app SvelteKit
Per creare una nuova app SvelteKit, esegui questo 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à usata da Capacitor più avanti, 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. Dopodiché basta eseguire un singolo sync comando.
Per prima cosa, installa il Capacitor CLI come dipendenza di sviluppo e configuralo nel tuo progetto. Durante il setup, puoi premere “invio” per accettare i valori predefiniti di name 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 devi installare Xcode.
Inoltre, dovresti trovare un 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 capacitor.config.ts file e aggiornare 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 lo svelte.config.js aggiornato, dovremo aggiungere un'opzione prerender creando un file +layout.js per la pagina src/routes e basta aggiungere questo export a +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 costruirà il 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, così da poterli visualizzare 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 ancora.
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 devi avere 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, devi solo attendere che tutto sia pronto e puoi distribuire l'app su un dispositivo connesso 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 guiderà nel processo (ma ricorda che devi essere iscritto al Developer Program). Dopodiché, ti basterà premere play per avviare l'app sul dispositivo connesso, che puoi selezionare in alto. Ecco un esempio:
Congratulazioni! 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, probabilmente sei abituato all'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 il 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 indicare a Capacitor di 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 copyIl 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 di nuovo la tua app tramite Android Studio o Xcode. Dopodiché, 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 camera, serve comunque un rebuild del progetto nativo. Questo perché i file nativi vengono modificati e l'operazione non può essere fatta al volo.
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 plugin Capacitor
Vediamo come usare un plugin Capacitor in azione, come abbiamo già menzionato un paio di volte. Per farlo, possiamo installare un semplice plugin eseguendo:
npm i @capacitor/shareNon c'è niente di speciale in Plugin di condivisione, ma apre la finestra di condivisione nativa! Per farlo, basta importare il pacchetto e chiamare 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 accennato 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 cliccato il pulsante, potrai vedere il bellissimo dialog di condivisione nativo in azione!
Successivamente, puoi rendere l'app più nativa su iOS e Android con navigazione e transizioni Capgo, e risolvere i comuni problemi di layout su iOS che causano overflow orizzontale o safe area tagliate.
UI dall'aspetto nativo con Capgo Native Navigation and Transitions
Ho lavorato per anni con Ionic per creare app cross-platform, ma integrarlo con SvelteKit è complicato e raramente ne vale la pena se 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 gestisce la UI nativa.
- @capgo/capacitor-transitions — transizioni di pagina in stile Ionic e swipe-back dal bordo 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 nell'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 del router 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 aree.
Guarda le guide complete: Usando @capgo/capacitor-native-navigation e Uso di @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 spargere env(safe-area-inset-*) manualmente. 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 più 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 la safe area di iOS da un unico wrapper root
Crea un unico app shell e applica lì il padding per la safe area — non in più 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);
}Racchiudi tutto il contenuto della pagina in .app-shell. Il padding della safe-area duplicato in header, modal e wrapper del layout spesso fa apparire l'interfaccia tagliata o troppo grande.
Con @capgo/tailwind-capacitor, puoi applicare lo stesso padding con utility come pt-safe pb-safe px-safe su quella singola shell.
Imposta Capacitor iOS contentInset a never per primo
In capacitor.config.ts, preferisci disabilitare i native inset e lascia che il CSS (o quella contentInsetMode: 'css'di Native Navigation) 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 CSS env(safe-area-inset-*) il padding è una causa comune di spaziature doppie.
Trova il vero 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 live updates alla tua app, così i tuoi utenti hanno sempre accesso alle ultime funzionalità e ai 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.
Continua da: Creare app mobile con SvelteKit e Capacitor
Se stai usando Creare app mobile con SvelteKit e Capacitor per pianificare l'automazione CI/CD e connetterla a CI/CD con Capgo per il workflow del prodotto in Capgo CI/CD, Capgo Native Build per il workflow di prodotto in Capgo Native Builds, Integrazioni Capgo per il workflow di prodotto in Integrazioni Capgo, Integrazione CI/CD per i dettagli implementativi in CI/CD Integration, e Integrazione GitHub Actions per i dettagli implementativi in GitHub Actions Integration.
