In questo tutorial vedremo come creare un'app mobile usando React e Capacitor. Alla fine saprai come trasformare un'app web 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 in React.js in un'app mobile nativa, senza dover apportare modifiche sostanziali o imparare nuove strategie come React Native.
Il processo richiede solo pochi semplici passaggi e, in un attimo, la tua app React.js diventerà un'applicazione mobile completa. 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 contemporaneamente i progetti Xcode e Android Studio. Inoltre, grazie ai suoi plugin, puoi accedere alle funzionalità native del dispositivo, come la fotocamera, tramite un bridge JS.
Capacitor offre un modo semplice per creare un'app mobile nativa senza complicazioni o curve di apprendimento ripide. La sua API intuitiva 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 momento. Prima, vediamo come integrare Capacitor nella nostra app React.
Integrare Capacitor nella tua app React.js
I passaggi iniziali di configurazione potrebbero sembrare dettagliati, ma dopo, aggiornare il wrapper della tua app nativa diventerà semplice come eseguire un sync comando.
Per prima cosa, installeremo la CLI di Capacitor come dev dependency e la configureremo nel progetto. Durante il setup, accetta i valori predefiniti per name e bundle ID premendo "invio".
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.
Poi, 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 per Android serve 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 deployare l'app su un dispositivo reale invece che sul simulatore. Dopo, ti basta premere play per avviare l'app sul dispositivo connesso, selezionabile in alto.
Se tutto è andato per il meglio, avrai convertito la tua web app in React.js in un'applicazione mobile nativa!
Capacitor Live Reload
I moderni framework di sviluppo includono solitamente l'hot reload e, per fortuna, puoi avere lo stesso con Capacitor ma sul tuo dispositivo mobile!
Puoi rendere accessibile la tua app 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.
Successivamente, istruisci Capacitor a caricare l'app direttamente dal server aggiungendo un parametro al tuo file capacitor.config.ts :
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 tuo progetto nativo.
Una volta effettuato il deploy dell'app tramite Android Studio o Xcode, ogni modifica alla tua app React verrà ricaricata e visualizzata automaticamente!
Tieni presente che se installi nuovi plugin, come la fotocamera, è necessario un rebuild del progetto nativo. Questo perché i file nativi saranno cambiati 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 di condivisione nativo:
npm i @capacitor/sharePer usarlo, importa il pacchetto e chiama la relativa share() funzione dalla nostra 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, ricorda di sincronizzare di nuovo 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 applicazioni 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, Liquid Glass tab bar su iOS e uno stile tab bar sfocato su Android. Il tuo React router gestisce lo stato delle rotte; il plugin gestisce la chrome 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 nel tuo 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 areas 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/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 spargere env(safe-area-inset-*) manualmente. Il progetto è in attivo 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 il padding della safe area lì, non in vari 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);
}Avvolgi 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 l'elemento che causa l'overflow
Il colpevole di solito è un elemento che usa 100vw, Tailwind w-screen, con una larghezza fissa in pixel o una 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. Happy coding!
Per saperne di più su come velocizzare il tuo processo di sviluppo app, registrati per un account gratuito oggi.
Continua la lettura: 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.
