快速入门指南

本指南将引导您完成安装和使用 @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 账户（应用部署环境）
• 使用 VSCode 时推荐安装 Nx Console VSCode 插件

步骤 1: 初始化新 Nx 工作区

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

pnpm

npx create-nx-workspace@~20.6.3 my-project --pm=pnpm --preset=ts --ci=skip --formatter=prettier

yarn

npx create-nx-workspace@~20.6.3 my-project --pm=yarn --preset=ts --ci=skip --formatter=prettier

npm

npx create-nx-workspace@~20.6.3 my-project --pm=npm --preset=ts --ci=skip --formatter=prettier

bun

npx create-nx-workspace@~20.6.3 my-project --pm=bun --preset=ts --ci=skip --formatter=prettier

完成后进入项目目录：

cd my-project

步骤 2: 添加 AWS Nx 插件

通过以下命令安装插件：

pnpm

pnpm add -Dw @aws/nx-plugin

yarn

yarn add -D @aws/nx-plugin

npm

npm install --legacy-peer-deps -D @aws/nx-plugin

bun

bun install -D @aws/nx-plugin

步骤 3: 使用生成器搭建项目结构

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

添加 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. 填写必需参数
   • apiName: demo-api
6. 点击 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api

npm

npx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api

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

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api --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#cloudscape-website
5. 填写必需参数
   • name: demo-website
6. 点击 Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#cloudscape-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#cloudscape-website#auth
5. 填写必需参数
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. 点击 Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#cloudscape-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-backend
6. 点击 Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

添加 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

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

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

打开 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');
    api.grantInvokeAccess(identity.identityPool.authenticatedRole);

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

这是部署全栈应用所需的所有 CDK 代码。

构建并部署基础设施

运行以下命令构建项目：

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

步骤 5: 本地运行前端

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

   pnpm

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

   yarn

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

   npm

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

   bun

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

2. 启动本地网站服务器

   pnpm

   pnpm nx run @demo/demo-website:serve

   yarn

   yarn nx run @demo/demo-website:serve

   npm

   npx nx run @demo/demo-website:serve

   bun

   bunx nx run @demo/demo-website:serve

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

---

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