Empezaremos con un nuevo React 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 te permite convertir fácilmente tu aplicación web de React en una aplicación móvil nativa sin necesidad de realizar modificaciones significativas o aprender una nueva habilidad como React Native.
Con solo unos pocos pasos simples, la mayoría de las aplicaciones de React pueden ser transformadas en aplicaciones móviles.
Este tutorial le guiará a través del proceso, comenzando con una nueva aplicación de React y luego incorporando Capacitor para moverse al reino de aplicaciones móviles nativas. También puede utilizar Capgo de navegación nativa, transiciones y tailwind-capacitor para áreas seguras.
Sobre Capacitor
CapacitorJS es un cambio de juego! Puede incorporarlo fácilmente en cualquier proyecto web, y lo envolverá en una vista web nativa, generando el proyecto de Xcode y Android Studio nativo para usted. Además, sus plugins proporcionan acceso a características de dispositivo nativo como la cámara a través de un puente de JS.
Con Capacitor, obtiene una fantástica aplicación móvil nativa sin ningún setup complicado o curva de aprendizaje empinada. Su API y funcionalidad escalonada lo hacen un placer integrarlo en su proyecto. Confíe en mí, se sorprenderá de lo fácil que es lograr una aplicación móvil nativa completamente funcional con Capacitor!
Preparando su aplicación de React
Mientras hay varios métodos para iniciar aplicaciones de React, vamos a elegir el más simple 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. Así que incluyamos un script directo en nuestro package.json que se puede utilizar para construir y exportar la aplicación de React:
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}Ahora puedes ejecutar npm run build sin preocupaciones, y deberías poder detectar una carpeta de salida fresca en la raíz de tu proyecto.
Esta carpeta se utilizará por Capacitor más adelante, pero por ahora debemos configurarla correctamente.
Agregar Capacitor a tu aplicación de React
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 solo sync comando.
Primero, podemos instalar el Capacitor CLI como una dependencia de desarrollo, y luego configurarlo dentro de nuestro proyecto. Durante la configuración, puedes pulsar ‘enter’ para aceptar los valores predeterminados para el nombre y el ID de la cesta.
En segundo lugar, debemos 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.
¡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 que contiene algunas configuraciones fundamentales Capacitor utilizadas durante la sincronización. Lo único que debes tener en cuenta es el carpetaWeb, que debe apuntar al resultado de tu comando de compilación. Actualmente, es inexacto.
Para corregir esto, abre el capacitor.config.json archivo y actualiza la carpetaWeb:
{
"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 simplemente compilará tu proyecto de React y exportará la compilación estática.
Mientras que el segundo comando npx cap sync syncronizará todas las web code en los lugares adecuados de las plataformas nativas para que puedan ser visualizadas en una aplicación.
Además, el comando sync puede actualizar las plataformas nativas e instalar plugins, por lo que cuando instales un nuevo plugins de Capacitor es hora de ejecutar npx cap sync de nuevo.
Sin darse cuenta, ahora estás realmente hecho, así que veamos la aplicación en un dispositivo!
Crear y desplegar 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 móvil nativo, puedes usar 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, debes configurar tu cuenta de firma para desplegar tu aplicación en un dispositivo real en lugar de solo en el simulador. Si no lo has hecho antes, Xcode te guía a través del proceso (pero de nuevo, debes 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 por tener la aplicación Capacitor cargar el contenido desde la URL específica.
El primer paso es determinar la dirección IP local. Si estás utilizando un Mac, puedes encontrar esto ejecutando el siguiente comando en la terminal:
ipconfig getifaddr en0On Windows, ejecuta :
ipconfigLuego busca la dirección IPv4.
Puedemos instruir a Capacitor para que cargue la aplicación directamente desde el servidor agregando otra entrada a nuestro archivo: capacitor.config.ts Asegúrate de utilizar
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;la dirección IP y el puerto correctos En este ejemplo, he utilizado el puerto de React por defecto.Ahora, podemos aplicar estos cambios copiándolos a nuestro proyecto nativo:
El
npx cap copycomando es similar a copy El comando es similar a syncpero 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, la aplicación se recargará automáticamente y mostrará los cambios!
Tenga en cuenta que si instala nuevos plugins como la cámara, todavía requiere una reconstrucción del proyecto nativo. Esto se debe a que los archivos nativos se han modificado, y no se puede hacer en tiempo real.
Ten en cuenta que debe utilizar la IP y el puerto correctos en su configuración. El bloque code anterior muestra el puerto de React por defecto para fines de demostración.
Usando Capacitor Plugins
Vamos a echar un vistazo a cómo utilizar un Capacitor plugin en acción, que mencionamos antes. Para hacer esto, podemos instalar un plugin bastante simple ejecutando:
npm i @capacitor/shareNo hay nada especial sobre el Compartir pluginPero, de todas formas, abre el diálogo de compartir nativo! Para esto, ahora solo necesitamos importar el paquete y llamar a la share() función desde nuestra aplicación. Vamos a cambiar el src/App.js a esto:
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;Como se mencionó anteriormente, cuando instalamos nuevos plugins, necesitamos realizar una operación de sincronización y luego volver a desplegar la aplicación en nuestro dispositivo. Para hacer esto, ejecuta el siguiente comando:
npx cap syncDespués de pulsar el botón, puedes ver el hermoso diálogo de compartir nativo en acción!
Enseguida, puedes hacer que la aplicación se sienta más nativa en iOS y Android con Capgo de navegación y transiciones, y solucionar problemas de diseño comunes de iOS que causan desbordamiento horizontal o áreas de seguridad recortadas.
Interfaz de usuario que se siente nativa con Capgo de Navegación Nativa y Transiciones
He trabajado durante años con Ionic para construir aplicaciones de múltiples plataformas, pero integrarla con React es engorrosa y raramente vale la pena cuando ya tienes Tailwind CSS.
Para un sentir móvil nativo en una aplicación React + Capacitor, utilice en su lugar plugins de Capgo en lugar de kits de interfaz de usuario web solo como Konsta UI:
- @capgo/capacitor-navegación-nativa — 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 ruta; el plugin es dueño de la barra de chrome nativa.
- @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 propiedad 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 su capa 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 páginas de ruta en cap-router-outlet, cap-pagey cap-contenty y llamar setDirection('forward') o setDirection('back') antes de navegar. No duplique encabezados o pie de página web cuando la navegación nativa se encarga de 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 del dispositivo en Tailwind CSS, utilice @capgo/tailwind-capacitor (publicado como tailwind-capacitor en el npm). Ofrece safe-areas utilidades y otros plugins de Tailwind compatibles con Capacitor:
bun add -D tailwind-capacitorIn src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utiliza utilidades como pt-safe, pb-safe, y px-safe en lugar de agregarlas env(safe-area-inset-*) manualmente. El proyecto está activamente en desarrollo — si algo falta para tu configuración de React, abre una solicitud de extracción en GitHub.
Corrección de problemas de diseño en 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 no suele solucionar el problema. Pasa por estos controles en orden.
Asegúrate de que la etiqueta meta de viewport se aplique correctamente
Agregar la etiqueta meta de viewport en index.html dentro de <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gestionar el área seguro de iOS desde un solo wrapper raíz
Crear una caja de aplicación única 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);
}Envolver todo el contenido de la página dentro de .app-shellEl relleno de área segura duplicado en encabezados, modales y wrappers de diseño a menudo hace que la interfaz de usuario parezca recortada o demasiado grande.
Con @capgo/tailwind-capacitorpuedes expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa caja única.
Establecer Capacitor iOS contentInset a never Inicialmente
En capacitor.config.ts, prefiere el diseño nativo deshabilitado y deja que CSS (o la navegación nativa) contentInsetMode: 'css') propietario del área segura:
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-*) 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 min-width.
In Safari Web Inspector, 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 rebosamiento horizontal provienen de 100vw / w-screenduplicado relleno de zona segura, o un contenedor de ancho fijo — no del meta etiqueta de viewport en sí.
Conclusion
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 Capgocontexto
If you would like to learn how to add Capgo to your React app, take a look at the next article:
Keep going from Building Mobile Apps with React and Capacitor
Si deseas aprender a agregar __CAPGO_KEEP_0__ a tu aplicación de React, mira el siguiente artículo: Sigue adelante desde Construyendo Aplicaciones Móviles con React y Capacitor para planificar la automatización de CI/CD, conectarlo con Capgo CI/CD para el flujo de trabajo del producto en Capgo CI/CD, Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas, Capgo Integraciones para el flujo de trabajo del producto en Capgo Integraciones, CI/CD Integration para los detalles de implementación en CI/CD Integration, y GitHub Acciones de Integración para los detalles de implementación en GitHub Acciones de Integración.
