Building Mobile Apps with React and Capacitor

In this tutorial, we’ll begin with a new 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 necesidades de modificaciones significativas o aprender una nueva habilidad como React Native.

Con solo unos pocos pasos sencillos, la mayoría de las aplicaciones de React pueden ser transformadas en aplicaciones móviles.

Este tutorial te guiará a través del proceso, comenzando con una nueva aplicación de React y luego incorporando Capacitor para moverte al reino de aplicaciones móviles nativas. También puedes utilizar Capgo de navegación nativa, transiciones y tailwind-capacitor para áreas de seguridad.

Sobre Capacitor

CapacitorJS es un verdadero cambio de juego. Puedes incorporarlo fácilmente en cualquier proyecto web, y lo envolverá en una vista web nativa, generando proyectos Xcode y Android Studio nativos para ti. Además, sus plugins te brindan acceso a características de dispositivos nativos como la cámara a través de un puente JS.

Con Capacitor, obtienes una aplicación móvil nativa fantástica sin ningún tipo de configuración complicada o curva de aprendizaje pronunciada. Su delgado API y funcionalidad simplificada lo hacen un placer integrarlo en tu proyecto. Confía en mí, te sorprenderá lo sencillo que es lograr una aplicación nativa completamente funcional con Capacitor!

Preparando su aplicación de React

Mientras que 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-app

Para crear una aplicación móvil nativa, necesitamos un exportación de nuestro proyecto. Por lo tanto, incluimos un script sencillo 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 esto npm run build sin preocupaciones, y deberías poder encontrar una carpeta de salida recién creada en la raíz de tu proyecto.

Este carpeta será utilizada por Capacitor más adelante, pero por ahora debemos configurarla correctamente.

Agregando Capacitor a tu aplicación de React

Este directorio se utilizará por __CAPGO_KEEP_0__ más adelante, pero por ahora debemos configurarlo correctamente. sync comando.

Primero, 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 la caja.

En segundo lugar, 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 android

En este punto, deberías poder observar nuevos ios y android carpetas en su proyecto de React.

Son proyectos nativos reales!

To 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 capacitor.config.ts archivo en tu proyecto, que contiene algunas configuraciones fundamentales Capacitor utilizadas durante la sincronización. Lo único que debes tener en cuenta 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 actualiza el carpetaWeb:

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "out",
  "bundledWebRuntime": false
}

Puedes probarlo ejecutando los siguientes comandos:

npm run build
npx cap sync

El primer comando npm run build simplemente construirá tu proyecto de React y exportará la construcción estática.

Mientras que el segundo comando npx cap sync sincronizará todos los 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 volver a ejecutar npx cap sync de nuevo.

Sin darte cuenta, ya estás listo, así que veamos la aplicación en un dispositivo!

Construye y Despliega aplicaciones nativas

To 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 android

Una 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 de solo en el simulador. Si no lo has hecho antes, Xcode te guía a través del proceso (pero, una vez más, 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 Recarga en vivo

Hasta ahora, probablemente estás acostumbrado a tener recarga en vivo con todos los marcos modernos, y la buena noticia es que puedes tener la misma funcionalidad en un dispositivo móvil con un mínimo esfuerzo!

Habilite el acceso a su aplicación localmente alojada con recarga en vivo on your network teniendo la aplicación Capacitor cargar el contenido desde la URL específica.

El primer paso es determinar su dirección IP local. Si está utilizando un Mac, puede encontrar esto ejecutando el comando siguiente en la terminal:

ipconfig getifaddr en0

En Windows, ejecuta:

ipconfig

Luego busque la dirección IPv4.

Puedemos instruir a Capacitor para que cargue 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úrate de utilizar la dirección IP y el puerto correctos, he utilizado el puerto de React por defecto en este ejemplo.

Ahora, podemos aplicar estos cambios copiándolos a nuestro proyecto nativo:

npx cap copy

El copy comando es similar a sync, but it will only copie los cambios realizados en la carpeta web y configuración, sin actualizar el proyecto nativo.

Puedes desplegar tu aplicación una vez más a través de Android Studio o Xcode. Después de eso, si cambias algo en tu aplicación de React, La aplicación se recargará automáticamente. ¡y muestra los cambios!

Tenga en cuenta que si instala nuevos plugins 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 usar un plugin Capacitor en acción, que mencionamos antes. Para hacer esto, podemos instalar un plugin bastante simple ejecutando:

npm i @capacitor/share

No hay nada especial en el plugin de Compartir, pero de todos modos 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;

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:

npx cap sync

Después de pulsar el botón, puede ver el diálogo de compartir nativo en acción!

En el siguiente paso, puede hacer que la aplicación se sienta más nativa en iOS y Android con Capgo de navegación y transiciones, y solucione problemas de diseño comunes de iOS que causan rebosamiento horizontal o áreas de seguridad recortadas.

Interfaz de usuario con un sentimiento nativo con Capgo Navegación y Transiciones nativas

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 plugins Capgo en lugar de kits UI solo para web como Konsta UI:

• @capgo/capacitor-native-navigation --- barra de navegación nativa, barra de pestañas de vidrio líquido en iOS, y un estilo de barra de pestañas empañado 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 WebView, sin adoptar la interfaz de usuario de Ionic.

Instale ambos:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Configura 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 propia del sistema; Android utiliza un fondo degradado 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-page, y cap-content, y 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.

Consulte 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). Ofrece safe-areas utilidades y otros plugins de Tailwind compatibles con Capacitor.

bun add -D tailwind-capacitor

In src/index.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Utilice utilidades como pt-safe, pb-safe, y 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.

Corrección de 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 no suele solucionarlo. 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 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);
}

Envuelve todo el contenido de la página dentro .app-shellEl uso duplicado de padding de área segura 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 primero

En capacitor.config.ts, prefiera el diseño nativo deshabilitado y deja que CSS (o la navegación nativa) contentInsetMode: 'css') tenga el área segura:

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'dist',
  ios: {
    contentInset: 'never',
  },
};

Mezclar Capacitor’s contenido automático de inserción con CSS env(safe-area-inset-*) El relleno es una causa común de doble espaciado.

Encuentre el elemento que se desborda realmente

El culpable habitual es un elemento que utiliza 100vwTailwind w-screen, una anchura de píxel fija, o una gran 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 desbordamiento horizontal provienen de 100vw / w-screen, duplicado relleno de área segura, o un contenedor de ancho fijo — no del etiqueta de meta de viewport en sí misma.

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.

And con la adición de CapgoEs incluso más sencillo 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, mira el siguiente artículo:

Sigue adelante desde Construyendo Aplicaciones Móviles con React y Capacitor

Si estás utilizando Construyendo Aplicaciones Móviles 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 Nativos para el flujo de trabajo del producto en Capgo Builds Nativos, 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.