快速入门指南

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

提示

如需更深入的完整应用构建教程，请查看 地牢冒险教程。

前提条件

开始前需要安装以下全局依赖：

必需

• Git
• Node >= 22（推荐使用NVM管理Node版本）
  • 验证命令：node --version
• PNPM >= 10（也可使用Yarn >= 4、Bun >= 1或NPM >= 10）
  • 验证命令：pnpm --version、yarn --version、bun --version或npm --version
• UV >= 0.5.29
  1. 安装Python 3.12：uv python install 3.12.0
  2. 验证安装：uv python list --only-installed
• 配置到目标AWS账户的AWS凭证（应用将部署至该账户）

推荐

• 部分生成器需要Docker
• 选择Terraform替代CDK进行基础设施即代码时需安装Terraform >= 1.12
  • 验证命令：terraform --version
• 使用VSCode时推荐安装Nx Console VSCode插件

提示

若使用Amazon Q Developer、Cursor、Claude Code或Cline等AI助手，建议安装适用于AWS MCP服务器的Nx插件

步骤 1：初始化新的 Nx 工作区

运行以下命令使用您选择的包管理器创建 Nx 工作区：

pnpm

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

yarn

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

npm

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

bun

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

提示

系统会提示您选择基础设施即代码（IaC）提供商，可选 CDK 或 Terraform。您可以通过添加 --iacProvider 参数跳过提示：

CDK

pnpm

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

yarn

npx create-nx-workspace@21.4.1 my-project --pm=yarn  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

npm

npx create-nx-workspace@21.4.1 my-project --pm=npm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

bun

npx create-nx-workspace@21.4.1 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

Terraform

pnpm

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

yarn

npx create-nx-workspace@21.4.1 my-project --pm=yarn  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip

npm

npx create-nx-workspace@21.4.1 my-project --pm=npm  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip

bun

npx create-nx-workspace@21.4.1 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip

完成后进入项目目录：

cd my-project

步骤 2：使用生成器搭建项目框架

本快速入门指南将添加 tRPC API、React 网站、Cognito 身份验证和 CDK/Terraform 基础设施。根据项目类型，您可以选择任意组合的生成器快速启动项目。查看左侧导航栏的 指南 获取完整选项列表。

添加 tRPC API

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

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

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

这将在 packages/demo-api 目录下创建 API。

添加 React 网站

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

这将在 packages/demo-website 目录下创建新的 React 网站。

添加 Cognito 身份验证

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

连接前端与后端

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

添加基础设施

根据选择的 IaC 提供商添加基础设施项目：

CDK

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

这将配置用于在 AWS 上部署基础设施的 CDK 应用。

Terraform

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

这将配置用于在 AWS 上部署基础设施的 Terraform 项目。

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

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

pnpm

pnpm nx run demo-website:serve-local

yarn

yarn nx run demo-website:serve-local

npm

npx nx run demo-website:serve-local

bun

bunx nx run demo-website:serve-local

网站将运行在 http://localhost:4200。

对网站和 API 的修改将实时生效，本地服务器支持热重载。

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

CDK

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

import * as cdk from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from ':my-project/common-constructs';
import { Construct } from 'constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.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 并添加以下代码：

# 包含 @aws/nx-plugin 使用指标跟踪
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

# 部署用户身份
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

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

# 授予认证用户调用 API 的权限
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "允许认证用户调用 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
}

# 部署网站
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 nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

提示

如遇 lint 错误，可运行以下命令自动修复：

pnpm

pnpm nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

初始化基础设施：

CDK

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

提示

CDK 初始化需要在目标部署区域和 us-east-1 区域执行，以便部署网站的 AWS WAF WebACL。

Terraform

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

提示

Terraform 初始化会创建存储状态文件的 S3 存储桶，每个 AWS 账户/区域组合只需执行一次。

部署项目：

CDK

pnpm

pnpm nx run infra:deploy my-project-sandbox/*

yarn

yarn nx run infra:deploy my-project-sandbox/*

npm

npx nx run infra:deploy my-project-sandbox/*

bun

bunx nx run infra:deploy my-project-sandbox/*

Terraform

pnpm

pnpm nx run infra:apply

yarn

yarn nx run infra:apply

npm

npx nx run infra:apply

bun

bunx nx run infra:apply

提示

此命令会先执行 terraform plan 显示变更计划，然后应用变更部署基础设施。

步骤 5：测试已部署云资源的网站

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

   pnpm

   pnpm nx run demo-website:load:runtime-config

   yarn

   yarn nx run demo-website:load:runtime-config

   npm

   npx nx run demo-website:load:runtime-config

   bun

   bunx nx run demo-website:load:runtime-config

2. 启动本地网站服务器

   pnpm

   pnpm nx run demo-website:serve

   yarn

   yarn nx run demo-website:serve

   npm

   npx nx run demo-website:serve

   bun

   bunx nx run demo-website:serve

网站将运行在 http://localhost:4200，并指向已部署的 API 和身份验证资源。

---

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