article
ローカルサンドボックスで開発する
ampless のカスタムテーマやローカルプラグインを、本番インフラを触らずに AWS リソース込みで試す方法です。npm run sandbox と npm run dev の役割、費用感、片づけ方をまとめます。
ローカルサンドボックスで開発する
カスタムテーマやプラグインを触るとき、「表示だけ手元で確認できれば十分」という場面もあれば、「投稿を保存したあとにイベントが流れるところまで見たい」という場面もあります。ampless では、そのどちらもローカル開発の流れに入れられます。Next.js の開発サーバーで画面を見ながら、必要なときは Amplify Gen 2 のサンドボックスを用意して、AWS リソースを通った結果まで確認する形です。
サンドボックスは、本番環境のテーブルやバケットを間借りする仕組みではありません。手元の開発用に Cognito、AppSync、DynamoDB、S3 などを AWS アカウント内へ用意し、ローカルの amplify_outputs.json をそのサンドボックス向けに書き換えます。ブラウザで開いているのは localhost でも、ログイン、記事データ、画像アップロード、API 呼び出しは実際の AWS リソースを通ります。
まず使うコマンド
ampless の標準プロジェクトでは、開発用の入口をこの 2 つに分けています。
npm run sandbox
npm run dev
最初に使うのは npm run sandbox です。内部では ampx sandbox --once を実行し、サンドボックス用の AWS リソースを作成してから next dev を起動します。初回は CloudFormation の作成や各サービスの準備が入るので、5〜10分ほど待つことがあります。ローカルに amplify_outputs.json が生成されるのもこの流れの中です。
ampless 本体をアップデートしたときは、AWS インフラの定義や Lambda 上で実行されるコードが変わっている可能性があります。その場合は npm run sandbox を使い、サンドボックス側にも差分を反映したうえで next dev を起動します。
一方で、ローカルなカスタムテーマや、AWS インフラを変えないプラグインのコードだけを直した場合は、既存のサンドボックスに接続したまま npm run dev で十分です。テーマの CSS やコンポーネントを保存すれば Next.js が再コンパイルし、ブラウザ側へ変更が反映されます。<head> にタグを出すだけのプラグインや、表示用の React コンポーネントを調整する作業も、バックエンド定義を触っていなければ毎回 npm run sandbox を走らせる必要はありません。
テーマを直すとき
カスタムテーマの作業では、通常の Next.js 開発とほとんど同じ感覚で進められます。テンプレート、コンポーネント、スタイルを保存すると、Next.js が必要なページを再コンパイルし、ブラウザ側にも変更が反映されます。構文を間違えたときはターミナルやブラウザのエラー画面に内容が出るので、どのファイルのどの行を見ればよいかも追いやすくなります。
ここでサンドボックスを使う意味は、表示確認の裏側にあります。記事一覧や記事詳細は、手元のモックではなく DynamoDB に入った記事データを AppSync 経由で読みます。画像をアップロードするテーマや、ログイン状態によって見せ方を変える管理画面まわりを触るときも、本番とは別のユーザープール、テーブル、バケットを使って試せます。
プラグインを作るとき
プラグイン開発では、サンドボックスを使う理由がもう少しはっきり出ます。<head> にタグを足すプラグインなら、ローカルのコード変更と npm run dev だけで多くの部分を確認できます。ページを開いて、出力された HTML に計測タグやメタタグが入っているか、管理画面の設定値が反映されているかを見る、という流れです。
一方で、記事の公開後にサイトマップや RSS を生成するようなプラグインは、イベントと保存先まで含めて見ておきたくなります。投稿が作成・更新されたときにフックが呼ばれるか。プラグインから公開済みの記事一覧を取得できるか。生成した XML や JSON を、公開サイトから読める場所に保存できるか。そうした確認では、AppSync、DynamoDB、S3、Lambda などが実際に組み合わさる環境が必要になります。
サンドボックスなら、本番の記事や本番の公開ファイルを汚さずに、その一連の流れを手元で確認できます。たとえば、ローカルプラグインを cms.config.ts に追加し、サンドボックス上の記事を管理画面から更新し、生成されたファイルをブラウザで開く。失敗したらコードを直し、もう一度同じイベントを起こす。公開前のプラグインには、この反復が欠かせません。
本番とは別の場所で試せる
ローカルサンドボックスは、開発マシンごと、開発者ごとに分けて作れます。チームで同じ本番環境を触っている場合でも、テーマ調整やプラグイン検証は自分のサンドボックスで進められます。誰かの試行錯誤で本番のテーブルにテスト記事が増えたり、公開バケットに確認用ファイルが混ざったりしません。
ただし、サンドボックスは実際の AWS リソースです。フルサーバレス構成なので、通常のテーマ調整や短時間のプラグイン検証で固定費を大きく見積もる必要はあまりありませんが、使った分の AWS 料金は発生します。大量の画像をアップロードする、イベントを連続で発火させる、長く残したままにする、といった使い方をすると、その分だけ確認すべき項目も増えます。
不要になったサンドボックスは、使い捨ての開発環境として片づけられます。このプロジェクトの npm run sandbox は --once を付けているため、作ったリソースは次回以降も使えるように残ります。消したいときは、プロジェクトのディレクトリで npx ampx sandbox delete を実行します。名前を分けて複数作っている場合は、対象のサンドボックス名を指定して削除します。
AWS コンソール側では、Amplify Console のサンドボックス一覧から対象を選んで削除できます。Amplify Gen 2 のサンドボックスは CloudFormation スタックとして作られるので、Cognito、AppSync、DynamoDB、S3 などの関連リソースをまとめて片づける前提で扱えます。残している間は AWS 上にリソースが存在するため、プロジェクトを離れるときや検証が終わったときは、不要なサンドボックスが残っていないか見ておくと安心です。
どんな作業に向いているか
ローカルサンドボックスは、次のような作業と相性がいいです。
- 公式テーマをコピーして、自分のサイト用にレイアウトや CSS を調整する
- 記事データや画像アップロードを含めて、テーマの表示を確認する
<head>タグ追加のような、表示に近いローカルプラグインを試す- サイトマップ、RSS、検索インデックスなど、記事イベントから公開ファイルを生成するプラグインを試す
- 管理画面の設定とプラグインの出力がつながっているか確認する
- 本番に出す前に、AWS リソース込みで一通り触っておく
ampless の開発では、手元のコードを直してすぐブラウザで見る Next.js の開発体験と、Cognito や DynamoDB や S3 まで含めて確認できる Amplify のサンドボックスを、同じ作業手順の中に置けます。見た目だけを直す日は npm run dev、バックエンドやプラグインの流れまで見る日は npm run sandbox。その切り替えを覚えておくと、カスタムテーマもローカルプラグインも、公開前にかなり踏み込んで確認できます。