En este tutorial, comenzaremos con una nueva aplicación de React y transitaremos a un desarrollo móvil nativo utilizando __CAPGO_KEEP_0__. También puedes agregar __CAPGO_KEEP_1__ de Navegación Nativa y Transiciones para un sentir móvil nativo, y utilizar tailwind-__CAPGO_KEEP_2__ para áreas seguras. app and transition to native mobile development using Capacitor. You can also add Capgo Native Navigation and Transitions for a native mobile feel, and use tailwind-capacitor for safe areas.
Capacitor allows you to easily convert your React web application into a native mobile app without significant modifications or learning a new skill like React Native.
Este tutorial te guiará a través del proceso, comenzando con una nueva aplicación de React y luego incorporando __CAPGO_KEEP_0__ para moverte al reino de las aplicaciones móviles nativas. También puedes utilizar __CAPGO_KEEP_1__ de Navegación Nativa, Transiciones y tailwind-__CAPGO_KEEP_2__ para áreas seguras.
This tutorial will guide you through the process, starting with a new React app and then incorporating Capacitor to move into the realm of native mobile apps. You can also use Capgo Native Navigation, Transitions, and tailwind-capacitor for safe areas.
About Capacitor
Martin Donadieu es Gerente de Contenido en Capgo. Con experiencia en marketing digital y contenido, ayuda a las empresas a crear historias que conectan con sus audiencias. En su tiempo libre, disfruta explorando nuevas tecnologías y aplicaciones móviles.
Con Capacitor, obtienes una aplicación móvil nativa fantástica sin ninguna configuración complicada o curva de aprendizaje pronunciada. Su API delgado y su funcionalidad simplificada lo hacen un placer integrarlo en tu proyecto. Confía en mí, te sorprenderá lo fácil que es lograr una aplicación nativa funcional completa con Capacitor!
Preparando tu aplicación de React
Si bien existen varios métodos para iniciar aplicaciones de React, vamos a elegir el más sencillo en este tutorial que proporciona una aplicación de React en blanco:
npx create-react-app my-appPara crear una aplicación móvil nativa, necesitamos un export de nuestro proyecto. Por lo tanto, incluyamos un script directo en nuestro package.json que se puede utilizar para construir y exportar el proyecto de React:
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}Puedes ejecutar npm run build sin preocupaciones, y deberías poder ver un nuevo directorio
This folder will be used by Capacitor later on, but for now, we must set it up correctly.
Este directorio se utilizará por Capacitor más adelante, pero por ahora debemos configurarlo correctamente.
Para empaquetar cualquier aplicación web en un contenedor móvil nativo, debemos seguir unos pocos pasos inicialmente, pero posteriormente es tan simple como ejecutar un sync command.
En primer lugar, podemos instalar el Capacitor CLI como una dependencia de desarrollo, y luego configurarlo dentro de nuestro proyecto. Durante la configuración, puede pulsar “enter” para aceptar los valores predeterminados para el nombre y el ID de paquete.
A continuación, necesitamos instalar el paquete principal y los paquetes relevantes para las plataformas iOS y Android.
Finalmente, podemos agregar las plataformas, y Capacitor creará carpetas para cada plataforma en la raíz de nuestro 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 androidEn este punto, deberías poder observar nuevas ios y android carpetas en tu proyecto de React.
¡Estos son proyectos nativos reales!
Para acceder al proyecto de Android más tarde, debes instalar Android Studio. Para iOS, necesitas un Mac y debes instalar Xcode.
Además, debes encontrar un archivo capacitor.config.ts en tu proyecto, que contiene algunas configuraciones fundamentales Capacitor utilizadas durante la sincronización. La única cosa a la que debes prestar atención es el webDir, que debe apuntar al resultado de tu comando de compilación. Actualmente, es inexacto.
Para corregir esto, abre el capacitor.config.json archivo y actualizar el webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}Puedes probarlo ejecutando los siguientes comandos:
npm run build
npx cap syncEl primer comando npm run build solo construirá tu proyecto de React y exportará la construcción estática.
Mientras que el segundo comando npx cap sync sincronizará todos los archivos web code en los lugares adecuados de las plataformas nativas para que puedan ser mostrados en una aplicación.
Además, el comando de sincronización podría actualizar las plataformas nativas e instalar plugins, por lo que cuando instales un nuevo Capacitor plugins es hora de ejecutar npx cap sync de nuevo.
Sin darte cuenta, ya estás hecho, así que veamos la aplicación en un dispositivo!
Desarrolla y despliega aplicaciones nativas
Para desarrollar aplicaciones iOS, necesitas tener Xcode instalado, y para aplicaciones Android, necesitas tener Android Studio instalado. Además, si planeas distribuir tu aplicación en la tienda de aplicaciones, necesitas inscribirte en el Programa de Desarrolladores de Apple para iOS y en el Console de Google Play para Android.
Si eres nuevo en el desarrollo de aplicaciones móviles nativas, puedes utilizar el Capacitor CLI para abrir fácilmente ambos proyectos nativos:
npx cap open ios
npx cap open androidUna vez que hayas configurado tus proyectos nativos, desplegar tu aplicación en un dispositivo conectado es fácil. En Android Studio, solo necesitas esperar a que todo esté listo, y puedes desplegar tu aplicación en un dispositivo conectado sin cambiar ninguna configuración. Aquí tienes un ejemplo:
En Xcode, necesitas configurar tu cuenta de firma para desplegar tu aplicación en un dispositivo real en lugar del simulador. Si no lo has hecho antes, Xcode te guía a través del proceso (pero de nuevo, necesitas estar inscrito en el Programa de Desarrolladores). Después de eso, puedes simplemente pulsar play para ejecutar la aplicación en tu dispositivo conectado, que puedes seleccionar en la parte superior. Aquí tienes un ejemplo:
Felicidades! Has desplegado con éxito tu aplicación web de React en un dispositivo móvil. Aquí tienes un ejemplo:
Pero espera, hay una forma más rápida de hacer esto durante el desarrollo…
Capacitor Live Reload
Por ahora, probablemente estás acostumbrado a tener hot reload con todas las marcos modernas, y la buena noticia es que puedes tener la misma funcionalidad en un dispositivo móvil con un mínimo esfuerzo!
Habilita el acceso a tu aplicación localmente alojada con live reload en tu red teniendo la aplicación Capacitor cargar el contenido desde la URL específica.
El primer paso es determinar tu dirección IP local. Si estás utilizando un Mac, puedes encontrar esto ejecutando el siguiente comando en la terminal:
ipconfig getifaddr en0En Windows, ejecuta:
ipconfigLuego busca la dirección IPv4.
We podemos instruir Capacitor para cargar la aplicación directamente desde el servidor agregando otra entrada a nuestro capacitor.config.ts archivo:
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'out',
bundledWebRuntime: false,
server: {
url: 'http://192.168.x.xx:3000',
cleartext: true
}
};
export default config;Asegúrese de utilizar el IP y puerto correctosEn este ejemplo, he utilizado el puerto de React por defecto.
Ahora, podemos aplicar estos cambios copiándolos a nuestro proyecto nativo:
npx cap copyEl copy comando es similar a sync, pero solo copiará los cambios realizados en la carpeta web y la configuración, sin actualizar el proyecto nativo.
Puede desplegar su aplicación una vez más a través de Android Studio o Xcode. Después de eso, si cambia algo en su aplicación de React, El app se recargará automáticamente y mostrará los cambios!
Tenga en cuenta que si instala nuevos complementos como la cámara, todavía requiere una reconstrucción de su proyecto nativo. Esto se debe a que los archivos nativos se han modificado, y no se puede hacer en tiempo real.
Nota que debe utilizar la IP y el puerto correctos en su configuración. El bloque code anterior muestra el puerto de demostración de React por defecto.
Usando Capacitor Plugins
Vamos a ver cómo utilizar un Capacitor plugin en acción, que mencionamos antes. Para hacer esto, podemos instalar un complemento bastante simple ejecutando:
npm i @capacitor/shareNo hay nada sofisticado en el Compartir plugin, pero de todos modos muestra el diálogo de compartir nativo. Para esto, ahora solo necesitamos importar el paquete y llamar al share() función desde nuestra app. Vamos a cambiar el src/App.js As mencionado anteriormente, cuando instalamos nuevos plugins, debemos realizar una operación de sincronización y luego volver a desplegar la aplicación en nuestro dispositivo. Para hacer esto, ejecute el siguiente comando:
import React from 'react';
import { Share } from '@capacitor/share';
function App() {
const share = async () => {
await Share.share({
title: 'Open Youtube',
text: 'Check new video on youtube',
url: 'https://www.youtube.com',
dialogTitle: 'Share with friends'
});
};
return (
<div>
<h1>Welcome to React and Capacitor!</h1>
<p>
<h2>Cool channel</h2>
<button onClick={() => share()}>Share now!</button>
</p>
</div>
);
}
export default App;Después de pulsar el botón, puede ver el diálogo de compartir nativo en acción!
npx cap syncreact-__CAPGO_KEEP_0__-share
Interfaz de usuario que se siente nativa con Capgo Navegación y Transiciones Nativas
Native-feeling UI with Capgo Native Navigation and Transitions
Ionic para crear aplicaciones de múltiples plataformas, pero integrarla con React es engorroso y raramente vale la pena cuando ya tienes Tailwind CSS Para un sentir móvil nativo en una aplicación React + __CAPGO_KEEP_0__, utilice en su lugar plugins __CAPGO_KEEP_1__ en lugar de kits de interfaz de usuario web solo como Konsta UI:.
@Capacitor/Capgo-native-navigation
- @capgo/capacitor-native-navigation — barra de navegación nativa, Liquid Glass de pestañas en iOS, y un estilo de pestañas desenfocadas en Android. Su router de React mantiene el estado de ruta; el complemento posee el navegador nativo.
- @capgo/capacitor-transiciones — transiciones de página estilo Ionic y retroceso de arrastre 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 de 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',
},
});Renderice una barra de pestañas de vidrio líquido (iOS utiliza la renderización propia del sistema; Android utiliza un fondo desenfocado 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 su capa de concha de 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-page, y cap-content, y llame a setDirection('forward') o setDirection('back') antes de navegar. No duplique los encabezados o pie de página web cuando la navegación nativa posee esas superficies.
Vea 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, utilice @capgo/tailwind-capacitor (publicado como tailwind-capacitor en npm). Proporciona 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-*) por mano. El proyecto está activamente desarrollado — si algo falta para tu configuración de React, abre una PR en GitHub.
Corrección de problemas de diseño de iOS (Viewport, Área Segura y Desbordamiento Horizontal)
Si el contenido parece recortado, desplazado o horizontalmente desplazable en iOS, agregar más overflow-x: hidden o ajustar la etiqueta de viewport sola no suele solucionar el problema. Trabaja a través de estas comprobaciones en orden.
Asegúrate de que la etiqueta meta de viewport se aplique correctamente
Agrega la etiqueta meta de viewport en index.html dentro de <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 contenedor de aplicación único 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);
}Envuelva todo el contenido de la página dentro de .app-shellSe duplicó el relleno de área de seguridad en encabezados, modales y wrappers de diseño, lo que a menudo hace que la interfaz de usuario se vea recortada o demasiado grande.
Con @capgo/tailwind-capacitor, puede expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en ese solo contenedor.
Establezca Capacitor iOS contentInset a never primero
En capacitor.config.ts, prefiera el área de seguridad deshabilitada nativa y deja que CSS (o la navegación nativa) contentInsetMode: 'css') propietaria del área de seguridad:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Mezclar el contenido automático de Capacitor con CSS env(safe-area-inset-*) El relleno de padding es una causa común de espaciado doble.
Encuentra el elemento que está desbordando realmente
El culpable habitual es un elemento que utiliza 100vw, Tailwind w-screen, una anchura de píxeles fija, o un ancho muy grande min-width.
Inicia el Safari Web Inspector y ejecuta:
[...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, reemplaza w-screen con w-full cuando sea posible. Muchos problemas de desbordamiento horizontal provienen de 100vw / w-screen, duplicado relleno de área de seguridad segura, o un contenedor de ancho fijo — no del meta de etiqueta de viewport en sí.
Conclusión
Capacitor es una excelente opción para crear aplicaciones nativas basadas en un proyecto web existente, ofreciendo una forma sencilla de compartir code y mantener una interfaz de usuario consistente.
Y con la adición de Capgo",es aún más fácil agregar actualizaciones en vivo a tu aplicación, asegurando que tus usuarios siempre tengan acceso a las últimas características y correcciones de errores.
Si deseas aprender a agregar Capgo a tu aplicación de React, consulta el siguiente artículo:
Sigue adelante desde Building Mobile Apps con React y Capacitor
Si estás utilizando Building Mobile Apps con React y Capacitor para planificar la automatización de CI/CD, conecta con Capgo CI/CD para el flujo de trabajo del producto en Capgo CI/CD, Capgo Builds Nativas para el flujo de trabajo del producto en Capgo Construcción Nativa, Capgo Integraciones para el flujo de trabajo del producto en Capgo Integraciones, Integración CI/CD para el detalle de implementación en Integración CI/CD, y GitHub Integración de Acciones para el detalle de implementación en GitHub Integración de Acciones.
