AWS Amplify Gen 2の使い方：ampxで初期化からCI/CDまで【2026年版】

「amplify 使い方」で検索して上位に出てくる日本語の入門記事は、2020年から2022年ごろのGen 1系がほとんどです。amplify init から始める記事か、Amplify StudioとFigma連携を紹介する記事のどちらかで、1位のQiita記事は最終更新が2020年3月23日です。ところがGen 1は2026年5月1日以降クリティカルな修正とセキュリティパッチのみとなり、2027年5月1日にサポートが終了します。Gen 2のプロジェクトで npx amplify sandbox と打つと、CLIは「The Amplify Gen 2 CLI has been renamed to ampx」というエラーで止まります。この記事では、プロジェクト作成からサンドボックスでのローカル開発、CI/CDでのデプロイまでを、2026年7月時点の公式仕様と実際のCLI実装（backend-cli 1.8.3）に基づいて整理します。

まとめ：Amplify Gen 2の使い方で先に押さえる5点

• Gen 2のCLIは ampx。amplify init amplify push amplify mock に当たるコマンドは存在せず、初期化は npm create amplify@latest、開発中のデプロイは npx ampx sandbox が引き受ける
• Gen 1は2026年5月1日からクリティカル修正とセキュリティパッチのみ、2027年5月1日に終了。新規プロジェクトはGen 2以外の選択肢がない
• バックエンドはコンソールやCLI対話ではなく amplify/backend.ts とカテゴリ別の resource.ts にTypeScriptで宣言する
• クラウドサンドボックスは開発者1人につき1つが原則。用途を分けるなら --identifier、AWSアカウントを分けるなら --profile を付ける
• CI/CDのバックエンド反映は npx ampx pipeline-deploy --branch --app-id。Amplify Hostingのブランチ連携で完結させるなら、この記述自体が不要になる

以下では、Gen 1のコマンドがなぜ通らないのかという対応関係から順に見ていきます。

Gen 1のコマンドがGen 2で通らない理由と置き換え表

Gen 1がメンテナンスモードに入った日付と終了予定

AWSはGen 1（Amplify CLI）について、公式リポジトリで次のように告知しています。「Starting May 1, 2026, Gen 1 backends will receive only critical bug fixes and security patches and will reach end of life on May 1, 2027.」（aws-amplify/amplify-cli issue #14881、2026年5月14日）。Amplify Studioも同じ扱いで、Gen 1の上に構築されているためメンテナンスモードに入っています。

Gen 1のパッケージ @aws-amplify/cli 自体は2026年6月25日に14.5.1が公開されており、いま動いているプロジェクトが即座に壊れるわけではありません。ただし新機能は入らず、2027年5月1日という期限が決まっています。これから学ぶなら、Gen 1の手順書はそのまま捨ててよい状況です。移行判断やGen 1とGen 2の設計思想の違いは、AWS Amplifyとは？Gen 2のバックエンド定義と料金・採用判断で整理しています。

amplify initやamplify mockに対応するGen 2コマンド

この表は完全な等価変換ではありません。amplify pull はバックエンド定義そのものを取得していましたが、generate outputs が取ってくるのはクライアント設定ファイルだけです。Gen 2ではバックエンド定義がリポジトリの amplify/ に入っているため、そもそも取得する対象がありません。

もっと注意したいのが amplify mock の行です。Gen 1ではローカルにモックサーバーを立てていましたが、Gen 2にローカルモックは用意されておらず、開発者ごとの実AWSリソース（クラウドサンドボックス）を立てる方式に変わりました。ローカルで完結させたい人ほどここで詰まります。

そして @aws-amplify/backend-cli のbin定義にも罠があります。このパッケージは ampx と amplify の両方を登録しているため npx amplify sandbox がコマンド不明にはなりませんが、起動直後の名前チェックで InvalidCommandError を投げて止まります。返るのはエラーメッセージ「The Amplify Gen 2 CLI has been renamed to ampx」だけです。なお、Gen 1のCLIをグローバルにインストール済みの環境では amplify がGen 1側に解決され、このメッセージすら出ずにGen 1が起動してしまうことがあります。ampx と打つ習慣にしておくのが確実です。

Amplify Gen 2プロジェクトの作成と初期設定

セットアップ前の前提条件

CLIパッケージ @aws-amplify/backend-cli と create-amplify は、いずれも engines.node に ^18.19.0 || ^20.6.0 || >=22 を指定しています。Node 18系でも18.19.0未満、20系でも20.6.0未満は対象外なので、マイナーバージョンまで確認してください。

サンドボックスは実際にCloudFormationスタックを作るため、ローカルのAWS認証情報が必須です。既定プロファイル以外を使う場合は各コマンドに --profile を付けます。付与する権限を検討する際は、AWS IAMのユーザー・ロール・ポリシーの違いと権限設計が判断材料になります。

npm create amplify@latestが生成するファイル構成

npm create amplify@latest
? Where should we create your project? (.) # press enter

実行すると、次のディレクトリが作られます。

amplify/
  auth/resource.ts
  data/resource.ts
  backend.ts
  tsconfig.json
  package.json

既存プロジェクトへ後から入れる場合は、スキャフォールドを使わず @aws-amplify/backend@latest @aws-amplify/backend-cli@latest typescript をdevDependenciesに追加する手順も公式に用意されています。2026年7月28日時点の最新版は @aws-amplify/backend が1.23.0、@aws-amplify/backend-cli が1.8.3（いずれも2026年5月28日公開）です。

backend.tsとresource.tsでのバックエンド宣言

Gen 1で amplify add api の対話に答えていた部分が、Gen 2ではTypeScriptのコードになります。データモデルの定義は amplify/data/resource.ts に書きます。

import { type ClientSchema, a, defineData } from '@aws-amplify/backend';

const schema = a.schema({
  Todo: a.model({
    content: a.string(),
  }).authorization(allow => [allow.owner()]),
});

export type Schema = ClientSchema<typeof schema>;
export const data = defineData({
  schema,
  authorizationModes: {
    defaultAuthorizationMode: 'userPool',
  },
});

この定義から生成されるのはAppSyncのGraphQL APIとDynamoDBのテーブルです。スキーマ設計やリゾルバの挙動で悩んだときは、Amplifyの抽象を剥がしてAWS AppSyncのGraphQL APIの仕組みを押さえたほうが早く解決します。ClientSchema 型をフロントエンド側にimportすると、クエリの戻り値まで型が効くのがGen 1との実務上の差です。

クラウドサンドボックスによるローカル開発

npx ampx sandboxが作るものと監視対象

npx ampx sandbox

このコマンドはCloudFormationスタックを作成し、そのあと amplify/ フォルダのファイル変更を監視してリアルタイムに反映し続けます。公式ドキュメントは「Cloud sandbox environments are designed for development purposes and are not intended for production workloads.」と明記しており、本番用途は想定されていません。

CIの検証ジョブのように監視を回したくない場面では --once を付けます。ヘルプの説明は「Execute a single sandbox deployment without watching for future file changes」で、1回デプロイして終了します。Lambda関数のログを手元で追いたいときは --stream-function-logs、対象を絞るなら --logs-filter を併用します。

amplify_outputs.jsonのフロントエンド読み込み

サンドボックスが動くと、バックエンドのエンドポイントや認証メタデータをまとめた amplify_outputs.json（クライアント設定ファイル）が生成されます。フロントエンド側ではこれを読み込ませます。

import { Amplify } from "aws-amplify";
import outputs from "@/amplify_outputs.json";

Amplify.configure(outputs);

2行目の @/ はNext.jsなどが持つパスエイリアスなので、素のViteプロジェクトでは tsconfig.json にエイリアスを足すか相対パスに書き換えてください。Remix SPAモードのフロントから読み込む場合の注意点はRemix SPAモードとAWS Amplify Gen 2の構成手順にまとめています。ストレージのAPIもGen 1世代から変わっています。aws-amplify v6（2026年7月21日時点で6.19.0）ではモジュール単位のimportになり、アップロードは次の形です。v5の Storage.put を載せた記事がまだ多いので、コピー元のバージョンに注意してください。

import { uploadData } from 'aws-amplify/storage';

const result = await uploadData({
  path: "album/2024/1.jpg",
  data: file,
}).result;

名前付きサンドボックスと–profileの使い分け

サンドボックスの識別子は、既定でコマンドを実行しているOSユーザー名が使われます。同じアプリで用途の違う環境を使い分けたいときは --identifier を付けます。

npx ampx sandbox --identifier feature1sandbox
npx ampx sandbox secret set foo --profile work

ただし同時に走らせられるのは1つだけで（公式は「only one can be running at a time」と記載）、複数作れても切り替えて使う形になります。公式は「Deploy one sandbox per Amplify app per developer to prevent conflicts」を原則とし、1人が複数の一時環境を抱えることは管理が複雑になるとして推奨していません。検証用アカウントと業務アカウントを分けたいだけなら、識別子を増やすのではなく --profile でAWSプロファイルを切り替えるほうが事故が少なくなります。

サンドボックスの停止・削除とコストの後始末

サンドボックスは実リソースなので、放置すればDynamoDBやCognitoのユーザープールが残り続けます。ここで誤解しやすいのが Ctrl+C の挙動です。実行中に Ctrl+C を押すとCLIは「Stopping the sandbox process. To delete the sandbox, run ampx sandbox delete」と表示して監視プロセスを終えるだけで、AWS上のリソースは残ります。削除の可否を尋ねるプロンプトは出ません。

削除は明示的に実行します。削除確認プロンプトを飛ばすなら -y を付けます。

npx ampx sandbox delete --identifier feature1sandbox

公式のCLIリファレンスには識別子の指定として --name と書かれていますが、backend-cli 1.8.3 の実装にこのオプションはありません。削除サブコマンドが自前で定義しているのは --yes だけで、対象の特定には親コマンドから継承された --identifier を使います。--name は解釈されずに無視され、既定識別子（OSユーザー名）のサンドボックスを消しに行くため、誤ったスタックを削除しかねません。Amplifyコンソールから消す方法もありますが、機能ブランチを閉じたタイミングで sandbox delete まで済ませる習慣にしておくと、識別子違いのスタックが積み上がりません。

CI/CDでのバックエンドデプロイ

Amplify Hostingのブランチ連携で完結させる場合

最短ルートは、Amplifyコンソールでリポジトリを接続してブランチを紐付ける方法です。以降はそのブランチへのコミットごとに、バックエンドとフロントエンドがまとめてデプロイされます。ビルド設定にバックエンド用のコマンドを書く必要はなく、Gen 1の amplify publish に相当する作業が消えます。

機能ブランチも自動で拾いたい場合は、コンソールの「App settings > Branch settings」で Branch auto-detection と Branch auto-disconnection を有効にし、dev staging feature/* のようなパターンを指定します。パターンに一致するブランチへプッシュすると環境が自動で立ち上がり、ブランチを消せば環境も切り離されます。フロントエンドを別のAmplifyアプリに分けるモノレポ構成では、フロントエンド側のビルドコマンドに npx ampx generate outputs --branch main --app-id BACKEND-APP-ID を追加してバックエンドの設定を取り込みます。料金の内訳や独自ドメインの扱いはAWS Amplify Hostingの料金・特徴とS3+CloudFrontとの違いにまとめています。

独自パイプラインでのampx pipeline-deploy

GitHub ActionsやCodeCatalystなど既存のパイプラインを使う場合は、バックエンドの反映を pipeline-deploy で明示します。公式のCodeCatalyst例では次の順序です。

export CI=1
npm ci
npx ampx pipeline-deploy --branch $BRANCH_NAME --app-id $AMPLIFY_APP_ID

pipeline-deploy は --branch と --app-id の両方が必須で、片方だけではデプロイ先のAmplifyアプリを特定できずに失敗します。フロントエンドのビルドを別ジョブに分けている場合は、そのジョブで最新の設定ファイルを取り直します。

npx ampx generate outputs --branch $AWS_BRANCH --app-id $AWS_APP_ID

こちらの generate outputs は指定の仕方が2通りあり、--app-id と --branch の組か、CloudFormationスタック名を渡す --stack 単独かのどちらかです。両者は併用できません。Amplify Hosting側のビルドを後段でキックしたいときは、コンソールで発行したWebhookへPOSTする方法が公式に示されています。

amplify_outputs.jsonがgit管理外になるチーム開発の落とし穴

npm create amplify@latest は初期化時に .gitignore へ次のパターンを追記します（create-amplify の gitignore_initializer.ts が実装）。

# amplify
node_modules
.amplify
amplify_outputs*
amplifyconfiguration*

つまり amplify_outputs.json はリポジトリに入りません。各開発者が自分のサンドボックスを立てれば自分の設定ファイルが手元に生成されるので、通常はこれで困りません。問題が起きるのは、フロントエンド担当がAWS認証情報を持っていないケースです。サンドボックスを立てられないため設定ファイルも生成されず、Amplify.configure に渡すものがない状態で止まります。

この場合、ファイルをチャットに貼って回すのは避けてください。中身にはAPIエンドポイントとCognitoの識別子が含まれます。ブランチのバックエンドが既にデプロイ済みなら npx ampx generate outputs --branch --app-id で正規の手段として取得できますし、これも権限的に無理なら、バックエンド担当とVS CodeのLive Shareで一時的に画面とファイルを共有して受け渡すのが現実的です。恒久的な解決は、フロントエンド担当にも検証用AWSアカウントのプロファイルを配ることです。

PoCでAmplifyを選ぶ基準と見送るべき場面

Amplify Gen 2がPoCで効くのは、認証・データ・ストレージ・関数という4カテゴリの標準構成で足りる場合です。defineAuth と defineData を数十行書けばCognitoとAppSyncとDynamoDBが揃い、型定義がフロントエンドまで通ります。同じ構成をCDKで直接書けばコンストラクト定義と権限設定でその数倍の行数になるので、標準カテゴリの範囲に収まっているうちは記述量で明確に上回ります。生成AI機能を短期間で載せたい場合も、Amplify AI Kitが同じ宣言方式に乗ります。

逆に見送るべき条件もはっきりしています。第一に、既存のVPCやRDSに載せる要件がある場合。Amplifyの4カテゴリから外れた瞬間、backend.ts の中でCDKを書くことになり、それならCDK単体で組んだほうが構成を追いやすくなります。第二に、AWS認証情報をチーム全員に配れない組織。前節のとおりサンドボックス前提の開発フローが成立しません。第三に、バックエンドの担当者が別チームで、リポジトリを分けたい場合。amplify/ がフロントエンドのリポジトリに同居する構成が前提なので、分離すると利点の大半が消えます。

PoCの入口で決めておくと後が楽なのは「Amplifyの標準カテゴリから外れる要件が出たら乗り換える」というラインを引いておくことです。判断軸の詳細はAWS AmplifyのGen 2バックエンド定義と採用判断に譲りますが、Amplifyを部分的に使い続けるより、外れた時点で切り替えるほうが判断がぶれません。

よくある質問

Gen 2でも amplify init は使えますか？

使えません。Gen 2に init サブコマンドはなく、プロジェクトの作成は npm create amplify@latest です。@aws-amplify/backend-cli は amplify という名前でも起動できますが、その場合は「The Amplify Gen 2 CLI has been renamed to ampx」というエラーで停止します。

amplify mock に相当するローカルモックはありますか？

ありません。Gen 2はローカルモックの代わりに、開発者ごとの実AWSリソースを立てるクラウドサンドボックス（npx ampx sandbox）を使います。オフラインでの開発は想定されていないため、AWSアカウントとネットワーク接続が前提になります。

Gen 1で作った既存プロジェクトはいつまで動きますか？

2026年5月1日以降はクリティカルなバグ修正とセキュリティパッチのみが提供され、2027年5月1日にサポートが終了します。Gen 1のCLI（@aws-amplify/cli）は2026年6月25日に14.5.1が公開されるなど更新自体は続いていますが、新機能は入りません。公式の移行ガイドとツールが用意されています。

サンドボックスは1人に1つでないといけませんか？

--identifier を使えば複数作れますが、同時に稼働できるのは1つだけです。公式も競合防止のためアプリごと・開発者ごとに1つを原則としており、1人が複数の一時環境を管理することは推奨していません。識別子を省略した場合は、実行中のOSユーザー名が自動的に使われます。

amplify pull に相当するコマンドはありますか？

近いのは npx ampx generate outputs ですが、取得できるのは amplify_outputs.json（クライアント設定）だけです。Gen 1の amplify pull のようにバックエンド定義を引き寄せる操作はありません。Gen 2ではバックエンド定義がリポジトリの amplify/ にあり、git pull で最新になるためです。

関連記事

• AWS Amplifyとは？Gen 2のバックエンド定義と料金・採用判断を実装者目線で解説
• AWS Amplify Hostingとは？料金・特徴とS3+CloudFront/App Runnerとの違い
• AWS AppSyncとは？GraphQL APIの仕組み・料金とAppSync Events・採用判断を実装者目線で解説