このチュートリアルでは、ReactとCapacitor を使用してモバイルアプリケーションを作成する手順を解説します。最後まで読むと、React.jsのWebアプリをCapacitor でネイティブモバイルアプリへと変換する方法や、Capgo Native Navigation と Transitions を使ってネイティブのような操作感を実現する方法が分かります。
Capacitor を使えば、React.jsのWebアプリを簡単にネイティブモバイルアプリへ変換できます。React Native のような新しい手法を学んだり、大幅なコード変更を行ったりする必要はありません。
プロセスはいくつかのシンプルなステップで構成されており、気づけばあなたの React.js アプリは完全に動作するモバイルアプリケーションになっています。それでは、このガイドに沿って進めていきましょう。
Capacitor の概要
CapacitorJS は革新的なツールです。あらゆるWebプロジェクトとシームレスに統合し、アプリをネイティブのWebViewでラップしながら、Xcode や Android Studio のネイティブプロジェクトを生成します。さらに、プラグインを通じて JS bridge 経由でカメラなどのネイティブデバイス機能にアクセスできます。
Capacitor は、手間や学習コストを抑えてネイティブモバイルアプリを作成する直感的な方法を提供します。シンプルな API と合理化された機能により、プロジェクトへの導入も容易です。
React.js アプリのセットアップ
まずは最もシンプルな方法で React アプリケーションを開始しましょう。npm パッケージマネージャーを使用して、新しい React アプリを作成します：
npx create-react-app my-appプロジェクトをネイティブモバイルアプリに変換するには、 エクスポート of our app is required.
これについては後ほど詳しく説明します。まずは、Reactアプリに Capacitor を統合する方法を理解しましょう。
React.jsアプリへの Capacitor の統合方法
初期セットアップの手順は少し詳しく感じるかもしれませんが、一度完了すれば、ネイティブアプリのラッパーを更新するのは、単にコマンドを実行するだけで済むようになります。 sync コマンドを実行してください。
まず、Capacitor の CLI を開発用依存関係としてインストールし、プロジェクト内でセットアップします。セットアップ中は、Enterキーを押して、名前とbundle IDのデフォルト値をそのまま受け入れてください。
次に、コアパッケージと、iOSおよびAndroidプラットフォーム向けの関連パッケージをインストールします。
最後に、各プラットフォームを追加します。すると、Capacitor がプロジェクトのルートに各プラットフォーム用のフォルダを作成します：
# 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この iOS と Android React.jsプロジェクト内にディレクトリが作成されました。
後でAndroidプロジェクトにアクセスできるように、以下をインストールしてください： デバッグ。iOSの場合はMacが必要で、次をインストールしてください： iOSプロファイリング.
次に、以下を更新します： webDir に capacitor.config.json ファイル（下記参照）：
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}ビルドコマンドを実行し、Capacitor とプロジェクトを同期させます：
npm run build
npx cap syncこの npm run build コマンドでReact.jsプロジェクトをビルドし、同時に npx cap sync web code をネイティブプラットフォームの適切な場所に配置し、アプリ内で実行できるようにします。
これで、運が良ければエラーもなく、React.js アプリをデバイスで起動する準備ができたはずです！
ネイティブアプリのビルドとデプロイ
iOS アプリの開発には iOSプロファイリング、Androidアプリには デバッグアプリをApp Storeで配布する予定なら、iOSはApple Developer Program、AndroidはGoogle Play Consoleへの登録が必要です。
Capacitor CLI を使えば、両方のネイティブプロジェクトを開く手順が簡単になります：
npx cap open ios
npx cap open androidネイティブプロジェクトのセットアップが完了すれば、接続したデバイスへのアプリのデプロイは簡単です。
Android Studioの場合は、すべての読み込みが完了するのを待ってから、接続したデバイスにアプリをデプロイしてください。
Xcodeの場合は、シミュレーターではなく実機にデプロイするために署名アカウントを設定してください。設定が済んだら、上部で選択した接続済みデバイスでアプリを実行するために再生ボタンを押すだけです。
すべてうまくいけば、React.jsのWebアプリをネイティブのモバイルアプリに変換できたことになります！
Capacitor Live Reload
モダンな開発フレームワークには通常ホットリロードが備わっていますが、幸いなことに Capacitor でも同じことができます。ただし、 モバイルデバイス上で!
Capacitor アプリに特定のURLからコンテンツを読み込ませることで、ローカルでホストしているアプリをネットワーク経由でライブリロードできるようになります。
まず、ローカルIPアドレスを確認します。Macの場合は、ターミナルで次を実行します ipconfig getifaddr en0 Windowsの場合は、次を実行します。 ipconfig IPv4アドレスを確認してください。
その後、Capacitor に、設定に別のパラメータを追加して、サーバーからアプリを直接ロードするよう指示します capacitor.config.ts ファイル内で参照します：
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;正確なIPとポートを必ず使用してください。次を実行して npx cap copy これらの変更をネイティブプロジェクトに適用します。
Android StudioやXcodeでアプリをもう一度デプロイすると、Reactアプリの変更が自動的にリロードされ、アプリに表示されます！
カメラなどの新しいプラグインをインストールすると、ネイティブプロジェクトの再ビルドが必要になることに注意してください。ネイティブファイルが変更され、オンザフライで更新できないためです。
Capacitor プラグインの使用
では、Capacitor プラグインの使い方を簡単に見ていきましょう。まずは、シンプルな プラグインを共有、これによりネイティブの共有ダイアログが表示されます：
npm i @capacitor/share使用するには、パッケージをインポートして、該当する share() 関数をアプリから呼び出します。こちらの 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;新しいプラグインをインストールした後は、必ずReactプロジェクトを再度同期してください。 npx cap sync.
次に、Capgo のナビゲーションとトランジションで、iOS と Android でアプリをよりネイティブに感じさせ、横方向のオーバーフローやセーフエリアの欠けを引き起こす iOS でよくあるレイアウト問題も修正できます。
Capgo Native Navigation and Transitions によるネイティブ感のあるUI
私は長年、 Ionic を使用してクロスプラットフォームアプリを構築できますが、Reactとの統合は無理があり、すでに Tailwind CSS がある場合は、あまりメリットがありません。.
React + Capacitor アプリでネイティブなモバイル体験を実現するには、Konsta UI のようなWeb専用のUIキットではなく、Capgo プラグインを使用してください：
- @capgo/capacitor-native-navigation — iOSではネイティブnavbarとLiquid Glassタブバー、Androidではぼかし付きタブバーのスタイルを提供します。React Routerがルート状態を保持し、ネイティブUIはプラグインが管理します。
- @capgo/capacitor-transitions — Ionic UIを採用せずに、WebViewレイヤーでIonicスタイルのページ遷移とiOSのエッジスワイプによる戻る操作を実現します。
両方をインストールしてください：
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncCSS insetモードでネイティブナビゲーションを設定し、Webコンテンツがネイティブバーと重ならないようにします：
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Liquid Glassタブバーをレンダリングします（iOSはシステム側のレンダリングを使用し、Androidはぼかし付き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}`);
});アプリシェルにネイティブページ遷移を追加します：
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>;
}ルーティングされたページを以下でラップします： cap-router-outlet, cap-pageや cap-content、そして呼び出します setDirection('forward') または setDirection('back') 遷移前に実行してください。ネイティブナビゲーションがその領域を管理している場合、Webのヘッダーやフッターを重複させないでください。
ガイドの全文はこちら： @capgo/capacitor-native-navigation の活用 と @capgo/capacitor-transitions の活用.
Tailwind によるセーフエリア対応
Tailwind CSS でデバイスのセーフエリアを扱うには、以下を使用します： @capgo/tailwind-capacitor （ tailwind-capacitor として npm で公開）。これは、 safe-areas ユーティリティや Capacitor と相性の良いその他の Tailwind プラグインを提供します：
bun add -D tailwind-capacitorでは src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";次のようなユーティリティを使用します： pt-safe, pb-safeや px-safe 手作業でばらまくのではなく env(safe-area-inset-*) 手動で行う必要はありません。このプロジェクトは活発に開発されており、React のセットアップに足りないものがあれば、 GitHub でPRを作成してください.
iOSのレイアウト問題を修正（ビューポート、セーフエリア、横方向のオーバーフロー）
iOSでコンテンツが切れて見えたり、ずれて見えたり、横スクロールが発生したりする場合は、さらに追加するだけでも、 overflow-x: hidden viewportタグを調整するだけでも通常は解決しません。以下のチェックを順番に確認してください。
viewport メタタグが正しく適用されているか確認する
viewport metaタグを以下に追加します index.html 既存の <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />iOSのセーフエリアは1つのルートラッパーだけで処理する
単一のアプリシェルを作成し、そこにセーフエリアのパディングを適用してください — 複数のネストしたコンポーネントではなく：
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);
}すべてのページコンテンツを以下でラップします： .app-shellヘッダー、モーダル、レイアウトラッパーで safe-area のパディングが重複すると、UI が欠けたり、逆に大きすぎたりすることがよくあります。
を使用すると、 @capgo/tailwind-capacitor同じパディングを次のようなユーティリティで表現できます： pt-safe pb-safe px-safe その単一のシェル上で。
Capacitor iOS を設定 contentInset まで never 最初に
では capacitor.config.ts、native inset を無効にすることを推奨し、CSS（または Native Navigation のもの contentInsetMode: 'css'）に safe area を任せる：
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Capacitor の自動コンテンツ inset と CSS を混在させると env(safe-area-inset-*) paddingが原因で、余白が二重に見えることがよくあります。
実際にオーバーフローしている要素を特定する
主な原因は、以下の要素を使用している場合です： 100vwTailwind、 w-screen固定ピクセル幅、または大きな min-width.
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,
}));Tailwindを使用する場合は、可能な限り w-screen を使用して w-full 置き換えてください。水平方向のオーバーフロー問題の多くは 100vw / w-screen、重複したセーフエリアのパディング、または固定幅のコンテナに起因し、viewportのmetaタグ自体が原因ではありません。
まとめ
Capacitor を使えば、既存のWebプロジェクトをベースにネイティブアプリをシームレスに構築でき、code の共有や一貫したUIの実現も簡単です。
Capacitor のような技術のおかげで、React.jsのWebアプリからモバイルアプリを構築するのはかつてないほど簡単になりました。Web開発のスキルを活かして、印象的なネイティブモバイルアプリを作りましょう。Happy coding!
アプリ開発プロセスを高速化する方法について詳しくはこちら： 無料アカウントに登録する を今すぐ作成してください。
「Pure React.js と Capacitor でモバイルアプリを構築する」の続きはこちら
使用している場合 Pure React.js と Capacitor によるモバイルアプリ開発 ネイティブメディアとインターフェースの挙動を計画するには、次と連携させてください @capgo/capacitor-live-activities の使用 @capgo/capacitor-live-activities の使用におけるネイティブ機能については、 @capgo/capacitor-live-activities @capgo/capacitor-live-activities の実装の詳細については、 @capgo/capacitor-video-playerの使用方法 @capgo/capacitor-video-player の使い方におけるネイティブ機能については、 @capgo/capacitor-video-player @capgo/capacitor-video-player の実装の詳細、および @capgo/capacitor-native-navigation の活用 @capgo/capacitor-native-navigation. の使い方におけるネイティブ機能については
