In questo tutorial ti guideremo nella creazione di un'app mobile usando React e Capacitor. Alla fine saprai come trasformare una web app in React.js in un'app mobile nativa con Capacitor, aggiungendo un feeling nativo grazie a Capgo Native Navigation e Transitions.
Capacitor permette di trasformare facilmente la tua web app React.js in un'app mobile nativa, senza richiedere modifiche sostanziali o l'apprendimento di nuove strategie come React Native.
Il processo prevede pochi semplici passaggi e, in un attimo, la tua app React.js diventerà un'applicazione mobile funzionante. Resta con noi mentre ti guidiamo in questo percorso.
Panoramica di Capacitor
CapacitorJS cambia le regole del gioco. Si integra perfettamente con qualsiasi progetto web e avvolge la tua app in una webview nativa, generando i progetti Xcode e Android Studio. Inoltre, tramite i suoi plugin, puoi accedere alle funzioni native del dispositivo, come la fotocamera, via JS bridge.
Capacitor offre un modo semplice per creare un'app mobile nativa senza complicazioni o curve di apprendimento ripide. Il suo API intuitivo e le funzionalità ottimizzate lo rendono facile da integrare nel tuo progetto.
Configurazione della tua App React.js
Usiamo il metodo più semplice per avviare un'applicazione React. Utilizzeremo il package manager npm per creare una nuova app React:
npx create-react-app my-appPer trasformare il nostro progetto in un'app mobile nativa, è necessario un export della nostra app.
Torniamo su questo punto tra un attimo. Prima, vediamo come integrare Capacitor nella nostra app React.
Integrare Capacitor nella tua app React.js
I passaggi iniziali per il setup potrebbero sembrare un po' dettagliati, ma dopo sarà semplicissimo aggiornare il tuo wrapper nativo con un semplice sync comando.
Per prima cosa, installeremo il Capacitor CLI come dev dependency e lo configureremo nel progetto. Durante il setup, accetta i valori predefiniti per name e bundle ID premendo “enter”.
Successivamente, installeremo il pacchetto core e i pacchetti necessari per le piattaforme iOS e Android.
Infine, aggiungeremo le piattaforme e Capacitor creerà le cartelle per ogni piattaforma nella root del progetto:
# Install the Capacitor CLI locally
npm install -D @capacitor/cli
# Initialize Capacitor in your React 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 androidIl iOS e Android le directory sono ora presenti nel tuo progetto React.js.
Per accedere al progetto Android in seguito, installa Android Studio. Per iOS, ti serve un Mac e devi installare Xcode.
Successivamente, aggiorna il webDir nel tuo capacitor.config.json file come mostrato di seguito:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}Esegui il comando di build e sincronizza il tuo progetto con Capacitor:
npm run build
npx cap syncIl npm run build il comando eseguirà il build del tuo progetto React.js, mentre npx cap sync allineerà il code web nelle posizioni corrette delle piattaforme native per l'esecuzione nell'app.
Ora, con un po' di fortuna e senza errori, la tua app React.js dovrebbe essere pronta per il lancio su un dispositivo!
Build e deploy delle tue app native
Sviluppare app iOS richiede Xcode, e le app Android richiedono Android Studio. Se intendi distribuire la tua app sugli store, devi iscriverti all'Apple Developer Program per iOS e alla Google Play Console per Android.
Il Capacitor CLI semplifica l'apertura di entrambi i progetti nativi:
npx cap open ios
npx cap open androidUna volta configurati i progetti nativi, il deploy della tua app su un dispositivo connesso è un processo semplicissimo.
Per Android Studio, attendi il caricamento completo e poi fai il deploy della tua app su un dispositivo connesso.
Per Xcode, configura il tuo account di signing per fare il deploy della tua app su un dispositivo reale invece che sul simulatore. Dopo averlo fatto, premi play per avviare l'app sul dispositivo connesso, che puoi selezionare in alto.
Se tutto è andato per il verso giusto, avrai convertito la tua web app in React.js in un'applicazione mobile nativa!
Live Reload con Capacitor
I moderni framework di sviluppo solitamente includono l'hot reload e, fortunatamente, puoi avere lo stesso con Capacitor, ma sul tuo dispositivo mobile!
Puoi rendere accessibile la tua applicazione locale con live reload sulla tua rete facendo caricare i contenuti all'app Capacitor da un URL specifico.
Per prima cosa, individua il tuo indirizzo IP locale. Su Mac, puoi farlo eseguendo ipconfig getifaddr en0 nel terminale. Su Windows, esegui ipconfig e cerca l'indirizzo IPv4.
Dopo questo, istruisci Capacitor a caricare l'app direttamente dal server aggiungendo un altro parametro al tuo capacitor.config.ts dell'app:
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'build',
bundledWebRuntime: false,
server: {
url: 'http://192.168.x.xx:3000',
cleartext: true
}
};
export default config;Assicurati di usare l'IP e la porta corretti. Esegui npx cap copy per applicare queste modifiche al nostro progetto nativo.
Una volta effettuato il deploy della tua app tramite Android Studio o Xcode, ogni modifica alla tua app React verrà ricaricata e visualizzata automaticamente!
Tieni presente che l'installazione di nuovi plugin, come la fotocamera, richiede un rebuild del progetto nativo. Questo perché i file nativi cambiano e non possono essere aggiornati on the fly.
Utilizzo dei plugin Capacitor
Vediamo rapidamente come usare un plugin Capacitor. Installiamone uno semplice, il Plugin di condivisione, che apre il dialog nativo per la condivisione:
npm i @capacitor/sharePer usarlo, importa il pacchetto e chiama la relativa share() function dalla tua app. Considera il App.js:
import { Share } from '@capacitor/share';
function ShareButton() {
const share = async () => {
await Share.share({
title: 'React App',
text: 'Visit this React App',
url: 'http://localhost:3000',
dialogTitle: 'Share with...'
});
};
return (
<button onClick={share}>
Share
</button>
);
}
export default ShareButton;Dopo aver installato un nuovo plugin, ricordati di sincronizzare nuovamente il tuo progetto React usando npx cap sync.
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 React è complicato e raramente ne vale la pena se hai già Tailwind CSS.
Per un feeling mobile nativo in un'app React + 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 tuo React router 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 }) => {
navigate(`/${id}`);
});Aggiungi transizioni di pagina native nell'app shell:
import { useEffect, useRef } from 'react';
import { useNavigate } from 'react-router-dom';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });
export function AppShell() {
const navigate = useNavigate();
const outletRef = useRef<HTMLElement>(null);
useEffect(() => {
if (outletRef.current) {
setupRouterOutlet(outletRef.current, { platform: 'auto', swipeGesture: 'auto' });
}
}, []);
const openSettings = () => {
setDirection('forward');
navigate('/settings');
};
return <cap-router-outlet ref={outletRef}>{/* routes */}</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 se la navigazione nativa gestisce già 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). Offre safe-areas utility e altri plugin Tailwind compatibili con Capacitor:
bun add -D tailwind-capacitorIn src/index.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 sparpagliare env(safe-area-inset-*) a mano. Il progetto è in costante sviluppo — se manca qualcosa per il tuo setup React, 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
Aggiungi il meta tag viewport in index.html dentro <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,
#root {
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 offre un modo fluido per creare app native partendo da un progetto web esistente, permettendo di condividere facilmente code e mantenere una UI coerente.
Grazie a tecnologie come Capacitor, creare app mobile da web app in React.js non è mai stato così semplice. Porta le tue competenze di web development al livello successivo creando app native incredibili. Buon coding!
Per saperne di più su come velocizzare il tuo processo di sviluppo app, registrati per un account gratuito oggi.
Continua la lettura da Building Mobile Apps with Pure React.js and Capacitor
Se stai usando Creare app mobile con Pure React.js e Capacitor per pianificare il comportamento dei media nativi e dell'interfaccia, collegalo a Uso di @capgo/capacitor-live-activities per la funzionalità nativa nella pagina Uso di @capgo/capacitor-live-activities, @capgo/capacitor-live-activities per il dettaglio implementativo in @capgo/capacitor-live-activities, Uso di @capgo/capacitor-video-player per la funzionalità nativa in Utilizzo di @capgo/capacitor-video-player, @capgo/capacitor-video-player per i dettagli di implementazione in @capgo/capacitor-video-player, e Usando @capgo/capacitor-native-navigation per la funzionalità nativa in Usando @capgo/capacitor-native-navigation.
