快速入门指南

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

全栈教程

如需更深入的全栈应用程序构建教程，请查看 Dungeon Adventure 教程。

前置条件

在继续之前，需要以下全局依赖项：

必需

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

推荐

• PNPM >= 11（如果你愿意，也可以使用 Yarn >= 4、Bun >= 1 或 NPM >= 10）
  • 通过运行 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。

AI 助手设置

如果您使用 AI 助手，例如 Kiro、Kiro CLI、Cursor、Claude Code 或 Cline，您可能还希望安装 Nx Plugin for AWS MCP 服务器。

步骤 1：初始化一个新的 Nx 工作空间

运行以下命令，使用您选择的包管理器创建一个 Nx 工作空间：

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

选择 IaC 提供商

系统将提示您选择首选的基础设施即代码（IaC）提供商，可以是 CDK 或 Terraform。您可以通过使用 --iac 运行命令来跳过提示，例如：

CDK

pnpm

pnpm create @aws/nx-workspace my-project --iac=cdk

yarn

yarn create @aws/nx-workspace my-project --iac=cdk

npm

npm create @aws/nx-workspace -- my-project --iac=cdk

bun

bun create @aws/nx-workspace my-project --iac=cdk

Terraform

pnpm

pnpm create @aws/nx-workspace my-project --iac=terraform

yarn

yarn create @aws/nx-workspace my-project --iac=terraform

npm

npm create @aws/nx-workspace -- my-project --iac=terraform

bun

bun create @aws/nx-workspace my-project --iac=terraform

完成后，导航到项目目录：

cd my-project

步骤 2：使用生成器搭建您的项目

在本快速入门指南中，我们将添加一个 tRPC API、React 网站、Cognito 身份验证以及 CDK 或 Terraform 基础设施。根据您正在构建的项目类型，您可以选择任意生成器组合来快速启动您的项目。查看左侧导航栏中的 生成器 以查看完整的选项列表，或尝试使用 图形构建器 以可视化方式构建您的工作空间。

作为快捷方式，您可以使用下面的按钮复制命令来搭建完整的应用程序。

Loading the diagram…

使用 AI 构建

Nx Plugin for AWS MCP Server 已在您的工作空间中配置，因此您可以要求您喜欢的 AI 编码代理（如 Kiro 或 Claude）为您构建这些项目，而无需自己输入 CLI 命令。

否则，请按照以下步骤自行运行每个生成器。

添加 tRPC API

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

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

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

VSCode

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

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

添加 React 网站

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

npm

npx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

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

pnpm

pnpm nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

VSCode

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

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

添加 Cognito 身份验证

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

npm

npx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

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

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

VSCode

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

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

连接前端到后端

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

yarn

yarn nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

npm

npx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

bun

bunx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

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

pnpm

pnpm nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

VSCode

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

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

添加基础设施

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

CDK

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

VSCode

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 应用程序，您可以使用它在 AWS 上部署基础设施。

Terraform

CLI

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

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

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

VSCode

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

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

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

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

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

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

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

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

CDK

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

import { Stack, StackProps } from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from '@my-project/common-constructs';
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 并添加以下代码：

# Include metrics tracking for @aws/nx-plugin usage
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

# 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]
}

这就是我们部署全栈应用程序所需编写的全部 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

引导您的基础设施：

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。

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 和身份验证部署的资源。

---

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