AWS のドキュメントではよくクライアント例として Amplify のライブラリが使われていますが、Amplify とは何か非常に分かりづらいのでメモします。Amplify には以下のような様々な機能がありますが、それぞれ独立しており、特に Amplify Library の関数群は Amplify CLI が無くても使えます。主にマーケティング的な理由で同じ名前にしているのではと思います。
- Amplify CLI:
- クライアントアプリにデータベースや認証などのバックエンドを追加する仕組み。
- バックエンドは AppSync や Cognito などの AWS サービスをうまい具合に調整してくれるらしい。
- Amplify CLI はエンドポイントを記した src/aws-exports.js を生成するのでクライアントはこの設定でバックエンドにアクセスする。
- Amplify Hosting:
- Amplify の中でウェブサイトを公開するしくみ。
- Amplify Library:
- AWS の色んなサービスに接続するクライアントライブラリ。
- src/aws-exports.js さえあれば Amplify CLI 無しでも動く。
ここでは特に分かりづらい Amplify CLI について書きます。特に覚えておきたいのは次の点です。
- Amplify 開発には少なくとも一つ AWS に環境をデプロイする必要がある。オフラインだけでは始められない。
-
amplify/.config/local-aws-info.json: デプロイに使った AWS PROFILE が書いてある。 -
amplify/.config/project-config.json: ビルドコマンドが書いてある。 -
amplify/team-provider-info.json: 利用中の全環境の App ID や Region や CloudFormation Stack が書いてある。 -
amplify deleteは使わない方がよい。
ドキュメント: https://docs.amplify.aws/start/q/integration/js/
Amplify CLI の初期設定
まずはインストールです。
npm install -g @aws-amplify/cli
最初は環境を汚したくないので -g を付けないで作業ディレクトリにインストールしていたのですが (Serverless framework 風) npx を毎度打つのが面倒になって普通の方法にしました。
amplify configure
親切にも Amplify で使う権限を持つ AWS IAM ユーザを作る機能が用意されています。
ここで指示に従って AWS console を開くと、AdministratorAccess-Amplify policy が設定されたアカウントと、アカウントにアクセスするための AWS Profile が作成されます。
まっさらなプロジェクトを新たに始める
mkdir amplify-test
cd amplify-test
git init
amplify init
を実行すると、デフォルトの設定が表示されます。特に、Build Command: npm run-script build のように検出されたビルドコマンド後ほど publish の際に使われます。
? Enter a name for the project amplifytest
The following configuration will be applied:
Project information
| Name: amplifytest
| Environment: dev
| Default editor: Visual Studio Code
| App type: javascript
| Javascript framework: none
| Source Directory Path: src
| Distribution Directory Path: dist
| Build Command: npm run-script build
| Start Command: npm run-script start
? Initialize the project with the above configuration? Yes
Using default provider awscloudformation
? Select the authentication method you want to use: AWS profile
For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html
? Please choose the profile you want to use (作成した Profile)
Adding backend environment dev to AWS Amplify app: d98vdlyr2v
ここで先程作成した AWS Profile を選ぶと amplify/.config/local-aws-info.json に記載され、今後のデプロイ作業に使われます。ということは Amplify の実行には AWS_PROFILE 環境変数の設定は不要です。またここで S3 と Role の設定が行われます。
クライアントはここで作成された src/aws-exports.js を使ってサーバーにアクセスします。
親切なことに amplify init は .gitignore を作ってくれるので、簡単に git で管理できます。
一方で、もしもこのプロジェクトを github のような場所に公開したい場合は手動で amplify/team-provider-info.json を .gitignore に追加する必要があります。amplify/team-provider-info.json はチーム無いで同じ環境を共有するために必要な情報が入っているため、公開する必要はありません。
既存のプロジェクトに参加する
他の人が作ったレポジトリを受け取ったら、中で amplify init を実行し環境を設定します。
もしもレポジトリに amplify/team-provider-info.json が含まれていたら、その人と同じ環境で開発を続ける事ができます。無くても新たに環境を作る事ができます。
- 元の作者と同じ環境を使って開発を続けたい場合
-
amplify initの質問 Do you want to use an existing environment? に Yes と答える - 既存の環境をそのまま使う事ができます。
- Team environments - Share single environment - AWS Amplify Docs
-
- 新しい環境を作って開発したい場合
-
amplify initの質問 Do you want to use an existing environment? に No と答える - 別の環境を作る事ができます。
-
参考: https://docs.amplify.aws/cli/usage/headless/#--app
既存のプロジェクトをもとに開発する
Github などで共有されたプロジェクトを元に開発を始めるには、空のディレクトリで
amplify init --app (レポジトリ URL)
のようにします。--app オプションによってプロジェクトが初期化され(npm install などが自動的に実行されます)、AWS Profile を聞かれます。この場合既存の amplify/team-provider-info.json は自動的に削除されます。
レポジトリ URL には github 以外も指定できました、ローカルディレクトリは駄目でした。
オフライン開発
という事で三通りのプロジェクト開始方法をご紹介しましたが、どうやら Amplify で開発するには少なくとも１つの環境は AWS にデプロイする必要があるようです。Serverless Framework のようにオフラインだけで開発を始めるという使い方はできないようです。
とはいえ、自分だけの閉じた環境で開発を行えるよう Amplify は複数環境の切り替えと mock によるオフライン環境が用意されています。mock の起動は簡単で
amplify mock
とするだけでバックエンドを開発マシンで実行することができます。src/aws-exports.js もローカルのエンドポイントに書き換わるのでそのまま Amplify Library を使ったクライアントもローカルを参照するようになります。
複数環境の切り替え
Amplify のバックエンドをデプロイするための新しい環境を作るには amplify env add コマンドを使います。
% amplify env add (環境名)
Note: It is recommended to run this command from the root of your app directory
Using default provider awscloudformation
? Select the authentication method you want to use: AWS profile
For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html
? Please choose the profile you want to use (環境名)
Adding backend environment (環境名) to AWS Amplify app: d1tnvi9fev27af
⠸ Initializing project in the cloud...
ダサいことに環境名としては小英文字しか使えません。dev-2 とかは駄目です。
amplify init の後の質問 Do you want to use an existing environment? に No と答えても amplify env add と同じ事が起こります。違いは分かりませんでした。環境の情報は amplify/team-provider-info.json ファイルに記載されます。
他の環境に切り替える方法です。
amplify env checkout (環境名)
環境の削除方法です。
amplify env remove (環境名)
環境を削除。今現在自分がいる環境を削除事は出来ません。ここでも「Amplify は少なくとも１つ環境が必要」という事が言えます」
なお、公式ドキュメントでは環境ごとに git branch を一つ作る事を推奨しています。ちょっと調べたところ amplify env add は amplify/team-provider-info.json くらいしか書き換えないので大きなお世話かなという気がします。
参考: Team environments - Overview - AWS Amplify Docs
その他のコマンド
amplify add api
GraphQL API を追加する。
amplify push
サーバに変更を反映する。API のためのコードも生成する。
amplify status
Amplify の状態を表示
amplify add hosting
amplify publish
ビルドコマンド(amplify/.config/project-config.json に設定)を実行し、コンテンツをデプロイする。
amplify configure project
プロジェクトのディレクトリを移動した後など、このコマンドで再設定できる。
amplify delete
禁断の削除コマンド。なんとローカルの amplify ディレクトリも削除されてしまうので、何のためにあるのかよくわかりません。
AWS Console > AWS Amplify でバックエンドだけ消す事ができます。