快速入门指南

本指南将引导您了解安装和使用 @aws/nx-plugin 在 AWS 上快速构建项目的基础知识。

前置条件

在继续之前,需要以下全局依赖项:

必需

• Git
• Node >= 22（我们建议使用类似 NVM 的工具来管理您的 node 版本）
  • 通过运行 node --version 来验证
• UV >= 0.5.29
  1. 通过运行以下命令安装 Python 3.14：uv python install 3.14
  2. 使用 uv python list --only-installed 验证

推荐

• PNPM >= 11（如果你愿意，也可以使用 Yarn >= 4、Bun >= 1 或 NPM >= 11）
  • 通过运行 pnpm --version、yarn --version、bun --version 或 npm --version 来验证
• 需要配置指向目标 AWS 账户的 AWS Credentials 来部署你的应用程序（以及用于某些本地开发工作流）。
• 某些生成器需要 Docker 或 Finch >= 1.6.0。对于 Docker，必须设置多平台构建；Finch 开箱即支持多平台构建。
• 如果你选择使用 Terraform >= 1.12 作为基础设施即代码工具而不是 CDK，则需要安装它
  • 通过运行 terraform --version 来验证
• 如果你正在使用 VSCode，我们建议安装 Nx Console VSCode Plugin。

步骤 1:创建工作空间

使用您选择的包管理器创建一个 Nx 工作空间,并打开它创建的目录:

创建工作区@aws/nx-workspace

pnpm

$ pnpm create @aws/nx-workspace my-project

yarn

$ yarn create @aws/nx-workspace my-project

npm

$ npm create @aws/nx-workspace -- my-project

bun

$ bun create @aws/nx-workspace my-project

构建你的命令3

workspace必需

iac

cdkterraform

containers

inferdockerfinch

cd my-project

系统会提示您选择基础设施即代码提供商,CDK 或 Terraform。

步骤 2:构建您的应用程序

我们将构建一个全栈应用程序:一个 tRPC API、一个 React 网站、Cognito 身份验证以及 CDK 或 Terraform 基础设施。您可以让 AI 助手为您搭建脚手架,或者自己运行生成器——两种方式都能达到相同的工作空间。

使用 AI

1. 在您的 AI 编码助手中打开工作空间。

   新工作空间已经为 Kiro、Claude Code、Cursor、Gemini CLI、GitHub Copilot 和 OpenAI Codex 配置了插件的 MCP server,因此您的助手可以查找插件的生成器并运行它们,无需任何设置。

2. 请求应用程序:

   Prompt

   Create a tRPC API called demo-api, and a React website called demo-website. Add Cognito authentication to the website, connect the website to the API, and add an infrastructure project called infra. Then instantiate the generated infrastructure components so the website and API deploy, granting authenticated users access to the API.

   您的助手通过 MCP server 发现生成器并按照依赖关系所需的顺序运行它们。查看它所做的更改,然后继续步骤 3。

使用 CLI

运行搭建应用程序的生成器。使用下面的按钮复制所有命令,或者按照图表下方的说明自己运行每个命令。

CDK

Loading the diagram…

Terraform

Loading the diagram…

根据您正在构建的项目类型,您可以选择任意生成器组合来快速启动您的项目。查看左侧导航栏中的 生成器 以查看完整的选项列表,或尝试使用 图形构建器 以可视化方式构建您的工作空间。

添加 tRPC API

运行此生成器@aws/nx-plugin:ts#api

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#api --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#api --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#api --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#api --no-interactive

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#api
5. 填写必需参数
6. 点击 Generate

此步骤的选项2

name必需

framework

trpc

--dry-run您还可以执行试运行以查看哪些文件会被更改

这将在 packages/demo-api 文件夹中创建 API。

添加 React 网站

运行此生成器@aws/nx-plugin:ts#website

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website --no-interactive

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#website
5. 填写必需参数
6. 点击 Generate

此步骤的选项1

name必需

--dry-run您还可以执行试运行以查看哪些文件会被更改

这将在 packages/demo-website 中搭建一个新的 React 网站。

添加 Cognito 身份验证

运行此生成器@aws/nx-plugin:ts#website#auth

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website#auth --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website#auth --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website#auth --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website#auth --no-interactive

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#website#auth
5. 填写必需参数
6. 点击 Generate

此步骤的选项1

project必需

--dry-run您还可以执行试运行以查看哪些文件会被更改

这将设置必要的基础设施和 React 代码,以便为您的网站添加 Cognito 身份验证。

连接前端到后端

运行此生成器@aws/nx-plugin:connection

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:connection --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:connection --no-interactive

npm

$ npx nx g @aws/nx-plugin:connection --no-interactive

bun

$ bunx nx g @aws/nx-plugin:connection --no-interactive

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - connection
5. 填写必需参数
6. 点击 Generate

此步骤的选项2

sourceProject必需

targetProject必需

--dry-run您还可以执行试运行以查看哪些文件会被更改

这将配置必要的提供程序,以确保您的网站可以调用您的 tRPC API。

添加基础设施

根据您选择的 IAC 提供商添加基础设施项目。

CDK

运行此生成器@aws/nx-plugin:ts#infra

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#infra --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#infra --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#infra --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#infra --no-interactive

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#infra
5. 填写必需参数
6. 点击 Generate

此步骤的选项1

name必需

--dry-run您还可以执行试运行以查看哪些文件会被更改

这将配置一个 CDK 应用程序,您可以使用它在 AWS 上部署基础设施。

Terraform

运行此生成器@aws/nx-plugin:terraform#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:terraform#project --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:terraform#project --no-interactive

npm

$ npx nx g @aws/nx-plugin:terraform#project --no-interactive

bun

$ bunx nx g @aws/nx-plugin:terraform#project --no-interactive

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - terraform#project
5. 填写必需参数
6. 点击 Generate

此步骤的选项1

name必需

--dry-run您还可以执行试运行以查看哪些文件会被更改

这将配置一个 Terraform 项目,您可以使用它在 AWS 上部署基础设施。

步骤 3:在本地运行您的网站和 API

使用以下命令为您的网站及其连接的 API 启动本地开发服务器:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

您的网站将在 http://localhost:4200 上可用。

对网站和 API 的更改都将实时反映,因为本地网站和 API 服务器都将热重载。

试试看:从您的网站调用 API

步骤 4:定义云资源并部署到 AWS

CDK

打开 packages/infra/src/stacks/application-stack.ts 并添加以下代码:

import {
  DemoApi,
  DemoWebsite,
  UserIdentity,
} from '@my-project/common-constructs';
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const identity = new UserIdentity(this, 'identity');
    const api = new DemoApi(this, 'api', {
      integrations: DemoApi.defaultIntegrations(this).build(),
    });
    api.grantInvokeAccess(identity.identityPool.authenticatedRole);

    new DemoWebsite(this, 'website');
  }
}

这就是我们部署全栈应用程序所需编写的全部 CDK 代码。

Terraform

打开 packages/infra/src/main.tf 并添加以下代码:

# Deploy user identity
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# Shared asset bucket — stages Lambda deployment zips for every lambda / API module
module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Deploy API
module "demo_api" {
  source = "../../common/terraform/src/app/apis/demo-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Grant authenticated users access to invoke the API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "Policy to allow authenticated users to invoke the API"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = "execute-api:Invoke"
        Resource = "${module.demo_api.api_execution_arn}/*/*"
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_api_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

# Deploy website
provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}

module "demo_website" {
  source = "../../common/terraform/src/app/static-websites/demo-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  depends_on = [module.user_identity, module.demo_api]
}

# Print the website URL and user pool id when the deployment finishes
output "website_url" {
  value = module.demo_website.website_url
}

output "user_pool_id" {
  value = module.user_identity.user_pool_id
}

这就是我们部署全栈应用程序所需编写的全部 Terraform 代码。

构建和部署基础设施

接下来,运行以下命令来构建您的项目:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

修复 Lint 和格式化错误

如果遇到任何 lint 或格式化错误,您可以运行以下命令自动修复它们。

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

The workspace is out of sync

如果构建报告 The workspace is out of sync,请接受提示以同步工作空间,或在重试构建之前直接运行以下同步命令:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

这将写入您的导入所需的 TypeScript 项目引用和 package.json 依赖项条目。

引导您的基础设施:

CDK

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

引导区域

CDK 引导对于您的目标部署 AWS 区域和 us-east-1 都是必需的,以允许为网站部署 AWS WAF WebACL。如果您要部署到其他地方,也请引导 us-east-1:

pnpm

pnpm nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

yarn

yarn nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

npm

npx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

bun

bunx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

Terraform

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

一次性设置

Terraform 引导会创建一个 S3 存储桶来存储您的 Terraform 状态文件。每个 AWS 账户/区域组合只需执行一次。

部署您的项目:

CDK

pnpm

pnpm nx deploy-sandbox infra

yarn

yarn nx deploy-sandbox infra

npm

npx nx deploy-sandbox infra

bun

bunx nx deploy-sandbox infra

Terraform

pnpm

pnpm nx apply infra

yarn

yarn nx apply infra

npm

npx nx apply infra

bun

bunx nx apply infra

应用前计划

此命令将首先运行 terraform plan 以显示将进行的更改,然后应用这些更改以部署您的基础设施。

步骤 5:使用已部署的云资源测试网站

1. 获取 runtime-config.json 文件:

   pnpm

   pnpm nx load-runtime-config demo-website

   yarn

   yarn nx load-runtime-config demo-website

   npm

   npx nx load-runtime-config demo-website

   bun

   bunx nx load-runtime-config demo-website

2. 启动本地网站服务器

   pnpm

   pnpm nx serve demo-website

   yarn

   yarn nx serve demo-website

   npm

   npx nx serve demo-website

   bun

   bunx nx serve demo-website

您的网站将在 http://localhost:4200 上可用,并将指向您为 API 和身份验证部署的资源。

要登录,您需要在 Cognito 用户池中创建用户。

点击此处查看使用 AWS CLI 的说明

您的网站也通过 CloudFront 提供服务。打开其分发域名(在部署后打印到您的终端)以使用完全在 AWS 上运行的版本。

恭喜!🎉 您已成功使用 @aws/nx-plugin 构建并部署了一个全栈应用程序!

步骤 6:清理

完成后,删除您部署的资源以避免持续产生费用:

CDK

pnpm

pnpm nx destroy-sandbox infra

yarn

yarn nx destroy-sandbox infra

npm

npx nx destroy-sandbox infra

bun

bunx nx destroy-sandbox infra

保留的资源

Cognito 用户池在创建时启用了删除保护,因此它不会被自动删除。如果您不再需要它(以及 Cognito 用于发送短信的 IAM 角色),请手动删除它们。

Terraform

pnpm

pnpm nx destroy infra

yarn

yarn nx destroy infra

npm

npx nx destroy infra

bun

bunx nx destroy infra

保留的资源

Cognito 用户池在创建时启用了删除保护,因此它不会被自动删除(destroy 命令将报告失败)。如果您不再需要它(以及 Cognito 用于发送短信的 IAM 角色),请手动删除它们。

要删除引导资源,请按照以下步骤操作:

CDK

删除您引导的每个区域(包括 us-east-1)中的引导堆栈。这将删除引导角色和容器镜像存储库:

aws cloudformation delete-stack --stack-name CDKToolkit --region <region>

资产存储桶

资产存储桶是有意保留的,因此需要单独删除。

Terraform

pnpm

pnpm nx bootstrap-destroy infra

yarn

yarn nx bootstrap-destroy infra

npm

npx nx bootstrap-destroy infra

bun

bunx nx bootstrap-destroy infra

您的 Terraform 状态也会被删除

这会清空并删除保存您的 Terraform 状态的 S3 存储桶,因此仅在您拆除所有已部署的基础设施后才运行它。

---

下一步

• Dungeon Adventure 教程 — 构建一个全栈 AI 地牢冒险游戏,获得比本指南更深入的演练。
• 工作空间 — 了解工作空间的布局以及生成器共享的配置。
• 添加到现有项目 — 在您现有的代码库中采用该插件。