ディレクトリ構成 - Cordova チュートリアル

Cordova CLI で作成したプロジェクトは、既定で以下のディレクトリ構成となります：

myapp/
├── config.xml
├── node_modules/
├── package.json
├── platforms/
├── plugins/
└── www

package.json

マニフェストファイル。プロジェクトで利用するJavaScriptパッケージの依存関係を定義し、Cordova、追加済みプラットフォーム、インストール済みプラグインの情報が記載されます。プラグイン設定用変数もこのファイルに保持されます。

フロントエンドフレームワークなどで自動生成された既存の package.json がプロジェクトに存在する場合もあります。Cordovaは自身に必要な設定を追記するだけで、他のツールや既存の依存設定に干渉しません。

{
  "name": "com.foxdevelop.hello",
  "displayName": "HelloWorld",
  "version": "1.0.0",
  "description": "A sample Apache Cordova application that responds to the deviceready event.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "ecosystem:cordova"
  ],
  "author": "Apache Cordova Team",
  "license": "Apache-2.0",
  "devDependencies": {
    "cordova-android": "^15.1.0",
    "cordova-plugin-camera": "^8.0.0"
  },
  "cordova": {
    "platforms": [
      "android"
    ],
    "plugins": {
      "cordova-plugin-camera": {
        "ANDROIDX_CORE_VERSION": "1.6.+"
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)

"name": "com.foxdevelop.hello" npmパッケージ名。Cordovaプロジェクトでは原則、config.xmlのwidget idと一致させます。

注意：これはAndroid/iOSのネイティブパッケージIDではありません。ネイティブ側のIDは config.xml 内の id で制御されます。

"displayName": "HelloWorld" 表示用の名称。アプリ名に相当し、config.xmlの <name> 要素と対応します。
"version": "1.0.0" プロジェクトのバージョン番号。セマンティックバージョニング メジャー.マイナー.パッチ に従い、config.xmlのバージョンと統一することが推奨されます。
"description": "A sample Apache Cordova application that responds to the deviceready event." プロジェクト説明文。npm上に表示されるメタ情報で、アプリのビルドや動作に影響を与えません。
"main": "index.js" npm規約上のエントリーファイル。Cordovaはこの項目をほぼ利用しません。テンプレートによる自動生成項目のため無視して構いません。Cordovaアプリの実際のWeb入口は www/index.html（config.xmlで制御）となります。
"scripts": { "test": "echo \"Error: no test specified\" && exit 1" } npmのカスタムスクリプト。既定テンプレートにはtestのみ定義され、ビルド・パッケージ用コマンドは存在しません。必要に応じて自身で追加可能です。例：

"scripts": {
  "build-android": "cordova build android"
}
Code language: JavaScript (javascript)

"keywords": ["ecosystem:cordova"] npm検索用タグ。ecosystem:cordova により、当プロジェクトがCordovaエコシステムのプロジェクトであることを示します。npm検索のみに使用され、実行時に影響はありません。
"author": "Apache Cordova Team" 作成者情報。メタデータのみです。
"license": "Apache-2.0" オープンソースライセンス：Apache 2.0。Cordova公式プロジェクトの既定ライセンスです。

config.xml

Cordovaアプリの各種設定項目を記述するファイルで、アプリの実行動作をカスタマイズします。

参考資料：config.xml 公式リファレンス

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.foxdevelop.hello" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
    <name>HelloWorld</name>
    <description>
        A sample Apache Cordova application that responds to the deviceready event.
    </description>
    <author email="dev@cordova.apache.org" href="https://cordova.apache.org">
        Apache Cordova Team
    </author>
    <content src="index.html" />
    <allow-intent href="http://*/*" />
    <allow-intent href="https://*/*" />
</widget>
Code language: HTML, XML (xml)

id="com.foxdevelop.hello"アプリ固有のパッケージID（Bundle ID）

Android：アプリのパッケージID applicationId
iOS：Bundle Identifier

ストア公開後は安易に変更しないでください。変更すると完全に別のアプリとして認識されます。命名ルール：逆ドメイン形式 企業ドメイン.プロジェクト名

version="1.0.0" アプリのバージョン番号（セマンティックバージョン major.minor.patch）。ビルド後のアプリバージョンに反映されます。

<name>HelloWorld</name>

アプリ表示名。スマホホーム画面アイコン下部に表示される名称です。

<description>

アプリ説明文。一部プラットフォームのビルド処理やストア情報に読み込まれます。

<author>

開発者情報：メールアドレス、公式サイト、作成者名。メタデータのみで動作に影響しません。

<content src="index.html" />

最も重要な設定項目

Cordovaアプリ起動時に読み込まれるトップページです。

アプリ起動後、Webコンテナが直接 www/index.html を読み込みます。

src="pages/home.html" に書き換えることで起動ページを変更可能です。

<allow-intent>

<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
Code language: HTML, XML (xml)

役割：アプリから外部ブラウザを起動し、Webページを開くことを許可する

allow-intent ＝ウェブビュー内のオリジン間通信許可ではありません！

混同されやすい二つの設定の違い：

allow-intent：target="_blank" のリンクをタップした際、システム標準ブラウザへ遷移させる許可設定。今回の設定では全てのhttp/httpsアドレスに対し外部ブラウザ起動を許可しています。
access origin：アプリ内WebViewから外部APIへリクエスト（オリジン間通信）を実行するか制御します。本設定ファイルには記載がありません！

⚠️ よくあるトラブル：

Web内のAJAX通信でオリジン間エラーが発生する場合、allow-intentだけでは解決できません。下記の設定を追加する必要があります。

xml

<!-- WebView内で全てのHTTPS通信を許可 -->
<access origin="*" />Code language: HTML, XML (xml)

www/

HTML、CSS、JavaScript、各種静的ファイルといったプロジェクトのWebリソースを格納するディレクトリです。

Cordova開発者は大半の業務コードとリソースをこちらに配置します。cordova prepare 実行後、このフォルダのファイルが各プラットフォーム配下のwwwディレクトリへコピーされます。

ソースの www フォルダは各プラットフォームサブディレクトリへ同期コピーされます。例：

platforms/ios/www または platforms/android/assets/www

CLIは常にルートのwwwディレクトリの内容で各プラットフォーム内ファイルを上書きします。platforms配下のファイルを直接編集せず、必ずルートのwww内ファイルを修正してください。

フロントエンドビルドツールを使用する場合は、ビルド成果物の出力先を www に設定してください。wwwフォルダ内で直接開発する場合は、このディレクトリをバージョン管理システムに登録することを推奨します。

node_modules/

npmリポジトリから取得した全JavaScript依存パッケージを格納。Cordova本体、関連ツール、package.jsonに記載されたプロジェクト依存が含まれます。

cordova platform add、cordova plugin add でプラットフォームやプラグインを追加する際、必要なリソースがnpmjsから取得され、このディレクトリに保存されます。

その後Cordovaがこのフォルダからプラットフォーム・プラグインのソースコードを各所へ複製し、アプリを正常に動作させます。

このディレクトリには cordova prepare、cordova build で各プラットフォームをビルドするためのスクリプトも格納されています。

⚠️ 重要：node_modules は依存ライブラリのソースフォルダのため、内部ファイルを手動で変更してはいけません。また、このディレクトリをバージョン管理システムにコミットしないでください。

詳細はnpmjsのディレクトリ規約ドキュメントを参照してください。

platforms/

プロジェクトに追加した各プラットフォームのソースコードとビルド用スクリプトを格納します。

⚠️ 注意：CLIによるビルド時、仕組みを十分に理解している、または公式ドキュメントに明記されている場合を除き、/platforms/ 内のファイルを編集しないでください。

プロジェクトのprepare実行やプラグイン再インストール時、このフォルダ内のファイルは頻繁に上書きされます。

plugins/

プラグインの一時的な受け渡し用ディレクトリ。インストールしたプラグインは一度こちらへコピーされた後、各プラットフォームへ配備されます。

このディレクトリをバージョン管理に登録することは推奨されません。

独自開発・内部カスタマイズ・改変済みのプラグインはplugins配下に保管しないでください。

バージョン管理のルール

platforms/、plugins/ をバージョン管理に含めないことを推奨。これらはビルド成果物に該当します。

インストール済みのプラットフォーム・プラグイン情報は自動的に package.json に記録されます。cordova prepare 実行時、必要なプラットフォームとプラグインが自動的に取得されます。

オプションディレクトリ

merges/

CordovaプロジェクトをCLIで作成した際、mergesディレクトリは既定で生成されません。公式はこのディレクトリの利用を推奨していませんが、互換性維持のため機能は残されています。

このディレクトリ内のサブフォルダにはプラットフォーム固有のWebリソース（HTML、CSS、JS）を配置します。prepare処理時に各ネイティブプロジェクトへ配備されます。

merges/ に配置したファイルは、対応するプラットフォームに限り、www配下の同名ファイルを上書きします。

ディレクトリ構成例：

plaintext

myapp/
├── merges
│   ├── android/
│   │   └── android.js
│   └── ios/
│       └── app.js
└── www/
    └── app.js

Android、iOSプロジェクトをビルドした結果：

Androidアプリ：app.js（wwwから読み込み）＋android.js が含まれる
iOSアプリ：app.js のみ存在。ソースは merges/ios/app.js となり、www汎用版app.jsを上書き

ディレクトリ構成

Previous: 最初のCordovaプロジェクト

Next: Cordova コマンドラインツール（CLI）（リファレンスマニュアル）