Crear aplicaciones móviles con React.js puro y Capacitor

Este tutorial te guiará a través de la creación de una aplicación móvil utilizando React y Capacitor. Al final, sabrás cómo transformar una aplicación web de React.js en una aplicación móvil nativa con Capacitor, y agregar un sentimiento nativo con Capgo Navegación y Transiciones nativas.

Capacitor permite la fácil transformación de tu aplicación web de React.js en una aplicación móvil nativa, requiriendo ninguna alteración sustancial o aprendizaje de nuevas estrategias como 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 completamente funcional. Así que mantente aquí mientras te guiamos en este viaje.

Capacitor Resumen

CapacitorJS es un juego de cambio. Puede integrarse de manera fluida con cualquier proyecto web y envolver su aplicación en una vista web nativa mientras genera el proyecto Xcode y Android Studio nativo. Además, a través de sus plugins, puede acceder a características de dispositivos nativos como la cámara a través de un puente JS.

Capacitor offers a straightforward way to create a native mobile application without any hassle or steep learning curve. Its simple API and streamlined functionality make it easy to incorporate into your project.

Configuración de la Aplicación de React.js

Vamos a elegir el método más sencillo para iniciar una aplicación de React. Usaremos el npm para crear una nueva aplicación de React:

npx create-react-app my-app

Para transformar nuestro proyecto en una aplicación móvil nativa, es necesario un export 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 la Aplicación de React.js

Los pasos de configuración inicial pueden ser un poco detallados, pero después de eso, actualizar el wrapper de la aplicación nativa se vuelve tan simple como ejecutar un sync comando.

Primero, instalaremos el Capacitor CLI como dependencia de desarrollo y lo configuraremos dentro de nuestro proyecto. Durante la configuración, acepte los valores predeterminados para el nombre y el ID de paquete presionando “enter.”

Instalaremos a continuación 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 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

El directorio ios y android ya están presentes en tu proyecto de React.js.

Para acceder al proyecto de Android más adelante, instala Android Studio. Para iOS, necesitas un Mac y debes instalar Xcode.

Actualiza directorioWeb en tu capacitor.config.json archivo 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 sync

La npm run build Este comando compilará tu proyecto de React.js, mientras que npx cap sync se encargará de 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!

Compilando y Desplegando Tus Aplicaciones Nativas

Desarrollar aplicaciones iOS requiere Xcodey aplicaciones de Android necesitan Estudio de AndroidSi planea distribuir su aplicación en la tienda de aplicaciones, debe inscribirse en el Programa de Desarrolladores de Apple para iOS y en el Console de Google Play para Android.

El Capacitor CLI simplifica el proceso de abrir ambos proyectos nativos:

npx cap open ios
npx cap open android

Una vez que sus proyectos nativos estén configurados, desplegar su aplicación en un dispositivo conectado es un proceso sencillo.

Para Estudio de Android, 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 el simulador. Después de hacer eso, 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 Live Reload

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 hospedada sea accesible con live reload en su red al tener la aplicación Capacitor cargar el contenido desde una URL específica.

Primero, determina tu dirección IP local. En un Mac, puedes hacerlo ejecutando ipconfig getifaddr en0 en la terminal. En Windows, ejecuta ipconfig y busca la dirección IPv4.

Después de esto, instruye a Capacitor a 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 realizar una reconstrucción de tu 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 compartirque despliega el diálogo de compartir nativo:

npm i @capacitor/share

Para utilizarlo, importa el paquete y llama al método correspondiente desde nuestra aplicación. Considera el share() App.js Después de instalar un nuevo plugin, recuerda sincronizar tu proyecto de React nuevamente utilizando:

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;

Siguiente, puedes hacer que la aplicación se sienta más nativa en iOS y Android con la navegación y transiciones de __CAPGO_KEEP_0__ y solucionar problemas de diseño comunes de iOS que causan desbordamiento horizontal o áreas de seguridad recortadas. npx cap sync.

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__, utiliza los plugins de __CAPGO_KEEP_1__ en lugar de kits de interfaz de usuario web solo como Konsta UI: .

For a native mobile feel in a React + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

• @capgo/capacitor-navegación nativa — barra de navegación nativa, Liquid Glass de pestañas en iOS, y un estilo de pestañas difuminado en Android. Su router de React mantiene el estado de la 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 sync

Configure 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',
  },
});

Renderice una barra de pestañas de vidrio líquido (iOS utiliza la renderización propia 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 concha:

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 es propietaria de 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). Proporciona safe-areas utilidades y otros plugins de Tailwind Capacitor-amigables:

bun add -D tailwind-capacitor

In src/index.css:

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

Use herramientas como pt-safe, pb-safe, y px-safe en lugar de agregarlos env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para tu configuración de React, abre una PR en GitHub.

Solucionar 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 solucionar el problema. 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 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

Crea un contenedor de aplicación único y aplica el relleno de área segura allí — 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 de .app-shell. El relleno de área duplicado en encabezados, modales y wrappers de diseño a menudo hace 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 ese contenedor único.

Establece Capacitor iOS contentInset a never primero

En capacitor.config.ts, prefiere el relleno de área 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: 'build',
  ios: {
    contentInset: 'never',
  },
};

Mezclar el contenido de inserción 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.

Inspecciona en Safari Web Inspector:

[...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, el relleno de área segura duplicado, o un contenedor de ancho fijo — no del meta de la etiqueta de la vista previa del navegador en sí.

Conclusión

Capacitor ofrece una forma fluida de construir 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 aplicaciones móviles nativas impresionantes. ¡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 Construyendo aplicaciones móviles con React.js puro y Capacitor

Si estás utilizando Construyendo aplicaciones móviles con React.js puro y Capacitor para planificar el comportamiento de medios y la 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-videos para la capacidad nativa en Usando @capgo/capacitor-reproductor-de-videos, @capgo/capacitor-reproductor-de-videos para los detalles de implementación en @capgo/capacitor-reproductor-de-videos, y Usando @capgo/capacitor-navegación-nativa para la capacidad nativa en Usando @capgo/capacitor-navegación-nativa.