【ITニュース解説】TanStack Start to Mobile: Building Robust Apps with Capacitor

システムエンジニアを目指す初心者に向けて、TanStack StartというウェブフレームワークとCapacitorというツールを組み合わせて、ウェブアプリケーションとモバイルアプリケーションの両方を効率的に開発する方法について解説する。現代のアプリケーション開発では、ウェブサイトとして動くものと、スマートフォンアプリとして動くものの両方が求められることが多く、これらを別々に開発するのは手間がかかる。この組み合わせは、一つのコードベースからウェブとネイティブモバイルアプリを作り出すことを可能にし、開発者の負担を大きく減らす。

TanStack Startは、ウェブ開発で人気のReactというライブラリをベースにしており、いくつかの強力な特徴を持つ。まず、「深い型安全性」は、プログラムの各部分（APIとの通信、データの取得、画面の表示など）が正しいデータの形を扱うことを保証する機能で、エラーを未然に防ぎ、コードの品質を向上させる。次に、「直感的なサーバー関数（createServerFn）」という機能は、通常はウェブサーバーのAPIとして個別に定義する必要がある処理を、まるでローカルの関数を呼び出すかのようにTypeScriptで書ける画期的な仕組みである。これにより、ウェブサーバー側の開発が非常にシンプルになる。また、「統一されたエコシステム」として、ルーティング（ページの遷移管理）にはTanStack Router、データ管理にはTanStack Queryといった成熟したライブラリが採用されており、これらが密接に連携することで、最適化された開発環境を提供する。

この開発手法の核となるアイデアは、TanStack Startで作ったアプリケーションをウェブサーバーとしてデプロイし、ウェブ用の機能とAPIの機能の両方を提供する。そして、Capacitorを使ってそのアプリケーションのユーザーインターフェース部分（クライアントサイド）だけをネイティブのiOSアプリやAndroidアプリとしてパッケージ化し、モバイルアプリからデプロイされたAPIにアクセスするというものである。これにより、ウェブとモバイルで共通のバックエンドロジックを使用できる。ただし、先述のcreateServerFnは、クライアント（アプリ）とサーバーが同じ場所にある（ウェブブラウザでの動作など）場合に有効であり、モバイルアプリのようにクライアントとサーバーが分離されている場合は直接利用できない。そのため、モバイルアプリからは明示的なAPIルートを通じてデータにアクセスする必要がある。

プロジェクトの初期設定は簡単である。まず、npm create @tanstack/start@latestコマンドを実行し、プロジェクト名や使用するフレームワーク（React）、言語（TypeScript）、SSRモード（Single Page Application: SPAを選択、これはCapacitorでモバイルアプリを構築する際に適している）、CSSフレームワーク（Tailwind CSSなど）を選択してTanStack Startプロジェクトを作成する。これにより、必要なファイルと基本的な構成が自動的に生成される。作成されたプロジェクトには、TanStack Router、TanStack Start本体、Capacitor関連、React、そしてCSSフレームワークなど、開発に必要な主要な依存関係がpackage.jsonに記述され、npm installコマンドでこれらがインストールされる。

次に、既存のルートファイルを編集して、モバイルからのAPIリクエストに対応させる。特に重要なのはsrc/routes/demo.start.api-request.tsxファイルである。このファイルでは、データの取得を行う部分でCapacitorライブラリを使って、現在のアプリケーションがネイティブモバイルプラットフォーム上で動作しているかどうかを判定する。もしモバイルであれば、環境変数import.meta.env.VITE_SERVER_BASE_URLで指定されたサーバーの完全なURLを使ってAPIにアクセスし、ウェブブラウザ上で動作していれば、相対パスでアクセスするように切り替える。このようにすることで、モバイルアプリはデプロイされたバックエンドサーバーに正しく接続できるようになる。

また、src/routes/__root.tsxというアプリケーション全体のルートコンポーネントも更新する。ここでは、@capacitor/status-barプラグインをインポートし、useEffectフック内でStatusBar.setOverlaysWebView({ overlay: false })を設定する。これは、モバイルアプリでウェブビュー（ウェブコンテンツを表示する部分）がステータスバーの下に隠れないようにするための設定であり、モバイルアプリの表示を最適化する。

アプリケーションのビルド設定を行うvite.config.tsファイルでは、特にCORS（クロスオリジンリソース共有）設定が重要になる。モバイルアプリがウェブサーバーとは異なるオリジン（アドレス）からAPIにアクセスするため、サーバー側でそのアクセスを許可する必要がある。server.corsセクションで、origin: "*"やcredentials: trueなどを設定し、モバイルアプリからのリクエストがブロックされないようにする。また、Capacitorがウェブアプリケーションのビルドファイルを正しく認識できるよう、tanstackStartプラグインのspa.enabledをtrueにし、build.outDirをdist、spa.prerender.outputPathをindex.htmlに設定することも重要である。

Capacitorをプロジェクトに導入する手順は以下の通りである。まず、@capacitor/cli、@capacitor/core、@capacitor/ios、@capacitor/android、@capacitor/status-barといったCapacitor関連のパッケージをインストールする。次に、npx cap init "アプリ名" "アプリID"コマンドでCapacitorを初期化し、capacitor.config.tsファイルを生成する。この際、アプリIDはcom.yourcompany.appnameのような逆ドメイン形式で一意なものを使用する。その後、npx cap add androidとnpx cap add iosコマンドを実行して、AndroidとiOSのネイティブプロジェクトフォルダを生成する。生成されたcapacitor.config.tsファイルでは、webDir: "dist/client"と設定されていることを確認する。これは、TanStack Startがビルドしたクライアントサイドの静的ファイルが保存されるディレクトリをCapacitorに伝えるための重要な設定である。

開発を効率化するため、package.jsonファイルに便利なスクリプトを追加する。例えば、cap:syncはウェブのビルド結果をネイティブプロジェクトにコピーする、cap:open:iosやcap:open:androidはそれぞれXcodeやAndroid Studioでネイティブプロジェクトを開く、といったコマンドを追加する。特に便利なのは、cap:dev:iosやcap:dev:androidといったスクリプトで、これらはnpm run devでウェブ開発サーバーを起動しながら、モバイルデバイスやエミュレータ上でライブリロードを伴う開発を可能にする。これにより、コードを変更するたびにモバイルアプリが自動的に更新され、開発効率が大幅に向上する。

実際の開発ワークフローでは、まず一つのターミナルでnpm run devコマンドを実行し、TanStack Startの開発サーバーを起動する。このサーバーは、ウェブアプリケーションの提供とAPIエンドポイントの両方を担当する。ブラウザでhttp://localhost:3000にアクセスすれば、ウェブアプリケーションとして動作を確認できる。モバイルアプリでの動作を確認するには、別のターミナルでnpm run cap:dev:iosまたはnpm run cap:dev:androidを実行する。これにより、開発サーバーと連携しながら、モバイルエミュレータまたは実機でアプリケーションをライブリロードでテストできる。変更がウェブとモバイルの両方に即座に反映されるため、非常にスムーズな開発体験が得られる。

ここで注意すべき重要な点が、createServerFnがモバイルアプリ内で直接動作しない理由である。createServerFnは、クライアントサイドが/__serverというパスで、同じオリジンにあるTanStack Startサーバーにアクセスすることを前提としている。しかし、Capacitorでパッケージ化されたモバイルアプリは、capacitor://localhostやfile://といった独自のオリジンで動作するため、/__serverというパスにサーバーが存在しない。そのため、モバイルアプリからのcreateServerFnの呼び出しは失敗する。この問題を解決するには、モバイルアプリからは明示的なAPIルート（例: src/routes/api.demo-names.tsのようなファイルで定義されたRESTfulなエンドポイント）を、デプロイされたTanStack Startサーバーの完全なURLを指定して呼び出す必要がある。前述のCapacitor.isNativePlatform()とVITE_SERVER_BASE_URLの組み合わせがそのための解決策となる。また、デプロイされたバックエンドサーバーが、モバイルアプリのオリジン（capacitor://localhost、http://localhost、開発中のデバイスIPなど）からのCORSリクエストを許可していることを必ず確認する必要がある。

まとめると、TanStack StartとCapacitorを組み合わせることで、ウェブとネイティブモバイルアプリケーションを単一のコードベースから効率的かつ型安全に開発できる強力な環境が手に入る。TanStack Startのファイルベースルーティングや統一されたエコシステムは開発を簡素化し、Capacitorは既存のウェブスキルでモバイルアプリを構築する道を拓く。モバイル環境でのAPIアクセスには特別な考慮が必要だが、Capacitor.isNativePlatform()による検出と適切なURL設定、そしてCORSの適切な構成により、この課題も容易に解決できる。このアプローチは、ウェブ開発者がモバイル領域へ進出し、現代の要件に応える堅牢なアプリケーションを構築するための優れた選択肢となる。