Pular para o conteúdo

Guia de Início Rápido

Este guia orienta você pelos fundamentos de instalação e uso do @aws/nx-plugin para construir projetos rapidamente na AWS.

Pré-requisitos

As seguintes dependências globais são necessárias antes de prosseguir:

  • Git
  • Node >= 22 (Recomendamos usar algo como NVM para gerenciar versões do Node)
    • verifique executando node --version
  • PNPM >= 10 (também pode usar Yarn >= 4, Bun >= 1 ou NPM >= 10 se preferir)
    • verifique executando pnpm --version, yarn --version, bun --version ou npm --version
  • UV >= 0.5.29
    1. instale Python 3.12 executando: uv python install 3.12.0
    2. verifique com uv python list --only-installed
  • Credenciais da AWS configuradas para a sua conta AWS de destino (onde sua aplicação será implantada)
  • Se estiver usando VSCode, recomendamos instalar o Nx Console VSCode Plugin.

Passo 1: Inicializar um Novo Workspace Nx

Execute o seguinte comando para criar um workspace Nx com o gerenciador de pacotes de sua escolha:

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

Após a conclusão, navegue até o diretório do projeto:

Terminal window
cd my-project

Passo 2: Adicionar o Plugin Nx para AWS

Instale o plugin com:

Terminal window
pnpm add -Dw @aws/nx-plugin

Passo 3: Usar Geradores para Estruturar seu Projeto

Adicionaremos uma API tRPC, Website React, Autenticação Cognito e Infraestrutura CDK neste guia rápido. Dependendo do tipo de projeto, você pode escolher qualquer combinação de geradores para inicializar seu projeto rapidamente. Confira os Guias na barra de navegação à esquerda para ver a lista completa de opções.

Adicionar uma API tRPC

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - ts#trpc-api
  5. Preencha os parâmetros obrigatórios
    • apiName: demo-api
  6. Clique em Generate

Isso criará a API na pasta packages/demo-api.

Adicionar um Website React

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - ts#cloudscape-website
  5. Preencha os parâmetros obrigatórios
    • name: demo-website
  6. Clique em Generate

Isso gera um novo website React em packages/demo-website.

Adicionar Autenticação Cognito

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - ts#cloudscape-website#auth
  5. Preencha os parâmetros obrigatórios
    • project: @my-project/demo-website
    • cognitoDomain: my-demo
  6. Clique em Generate

Isso configura a infraestrutura necessária e o código React para adicionar Autenticação Cognito ao seu website.

Conectar Frontend ao Backend

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - api-connection
  5. Preencha os parâmetros obrigatórios
    • sourceProject: @my-project/demo-website
    • targetProject: @my-project/demo-api-backend
  6. Clique em Generate

Isso configura os provedores necessários para garantir que seu website possa chamar sua API tRPC.

Adicionar Infraestrutura CDK

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - ts#infra
  5. Preencha os parâmetros obrigatórios
    • name: infra
  6. Clique em Generate

Isso configura uma Aplicação CDK que você pode usar para implantar sua infraestrutura na AWS.

Passo 4: Definir Recursos Cloud e Implantar na AWS

Abra packages/infra/src/stacks/application-stack.ts e adicione o seguinte código:

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');
}
}

Este é todo o código CDK necessário para implantar nossa aplicação full-stack.

Compilar e Implantar a Infraestrutura

Em seguida, execute o seguinte comando para compilar seu projeto:

Terminal window
pnpm nx run-many --target build --all

Passo 5: Executar o Frontend Localmente

  1. Obter o arquivo runtime-config.json:

    Terminal window
    pnpm nx run @demo/demo-website:load:runtime-config
  2. Iniciar o servidor local do website

    Terminal window
    pnpm nx run @demo/demo-website:serve

Seu website estará disponível em http://localhost:4200.


Parabéns! 🎉 Você implantou com sucesso uma aplicação full-stack usando @aws/nx-plugin!