Build a Next.js Mobile App from Scratch with Capacitor 8

導入

Next.jsモバイルアプリケーションを作成するには、最初からモバイルに最適化されたNext.js 15プロジェクトを作成し、ネイティブiOSとAndroidアプリとしてパッケージ化する方法を説明します。 Capacitor 8.

このチュートリアルを終了すると、シミュレータ上で動作するワーキングモバイルアプリケーションを取得し、続発開発し、最終的にApp StoreとGoogle Playに公開することができます。

所要時間: ~30分

~30分

~30分
~30分
Capacitor 8 に必要なプラグインを含む
~30分
~30分

~30分 ~30分 ~30分

~30分

Node.js 18+ (確認してください) node --version)
Bun パッケージマネージャー（)curl -fsSL https://bun.sh/install | bash)
Xcode (macOSのみ、iOS開発用)
Android Studio (アンドロイド開発用)

Step 1: Next.jsアプリの作成

Step 1: Next.jsアプリを作成するには、まず新しいNext.js 15プロジェクトを作成します。

bunx create-next-app@latest my-mobile-app

TypeScript:

__CAPGO_KEEP_0__ はい（推奨）
ESLint: Yes
テールウィンドCSS: はい（モバイルスタイリングの場合に推奨）
src/ directory: Yes
アプリケーションルーター: はい（推奨）
Import alias: Default (@/*)

プロジェクトに移動してください。

cd my-mobile-app

Step 2: Next.js を静的エクスポート用に設定する

Capacitor は静的 HTML/JS/CSS ファイルが必要です。Next.js を静的エクスポート用に設定するには、 next.config.ts:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  // Ensure trailing slashes for proper routing in Capacitor
  trailingSlash: true,
};

export default nextConfig;

なぜこれらの設定が必要なのでしょうか?

output: 'export' — 静的 HTML を生成し、Node.js サーバーが必要なくなる
images: { unoptimized: true } — Next.js の画像最適化を無効にする (サーバーが必要)
trailingSlash: true — ネイティブ WebView で正しいルーティングが保証される

Step 3: モバイルスクリプトを追加する

__CAPGO_KEEP_0__ を package.json モバイル開発用のスクリプトで更新してください:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "mobile": "bun run build && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

ビルドをテストしてください:

bun run build

静的ファイルが含まれる out ディレクトリが見つかります。

Step 4: Capacitor をインストールする

Capgo の Capacitor コアパッケージをインストールする

bun add @capacitor/core
bun add -D @capacitor/cli

Capgo のエッセンスなプラグインをインストールする

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/status-bar @capacitor/preferences

これらのプラグインは何を実行するか

@capacitor/app — アプリライフサイクルイベント (前景/背景、深いリンク)
@capacitor/keyboard — ネイティブスプラッシュスクリーンを制御する
@capacitor/splash screen @__CAPGO_KEEP_0__/keyboard
@capacitor/splash-screen @__CAPGO_KEEP_0__/status-bar
@capacitor/preference — キー値ストレージ (localStorage に似ていますが、ネイティブ)

ステップ 5: Capacitor を初期化する

初期化 Capacitor にプロジェクトの詳細:

bunx cap init "My Mobile App" com.example.mymobileapp --web-dir out

置き換え:

"My Mobile App" アプリの表示名
com.example.mymobileapp アプリ ID (逆ドメイン表記)

これにより capacitor.config.tsプラグインの構成で更新

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'light',
    },
  },
};

export default config;

ステップ 6: ネイティブプラットフォームを追加

プラットフォームパッケージをインストール:

bun add @capacitor/ios @capacitor/android

ネイティブプロジェクトを生成:

bunx cap add ios
bunx cap add android

これにより ios そして android ディレクトリが生成されます

Step 7: ビルドと実行

プロジェクトをビルドしてネイティブプラットフォームと同期する

bun run mobile

iOS シミュレータで開く

bun run mobile:ios

または Android エミュレータで開く

bun run mobile:android

Xcode (iOS) で

デバイスのドロップダウンからシミュレータを選択
プレイボタンをクリックまたは Cmd + R

Android Studio で

Gradle の同期が完了するのを待つ
デバイスのドロップダウンからエミュレータを選択してください
Run ボタンをクリックまたは Shift + F10

ステップ 8: Live Update の設定

ページ: Capgo のページ。役割: UI ラベル。見られる場所: about.astro のページ。メッセージキー `about_how_step_label` (About How Step Label)。

開発のために、変更が即座にデバイスに表示されるように Live Reload を有効にすると、開発が速くなります。

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

Create a development Capacitor config. Add to capacitor.config.ts:

import type { CapacitorConfig } from '@capacitor/cli';

const devConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... same plugin config
  },
};

const prodConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  plugins: {
    // ... same plugin config
  },
};

const config = process.env.NODE_ENV === 'development' ? devConfig : prodConfig;

export default config;

開発用の __CAPGO_KEEP_0__ 設定を作成します。Add to

bun run dev &
NODE_ENV=development bunx cap copy

開発サーバーを起動し、設定をネイティブにコピーしてください:

Next.js code の編集は、デバイス上で即時反映されます。

次に、Next.js の __CAPGO_KEEP_0__ の編集は、デバイスで即時反映されます。

ステップ 9: 最初のモバイルスクリーンを作成 src/app/page.tsx:

'use client';

import { useEffect, useState } from 'react';
import { App } from '@capacitor/app';
import { Keyboard } from '@capacitor/keyboard';

export default function Home() {
  const [appInfo, setAppInfo] = useState<{ name: string; version: string } | null>(null);

  useEffect(() => {
    // Get app info on mount
    App.getInfo().then(setAppInfo).catch(console.error);

    // Handle back button on Android
    const backHandler = App.addListener('backButton', ({ canGoBack }) => {
      if (!canGoBack) {
        App.exitApp();
      } else {
        window.history.back();
      }
    });

    // Hide keyboard when tapping outside inputs
    const keyboardHandler = Keyboard.addListener('keyboardWillShow', () => {
      document.body.classList.add('keyboard-open');
    });

    return () => {
      backHandler.then(h => h.remove());
      keyboardHandler.then(h => h.remove());
    };
  }, []);

  return (
    <main className="min-h-screen bg-linear-to-b from-blue-500 to-blue-700 flex flex-col items-center justify-center p-6 text-white">
      <h1 className="text-4xl font-bold mb-4">My Mobile App</h1>
      <p className="text-xl mb-8 text-center opacity-90">
        Built with Next.js 15 + Capacitor 8
      </p>

      {appInfo && (
        <div className="bg-white/20 rounded-lg p-4 backdrop-blur-sm">
          <p className="text-sm">
            {appInfo.name} v{appInfo.version}
          </p>
        </div>
      )}

      <div className="mt-12 space-y-4 w-full max-w-sm">
        <button className="w-full py-4 px-6 bg-white text-blue-600 rounded-xl font-semibold text-lg shadow-lg active:scale-95 transition-transform">
          Get Started
        </button>
        <button className="w-full py-4 px-6 bg-white/20 text-white rounded-xl font-semibold text-lg backdrop-blur-sm active:scale-95 transition-transform">
          Learn More
        </button>
      </div>
    </main>
  );
}

ページ: Capgo のページ。役割: UI ラベル。見られる場所: about.astro のページ。メッセージキー `about_how_step_label` (About How Step Label)。

モバイルデバイスにはノッチ、ホームインジケータ、ステータスバーがあります。Tailwindでセーフエリアハンドリングを追加します。

アップデート src/app/globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
  --sat: env(safe-area-inset-top);
  --sar: env(safe-area-inset-right);
  --sab: env(safe-area-inset-bottom);
  --sal: env(safe-area-inset-left);
}

body {
  padding-top: var(--sat);
  padding-right: var(--sar);
  padding-bottom: var(--sab);
  padding-left: var(--sal);
}

/* Prevent text selection on mobile */
* {
  -webkit-user-select: none;
  user-select: none;
  -webkit-tap-highlight-color: transparent;
}

/* Allow text selection in inputs */
input, textarea {
  -webkit-user-select: auto;
  user-select: auto;
}

/* Keyboard handling */
.keyboard-open {
  --sab: 0px;
}

プロジェクト構造

プロジェクト構造は次のようになります。

my-mobile-app/
├── android/              # Android native project
├── ios/                  # iOS native project
├── out/                  # Static build output
├── src/
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── ...
├── capacitor.config.ts   # Capacitor configuration
├── next.config.ts        # Next.js configuration
├── package.json
└── ...

次のステップ

あなたは機能するNext.jsモバイルアプリを持っています。ここで何をするかを知っておく必要があります。

基本設定

アプリアイコン: デフォルトのアイコンを置き換えます。 ios/App/App/Assets.xcassets そして android/app/src/main/res
スプラッシュスクリーン: ネイティブプロジェクトでカスタマイズするか、または @capacitor/splash-screen config
Deep Links: URLスキームを設定

機能を追加

カメラ: bun add @capacitor/camera
位置情報: bun add @capacitor/geolocation
プッシュ通知: bun add @capacitor/push-notifications
ファイルシステム: bun add @capacitor/filesystem

ネイティブUIとトランジション

Capgo プラグインを使用することで、Konsta UI の代わりにネイティブモバイルのフィールを実現できます。

@capgo/capacitor-native-ナビゲーション @capacitor/core@native-navigation
@capgo/capacitor-transitions — 本物感のあるページ遷移

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

Tailwindの安全エリアに追加するには @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

See Using @capgo/capacitor-native-navigation, Using @capgo/capacitor-transitions, そして tailwind-capacitor リポジトリ

iOSレイアウトの問題を修正する (ビューポート、安全エリア、水平オーバーフロー)

iOSでコンテンツが切り取られた、ずれた、または水平方向にスクロールできる場合、追加 overflow-x: hidden または、ビューポートタグを調整するだけでは、通常、問題を解決しません。これらのチェックを順番に実行してください。

ビューポートメタタグが正しく適用されていることを確認してください

App Router (app/export viewport から app/layout.tsx:

import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

ページルーター (pages/ビューポートメタタグを pages/_app.tsx、ではなく _document.tsx.

iOS セーフエリアを 1 つのルートラッパーからのみハンドリングする

単一のアプリシェルを作成し、セーフエリアのパディングをそこに適用する — 複数のネストされたコンポーネントに適用するのではなく:

html,
body,
#__next {
  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ヘッダー、モーダル、レイアウトラッパーに重複したセーフエリアのパディングを適用すると、UI がカットされたり大きすぎるように見えることがよくあります。

With @capgo/capacitor, __CAPGO_KEEP_0__のユーティリティを使用して、同じパディングを表現できます。 pt-safe pb-safe px-safe シングルシェル上に。

Capacitor iOS `contentInset` を `never` に設定します。

最初に capacitor.config.tsに contentInsetMode: 'css', 自然のインセットを無効にして、CSS (またはNative Navigationの)

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

Capacitorの自動コンテンツ内側とCSSを組み合わせる env(safe-area-inset-*) padding はダブルスペースの原因となるよくある問題です。

実際のオーバーフロー要素を探す

通常の原因は、固定ピクセル幅の要素や大きい 100vw, Tailwind w-screenTailwindの場合、 min-width.

可能な限り

[...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,
  }));

水平方向のオーバーフロー問題の多くは、 w-screen with w-full オーバー・ザ・エア更新 100vw / w-screen設定

__CAPGO_KEEP_0__

Capgoの更新 Capgo アプリをアップデートするためにアプリストアへの再提出を回避する:

bunx @capgo/cli init

トラブルシューティング

ビルドが「モジュールが見つかりません」というエラーで失敗する 実行 bun install iOS: 「署名のIDが見つかりません」

Xcodeを開き、Signing & Capabilitiesに移動し、開発チームを選択してください。 Android: 「__CAPGO_KEEP_0__」の場所が見つかりません

Android: “SDK の位置が見つかりません” と android/local.properties with sdk.dir=/path/to/android/sdk

デバイス上で表示されない変更があれば、 変更がデバイス上で表示されない場合、 bun run mobile 変更を保存した後。ライブリロードの場合、IPアドレスが正しいかどうかと開発サーバーが実行中かどうかを確認してください。

リソース

アプリを配信する準備ができましたか？ Capgo がアップデートをより速く配信できるように助けます — 無料アカウントに登録する今日。

Next.jsモバイルアプリケーションから始めてCapacitor8

Capgoを使用している場合 Build a Next.js Mobile App from Scratch with Capacitor 8 Live Updateを使用してCI/CDの自動化を計画し、Cloudflareに接続する Capgo CI/CD Capgoの製品ワークフローにおけるCapgo CI/CDのために Capgo 本機ビルド Capgoの製品ワークフローにおけるCapgoネイティブビルドのために。 Capgo 連携機能 Capacitorの製品ワークフローでCapgo統合を使用します。 Capacitor Actions Integration Capacitor Actions Integration GitHub アクション統合 GitHub Actions Integration.

Capacitor 8 を使用した Next.js モバイル アプリの作成

導入

~30分

Step 1: Next.jsアプリの作成

Step 2: Next.js を静的エクスポート用に設定する

Step 3: モバイル スクリプトを追加する

Step 4: Capacitor をインストールする

ステップ 5: Capacitor を初期化する

ステップ 6: ネイティブ プラットフォームを追加

Step 7: ビルドと実行

ステップ 8: Live Update の設定

次に、Next.js の __CAPGO_KEEP_0__ の編集は、デバイスで即時反映されます。

ページ: Capgo のページ。役割: UI ラベル。見られる場所: about.astro のページ。メッセージキー `about_how_step_label` (About How Step Label)。

プロジェクト構造

次のステップ

基本設定

機能を追加

ネイティブUIとトランジション

iOSレイアウトの問題を修正する (ビューポート、安全エリア、水平オーバーフロー)

ビューポートメタタグが正しく適用されていることを確認してください

iOS セーフエリアを 1 つのルートラッパーからのみハンドリングする

Capacitor iOS contentInset を never に設定します。

実際のオーバーフロー要素を探す

__CAPGO_KEEP_0__

トラブルシューティング

リソース

Next.jsモバイルアプリケーションから始めてCapacitor8

Capacitor 8 を使用した Next.js モバイルアプリの作成

Step 3: モバイルスクリプトを追加する

ステップ 6: ネイティブプラットフォームを追加

Capacitor iOS `contentInset` を `never` に設定します。