diff --git a/.vscode/settings.json b/.vscode/settings.json index 1471fb96..e9b55746 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,3 +1,25 @@ { - "eslint.validate": ["json"] + "eslint.validate": [ + "json" + ], + "workbench.colorCustomizations": { + "activityBar.activeBackground": "#93e6fc", + "activityBar.background": "#93e6fc", + "activityBar.foreground": "#15202b", + "activityBar.inactiveForeground": "#15202b99", + "activityBarBadge.background": "#fa45d4", + "activityBarBadge.foreground": "#15202b", + "commandCenter.border": "#15202b99", + "sash.hoverBorder": "#93e6fc", + "statusBar.background": "#61dafb", + "statusBar.foreground": "#15202b", + "statusBarItem.hoverBackground": "#2fcefa", + "statusBarItem.remoteBackground": "#61dafb", + "statusBarItem.remoteForeground": "#15202b", + "titleBar.activeBackground": "#61dafb", + "titleBar.activeForeground": "#15202b", + "titleBar.inactiveBackground": "#61dafb99", + "titleBar.inactiveForeground": "#15202b99" + }, + "peacock.color": "#61dafb" } diff --git a/docs/src/content/docs/assets/dungeon-game-architecture.png b/docs/src/content/docs/assets/dungeon-game-architecture.png index 0d2992f3..f03b864c 100644 Binary files a/docs/src/content/docs/assets/dungeon-game-architecture.png and b/docs/src/content/docs/assets/dungeon-game-architecture.png differ diff --git a/docs/src/content/docs/en/get_started/concepts.mdx b/docs/src/content/docs/en/get_started/concepts.mdx index 9314f6db..19f9efa6 100644 --- a/docs/src/content/docs/en/get_started/concepts.mdx +++ b/docs/src/content/docs/en/get_started/concepts.mdx @@ -1,6 +1,6 @@ --- title: Concepts -description: Key concepts. +description: Key concepts --- import { Image } from 'astro:assets'; @@ -9,9 +9,9 @@ import typeSafetyGif from '@assets/type-safety.gif'; import websiteGeneratorGif from '@assets/website-generator.gif'; import generatorsJpg from '@assets/generators.png'; -The `@aws/nx-plugin` is an [Nx](https://nx.dev/) plugin that provides a toolkit for simplifying the process of building and deploying full-stack applications on AWS. It provides developers with pre-configured templates for both application and IaC code, significantly reducing the time spent on setup and configuration. The plugin handles the complexity of AWS service integration while maintaining flexibility for customization. +The `@aws/nx-plugin` is an [Nx](https://nx.dev/) plugin that provides a toolkit for simplifying the process of building and deploying full-stack applications on AWS. It provides developers with pre-configured templates for both application and Infrastructure-as-Code (IaC) code, significantly reducing the time spent on setup and configuration. The plugin handles the complexity of AWS services integration while maintaining flexibility for customization. -Users simplify pick and choose which components they want from the list of available [Generators](#generators), provide any configuration options and have the `@aws/nx-plugin` generate the required starter code. Several generators exist within this toolkit which can create APIs, websites, infrastructure and even do more sophistacted things like integrated a frontend to a backend (including updating existing files via AST transforms!) with type-safe clients. +Users can pick and choose which components they want from the list of available [generators](#generators), provide any configuration options and have the `@aws/nx-plugin` generate the required starter code. You can use specific generators within this toolkit to create APIs, websites, infrastructure and sophistacted things like integrating a frontend with a backend (including updating existing files via Abstract Syntax Tree (AST) transforms) with type-safe clients. generator @@ -27,43 +27,44 @@ Together, these features make Nx particularly effective for managing monorepos a ## Generators -All components available in this plugin as implemented as [Generators](https://nx.dev/features/generate-code) which enable the automation of repetitive tasks and allow consistent scaffolding of both new and existing projects. +All components available in this plugin are implemented as [Generators](https://nx.dev/features/generate-code) which automate repetitive tasks and allow consistent scaffolding of both new and existing projects. -Generators can be invoked via the [Nx CLI](https://nx.dev/features/generate-code#invoke-generators) or the [Nx Console IDE plugin](https://nx.dev/getting-started/editor-setup). +You can invoke generators via the [Nx CLI](https://nx.dev/features/generate-code#invoke-generators) or the [Nx Console IDE plugin](https://nx.dev/getting-started/editor-setup). generators ## Open for modification -All code generated is your code, meaning it is free to be edited as you see fit. This drastically simplifies the developer experience as if you don't like something in the generated code, you are free to modify it. +All code generated is your code, meaning it is free to be edited as you see fit. This drastically simplifies the developer experience, as if you don't like something in the generated code, you are free to modify it. ## Minimal dependencies -The `@aws/nx-plugin` strives to keep the number of dependencies to a minimum and as such the global requirements for getting started boil down to what generators you invoke. +The `@aws/nx-plugin` strives to keep the number of dependencies to a minimum, so the global requirements for getting started depend on the generators you invoke. -As an example, any Typescript based generator will only require [Node](https://nodejs.org/en/download) to be installed. For Python based projects, [UV](https://docs.astral.sh/uv/) is the only requirement. +For example: + +- Any Typescript based generator will only require [Node](https://nodejs.org/en/download) to be installed. +- For Python based projects, [UV](https://docs.astral.sh/uv/) is the only requirement. ## Single version policy -The default monorepo setup uses a [single version policy](https://nx.dev/concepts/decisions/dependency-management#single-version-policy) for both Node and Python based project. +The default monorepo setup uses a [single version policy](https://nx.dev/concepts/decisions/dependency-management#single-version-policy) for both Node and Python based projects. -This means that all projects within your monorepo will be using the same version of dependencies by default, reducing issues related to packages in the same monorepo running into version mismatch issues. +This means that all projects within your monorepo use the same version of dependencies by default, reducing issues related to packages in the same monorepo running into version mismatch issues. -From a Node perspective this means a single lockfile at the root with a single `node_modules` containing all dependencies. If you need to add a new dependency, you do it in the root `package.json`. +For Node based projects, a single lockfile at the root with a single `node_modules` contains all dependencies. If you need to add a new dependency, add it in the root `package.json`. -From a Python perspective, this means a single `.venv` in the root of the monorepo with all dependencies installed into it. Each Python project however will have it's own `pyproject.toml`, but the versions of those dependencies are managed by the uv workspace and subsequently written out to the `uv.lock` file in the root. +For Python based projects, a single `.venv` in the root of the monorepo contains all dependencies installed into it. Each Python project however will have it's own `pyproject.toml`, but the versions of those dependencies are managed by the uv workspace and subsequently written out to the `uv.lock` file in the root. ## Type safety -The `@aws/nx-plugin` employs type-safety to simplify the developer experience via IDE completions, whilst also eliminating runtime errors which would only occur in a non type-safe implementation. As such, all components that are vended will be type-safe by default. +The `@aws/nx-plugin` uses type-safety to simplify the developer experience via IDE completions, whilst also eliminating runtime errors which would only occur in a non type-safe implementation. By default, all components that are vended are type-safe. generators diff --git a/docs/src/content/docs/en/get_started/quick-start.mdx b/docs/src/content/docs/en/get_started/quick-start.mdx index 4c881f7a..3f889bb4 100644 --- a/docs/src/content/docs/en/get_started/quick-start.mdx +++ b/docs/src/content/docs/en/get_started/quick-start.mdx @@ -10,25 +10,25 @@ import InstallCommand from '@components/install-command.astro'; import RunGenerator from '@components/run-generator.astro'; import NxCommands from '@components/nx-commands.astro'; -This guide walks you through the basics of installing and using `@aws/nx-plugin` to rapidly build projects on AWS. +This guide walks you through the basics of installing and using the `@aws/nx-plugin` to rapidly build projects on AWS. :::tip -For a more in-depth tutorial for building a full-stack application, check out the Dungeon Adventure Tutorial. +For an in-depth tutorial for building a full-stack application, refer to the Dungeon Adventure Tutorial. ::: ## Prerequisites -The following global dependencies are needed before proceeding: +Before proceeding, install these global dependencies: -## Step 1: Initialize a New Nx Workspace +## Step 1: Initialize a new Nx Workspace -Run the following command to create an Nx workspace with the package manager of your choice: +To create an Nx workspace with the package manager of your choice, run the following command : -Once complete, navigate to the project directory: +Navigate to the project directory: ```sh cd my-project @@ -36,13 +36,14 @@ cd my-project ## Step 2: Add the Nx Plugin for AWS -Install the plugin with: +Install the plugin using your package manager. ## Step 3: Use Generators to Scaffold your Project -We'll add a tRPC API, React Website, Cognito Authentication, and CDK Infrastructure in this quick-start guide. Depending on the type of project you're building, you can choose any combination of generators to quickly bootstrap your project. Check out the __Guides__ in the navigation bar to the left to see the full list of options. +For the purposes of this quick start guide, we will add a tRPC API, React website, Cognito authentication, and CDK infrastructure to our project. +Depending on the type of project you're building, you can choose any combination of generators to bootstrap your project. To see the full list of options, refer to the __Guides__ section in the navigation bar on the left. ### Add a tRPC API @@ -60,7 +61,7 @@ This scaffolds a new React website in `packages/demo-website`. -This sets up the necessary infrastructure and React code to add Cognito Authentication to your website. +This sets up the necessary infrastructure and React code to add Cognito authentication to your website. ### Connect Frontend to Backend @@ -74,7 +75,7 @@ This configures the necessary providers to ensure your website can call your tRP This configures a CDK App which you can use to deploy your infrastructure on AWS. -## Step 4: Define Cloud Resources and Deploy to AWS +## Step 4: Define Cloud resources and deploy to AWS Open `packages/infra/src/stacks/application-stack.ts` and add the following code: @@ -95,34 +96,33 @@ export class ApplicationStack extends cdk.Stack { } } ``` +__Note__: This is all the CDK we need to write to deploy our full stack application. -This is all the CDK we need to write to deploy our full stack application. +### Build and deploy the infrastructure -### Build and Deploy the Infrastructure - -Next, run the following command to build your project: +To build your project, run the following command: :::tip -If you encounter any lint errors, you can run the following command to automatically fix them. +If you encounter any lint errors, run the following command to automatically fix them. ::: -## Step 5: Run the Frontend Locally +## Step 5: Run the frontend locally -1. Fetch the `runtime-config.json` file: +1. Fetch the `runtime-config.json` file -2. Start the local website server +2. Start the local web server -Your website will be available at `http://localhost:4200`. +You can preview your website at `http://localhost:4200` in a browser. --- diff --git a/docs/src/content/docs/en/get_started/tutorials/dungeon-game/1.mdx b/docs/src/content/docs/en/get_started/tutorials/dungeon-game/1.mdx index 7b771a4b..04cb1a57 100644 --- a/docs/src/content/docs/en/get_started/tutorials/dungeon-game/1.mdx +++ b/docs/src/content/docs/en/get_started/tutorials/dungeon-game/1.mdx @@ -19,13 +19,16 @@ import nxGraphPng from '@assets/nx-graph.png' import gameSelectPng from '@assets/game-select.png' import gameConversationPng from '@assets/game-conversation.png' -## Module 1: Monorepo setup +## Module 1: Set up your Monorepo -We are going to start by creating a new monorepo. From within your desired directory, run the following command: +Start by creating a new monorepo. A monorepo is a single repository containing multiple distinct projects, with well-defined relationships. + +Within your desired directory, run the following command: -This will set up a NX monorepo within the `dungeon-adventure` directory which you can then open in vscode. It should look like the following: +This will set up a NX monorepo within the `dungeon-adventure` directory. +Open the directory in vscode. You will see the following file structure: - .nx/ @@ -45,29 +48,27 @@ This will set up a NX monorepo within the `dungeon-adventure` directory which yo - tsconfig.json -In order to start adding components from the `@aws/nx-plugin` into the monorepo, we need to install it as a dev dependency by running the following command from the root of the `dungeon-adventure` monorepo: +Before we add components from the `@aws/nx-plugin` into the monorepo, we need to install it as a dev dependency. +To do this, run the following command in the root of the `dungeon-adventure` monorepo: -Now we are ready to start creating our different sub-projects using the `@aws/nx-plugin`. +We are now ready to start creating our different sub-projects using the `@aws/nx-plugin`. - + -### Game API +### Generate the Game API -First let's create our Game API. To do this, let's create a tRPC API called `GameApi` by following the below steps: +We will start with creating our Game API. This API is used for managing the game state. +To do this, create a tRPC API called `GameApi` using these steps:
-You should see some new files have appeared in your file tree. +You will see new files appear in your file tree. - - - + Below is a list of all files which have been generated by the `ts#trpc-api` generator. We are going to examine some of the key files highlighted in the file tree: - packages/ @@ -124,7 +125,7 @@ Below is a list of all files which have been generated by the `ts#trpc-api` gene - vitest.workspace.ts -Taking a look at a few of the key files: +Let us look at these key files: ```ts {5,12} // packages/game-api/backend/src/router.ts @@ -151,7 +152,8 @@ export const handler = awsLambdaRequestHandler({ export type AppRouter = typeof appRouter; ``` -The router defines the entrypoint for your tRPC API and is the place where you will declare all of your API methods. As you can see above, we have a method called `echo` with it's implementation living in the `./procedures/echo.ts` file. +The router defines the entry oint for your tRPC API and is the place where you will declare all of your API methods. +We have a method called `echo` with it's implementation in the `./procedures/echo.ts` file. ```ts {2-5} // packages/game-api/backend/src/procedures/echo.ts @@ -167,9 +169,9 @@ export const echo = publicProcedure .query((opts) => ({ result: opts.input.message })); ``` -This file is the implementation of the `echo` method and as you can see is strongly typed by declaring its input and output data structures. It is importing these definitions from the `:dungeon-adventure/game-api-schema` project which is an [alias](https://www.typescriptlang.org/tsconfig/paths.html) for the schema project. +This file is the implementation of the `echo` method, which is strongly typed by declaring its input and output data structures. It imports these definitions from the `:dungeon-adventure/game-api-schema` project which is an [alias](https://www.typescriptlang.org/tsconfig/paths.html) for the schema project. - + ```ts // packages/game-api/schema/src/procedures/echo.ts @@ -188,7 +190,7 @@ export const EchoOutputSchema = z.object({ export type IEchoOutput = z.TypeOf; ``` -All tRPC schema definitions are defined using [Zod](https://zod.dev/) and are exported as typescript types via the `z.TypeOf` syntax. +All tRPC schema definitions are defined using [Zod](https://zod.dev/), and are exported as typescript types via the `z.TypeOf` syntax. ```ts // packages/common/constructs/src/app/http-apis/game-api.ts @@ -216,19 +218,25 @@ export class GameApi extends HttpApi { } ``` -This is the CDK construct that defines our GameApi. As you can see, it has already configured the handler file path to the generated bundle for our tRPC backend implementation. This means that at `cdk synth` time, bundling does not occur (opposed to using [NodeJsFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.NodejsFunction.html)) as we have already bundled it as part of the backend project's build target. +This is the CDK construct that defines our GameAPI. It has configured the handler file path to the generated bundle for our tRPC backend implementation, so that at `cdk synth` time, bundling does not occur (opposed to using [NodeJsFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.NodejsFunction.html)), as we have already bundled it as part of the backend project's build target. -### Story API + + +### Generate the Story API -Now let's create our Story API. To do this, let's create a Fast API called `StoryApi` by following the below steps: +Next, let's create our Story API using the FastAPI generator. The Story API is used with streaming responses for story generation, using Amazon Bedrock. +To do this, create a Fast API called `StoryApi` using these steps: -You should see some new files have appeared in your file tree. +You will see new files appear in your file tree. + -Below is a list of all files which have been generated by the `py#fast-api` generator. We are going to examine some of the key files highlighted in the file tree: +This is a list of all files which have been generated by the `py#fast-api` generator. Let us examine some of the key files highlighted in the file tree: - .venv/ single virtual env for monorepo - packages/ @@ -283,7 +291,7 @@ export class StoryApi extends HttpApi { } ``` -This is the CDK construct that defines our StoryApi. As you can see, it has already configured the handler file path to the generated bundle for our Fast API backend implementation. This means that at `cdk synth` time, bundling does not occur (opposed to [PythonFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-lambda-python-alpha.PythonFunction.html)) as we have already bundled it as part of the backend project's build target. +This is the CDK construct that defines our StoryApi. It configures the handler file path to the generated bundle for our Fast API backend implementation. This means that at `cdk synth` time, bundling does not occur (opposed to [PythonFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-lambda-python-alpha.PythonFunction.html)) as we have already bundled it as part of the backend project's build target. ```diff lang="ts" // packages/common/types/src/runtime-config.ts @@ -315,16 +323,17 @@ This is where all your API method will be defined. As you can see here, we have -### Game UI: Website +### Add the Game UI website -Now let's create the UI which will enable you to interact with the game. To do this, let's create a website called `GameUI` by following the below steps: +To interact with the game, create the UI using CloudScape website generator. +To do this, create a website called `GameUI` using these steps: -You should see some new files have appeared in your file tree. +You will see new files appear in your file tree. -Below is a list of all files which have been generated by the `ts#cloudscape-website` generator. We are going to examine some of the key files highlighted in the file tree: +Below is a list of all files which have been generated by the `ts#cloudscape-website` generator. Let us examine some of the key files highlighted in the file tree:: - packages/ - common/ @@ -443,16 +452,16 @@ A component which will be rendered when navigating to the `/welcome` route. `@ta -### Game UI: Auth +### Add Game UI authentication -Now let's configure our Game UI to require authenticated access via Amazon Cognito by following the below steps: +To configure our Game UI with authenticated access via Amazon Cognito, use these steps: -You should see some new files have appeared/changed in your file tree. +You will see new files appear in your file tree. -Below is a list of all files which have been generated/updated by the `ts#cloudscape-website#auth` generator. We are going to examine some of the key files highlighted in the file tree: +Below is a list of all files which have been generated/updated by the `ts#cloudscape-website#auth` generator. Let us examine some of the key files highlighted in the file tree: - packages/ - common/ @@ -510,20 +519,20 @@ root && ); ``` -The `RuntimeConfigProvider` and `CognitoAuth` components have been added to the `main.tsx` file via an AST transform. This allows the `CognitoAuth` component to authenticate with Amazon Cognito by fetching the `runtime-config.json` which contains the required cognito connection configuration in order to make the backend calls to the correct destination. +The `RuntimeConfigProvider` and `CognitoAuth` components have been added to the `main.tsx` file via an AST transform. This allows the `CognitoAuth` component to authenticate with Amazon Cognito by fetching the `runtime-config.json` which contains the required cognito connection configuration to make the backend calls to the correct destination. -### Game UI: Connect to Story API +### Configure Game UI to connect to the Story API -Now let's configure our Game UI to connect to our previously created Story API: +To configure our Game UI to connect to our previously created Story API, use these steps: -You should see some new files have appeared/changed in your file tree. +You will see new files appear in your file tree. -Below is a list of all files which have been generated/updated by the `api-connection` generator. We are going to examine some of the key files highlighted in the file tree: +Below is a list of all files which have been generated/updated by the `api-connection` generator. Let us examine some of the key files highlighted in the file tree: - packages/ - game-ui/ @@ -568,7 +577,7 @@ export const useStoryApi = (): StoryApi => { }; ``` -This hook can be used to make authenticated API requests to the `StoryApi`. As you can see in the implementation, it uses the `StoryApi` which is generated at build time and as such you will see an error in your IDE until we build our code. For more details on how the client is generated or how to consume the API, refer to the React to FastAPI guide. +You can use this hook to make authenticated API requests to the `StoryApi`. It uses the `StoryApi` which is generated at build time, and you will see an error in your IDE until we build our code. For more details on how the client is generated, or how to consume the API, refer to the React to FastAPI guide. ```tsx // packages/game-ui/src/components/StoryApiProvider.tsx @@ -607,16 +616,16 @@ The `src/generated/story-api/*.gen.ts` files should never be modified manually a -### Game UI: Connect to Game API +### Configure Game UI to connect to the Game API -Now let's configure our Game UI to connect to our previously created Game API: +To configure our Game UI to connect to our Game API, use these steps: You should see some new files have appeared/changed in your file tree. -Below is a list of all files which have been generated/updated by the `api-connection` generator. We are going to examine some of the key files highlighted in the file tree: +Below is a list of all files which have been generated/updated by the `api-connection` generator. Let us examine some of the key files highlighted in the file tree: - packages/ - game-ui/ @@ -641,7 +650,7 @@ import { TrpcApis } from '../components/TrpcClients'; export const useGameApi = () => TrpcApis.GameApi.useTRPC(); ``` -This hook uses tRPC's latest [React Query integration](https://trpc.io/blog/introducing-tanstack-react-query-client) allowing user's to interact with `@tanstack/react-query` directly without any additional layers of abstraction. For examples on how to call tRPC APIs, refer to the using the tRPC hook guide. +This hook uses tRPC's latest [React Query integration](https://trpc.io/blog/introducing-tanstack-react-query-client) allowing users to interact with `@tanstack/react-query` directly without any additional layers of abstraction. For examples on how to call tRPC APIs, refer to the using the tRPC hook guide.