This tutorial will walk you through crafting a mobile application using React and Capacitor. By the end, you’ll know how to morph a React.js web app into a native mobile application with Capacitor, and add a native feel with Capgo Native Navigation and Transitions.
Capacitor enables the easy transformation of your React.js web app into a native mobile application, requiring no substantial alterations or learning of new strategies such as React Native.
El proceso implica unos pocos pasos simples, y antes de que lo sepas, tu aplicación de React.js será una aplicación móvil funcional. Así que mantente aquí mientras te guío en este viaje.
Capacitor Overview
CapacitorJS es un juego de cambio. Puede integrarse de manera fluida con cualquier proyecto web y envolver tu aplicación en una vista web nativa mientras genera el proyecto de Xcode y Android Studio nativo. Además, a través de sus plugins, puedes acceder a características de dispositivos nativos como la cámara a través de un puente JS.
Capacitor ofrece una forma sencilla de crear una aplicación móvil nativa sin ningún problema o curva de aprendizaje pronunciada. Su API simple y funcionalidad escalonada lo hacen fácil de incorporar en tu proyecto.
Configuración de tu aplicación de React.js
Vamos a utilizar el método más sencillo para iniciar una aplicación de React. Usaremos el administrador de paquetes npm para crear una nueva aplicación de React:
npx create-react-app my-appPara transformar nuestro proyecto en una aplicación móvil nativa, un exportación de nuestra aplicación.
Volveremos a esto en un momento. Primero, debemos entender cómo integrar Capacitor en nuestra aplicación de React.
Integración de Capacitor en tu aplicación de React.js
La configuración inicial puede ser un poco detallada, pero después de eso, actualizar su wrapper de aplicación nativa se vuelve tan simple como ejecutar un sync comando.
Primero, instalaremos el Capacitor CLI como una dependencia de desarrollo y lo configuraremos dentro de nuestro proyecto. Durante la configuración, acepta los valores predeterminados para el nombre y el ID de paquete presionando “enter”.
Después, instalaremos el paquete principal y los paquetes relevantes para las plataformas iOS y Android.
Finalmente, agregaremos las plataformas, y Capacitor creará carpetas para cada plataforma en nuestra raíz de proyecto:
# 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 androidEl ios y android Las carpetas ahora están presentes en su proyecto de React.js.
Para acceder al proyecto de Android más adelante, instale Android Studio. Para iOS, necesita un Mac y debe instalar Xcode.
Siguiente, actualice webDir en tu capacitor.config.json como se muestra a continuación:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}Ejecuta el comando de compilación y sincroniza tu proyecto con Capacitor:
npm run build
npx cap syncLa npm run build comando construirá tu proyecto de React.js, mientras que npx cap sync se alineará el web code en los lugares precisos de las plataformas nativas para que puedan ejecutarse en una aplicación.
Ahora, con un poco de suerte y sin errores, tu aplicación de React.js debería estar lista para su lanzamiento en un dispositivo!
Crear y Desplegar Aplicaciones Nativas
Desarrollar aplicaciones de iOS requiere Xcode, y las aplicaciones de Android necesitan Android StudioSi planea distribuir su aplicación en la tienda de aplicaciones, debe inscribirse en el programa de desarrolladores de Apple para iOS y en el consola de Google Play para Android.
El Capacitor CLI simplifica el proceso de abrir ambos proyectos nativos:
npx cap open ios
npx cap open androidUna vez que sus proyectos nativos estén configurados, desplegar su aplicación en un dispositivo conectado es un proceso sencillo.
Para Android Studio, espere a que todo se cargue y luego despliegue su aplicación en un dispositivo conectado.
Para Xcode, establezca su cuenta de firma para desplegar su aplicación en un dispositivo real en lugar de solo en el simulador. Después de hacerlo, simplemente presione play para ejecutar la aplicación en su dispositivo conectado, que puede elegir en la parte superior.
Si todo ha ido bien, habrá convertido su aplicación web de React.js en una aplicación móvil nativa!
Capacitor Recarga en vivo
Los marcos de desarrollo modernos suelen venir con hot reload, y afortunadamente, puede tener lo mismo con Capacitor pero en su dispositivo móvil!
Puede hacer que su aplicación localmente alojada sea accesible con live reload en su red al tener la aplicación Capacitor cargar el contenido desde una URL específica.
Primero, determine su dirección IP local. En un Mac, puede hacerlo ejecutando ipconfig getifaddr en0 en el terminal. En Windows, ejecuta ipconfig y busca la dirección IPv4.
Después de esto, instruye a Capacitor para cargar la aplicación directamente desde el servidor agregando otro parámetro a tu capacitor.config.ts archivo:
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;Asegúrate de utilizar la IP y el puerto precisos. Ejecuta npx cap copy para aplicar estos cambios a nuestro proyecto nativo.
Al desplegar tu aplicación una vez más a través de Android Studio o Xcode, cualquier cambio en tu aplicación de React se recargarán automáticamente y se mostrarán en tu aplicación.
Tenga en cuenta que si se instalan nuevos plugins, como la cámara, es necesario reconstruir el proyecto nativo. Esto se debe a que los archivos nativos habrán cambiado y no pueden ser actualizados en tiempo real.
Usando Capacitor Plugins
Vamos a echar un vistazo rápido a cómo utilizar un plugin de Capacitor. Vamos a instalar uno simple, el plugin de compartir, que muestra el diálogo de compartir nativo:
npm i @capacitor/sharePara utilizarlo, importe el paquete y llame al método correspondiente share() función de nuestra aplicación. Ten en cuenta el 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;Sincronice de nuevo tu proyecto de React después de instalar un nuevo plugin. npx cap sync.
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.
Interfaz de usuario con un sentimiento nativo con Capgo Navegación y Transiciones nativas
He trabajado durante años con Ionic para crear aplicaciones de múltiples plataformas, pero integrarlo con React es engorroso y raramente vale la pena cuando ya tienes Tailwind CSS.
Para un sentir móvil nativo en una aplicación de React + Capacitor, utilice plugins Capgo en lugar de kits de interfaz de usuario web solo como Konsta UI:
- @capgo/capacitor-native-navigation – barra de navegación nativa, Liquid Glass barra de pestañas en iOS y un estilo de barra de pestañas difuminado en Android. Su router de React mantiene el estado de la ruta; el plugin posee el navegador nativo.
- @capgo/capacitor-transiciones Transiciones de página estilo Ionic y retroceso por swipe en iOS en la capa de WebView, sin adoptar la interfaz de usuario de Ionic.
Instale ambos:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigure la navegación nativa con el modo de inserción CSS para que el contenido web respete las barras nativas:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Render un tablero de Liquid Glass (iOS utiliza la renderización del sistema; Android utiliza un fondo difuminado de 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 }) => {
navigate(`/${id}`);
});Agregue transiciones de página nativas en la caja de su aplicación:
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>;
}Envuelva las páginas de rutas en cap-router-outlet, cap-pagey cap-contenty llame a setDirection('forward') o setDirection('back') antes de navegar. No duplique encabezados o pie de página web cuando la navegación nativa controla esas superficies.
Ver las guías completas: Usando @capgo/capacitor-navegación nativa y Usando @capgo/capacitor-transiciones.
Áreas seguras con Tailwind
Para áreas seguras de dispositivos en Tailwind CSS, use @capgo/tailwind-capacitor (publicado como) tailwind-capacitor en npm. Ofrece safe-areas utilidades y otros plugins de Tailwind amigables con Capacitor:
bun add -D tailwind-capacitorEn src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilice utilidades como pt-safe, pb-safey px-safe en lugar de esparcir env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para tu configuración de React, abre una PR en GitHub.
Resolviendo Problemas de Diseño de iOS (Viewport, Área Segura y Desbordamiento Horizontal)
Si el contenido parece recortado, desplazado o desplazable horizontalmente en iOS, agregar más overflow-x: hidden o ajustar la etiqueta de viewport sola usualmente no lo resuelve. Trabaja a través de estos controles en orden.
Asegúrate de que la etiqueta meta de viewport se aplique correctamente
Agrega la etiqueta meta de viewport en index.html dentro <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gestiona el área segura de iOS desde un solo contenedor raíz
Crear un solo contenedor de aplicación y aplicar allí el relleno de área segura — no en múltiples componentes anidados:
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);
}Wrap all page content inside .app-shellEl uso duplicado de la zona de seguridad en encabezados, modales y wrappers de diseño puede hacer que la interfaz de usuario se vea recortada o demasiado grande.
Con @capgo/tailwind-capacitor, puedes expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa sola capa.
Establece Capacitor iOS contentInset a never first
primero capacitor.config.ts, prefiera el diseño nativo deshabilitado y deja que CSS (o la navegación nativa) contentInsetMode: 'css'Propietario de la zona segura:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Mezclar Capacitor’s ajuste automático de contenido con CSS env(safe-area-inset-*) El relleno de padding es una causa común de doble espaciado.
Encuentre el elemento que se desborda realmente
El culpable habitual es un elemento que utiliza 100vw, Tailwind w-screenuna anchura de píxel fija, o una gran min-width.
En Safari Web Inspector, ejecute:
[...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, reemplace w-screen con w-full cuando sea posible. Muchos problemas de desbordamiento horizontal provienen de 100vw / w-screenNo se debe obtener el tamaño de la ventana del viewport meta tag en sí mismo.
Conclusión
Capacitor ofrece una forma fluida de crear aplicaciones nativas basadas en un proyecto web existente, proporcionando una forma sencilla de compartir code y tener una interfaz de usuario consistente.
Gracias a tecnologías como Capacitor, nunca ha sido más fácil crear aplicaciones móviles a partir de aplicaciones web de React.js. Lleva tus habilidades de desarrollo web al siguiente nivel creando impresionantes aplicaciones móviles nativas. ¡Disfruta codificando!
Para obtener más información sobre cómo acelerar tu proceso de desarrollo de aplicaciones, regístrate para una cuenta gratuita hoy.
Sigue adelante desde Crear aplicaciones móviles con React.js puro y Capacitor
Si estás utilizando Crear aplicaciones móviles con React.js puro y Capacitor para planificar el comportamiento de medios y interfaz nativa, conecta con Usando @capgo/capacitor-actividades-en-vivo para la capacidad nativa en Usando @capgo/capacitor-actividades-en-vivo, @capgo/capacitor-actividades-en-vivo para los detalles de implementación en @capgo/capacitor-actividades en vivo, Usando @capgo/capacitor-reproductor de video para la capacidad nativa en Usando @capgo/capacitor-reproductor de video, @capgo/capacitor-reproductor de video para los detalles de implementación en @capgo/capacitor-reproductor de video, y Usando @capgo/capacitor-navegación nativa para la capacidad nativa en Usando @capgo/capacitor-navegación nativa.
