AWS Amplifyの各種ファイルの意味、手動でいじってよもの・悪いもの

## はじめに

AWS Amplifyって自動でバックエンドに関するいろいろなことをよしなにやってくれてめっちゃべんりなんだけど、勝手に作られるファイルがよく分からなくてトラブルシューティングがキツい、ってなりませんか? 私はよくなります。

そんなときに見る以下のページが英語だったので、頻繁に見るため翻訳しておいたほうが見やすいなと思い、本記事を作成しました。

https://docs.amplify.aws/cli/reference/files/#parametersjson

## 注意事項
:::note alert
Amplifyに限らずこの手のサービスでは、「マニュアルで編集してはいけないファイル」が多くあります。Amplifyも同様にマニュアルで編集すべきでないファイルが多いため、「手動編集：OK」となっているものを中心に見ていくと効率的かもしれません。逆にNGのものを触ると沼にハマる可能性が高いのでご注意ください。
:::


## フォルダ-構成

amplify init すると以下のようになるよ、と。

```
amplify
  .config
  #current-cloud-backend
  backend
```



## 各ファイル

### amplify/.config

- 手動編集：NG
- バージョン管理：OK

クラウドの構成や設定・プリファレンスを保存するファイルが含まれています。amplify configureを実行して、プロジェクトの設定を変更します。



### amplify/#current-cloud-backend

- 手動編集：NG
- バージョン管理：NG

チェックアウトした環境のリソースの現在のクラウド状態が格納されています。このフォルダの内容は、決して手動で更新してはいけません。amplify push, amplify pull, amplify env checkout などの操作で上書きされます。



### amplify/backend

- 手動編集：OK
- バージョン管理：OK

チェックアウトした環境のリソースの最新のローカル開発状態が格納されています。このフォルダの内容は変更可能で、amplify pushを実行すると、このディレクトリの変更がクラウドにプッシュされます。各プラグインは、このフォルダー内の独自のサブフォルダーにコンテンツを保存します。



### amplify/mock-data

- 手動編集：NG
- バージョン管理：NG

amplify mock apiを実行した後に作成されます。モック時にローカルAPIをバックアップするために使用するSQLiteデータベースが含まれています。中身を変更してはいけませんが、ローカルのAPIの状態を消したい場合は、このフォルダを削除してください。



## Amplifyの重要ファイル

これらのファイルは、プロジェクトにどのようなリソースが設定されているか、リソース間の依存関係、最後のプッシュはいつかなど、Amplifyプロジェクトの全体的な状態を維持するために連携して動作します。

### backend-config.json

- 手動編集：OK
- バージョン管理：OK

backendディレクトリにあるbackend-config.jsonには、AWSリソースへの接続方法など、プロジェクトのバックエンドに関する設定が含まれています（例：認証用のCognitoやAPIバックエンド用のAppSync）。通常、このファイルはamplify add authやamplify add apiなどのCLIコマンドで更新されます。また、Amplify CLIの機能を超えてバックエンドを設定するために、手動で拡張することも可能です。amplify/backendとamplify/#current-cloud-backendの両ディレクトリには、backend-config.jsonファイルが含まれています。



### amplify-meta.json

- 手動編集：NG
- バージョン管理：NG

amplify/backendとamplify/#current-cloud-backendの両ディレクトリには、amplify-meta.jsonファイルが含まれています。backendディレクトリにあるamplify-meta.jsonは、CLIコアとプラグインが内部情報を記録し、相互に通信するためのホワイトボードとして機能します。

CLIコアは、プラグインに対してこのファイルへの読み取りと書き込みのアクセスを提供します。例えばawscloudformationプロバイダは、ルートスタック、デプロイ先S3バケット、認可/非認可IAMロールの情報を出力し、providers.awscloudformationオブジェクトの下に記録されます。各カテゴリーのプラグインは、それぞれの名前で情報を記録する。

1つのカテゴリが1つのプロジェクト内で複数のサービスを作成する可能性があるため（例えば、interactionsカテゴリは複数のbotを作成できる）、一般的にカテゴリメタデータは次のような2階層構造になっています。

```
{
  "<category>": {
    "<service1>": {
      //service1 metadata
    },
    "<service2>": {
      //service2 metadata
    }
  }
}
```

各サービスのメタデータは、amplify <category> addコマンドの実行後、まずメタファイルに記録され、そのカテゴリの1サービスがローカルに追加されたことを示すいくつかの一般的な情報が含まれます。その後、amplify pushコマンドの実行が成功すると、サービスのメタデータに、実際に作成または更新されたクラウドリソースを記述する情報が出力オブジェクトとして追加/更新されます。



### aws-export.js

- 手動編集：NG
- バージョン管理：NG

このファイルは、JavaScriptプロジェクトにのみ生成されます。すべてのカテゴリからの統合された出力を含み、initプロセス中に指定されたsrcディレクトリの下に配置されます。amplify pushの後に更新されます。

このファイルは、設定のためにAmplify JavaScriptライブラリによって消費されます。このファイルには、機密性はなく、クライアントからの外部で未認証のアクション（Authの場合のユーザー登録やサインインフローなど）、または認証が行われた後に適切なエンドポイントURLを構築するためにのみ必要となる情報が含まれています。より詳細な説明は、以下をご覧ください。

- [Cognito security best practices for web app](https://forums.aws.amazon.com/message.jspa?messageID=757990#757990)
- [Security / Best Practice for poolData (UserPoolId, ClientId) in a browser JS app](https://github.com/amazon-archives/amazon-cognito-identity-js/issues/312)
- [Are the Cognito User pool id and Client Id sensitive?](https://stackoverflow.com/a/47865747/194974)



### amplifyconfiguration.json

- 手動編集：NG
- バージョン管理：NG

このファイルはaws-exports.jsと同じですが、AndroidとiOSのプロジェクト用です。

iOSとAndroidのネイティブSDKが設定するために消費されます。



### .gitignore

- 手動編集：OK
- バージョン管理：OK

Amplify CLIから新しいプロジェクトを初期化する際、Amplifyはルートディレクトリの.gitignoreファイルに以下を追記します。.gitignoreファイルが存在しない場合は作成されます。

```
#amplify-do-not-edit-begin
amplify/\#current-cloud-backend
amplify/.config/local-*
amplify/logs
amplify/mock-data
amplify/backend/amplify-meta.json
amplify/backend/awscloudformation
amplify/backend/.temp
build/
dist/
node_modules/
aws-exports.js
awsconfiguration.json
amplifyconfiguration.json
amplifyconfiguration.dart
amplify-build-config.json
amplify-gradle-config.json
amplifytools.xcconfig
.secret-*
#amplify-do-not-edit-end
```



### team-provider-info.json

- 手動編集：NG
- バージョン管理：レポジトリがプライベートな場合のみOK

チーム内でプロジェクト情報を共有するために使用します。詳しくは、Share single environmentをご覧ください。



### cli.json

- 手動編集：OK
- バージョン管理：OK

プロジェクトの機能フラグ設定が含まれます。このファイルが存在しない場合、amplify initの際にAmplify CLIによって作成されます。環境固有の機能フラグのオーバーライドは cli.<environment name>.json で定義することもできます。現在チェックアウトしている環境に環境固有のファイルが存在する場合、amplify env addコマンドで新しく作成される環境にも同じファイルがコピーされます。詳しくは機能フラグをご覧ください。



## General Category Files

各カテゴリーのプラグインには固有のファイルがありますが、すべてのカテゴリーに共通するファイルもあります。



 ### <category>-parameters.json

- 手動編集：NG
- バージョン管理：OK

amplify add <category> の際に選択されたパラメータを保存し、amplify update <category> の際に回答を入力するのに使用できるようにします。このファイルは基本的なカテゴリの設定を変更するものではありません。



### parameters.json

- 手動編集：OK
- バージョン管理：OK

CloudFormationのパラメータ名と、カテゴリのCloudFormationテンプレートに渡される値をマッピングしたJSONオブジェクトが含まれています。例えば、CloudFormationテンプレートがパラメータを持つ場合が該当します。

```
{
  "Parameters": {
    "RoleArn": {
      "Type": "String",
      "Default": "<default role ARN>"
    }
  }
}
```

そして parameters.json は以下を含みます。

```
{
  "RoleArn": "<role ARN override>"
}
```

すると、テンプレートがプッシュされたときの「RoleArn」の値は、「<role ARN override>」となります。



## Function Category Files

### amplify.state

- 手動編集：NG
- バージョン管理：OK

CLIがどのように関数を構築し、呼び出すべきかという内部メタデータが含まれています。



## AppSync API Category Files

### transform.conf.json

- 手動編集：NG
- バージョン管理：OK

GraphQLスキーマを解釈し、AppSyncリゾルバに変換する方法に関する設定が含まれています。amplify api updateを実行し、APIカテゴリ設定を変更します。