Skip to content
@aws/nx-plugin
Blog

Jack

3 posts by Jack

AWSのPDKからの移行

Jack
Jack
Senior Prototyping Engineer (AWS)

このガイドでは、AWS PDKプロジェクトをNx Plugin for AWSに移行する具体例と、このトピックに関する一般的なガイダンスを提供します。

PDKからNx Plugin for AWSへの移行により、以下のメリットが得られます:

  • ビルドの高速化
  • 使いやすさの向上（UIとCLI）
  • バイブコーディング対応（MCPサーバーを試してみよう！）
  • モダンな技術スタック
  • ローカルでのAPI/ウェブサイト開発
  • 制御性の向上（ベンダードファイルのカスタマイズ可能）
  • その他多数

移行例: ショッピングリストアプリケーション

Section titled “移行例: ショッピングリストアプリケーション”

このガイドではPDKチュートリアルのショッピングリストアプリケーションを移行対象として使用します。実際に手順を追いたい場合は、まず上記チュートリアルで対象プロジェクトを作成してください。

ショッピングリストアプリケーションは以下のPDKプロジェクトタイプで構成されています:

  • MonorepoTsProject
  • TypeSafeApiProject
  • CloudscapeReactTsWebsiteProject
  • InfrastructureTsProject

ワークスペースの作成

Section titled “ワークスペースの作成”

最初に、新しいプロジェクト用のワークスペースを作成します。既存環境での移行よりも極端なアプローチですが、最もクリーンな結果を得られます。Nxワークスペースの作成は、PDKのMonorepoTsProjectに相当します:

Terminal window
npx create-nx-workspace@21.4.1 shopping-list --pm=pnpm  --preset=@aws/nx-plugin@0.50.0 --iacProvider=CDK --ci=skip

このコマンドで作成されたshopping-listディレクトリを、お気に入りのIDEで開きます。

APIの移行

Section titled “APIの移行”

ショッピングリストアプリケーションで使用されたTypeSafeApiProjectは以下を利用していました:

  • モデリング言語としてSmithy
  • オペレーション実装用のTypeScript
  • Reactウェブサイト連携用のTypeScriptフック生成

したがって、同等の機能を提供するためにts#smithy-apiジェネレーターを使用できます。

TypeScript Smithy APIの生成

Section titled “TypeScript Smithy APIの生成”

packages/apiにAPIプロジェクトをセットアップするため、ts#smithy-apiジェネレーターを実行します:

  1. インストール Nx Console VSCode Plugin まだインストールしていない場合
  2. VSCodeでNxコンソールを開く
  3. クリック Generate (UI) "Common Nx Commands"セクションで
  4. 検索 @aws/nx-plugin - ts#smithy-api
  5. 必須パラメータを入力
    • name: api
    • namespace: com.aws
    • auth: IAM
  6. クリック Generate

これによりmodelプロジェクトとbackendプロジェクトが生成されます。modelプロジェクトにはSmithyモデルが含まれ、backendにはサーバー実装が含まれます。

バックエンドはSmithy Server Generator for TypeScriptを使用しています。これについては後ほど詳しく説明します。

Smithyモデルの移行

Section titled “Smithyモデルの移行”

Smithy APIプロジェクトの基本構造ができたので、モデルを移行します:

  1. packages/api/model/src内の生成されたサンプルSmithyファイルを削除

  2. PDKプロジェクトのpackages/api/model/src/main/smithyディレクトリから新しいプロジェクトのpackages/api/model/srcディレクトリへモデルをコピー

  3. smithy-build.jsonのサービス名と名前空間をPDKアプリケーションに合わせて更新:

    smithy-build.json
    "plugins": {
        "openapi": {
          "service": "com.aws#MyApi",
          ...

  4. main.smithyのサービスにValidationExceptionエラーを追加（Smithy TypeScript Server SDK使用時に必要）:

    main.smithy
    use smithy.framework#ValidationException
    

    /// My Shopping List API
    @restJson1
    service MyApi {
        version: "1.0"
        operations: [
            GetShoppingLists
            PutShoppingList
            DeleteShoppingList
        ]
        errors: [
            BadRequestError
            NotAuthorizedError
            InternalFailureError
            ValidationException
        ]
    }

  5. packages/api/model/srcにextensions.smithyファイルを追加（生成クライアントにページネーション情報を提供するトレイト定義）:

    extensions.smithy
    $version: "2"
    namespace com.aws
    

    use smithy.openapi#specificationExtension
    

    @trait
    @specificationExtension(as: "x-cursor")
    structure cursor {
        inputToken: String
        enabled: Boolean
    }

  6. get-shopping-lists.smithyのGetShoppingListsオペレーションに新しい@cursorトレイトを追加:

    operations/get-shopping-lists.smithy
    @readonly
    @http(method: "GET", uri: "/shopping-list")
    @paginated(inputToken: "nextToken", outputToken: "nextToken", pageSize: "pageSize", items: "shoppingLists")
    @cursor(inputToken: "nextToken")
    @handler(language: "typescript")
    operation GetShoppingLists {
        input := with [PaginatedInputMixin] {
            @httpQuery("shoppingListId")
            shoppingListId: ShoppingListId
        }

    Nx Plugin for AWS（api-connectionジェネレーター経由）のクライアントジェネレーターを使用する場合、@paginatedオペレーションには@cursorも使用する必要があります。

  7. 最後に、すべてのオペレーションから@handlerトレイトを削除（Nx Plugin for AWSではサポートされていないため）。ts#smithy-apiを使用する場合、このトレイトが生成するLambda関数CDKコンストラクトとバンドリングターゲットは不要です（すべてのLambda関数に単一バンドルを使用）。

ここでビルドを実行し、モデル変更を確認するとともに生成されたサーバーコードを確認できます。バックエンドプロジェクト（@shopping-list/api）でいくつかのエラーが発生しますが、次に対処します。

Terminal window
pnpm nx run-many --target build

Lambdaハンドラーの移行

Section titled “Lambdaハンドラーの移行”

api/backendプロジェクトは、Type Safe APIのapi/handlers/typescriptプロジェクトとある程度同等とみなせます。

Type Safe APIとts#smithy-apiジェネレーターの主な違いの1つは、ハンドラーがSmithy Server Generator for TypeScriptを使用して実装される点です（Type Safe API独自の生成されたハンドラーラッパーではなく）。

ショッピングリストアプリケーションのLambdaハンドラーは@aws-sdk/client-dynamodbパッケージに依存しているため、まずこれをインストールします:

Terminal window
pnpm add -w @aws-sdk/client-dynamodb

次に、PDKプロジェクトのhandlers/src/dynamo-client.tsファイルをbackend/src/operationsにコピーし、ハンドラーで利用可能にします。

ハンドラーの移行には以下の一般的な手順に従います:

  1. PDKプロジェクトのpackages/api/handlers/typescript/srcディレクトリから新しいプロジェクトのpackages/api/backend/src/operationsディレクトリへハンドラーをコピー

  2. my-api-typescript-runtimeインポートを削除し、代わりに生成されたTypeScript Server SDKからオペレーションタイプとServiceContextをインポート:

    import {
      deleteShoppingListHandler,
      DeleteShoppingListChainedHandlerFunction,
      INTERCEPTORS,
      Response,
      LoggingInterceptor,
    } from 'myapi-typescript-runtime';
    import { DeleteShoppingList as DeleteShoppingListOperation } from '../generated/ssdk/index.js';
    import { ServiceContext } from '../context.js';

  3. ハンドラーラッパーのエクスポートを削除:

    export const handler = deleteShoppingListHandler(
      ...INTERCEPTORS,
      deleteShoppingList,
    );

  4. オペレーションハンドラーのシグネチャをSSDK用に更新:

    export const deleteShoppingList: DeleteShoppingListChainedHandlerFunction = async (request) => {
    export const DeleteShoppingList: DeleteShoppingListOperation<ServiceContext> = async (input, ctx) => {

  5. LoggingInterceptorの使用をctx.loggerに置換（メトリクスとトレーシングインターセプターも同様）:

    LoggingInterceptor.getLogger(request).info('...');
    ctx.logger.info('...');

  6. 入力パラメーターへの参照を更新。SSDKはSmithyモデルに完全に一致するタイプを提供するため、入力参照を適宜更新:

    const shoppingListId = request.input.requestParameters.shoppingListId;
    const shoppingListId = input.shoppingListId;

  7. Responseの使用を削除。SSDKではプレーンオブジェクトを返します:

    return Response.success({ shoppingListId });
    return { shoppingListId };

    Responseのスローや返信も行わず、代わりにSSDKが生成したエラーをスロー:

    throw Response.badRequest({ message: 'oh no' });
    return Response.badRequest({ message: 'oh no' });
    import { BadRequestError } from '../generated/ssdk/index.js';
    throw new BadRequestError({ message: 'oh no' });

  8. 相対インポートに.js拡張子を追加してESM構文を使用するようインポートを更新

  9. service.tsにオペレーションを追加:

    service.ts
    import { ServiceContext } from './context.js';
    import { MyApiService } from './generated/ssdk/index.js';
    import { DeleteShoppingList } from './operations/delete-shopping-list.js';
    import { GetShoppingLists } from './operations/get-shopping-lists.js';
    import { PutShoppingList } from './operations/put-shopping-list.js';
    

    // オペレーションをサービスに登録
    export const Service: MyApiService<ServiceContext> = {
      PutShoppingList,
      GetShoppingLists,
      DeleteShoppingList,
    };
チュートリアルの3つのショッピングリストオペレーションの完全なBefore/After例を見るにはここをクリック

Smithy APIプロジェクトをapiという名前で生成したのは、PDKプロジェクトとの一貫性を保つためpackages/apiに配置するためでした。現在のSmithy APIがservice Apiではなくservice MyApiを定義しているため、getApiServiceHandlerのインスタンスをすべてgetMyApiServiceHandlerに更新する必要があります。

handler.tsを以下のように変更します:

packages/api/backend/src/handler.ts
 import { getApiServiceHandler } from './generated/ssdk/index.js';
 import { getMyApiServiceHandler } from './generated/ssdk/index.js';


process.env.POWERTOOLS_METRICS_NAMESPACE = 'Api';
process.env.POWERTOOLS_SERVICE_NAME = 'Api';


const tracer = new Tracer();
const logger = new Logger();
const metrics = new Metrics();


 const serviceHandler = getApiServiceHandler(Service);
 const serviceHandler = getMyApiServiceHandler(Service);

local-server.tsも同様に変更します:

packages/api/backend/src/local-server.ts
import { getApiServiceHandler } from './generated/ssdk/index.js';
import { getMyApiServiceHandler } from './generated/ssdk/index.js';


const PORT = 3001;


const tracer = new Tracer();
const logger = new Logger();
const metrics = new Metrics();


const serviceHandler = getApiServiceHandler(Service);
const serviceHandler = getMyApiServiceHandler(Service);

さらに、packages/api/backend/project.jsonのmetadata.apiNameをmy-apiに更新します:

packages/api/backend/project.json
  "metadata": {
    "generator": "ts#smithy-api",
    "apiName": "api",
    "apiName": "my-api",
    "auth": "IAM",
    "modelProject": "@shopping-list/api-model",
    "ports": [3001]
  },

ビルドによる検証

Section titled “ビルドによる検証”

ここまでの移行が正常に完了したか確認するため、プロジェクトをビルドします:

Terminal window
pnpm nx run-many --target build

ウェブサイトの移行

Section titled “ウェブサイトの移行”

ショッピングリストアプリケーションで使用された CloudscapeReactTsWebsiteProject は、CloudScape と Cognito 認証が組み込まれた React ウェブサイトを設定していました。

このプロジェクトタイプは非推奨となった create-react-app を利用していました。このガイドでは、より現代的でサポートされた技術（具体的には [Vite](https://vite.dev/））を使用する ts#react-website ジェネレータ を利用してウェブサイトの移行を行います。

移行の一環として、PDK で設定されていた React Router から TanStack Router に移行し、ルーティングの型安全性を強化します。

React ウェブサイトの生成

Section titled “React ウェブサイトの生成”

ts#react-website ジェネレータ を実行して、packages/website にウェブサイトプロジェクトをセットアップします：

  1. インストール Nx Console VSCode Plugin まだインストールしていない場合
  2. VSCodeでNxコンソールを開く
  3. クリック Generate (UI) "Common Nx Commands"セクションで
  4. 検索 @aws/nx-plugin - ts#react-website
  5. 必須パラメータを入力
    • name: website
  6. クリック Generate

Cognito 認証の追加

Section titled “Cognito 認証の追加”

上記の React ウェブサイトジェネレータは CloudscapeReactTsWebsiteProject のようにデフォルトで Cognito 認証をバンドルしていないため、ts#react-website#auth ジェネレータ を使用して明示的に追加します。

  1. インストール Nx Console VSCode Plugin まだインストールしていない場合
  2. VSCodeでNxコンソールを開く
  3. クリック Generate (UI) "Common Nx Commands"セクションで
  4. 検索 @aws/nx-plugin - ts#react-website#auth
  5. 必須パラメータを入力
    • project: website
    • cognitoDomain: shopping-list
  6. クリック Generate

これにより、Cognito ホスト型 UI を使用したユーザーログインを確実に行うためのリダイレクトを管理する React コンポーネントが追加されます。また、packages/common/constructs に UserIdentity という名前の Cognito リソースをデプロイする CDK コンストラクトも追加されます。

ウェブサイトとAPIの接続

Section titled “ウェブサイトとAPIの接続”

PDK では、プロジェクト間で相互に Projen プロジェクトを渡すことで統合コードを生成できました。ショッピングリストアプリケーションでは、この機能を使用してウェブサイトがAPIと連携できるように設定していました。

Nx Plugin for AWS では、api-connection ジェネレータ を介してAPI統合をサポートしています。以下を使用して、ウェブサイトが Smithy API を呼び出せるようにします：

  1. インストール Nx Console VSCode Plugin まだインストールしていない場合
  2. VSCodeでNxコンソールを開く
  3. クリック Generate (UI) "Common Nx Commands"セクションで
  4. 検索 @aws/nx-plugin - api-connection
  5. 必須パラメータを入力
    • sourceProject: website
    • targetProject: api
  6. クリック Generate

これにより、生成された TypeScript クライアントを介してAPIを呼び出すために必要なクライアントプロバイダとビルドターゲットが生成されます。

AWS Northstar 依存関係の追加

Section titled “AWS Northstar 依存関係の追加”

CloudscapeReactTsWebsiteProject は自動的に @aws-northstar/ui の依存関係を含んでいました。ショッピングリストアプリケーションで使用されているため、ここで追加します：

Terminal window
pnpm add -w @aws-northstar/ui

コンポーネントとページの移動

Section titled “コンポーネントとページの移動”

ショッピングリストアプリケーション には CreateItem コンポーネントと、ShoppingList、ShoppingLists の2つのページがあります。これらを新しいウェブサイトに移行し、TanStack Router と Nx Plugin for AWS の TypeScript クライアントコードジェネレータを使用するために若干の調整を行います。

  1. PDK プロジェクトから packages/website/src/components/CreateItem/index.tsx を新しいプロジェクトの同じ場所にコピー

  2. ShoppingLists ページをホームページとして使用するため、packages/website/src/pages/ShoppingLists/index.tsx を packages/website/src/routes/index.tsx にコピー（TanStack Router のファイルベースルーティングを使用）

  3. /:shoppingListId ルートで表示する ShoppingList ページを、packages/website/src/pages/ShoppingList/index.tsx から packages/website/src/routes/$shoppingListId.tsx にコピー

IDE にビルドエラーが表示されますが、以下の変更で新しいフレームワークに適合させます。

React Router から TanStack Router への移行

Section titled “React Router から TanStack Router への移行”

ファイルベースルーティング を使用しているため、ローカル開発サーバーでルート設定の自動生成を管理できます。まずローカルサーバーを起動：

Terminal window
pnpm nx serve-local website

エラーが表示されますが、ローカルウェブサイトサーバーはポート 4200 で、Smithy API サーバーはポート 3001 で起動します。

以下の手順で routes/index.tsx と routes/$shoppingListId.tsx を TanStack Router に移行：

  1. 各ルートを登録する createFileRoute を追加：

    import { createFileRoute } from "@tanstack/react-router";
    ...
    export default ShoppingLists;
    export const Route = createFileRoute('/')({
      component: ShoppingLists,
    });

    ファイル保存後、createFileRoute の型エラーが解消されます。

  2. useNavigate フックの置き換え：

    インポートを更新：

    import { useNavigate } from 'react-router-dom';
    import { useNavigate } from '@tanstack/react-router';

    navigate メソッドの呼び出しを型安全なルート指定に変更：

    navigate(`/${cell.shoppingListId}`);
    navigate({
      to: '/$shoppingListId',
      params: { shoppingListId: cell.shoppingListId },
    });

  3. useParams フックの置き換え：

    インポートを削除：

    import { useParams } from 'react-router-dom';

    useParams の呼び出しを Route から取得するように変更（型安全）：

    const { shoppingListId } = useParams();
    const { shoppingListId } = Route.useParams();

コンポーネントインポートの修正

Section titled “コンポーネントインポートの修正”

ファイル構造の変更に伴い、CreateItem のインポートパスを修正：

import CreateItem from "../../components/CreateItem";
import CreateItem from "../components/CreateItem";

AppLayoutContext の場所も変更：

import { AppLayoutContext } from "../../layouts/App";
import { AppLayoutContext } from "../components/AppLayout";

新しい生成TypeScriptクライアントへの移行

Section titled “新しい生成TypeScriptクライアントへの移行”

Nx Plugin for AWS が生成するTypeScriptクライアントを使用するため、以下の手順を実行：

  1. 新しいクライアントと型をインポート：

    import {
      ShoppingList,
      usePutShoppingList,
      useDeleteShoppingList,
      useGetShoppingLists,
    } from "myapi-typescript-react-query-hooks";
    import { ShoppingList } from "../generated/my-api/types.gen";
    import { useMyApi } from "../hooks/useMyApi";
    import { useInfiniteQuery, useMutation } from "@tanstack/react-query";

  2. TanStack Query フックを初期化：

    const getShoppingLists = useGetShoppingLists({ pageSize: PAGE_SIZE });
    const putShoppingList = usePutShoppingList();
    const deleteShoppingList = useDeleteShoppingList();
    const api = useMyApi();
    const getShoppingLists = useInfiniteQuery(
      api.getShoppingLists.infiniteQueryOptions(
        { pageSize: PAGE_SIZE },
        { getNextPageParam: (p) => p.nextToken },
      ),
    );
    const putShoppingList = useMutation(api.putShoppingList.mutationOptions());
    const deleteShoppingList = useMutation(
      api.deleteShoppingList.mutationOptions(),
    );

  3. リクエストボディのラッパーを削除：

    await putShoppingList.mutateAsync({
      putShoppingListRequestContent: {
        name: item,
      },
    });

TanStack Query v4 から v5 への移行

Section titled “TanStack Query v4 から v5 への移行”

api-connection ジェネレータが追加した TanStack Query v5 との差異を修正：

  1. ミューテーションの isLoading を isPending に置換：

    putShoppingList.isLoading
    putShoppingList.isPending

  2. InfiniteQueryTable の型エラーを抑制：

    <InfiniteQueryTable
      query={getShoppingLists}
      query={getShoppingLists as any}

ローカルウェブサイトの確認

Section titled “ローカルウェブサイトの確認”

http://localhost:4200/ にアクセスして動作確認できます。API、ウェブサイト、認証に加えて DynamoDB テーブル shopping_list がリージョン内に存在し、ローカルAWS認証情報でアクセス可能な場合、完全に機能します。

インフラストラクチャの移行は次に行います。

クリックで移行前後の完全なコード例を表示

インフラストラクチャの移行

Section titled “インフラストラクチャの移行”

ショッピングリストアプリケーションで最後に移行が必要なプロジェクトが InfrastructureTsProject です。これはTypeScript CDKプロジェクトであり、Nx Plugin for AWSの同等機能はts#infra ジェネレータです。

PDKはProjenプロジェクトに加えて、これらのプロジェクトが依存するCDKコンストラクトも提供していました。私たちはこれらのCDKコンストラクトからもショッピングリストアプリケーションを移行し、Nx Plugin for AWSが生成するコンストラクトを採用します。

TypeScript CDKインフラストラクチャプロジェクトの生成

Section titled “TypeScript CDKインフラストラクチャプロジェクトの生成”

packages/infra にインフラプロジェクトをセットアップするため、ts#infra ジェネレータを実行します：

  1. インストール Nx Console VSCode Plugin まだインストールしていない場合
  2. VSCodeでNxコンソールを開く
  3. クリック Generate (UI) "Common Nx Commands"セクションで
  4. 検索 @aws/nx-plugin - ts#infra
  5. 必須パラメータを入力
    • name: infra
  6. クリック Generate

CDKインフラストラクチャの移行

Section titled “CDKインフラストラクチャの移行”

PDKショッピングリストアプリケーションは、CDKアプリケーションスタック内で以下のコンストラクトをインスタンス化していました：

  • ショッピングリストを保存するDynamoDBテーブルのための DatabaseConstruct
  • PDKから直接インポートしたCognitoリソース用の UserIdentity
  • Smithy APIをデプロイするための MyApi（PDKの TypeSafeRestApi CDKコンストラクトを使用したタイプセーフな統合）
  • PDKの StaticWebsite CDKコンストラクトをラップしたウェブサイトデプロイ用の Website

次に、これらを新しいプロジェクトに移行します。

アプリケーションスタックのコピー
Section titled “アプリケーションスタックのコピー”

PDKショッピングリストアプリケーションの packages/infra/src/stacks/application-stack.ts を新しいプロジェクトの同じ場所にコピーします。TypeScriptエラーが表示されますが、後で対応します。

データベースコンストラクトのコピー
Section titled “データベースコンストラクトのコピー”

PDKアプリケーションの packages/src/constructs/database.ts にある Database コンストラクトを新しいプロジェクトの同じ場所にコピーします。

Nx Plugin for AWSはPDK Nagよりも厳格なCheckovを使用するため、以下の抑制ルールを追加します：

constructs/database.ts
import { suppressRules } from ':shopping-list/common-constructs';
...
suppressRules(
  this.shoppingListTable,
  ['CKV_AWS_28', 'CKV_AWS_119'],
  'Backup and KMS key not required for this project',
);

application-stack.ts で DatabaseConstruct のインポートをESM構文に更新します：

stacks/application-stack.ts
import { DatabaseConstruct } from '../constructs/database';
import { DatabaseConstruct } from '../constructs/database.js';
UserIdentityコンストラクトの移行
Section titled “UserIdentityコンストラクトの移行”

UserIdentity コンストラクトは基本的にインポートを変更するだけで置換可能です：

import { UserIdentity } from "@aws/pdk/identity";
import { UserIdentity } from ':shopping-list/common-constructs';
...
const userIdentity = new UserIdentity(this, `${id}UserIdentity`);

新しい UserIdentity コンストラクトが使用する基盤リソースは aws-cdk-lib から直接提供され、PDKでは @aws-cdk/aws-cognito-identitypool-alpha を使用していました。

APIコンストラクトの移行
Section titled “APIコンストラクトの移行”

PDKアプリケーションの constructs/apis/myapi.ts には、Smithyモデルから生成されたタイプセーフなCDKコンストラクトをインスタンス化するコードがありました。

Nx Plugin for AWSもSmithyモデルに基づいたタイプセーフな統合を提供しますが、よりシンプルで柔軟な方法を採用しています。packages/common/constructs/src/app/apis/api.ts が使用する最小限のメタデータを生成し、詳細はts#smithy-api ガイドで確認できます。

以下の手順で移行します：

  1. application-stack.ts で Api コンストラクトをインスタンス化

    stacks/application-stack.ts
    import { MyApi } from "../constructs/apis/myapi";
    import { Api } from ':shopping-list/common-constructs';
    ...
    const myapi = new MyApi(this, "MyApi", {
      databaseConstruct,
      userIdentity,
    });
    const api = new Api(this, 'MyApi', {
      integrations: Api.defaultIntegrations(this).build(),
    });

    Api.defaultIntegrations(this).build() はAPIの各操作に対してLambda関数を作成するデフォルト動作です。

  2. Lambda関数にDynamoDBテーブルへのアクセス権限を付与

    stacks/application-stack.ts
    databaseConstruct.shoppingListTable.grantReadData(
      api.integrations.getShoppingLists.handler,
    );
    [
      api.integrations.putShoppingList.handler,
      api.integrations.deleteShoppingList.handler,
    ].forEach((f) => databaseConstruct.shoppingListTable.grantWriteData(f));

  3. 認証ユーザーにAPI呼び出し権限を付与

    stacks/application-stack.ts
    api.grantInvokeAccess(userIdentity.identityPool.authenticatedRole);
ウェブサイトコンストラクトの移行
Section titled “ウェブサイトコンストラクトの移行”

最後に、Website コンストラクトを application-stack.ts に追加します：

import { Website } from "../constructs/websites/website";
import { Website } from ':shopping-list/common-constructs';
...
new Website(this, "Website", {
  userIdentity,
  myapi,
});
new Website(this, 'Website');

Nx Plugin for AWSのコンストラクトでは、ランタイム設定が各コンストラクト内で管理され、/runtime-config.json に自動デプロイされます。

すべてのコードを移行したら、プロジェクトをビルドします：

Terminal window
pnpm nx run-many --target build

デプロイ

Section titled “デプロイ”

コードベースの完全な移行が完了したので、デプロイ方法を検討できます。この時点で選択可能な2つのアプローチがあります。

新規リソースをすべて作成する（シンプルな方法）

Section titled “新規リソースをすべて作成する（シンプルな方法）”

最もシンプルなアプローチは、これを完全に新しいアプリケーションとして扱うことです。つまり、新しいDynamoDBテーブルとCognitoユーザープールを「最初から作成」し、既存のユーザーとそのショッピングリストをすべて失います。この方法では、以下の手順を実行するだけです：

  1. shopping_listという名前のDynamoDBテーブルを削除

  2. 新しいアプリケーションをデプロイ：

    Terminal window
    pnpm nx deploy infra shopping-list-infra-sandbox/*

🎉 これで完了です！ 🎉

既存のステートフルリソースをダウンタイムなしで移行（より複雑な方法）

Section titled “既存のステートフルリソースをダウンタイムなしで移行（より複雑な方法）”

実際には、既存のAWSリソースを新しいコードベースで管理できるように移行しつつ、顧客へのサービス停止を回避したい場合がほとんどでしょう。

ショッピングリストアプリケーションにおいて重要なステートフルリソースは、ユーザーのショッピングリストを含むDynamoDBテーブルと、登録ユーザーの詳細を含むユーザープールです。高レベルの計画としては、これら2つの主要リソースを保持し、新しいスタックで管理されるように移動した後、DNSを更新して新しいWebサイト（および顧客に公開されている場合はAPI）を指すようにします。

  1. 保持したい既存リソースを参照するように新しいアプリケーションを更新

    ショッピングリストアプリケーションでは、DynamoDBテーブルに対して以下を実行：

    constructs/database.ts
    this.shoppingListTable = new Table(this, 'ShoppingList', {
      ...
    this.shoppingListTable = Table.fromTableName(
      this,
      'ShoppingList',
      'shopping_list',
    );

    Cognitoユーザープールに対しては：

    packages/common/constructs/src/core/user-identity.ts
    this.userPool = this.createUserPool();
    this.userPool = UserPool.fromUserPoolId(
      this,
      'UserPool',
      '<your-user-pool-id>',
    );

  2. 新しいアプリケーションをビルドしてデプロイ：

    Terminal window
    pnpm nx run-many --target build
    Terminal window
    pnpm nx deploy infra shopping-list-infra-sandbox/*

    これで既存リソースを参照する新しいアプリケーションが起動しましたが、まだトラフィックは受けていません。

  3. 完全な結合テストを実施し、新しいアプリケーションが期待通りに動作することを確認。ショッピングリストアプリケーションでは、Webサイトをロードしてサインイン、ショッピングリストの作成/表示/編集/削除が可能か確認。

  4. 既存リソースを参照する変更を新しいアプリケーションで元に戻す（ただしまだデプロイしない）：

    constructs/database.ts
    this.shoppingListTable = new Table(this, 'ShoppingList', {
      ...
    this.shoppingListTable = Table.fromTableName(
      this,
      'ShoppingList',
      'shopping_list',
    );

    Cognitoユーザープールに対しては：

    packages/common/constructs/src/core/user-identity.ts
    this.userPool = this.createUserPool();
    this.userPool = UserPool.fromUserPoolId(
      this,
      'UserPool',
      '<your-user-pool-id>',
    );

    その後ビルドを実行：

    Terminal window
    pnpm nx run-many --target build

  5. 新しいアプリケーションのpackages/infraフォルダでcdk importを実行し、インポート対象リソースを確認：

    New Application
    cd packages/infra
    pnpm exec cdk import shopping-list-infra-sandbox/Application --force

    Enterキーを押してプロンプトを進めてください。リソースが別スタックで管理されているためインポートは失敗します（これは予期された動作です）。インポート対象リソースを確認するためだけのステップです。以下のような出力が表示されます：

    Terminal window
    shopping-list-infra-sandbox/Application/ApplicationUserIdentity/UserPool/smsRole/Resource (AWS::IAM::Role): enter RoleName (empty to skip)
    shopping-list-infra-sandbox/Application/ApplicationUserIdentity/UserPool/Resource (AWS::Cognito::UserPool): enter UserPoolId (empty to skip)
    shopping-list-infra-sandbox/Application/Database/ShoppingList/Resource (AWS::DynamoDB::Table): import with TableName=shopping_list (y/n) y

    これにより、実際には3つのリソースを新しいスタックにインポートする必要があることがわかります。

  6. 前のステップで発見したリソースに対して、古いPDKプロジェクトでRemovalPolicyをRETAINに設定：

    application-stack.ts
    const userIdentity = new UserIdentity(this, `${id}UserIdentity`, {
      userPool,
    });
    

    const smsRole = userIdentity.userPool.node.findAll().filter(
      c => CfnResource.isCfnResource(c) &&
        c.node.path.includes('/smsRole/'))[0] as CfnResource;
    smsRole.applyRemovalPolicy(RemovalPolicy.RETAIN);

  7. 削除ポリシーを適用するためPDKプロジェクトをデプロイ：

    PDK Application
    cd packages/infra
    npx projen deploy

  8. CloudFormationコンソールでcdk importステップで要求された値を記録：

    1. ユーザープールID（例：us-west-2_XXXXX）
    2. SMSロール名（例：infra-sandbox-UserIdentityUserPoolsmsRoleXXXXXX）

  9. リソースを作成する代わりに既存リソースを参照するようPDKプロジェクトを更新：

    constructs/database.ts
    this.shoppingListTable = new Table(this, 'ShoppingList', {
      ...
    this.shoppingListTable = Table.fromTableName(
      this,
      'ShoppingList',
      'shopping_list',
    );

    Cognitoユーザープールに対しては：

    application-stack.ts
    const userPool = UserPool.fromUserPoolId(
      this,
      'UserPool',
      '<your-user-pool-id>',
    );
    const userIdentity = new UserIdentity(this, `${id}UserIdentity`, {
      // PDKコンストラクトはIUserPoolではなくUserPoolを受け取りますが、問題なく動作します！
      userPool: userPool as any,
    });

  10. PDKプロジェクトを再度デプロイ（これによりリソースがPDKプロジェクトのCloudFormationスタックで管理されなくなります）：

    PDK Application
    cd packages/infra
    npx projen deploy

  11. リソースが管理対象外になったら、新しいアプリケーションでcdk importを実行して実際にインポート：

    New Application
    cd packages/infra
    pnpm exec cdk import shopping-list-infra-sandbox/Application --force

    プロンプトで値を入力すると、インポートが正常に完了します。

  12. 既存リソース（現在は新しいスタックで管理）への変更を適用するため、新しいアプリケーションを再度デプロイ：

    Terminal window
    pnpm nx deploy infra shopping-list-infra-sandbox/*

  13. 新しいアプリケーションの完全テストを再度実施

  14. 新しいWebサイト（および必要に応じてAPI）を指すようDNSレコードを更新：

    Route53のWeighted Routingを使用した段階的な移行を推奨します。最初は一部のリクエストを新しいアプリケーションに転送し、メトリクスを監視しながら徐々に重みを増やしていき、最終的に古いPDKアプリケーションへのトラフィックをゼロにします。

    DNSがなくWebサイト/APIに自動生成ドメインを使用している場合は、CloudFront HTTP originやAPI Gateway HTTP integrationを使用してリクエストをプロキシできます。

  15. PDKアプリケーションのメトリクスを監視してトラフィックがないことを確認後、古いCloudFormationスタックを削除：

    Terminal window
    cd packages/infra
    npx projen destroy

かなり手間がかかりましたが、ユーザーをシームレスに新しいアプリケーションに移行できました！ 🎉🎉🎉

これで、PDKよりもNx Plugin for AWSの新しいメリットを享受できます：

  • より高速なビルド
  • ローカルAPI開発のサポート
  • 快適なコーディングが可能なコードベース（MCPサーバーを試してみてください！）
  • より直感的なタイプセーフなクライアント/サーバーコード
  • その他多数！

よくある質問

Section titled “よくある質問”

このセクションでは、上記の移行例でカバーされていないPDK機能に関するガイダンスを提供します。

一般的なルールとして、PDKからの移行時にはNxワークスペースからプロジェクトを開始することを推奨します（PDK Monorepoとの類似性を考慮）。また、新しいタイプを構築する際の基盤として、当プラグインのジェネレータを使用することをお勧めします。

Terminal window
npx create-nx-workspace@21.4.1 my-project --pm=pnpm  --preset=@aws/nx-plugin --ci=skip

CDK Graph

Section titled “CDK Graph”

CDK Graphは接続されたCDKリソースのグラフを構築し、2つのプラグインを提供します：

Diagram Plugin

Section titled “Diagram Plugin”

CDK Graph Diagram PluginはCDKインフラストラクチャからAWSアーキテクチャ図を生成します。

同様の決定論的アプローチとして有効な代替手段はCDK-Diaがあります。

生成AIの進化に伴い、多くの基盤モデルがCDKインフラストラクチャから高品質な図を作成可能です。AWS Diagram MCP Serverの使用をお試しください。チュートリアルについてはこちらのブログ記事を参照してください。

Threat Composer Plugin

Section titled “Threat Composer Plugin”

CDK Graph Threat Composer PluginはCDKコードからThreat Composerのスターター脅威モデルを生成します。

このプラグインは、サンプルの脅威を含むベース脅威モデルをフィルタリングし、スタックで使用するリソースに基づいて絞り込むことで機能します。

これらの具体的なサンプル脅威に興味がある場合は、ベース脅威モデルをコピーしてフィルタリングするか、基盤モデルが類似モデルを生成する際のコンテキストとして使用できます。

AWS Arch

Section titled “AWS Arch”

AWS Arch は、CDK Graph向けにCloudFormationリソースと関連するアーキテクチャアイコンのマッピングを提供しています。

アイコン関連のリソースについては AWS Architecture Icons page を参照してください。Diagrams はコードとしてダイアグラムを構築する方法も提供しています。

直接使用する場合は、プロジェクトをフォークしてオーナーシップを取得することを検討してください！

パイプライン

Section titled “パイプライン”

PDKはPDKPipelineProjectを提供しており、CDKインフラストラクチャプロジェクトをセットアップし、CDK PipelinesリソースをラップしたCDKコンストラクトを利用していました。

これから移行する場合、CDK Pipelinesコンストラクトを直接使用できます。ただし実際には、CDK Stagesを定義し、適切なステージのデプロイコマンドを直接実行するGitHub ActionsやGitLab CI/CDのようなツールを使用する方がより直接的である可能性が高いでしょう。

PDK Nag

Section titled “PDK Nag”

PDK NagはCDK Nagをラップし、プロトタイプ構築向けの特定ルールセットを提供します。

PDK Nagからの移行にはCDK Nagを直接使用してください。同じルールセットが必要な場合、こちらのドキュメントに従って独自の「パック」を作成できます。

Type Safe API

Section titled “Type Safe API”

上記の移行例ではType Safe APIで最も一般的に使用されるコンポーネントをカバーしていますが、他の機能に関する移行の詳細は以下に記載します。

OpenAPIでモデル化されたAPI

Section titled “OpenAPIでモデル化されたAPI”

Nx Plugin for AWSはSmithyでモデル化されたAPIをサポートしていますが、直接OpenAPIでモデル化されたAPIはサポートしていません。ts#smithy-apiジェネレーターはカスタマイズ可能な良い出発点となります。Smithyの代わりにOpenAPI仕様をmodelプロジェクトのsrcフォルダーに定義し、クライアント/サーバーのコード生成ツールがNPMで利用できない場合、build.Dockerfileを修正して目的のツールを使用できます。目的のツールがNPMで利用可能な場合、Nxワークスペースに開発依存関係としてインストールし、Nxビルドターゲットから直接呼び出すことができます。

バックエンド
Section titled “バックエンド”

OpenAPIでモデル化された型安全なバックエンドには、OpenAPI Generatorのサーバージェネレーターの使用を検討できます。これらはAWS Lambda向けに直接生成しませんが、AWS Lambda Web Adapterを使用して多くのケースでギャップを埋めることができます。

クライアント
Section titled “クライアント”

TypeScriptクライアントの場合、ts#react-websiteジェネレーターとapi-connectionジェネレーターをts#smithy-apiの例と組み合わせて使用し、クライアントの生成とウェブサイトへの統合方法を確認できます。これはopen-api#ts-clientまたはopen-api#ts-hooksジェネレーターを呼び出すビルドターゲットを設定します。これらのジェネレーターをOpenAPI仕様を指すように自分で使用できます。

その他の言語の場合、OpenAPI Generatorのジェネレーターが要件に合うか確認できます。

ts#nx-generatorジェネレーターを使用してカスタムジェネレーターを構築することも可能です。OpenAPIからのコード生成方法の詳細については、該当ジェネレーターのドキュメントを参照してください。Nx Plugin for AWSのテンプレートを出発点として使用できます。PDKコードベースのテンプレートも参考にできますが、テンプレートが操作するデータ構造がNx Plugin for AWSとは若干異なる点に注意してください。

TypeSpecでモデル化されたAPI

Section titled “TypeSpecでモデル化されたAPI”

TypeSpecの場合、上記のOpenAPIに関するセクションが同様に適用されます。ts#smithy-apiを生成し、TypeSpecコンパイラーとOpenAPIパッケージをNxワークスペースにインストールした後、モデルプロジェクトのcompileターゲットをtsp compileを実行するように更新し、OpenAPI仕様をdistディレクトリに出力するようにします。

バックエンド
Section titled “バックエンド”

推奨アプローチは、TypeSpec HTTP Server generator for JavaScriptを使用してサーバーコードを生成することです。これはTypeSpecモデルを直接操作します。

AWS Lambdaでの実行にはAWS Lambda Web Adapterを使用できます。

上記のOpenAPIオプションも使用可能です。

クライアント
Section titled “クライアント”

TypeSpecはType Safe APIがサポートする3言語すべてでクライアント生成機能を備えています：

TypeSpecはOpenAPIにコンパイル可能なため、上記のOpenAPIセクションも適用されます。

Smithyでモデル化されたAPI

Section titled “Smithyでモデル化されたAPI”

上記の移行例ではts#smithy-apiジェネレーターへの移行の概要を説明しています。このセクションではPythonとJavaのバックエンドおよびクライアントのオプションについて説明します。

バックエンド
Section titled “バックエンド”

Smithy JavaコードジェネレーターはJavaサーバージェネレーターとAWS Lambda用アダプターを提供します。

SmithyはPython用サーバージェネレーターを持たないため、OpenAPI経由で対応する必要があります。Pythonバックエンドのオプションについては、上記のOpenAPIでモデル化されたAPIセクションを参照してください。

クライアント
Section titled “クライアント”

Smithy JavaコードジェネレーターはJavaクライアントジェネレーターを提供します。

PythonクライアントにはSmithy Pythonを確認できます。

TypeScriptにはSmithy TypeScriptを使用するか、ts#smithy-apiで採用したOpenAPI経由のアプローチ（tRPC、FastAPI、Smithy API間で一貫性を保つためTanStack Queryフックを使用）を適用できます。

Smithy Shapeライブラリ
Section titled “Smithy Shapeライブラリ”

Type Safe APIはSmithyShapeLibraryProjectというProjenプロジェクトタイプを提供し、複数のSmithyベースAPIで再利用可能なSmithyモデルを含むプロジェクトを設定しました。

これを実現する最も簡単な方法は以下の通りです：

Shapeライブラリの作成
Section titled “Shapeライブラリの作成”

  1. smithy#projectジェネレーターでshapeライブラリを作成：

    1. インストール Nx Console VSCode Plugin まだインストールしていない場合
    2. VSCodeでNxコンソールを開く
    3. クリック Generate (UI) "Common Nx Commands"セクションで
    4. 検索 @aws/nx-plugin - smithy#project
    5. 必須パラメータを入力
      • クリック Generate

      serviceNameオプションには任意の名前を指定（後でservice shapeを削除します）

    6. srcのデフォルトモデルを必要なshape定義に置き換え

    7. smithy-build.jsonを更新してpluginsと未使用のMaven依存関係を削除

    8. build.Dockerfileを最小限のビルドステップに置き換え：

      build.Dockerfile
      FROM public.ecr.aws/docker/library/node:24 AS builder
      

      # 出力ディレクトリ
      RUN mkdir /out
      

      # Smithy CLIのインストール
      # https://smithy.io/2.0/guides/smithy-cli/cli_installation.html
      WORKDIR /smithy
      ARG TARGETPLATFORM
      RUN if [ "$TARGETPLATFORM" = "linux/arm64" ]; then ARCH="aarch64"; else ARCH="x86_64"; fi && \
          mkdir -p smithy-install/smithy && \
          curl -L https://github.com/smithy-lang/smithy/releases/download/1.61.0/smithy-cli-linux-$ARCH.zip -o smithy-install/smithy-cli-linux-$ARCH.zip && \
          unzip -qo smithy-install/smithy-cli-linux-$ARCH.zip -d smithy-install && \
          mv smithy-install/smithy-cli-linux-$ARCH/* smithy-install/smithy
      RUN smithy-install/smithy/install
      

      # プロジェクトファイルのコピー
      COPY smithy-build.json .
      COPY src src
      

      # MavenキャッシュマウントでのSmithyビルド
      RUN --mount=type=cache,target=/root/.m2/repository,id=maven-cache \
          smithy build
      

      RUN cp -r build/* /out/
      

      # /outディレクトリのエクスポート
      FROM scratch AS export
      COPY --from=builder /out /
    Shapeライブラリの利用
    Section titled “Shapeライブラリの利用”

    サービスモデルプロジェクトで以下の変更を行いshapeライブラリを利用：

    1. project.jsonのcompileターゲットを更新し、ワークスペースをビルドコンテキストとして追加し、shapeライブラリのbuildターゲットに依存：

      project.json
      {
        "cache": true,
        "outputs": ["{workspaceRoot}/dist/{projectRoot}/build"],
        "executor": "nx:run-commands",
        "options": {
          "commands": [
            "rimraf dist/packages/api/model/build",
            "make-dir dist/packages/api/model/build",
            "docker build --build-context workspace=. -f packages/api/model/build.Dockerfile --target export --output type=local,dest=dist/packages/api/model/build packages/api/model"
          ],
          "parallel": false,
          "cwd": "{workspaceRoot}"
        },
        "dependsOn": ["@my-project/shapes:build"]
      }

    2. build.Dockerfileを更新してshapeライブラリのsrcディレクトリをコピー（例：shapeライブラリがpackages/shapesにある場合）：

      build.Dockerfile
      # プロジェクトファイルのコピー
      COPY smithy-build.json .
      COPY src src
      COPY --from=workspace packages/shapes/src shapes

    3. smithy-build.jsonを更新してsourcesにshapesディレクトリを追加：

      smithy-build.json
      {
        "version": "1.0",
        "sources": ["src/", "shapes/"],
        "plugins": {
        ...
      }

    インターセプター

    Section titled “インターセプター”

    Type Safe APIは以下のデフォルトインターセプターを提供：

    • Powertools for AWS Lambdaを使用したロギング、トレーシング、メトリクス
    • 未捕捉例外処理用try-catchインターセプター
    • CORSヘッダー返信用インターセプター

    ts#smithy-apiジェネレーターはMiddyを使用してPowertools for AWS Lambdaによるロギング、トレーシング、メトリクスを計装します。try-catchインターセプターの動作はSmithy TypeScript SSDKに組み込まれており、CORSヘッダーはhandler.tsで追加されます。

    任意の言語でのロギング、トレーシング、メトリクスインターセプターにはPowertools for AWS Lambdaを直接使用します。

    カスタムインターセプターの移行には以下を推奨：

    ドキュメント生成

    Section titled “ドキュメント生成”

    Type Safe APIはRedocly CLIを使用したドキュメント生成を提供しました。これは上記の移行後に既存プロジェクトに簡単に追加できます。

    1. Redocly CLIをインストール：

      Terminal window
      pnpm add -Dw @redocly/cli

    2. redocly build-docsを使用してモデルプロジェクトにドキュメント生成ターゲットを追加：

      model/project.json
      {
        ...
        "documentation": {
          "cache": true,
          "outputs": ["{workspaceRoot}/dist/{projectRoot}/documentation"],
          "executor": "nx:run-commands",
          "options": {
            "command": "redocly build-docs dist/packages/api/model/build/openapi/openapi.json --output=dist/packages/api/model/documentation/index.html",
            "cwd": "{workspaceRoot}"
          },
          "dependsOn": ["compile"]
        }
      }

    OpenAPI Generatorのドキュメントジェネレーターも検討可能です。

    モック統合

    Section titled “モック統合”

    Type Safe APIは生成されたインフラストラクチャパッケージ内にモックを生成しました。

    JSON Schema Fakerに移行可能です。これはOpenAPI仕様に基づいてモックデータを作成でき、CLIをmodelプロジェクトのビルドの一部として実行できます。

    CDKインフラストラクチャを更新してJSON Schema Fakerが生成したJSONファイルを読み込み、適切なAPI GatewayMockIntegrationを返すようにします（ts#smithy-apiジェネレーターを使用した場合のmetadata.gen.tsをベースに）。

    混合言語バックエンド

    Section titled “混合言語バックエンド”

    Type Safe APIは複数言語でのAPI実装をサポートしていました。これはCDKでAPIコンストラクトをインスタンス化する際に統合をオーバーライドすることで実現可能です：

    application-stack.ts
    const pythonLambdaHandler = new Function(this, 'PythonImplementation', {
      runtime: Runtime.PYTHON_3_12,
      ...
    });
    

    new MyApi(this, 'MyApi', {
      integrations: Api.defaultIntegrations(this)
        .withOverrides({
          echo: {
            integration: new LambdaIntegration(pythonLambdaHandler),
            handler: pythonLambdaHandler,
          },
        })
        .build(),
    });

    ts#smithy-apiとTypeScript Server SDKを使用する場合、サービス/ルーターのスタブを作成する必要があります：

    service.ts
    export const Service: ApiService<ServiceContext> = {
      ...
      Echo: () => { throw new Error(`Not Implemented`); },
    };

    入力バリデーション

    Section titled “入力バリデーション”

    Type Safe APIはSpecRestApiコンストラクトを使用して、OpenAPI仕様に基づくAPI Gatewayのネイティブリクエストボディバリデーションを実装していました。

    ts#smithy-apiジェネレーターでは、バリデーションはServer SDK自体で実行されます。これはほとんどのサーバージェネレーターで同様です。

    ネイティブのAPI Gatewayバリデーションを実装するには、packages/common/constructs/src/core/api/rest-api.tsを修正して、各操作のリクエストボディに関連するJSONスキーマをOpenAPI仕様から読み取るようにします。

    WebSocket API

    Section titled “WebSocket API”

    Type Safe APIのWebSocket API（API GatewayとLambdaを使用したモデル駆動開発）の直接的な移行パスは残念ながらありませんが、いくつかのアイデアを提示します。

    非同期API向けに設計されたAsyncAPIの使用を検討できます。AsyncAPI NodeJSテンプレートで生成したNode WebSocketバックエンドをECSでホストできます。

    インフラストラクチャにはAppSync EventsとPowertoolsの使用を検討できます。関連ブログ記事が参考になります。

    AppSyncのWebSocket対応GraphQL APIも選択肢です。GitHubイシューで要望表明可能です。AppSync開発者ガイドとサンプルプロジェクトを参照してください。

    Type Safe APIと同じベンダー拡張を解釈するカスタムコードジェネレーターの作成も可能です。OpenAPIベースのカスタムジェネレーター構築についてはOpenAPIでモデル化されたAPIセクションを参照。API Gateway WebSocket API Lambdaハンドラーテンプレートとクライアントテンプレートを参考にできます。

    ts#trpc-apiジェネレーターへの移行も検討可能です（現時点ではサブスクリプション/ストリーミング未サポート）。関連GitHubイシューで要望表明可能です。

    Smithyはプロトコル非依存ですが、WebSocketプロトコルのサポートは未実装です。GitHubイシューを参照してください。

    Python/Javaでのインフラストラクチャ

    Section titled “Python/Javaでのインフラストラクチャ”

    PDKがサポートするPythonおよびJavaで記述されたCDKインフラストラクチャ。現時点ではNx Plugin for AWSではこれをサポートしていません。

    推奨される解決策としては、CDKインフラストラクチャをTypeScriptに移行するか、当社のジェネレータを使用して共通コンストラクトパッケージを目的の言語に移行する方法があります。Amazon Q CLIなどのGenerative AIを活用して、合成されたCloudFormationテンプレートが同一になるまでAIエージェントに移作業を反復させることが可能です。

    この原則はPythonやJavaで生成されるType Safe APIのインフラストラクチャにも適用されます。共通コンストラクトパッケージから汎用的なrest-api.tsコンストラクトを翻訳し、対象言語向けのシンプルなメタデータジェネレータを独自に実装できます（OpenAPIでモデル化されたAPIセクション参照）。

    Pythonプロジェクトのベースとしてpy#projectジェネレータを使用し、CDKコードを追加できます（cdk.jsonファイルを移行し、関連ターゲットを追加）。JavaプロジェクトにはNxの@nx/gradleプラグインを、Mavenには@jnxplus/nx-mavenを使用できます。

    Projenの使用

    Section titled “Projenの使用”

    PDKはProjenを基盤として構築されました。ProjenとNxジェネレータには根本的な違いがあるため、技術的には組み合わせることが可能ではあるものの、それはアンチパターンとなる可能性が高いです。Projenはプロジェクトファイルをコードとして管理するため直接編集ができませんが、Nxジェネレータはプロジェクトファイルを一度生成した後は自由にコードを変更できます。

    Projenの使用を継続したい場合、独自に目的のProjenプロジェクトタイプを実装できます。Nx Plugin for AWSのパターンに従うには、当社のジェネレータを実行するかGitHub上のソースコードを確認して目的のプロジェクトタイプがどのように構築されているかを把握し、Projenのプリミティブを使用して関連部分を実装することが可能です。

    AWS MCP サーバー用の Nx プラグインの紹介

    Jack
    Jack
    Senior Prototyping Engineer (AWS)

    ソフトウェア開発が急速に進化する中で、AIアシスタントはコーディングの旅路において貴重な協働者となりました。多くの開発者が「vibe-coding」と呼ぶ、人間の創造性とAI支援の協調的なダンスを受け入れています。あらゆる新興プラクティスと同様に、これは刺激的な利点と注目すべき課題の両方をもたらします。この記事では、AWS製品やサービスを扱う際のAI支援開発体験を強化するNx Plugin for AWS MCP Serverを紹介します。

    Vibe-codingの台頭

    Section titled “Vibe-codingの台頭”

    AIアシスタントと協調的にソフトウェアを構築するプラクティスであるvibe-codingは、多くの組織のソフトウェア開発アプローチを変革しました。構築したいものを説明すると、AIアシスタントがコードやテストの作成、ビルドコマンドの実行、協調的な反復を通じてビジョンを実現する手助けをします。

    この協調的アプローチにより、開発サイクルが大幅に加速されました。従来は手作業で数時間かかっていた複雑な実装が、数分で完了することも珍しくありません。

    Vibe-codingの課題

    Section titled “Vibe-codingの課題”

    利点がある一方で、vibe-codingには作業の流れを乱しフラストレーションを招く落とし穴があります。AIツールはプロジェクト全体で一貫性のないパターンを生成する可能性があり、将来的に保守上の問題を引き起こす可能性があります。具体的なガイダンスがない場合、AIは経験豊富な開発者が自然に組み込むAWS固有のベストプラクティスやセキュリティ考慮事項を見落とす可能性があります。

    明確なプロジェクト構造がない場合、AI支援によるコードは整理されず保守が困難になる可能性があります。AIは既存の解決策がある問題に対して独自の実装を作成し、不必要に車輪の再発明をする可能性があります。

    これらの課題は、単一フレームワークの範囲内ではなく、様々に相互接続するAWSサービスを扱う際に、技術的負債、セキュリティ脆弱性、フラストレーションを引き起こす可能性があります。

    AWS向けNxプラグイン

    Section titled “AWS向けNxプラグイン”

    Nx Plugin for AWSは、Nxモノレポツーリングを使用してAWSアプリケーションを構築するための構造化された基盤を提供します。白紙の状態から始める代わりに、プロジェクト構成の一貫したフレームワークを提供します。

    このプラグインは、一般的なプロジェクトタイプ向けのジェネレータを通じて一貫したプロジェクトスキャフォールディングを保証し、コードベース全体の構造的整合性を維持します。AWSのベストプラクティスに従う事前設定済みテンプレートを組み込むことで、開発者が一般的な落とし穴やセキュリティ問題を回避できるよう支援します。統合されたツーリングは、AWSアプリケーションのビルド、テスト、デプロイのための組み込みコマンドを提供し、ローカル開発サーバーを通じて開発ワークフローを効率化します。さらに、複雑なプロジェクト向けにNxの強力な依存関係管理を活用し、モノレポ管理を簡素化します。

    この構造を提供することで、Nx Plugin for AWSはAIアシスタントが作業する明確な枠組みを与えます。AIアシスタントがゼロからパターンを考案する代わりに、確立された規約に従うことで、より一貫性があり保守可能なコードベースが実現します。

    MCPサーバーによるAI機能強化

    Section titled “MCPサーバーによるAI機能強化”

    Model Context Protocol（MCP）は、AIアシスタントが外部ツールやリソースと相互作用するためのオープンスタンダードです。Nx Plugin for AWS MCPサーバーは、AWS向けNxプラグインに関する専門知識でAIアシスタントの機能を拡張します。

    MCPサーバーは、AWS開発に特化したベストプラクティス、利用可能なプロジェクト構造、実装パターンに関する文脈情報を提供します。AIツーリングがワークスペースを作成し、一般的なプロジェクトタイプをスキャフォールドするジェネレータを実行できるようにします。この文脈認識により、AIは確立されたパターンに沿ったより情報に基づいた提案を行い、一般的な落とし穴を回避できます。

    ベストプラクティスに沿わないコードや存在しない機能を参照する可能性のあるコードを生成する代わりに、AIアシスタントはMCPサーバーを活用してプロジェクトの基盤を構築できます。その結果、プロジェクトのコアコンポーネントの堅牢な基盤から始め、ビジネスロジックを埋めるためにAIを活用できる、より決定論的で信頼性の高い開発体験が実現します。

    はじめに

    Section titled “はじめに”

    構造化され信頼性の高いAI支援AWS開発を探求したい場合は、Nx Plugin for AWS MCP Serverをお試しください。以下のMCPサーバー設定で、お気に入りのAIアシスタント（Amazon Q Developer、Cline、Claude Codeなど）にセットアップできます：

    {
      "mcpServers": {
        "aws-nx-mcp": {
          "command": "npx",
          "args": ["-y", "-p", "@aws/nx-plugin", "aws-nx-mcp"]
        }
      }
    }

    詳細な手順については、AIによる構築ガイドを参照してください。

    @aws/nx-プラグインへようこそ

    Adrian
    Adrian
    Principal Software Engineer (AWS)
     Jack
    Jack
    Senior Prototyping Engineer (AWS)

    さあ、始まりました！🚀

    Nx Plugin for AWSは、フルスタックアプリケーションの構築とAWSへのデプロイを簡素化するツールキットを提供するNxプラグインです。開発者向けにアプリケーションコードとIaCコードの事前設定済みテンプレートを提供し、セットアップや設定に費やす時間を大幅に削減します。AWSサービスの統合に伴う複雑さを処理しつつ、カスタマイズの柔軟性を維持します。

    ユーザーは利用可能なジェネレーターリストから必要なコンポーネントを選択し、設定オプションを提供するだけで、@aws/nx-pluginが必要なスターターコードを生成します。このツールキットにはAPI、ウェブサイト、インフラストラクチャを作成するジェネレーターに加え、フロントエンドとバックエンドの統合（既存ファイルのAST変換による更新を含む！）やタイプセーフなクライアントの生成など、より高度な処理を行うジェネレーターも含まれています。

    ジェネレーター

    詳細については、プラグインの主要コンポーネントをすべて網羅し基本的な使い方を学べるダンジョンアドベンチャーチュートリアルから始めてください。

    皆様のフィードバックをお待ちしています。ディスカッションへの投稿やイシューの作成でご意見や今後の要望をお聞かせください！

    試してみる！