@aws/nx-plugin-mcp 1.0.0-rc.37 → 1.0.0-rc.39

package/docs/get_started/tutorials/contribute-generator.mdx

@@ -0,0 +1,405 @@
+---
+title: Contribute a Generator
+description: A walkthrough of how to build a generator using the @aws/nx-plugin.
+---
+
+import {
+  Aside,
+  Code,
+  FileTree,
+  Steps,
+  Tabs,
+  TabItem,
+} from '@astrojs/starlight/components';
+import { Image } from 'astro:assets';
+import Drawer from '@components/drawer.astro';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import LinkCommand from '@components/link-command.astro';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
+import InstallCommand from '@components/install-command.astro';
+import dungeonAdventureArchitecturePng from '@assets/dungeon-game-architecture.png';
+import baselineWebsitePng from '@assets/baseline-website.png';
+import baselineGamePng from '@assets/baseline-game.png';
+import nxGraphPng from '@assets/nx-graph.png';
+import gameSelectPng from '@assets/game-select.png';
+import gameConversationPng from '@assets/game-conversation.png';
+
+:::tip[Learning By Example]
+This tutorial guides you through contributing a generator to the Nx Plugin for AWS with a practical example. It can also serve as useful reference for ways to think about and test generators. You can skip to the general guidance section for some top tips for working on generators.
+:::
+
+Let's create a new generator to contribute to `@aws/nx-plugin`. Our objective will be to generate a new procedure for a tRPC API.
+
+### Check Out the Plugin
+
+First, let's clone the plugin:
+
+```bash
+git clone git@github.com:awslabs/nx-plugin-for-aws.git
+```
+
+Next, install and build:
+
+```bash
+cd nx-plugin-for-aws
+pnpm i
+pnpm nx run-many --target build --all
+```
+
+### Create an Empty Generator
+
+Let's create the new generator in `packages/nx-plugin/src/trpc/procedure`.
+
+We provide a generator for creating new generators so you can quickly scaffold your new generator! You can run this generator as follows:
+
+<RunGenerator generator="ts#nx-generator" requiredParameters={{ pluginProject: '@aws/nx-plugin', name: 'ts#trpc-api#procedure', directory: 'trpc/procedure', description: 'Adds a procedure to a tRPC API' }} />
+
+You will notice the following files have been generated for you:
+
+<FileTree>
+  - packages/nx-plugin/src/trpc/procedure
+    - schema.json Defines the input for the generator
+    - schema.d.ts A typescript interface which matches the schema
+    - generator.ts Function which Nx runs as the generator
+    - generator.spec.ts Tests for the generator
+  - docs/src/content/docs/guides/
+    - trpc-procedure.mdx Documentation for the generator
+  - packages/nx-plugin/generators.json Updated to include the generator
+</FileTree>
+
+Let's update the schema to add the properties we'll need for the generator:
+
+<Tabs>
+  <TabItem label="schema.json">
+    ```json
+    {
+      "$schema": "https://json-schema.org/schema",
+      "$id": "tRPCProcedure",
+      "title": "Adds a procedure to a tRPC API",
+      "type": "object",
+      "properties": {
+        "project": {
+          "type": "string",
+          "description": "tRPC API project",
+          "x-prompt": "Select the tRPC API project to add the procedure to",
+          "x-dropdown": "projects",
+          "x-priority": "important"
+        },
+        "procedure": {
+          "description": "The name of the new procedure",
+          "type": "string",
+          "x-prompt": "What would you like to call your new procedure?",
+          "x-priority": "important",
+        },
+        "type": {
+          "description": "The type of procedure to generate",
+          "type": "string",
+          "x-prompt": "What type of procedure would you like to generate?",
+          "x-priority": "important",
+          "default": "query",
+          "enum": ["query", "mutation"]
+        }
+      },
+      "required": ["project", "procedure"]
+    }
+    ```
+  </TabItem>
+  <TabItem label="schema.d.ts">
+    ```ts
+    export interface TrpcProcedureSchema {
+      project: string;
+      procedure: string;
+      type: 'query' | 'mutation';
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+:::note[Virtual File System]
+Notice the generator is given a `Tree` as input, as well as the options we defined in our schema. The `Tree` is essentially a virtual file system which we can read from and write to in order to create or update project files. We don't want to touch the filesystem directly, as we don't want to make any changes if users run the generator in "dry-run" mode.
+:::
+
+You will notice the generator has already been hooked up in `packages/nx-plugin/generators.json`:
+
+```json
+ ...
+  "generators": {
+    ...
+    "ts#trpc-api#procedure": {
+      "factory": "./src/trpc/procedure/generator",
+      "schema": "./src/trpc/procedure/schema.json",
+      "description": "Adds a procedure to a tRPC API"
+    }
+  },
+...
+```
+
+### Implement the Generator
+
+To add a procedure to a tRPC API, we need to do two things:
+
+1. Create a TypeScript file for the new procedure
+2. Add the procedure to the router
+
+#### Create the new Procedure
+
+To create the TypeScript file for the new procedure, we'll use a utility called `generateFiles`. Using this, we can define an [EJS](https://ejs.co/) template which we can render in our generator with variables based on the options selected by the user.
+
+First, we'll define the template in `packages/nx-plugin/src/trpc/procedure/files/procedures/__procedureNameKebabCase__.ts.template`:
+
+```ts title="files/procedures/__procedureNameKebabCase__.ts.template"
+import { publicProcedure } from '../init.js';
+import { z } from 'zod';
+
+export const <%- procedureNameCamelCase %> = publicProcedure
+  .input(z.object({
+    // TODO: define input
+  }))
+  .output(z.object({
+    // TODO: define output
+  }))
+  .<%- procedureType %>(async ({ input, ctx }) => {
+    // TODO: implement!
+    return {};
+  });
+```
+
+:::tip[Template Substitutions]
+When `generateFiles` consumes the template, it will replace references to `__<variable>__` in file/directory names with the values it's provided, as well as stripping the `.template` from the file name.
+
+The template content is [EJS](https://ejs.co/), where variables are referenced using the `<% ... %>` syntax.
+:::
+
+In the template, we referenced three variables:
+
+- `procedureNameCamelCase`
+- `procedureNameKebabCase`
+- `procedureType`
+
+So we'll need to make sure we pass those to `generateFiles`, as well as the directory to generate files into, namely the location of source files (i.e. `sourceRoot`) for the tRPC project the user selected as input for the generator, which we can extract from the project configuration.
+
+Let's update the generator to do that:
+
+```ts title="procedure/generator.ts" {8-19}
+import {
+  generateFiles,
+  joinPathFragments,
+  readProjectConfiguration,
+  type Tree,
+} from '@nx/devkit';
+import type { TrpcProcedureSchema } from './schema.js';
+import { formatFilesInSubtree } from '../../utils/format';
+import camelCase from 'lodash.camelcase';
+import kebabCase from 'lodash.kebabcase';
+
+export const trpcProcedureGenerator = async (
+  tree: Tree,
+  options: TrpcProcedureSchema,
+) => {
+  const projectConfig = readProjectConfiguration(tree, options.project);
+
+  const procedureNameCamelCase = camelCase(options.procedure);
+  const procedureNameKebabCase = kebabCase(options.procedure);
+
+  generateFiles(
+    tree,
+    joinPathFragments(import.meta.dirname, 'files'),
+    projectConfig.sourceRoot,
+    {
+      procedureNameCamelCase,
+      procedureNameKebabCase,
+      procedureType: options.type,
+    },
+  );
+
+  await formatFilesInSubtree(tree);
+};
+
+export default trpcProcedureGenerator;
+```
+
+:::tip[File Formatting]
+We also called `formatFilesInSubtree` at the end of the generator, which ensures that any files we create or modify are formatted according to the workspace's [Biome](https://biomejs.dev/) configuration.
+:::
+
+#### Add the Procedure to the Router
+
+Next, we want the generator to hook up the new procedure to the router. This means reading and updating the user's source code!
+
+We use [GritQL](https://docs.grit.io/) to declaratively search and transform source code. The `addDestructuredImport` helper adds named imports, and `applyGritQL` applies a GritQL pattern to add the procedure to the router's object literal.
+
+```ts title="procedure/generator.ts" {6, 23-36}
+import {
+  generateFiles,
+  joinPathFragments,
+  readProjectConfiguration,
+  type Tree,
+} from '@nx/devkit';
+import type { TrpcProcedureSchema } from './schema.js';
+import { formatFilesInSubtree } from '../../utils/format';
+import camelCase from 'lodash.camelcase';
+import kebabCase from 'lodash.kebabcase';
+import { addDestructuredImport, applyGritQL } from '../../utils/ast';
+
+export const trpcProcedureGenerator = async (
+  tree: Tree,
+  options: TrpcProcedureSchema,
+) => {
+  const projectConfig = readProjectConfiguration(tree, options.project);
+
+  const procedureNameCamelCase = camelCase(options.procedure);
+  const procedureNameKebabCase = kebabCase(options.procedure);
+
+  generateFiles(
+    tree,
+    joinPathFragments(import.meta.dirname, 'files'),
+    projectConfig.sourceRoot,
+    {
+      procedureNameCamelCase,
+      procedureNameKebabCase,
+      procedureType: options.type,
+    },
+  );
+
+  const routerPath = joinPathFragments(projectConfig.sourceRoot, 'router.ts');
+
+  await addDestructuredImport(
+    tree,
+    routerPath,
+    [procedureNameCamelCase],
+    `./procedures/${procedureNameKebabCase}.js`,
+  );
+
+  await applyGritQL(
+    tree,
+    routerPath,
+    `\`router({ $props })\` => \`router({ $props, ${procedureNameCamelCase} })\` where { $props <: not contains \`${procedureNameCamelCase}\` }`,
+  );
+
+  await formatFilesInSubtree(tree);
+};
+
+export default trpcProcedureGenerator;
+```
+
+:::tip[GritQL Patterns]
+In the above code snippet, `applyGritQL` uses a [GritQL](https://docs.grit.io/) pattern to find the `router({ ... })` call and add the new procedure to its object literal. The `where` clause ensures idempotency — if the procedure is already present, no change is made.
+
+You can try out GritQL patterns in the [GritQL Playground](https://docs.grit.io/playground), or install the GritQL CLI to test patterns locally:
+
+```bash
+npm install -g @getgrit/cli
+grit apply '`router({ $props })` => `router({ $props, myProcedure })`' --dry-run
+```
+:::
+
+Now that we've implemented the generator, let's compile it to make sure it's available for us to test it out in our dungeon adventure project.
+
+```bash
+pnpm nx compile @aws/nx-plugin
+```
+
+### Testing the Generator
+
+To test the generator, we'll link our local Nx Plugin for AWS to an existing codebase.
+
+#### Create a Test Project with a tRPC API
+
+:::note[Using Your Own Project]
+If you have completed the <Link path="get_started/tutorials/dungeon_game/overview">dungeon adventure tutorial</Link>, or already have another existing Nx workspace which uses a tRPC API, you can skip this step.
+:::
+
+In a separate directory, create a new test workspace:
+
+<CreateNxWorkspaceCommand workspace="trpc-generator-test" />
+
+Next, let's generate a tRPC API to add the procedure to:
+
+<RunGenerator generator="ts#api" requiredParameters={{name:"test-api", framework:"trpc"}} noInteractive />
+
+#### Link our local Nx Plugin for AWS
+
+In your codebase, let's link our local `@aws/nx-plugin`:
+
+<LinkCommand
+  dependency="@aws/nx-plugin"
+  dependencyPath="path/to/nx-plugin-for-aws/dist/packages/nx-plugin"
+  projectPath="path/to/trpc-generator-test"
+/>
+
+:::note[Compiled Plugin Path]
+Notice above we linked to the compiled plugin in `dist/packages/nx-plugin` rather than the source code.
+:::
+
+#### Run the new Generator
+
+Let's try the new generator:
+
+<RunGenerator generator="ts#trpc-api#procedure" />
+
+:::note[Generator Not Showing]
+If you don't see the new generator in the list in VSCode, you might need to refresh the Nx workspace:
+
+<NxCommands commands={['reset']} />
+:::
+
+If successful, we should have generated a new procedure and added the procedure to our router in `router.ts`.
+
+### Exercises
+
+If you've got this far and still have some time to experiment with Nx generators, here are some suggestions of features to add to the procedure generator:
+
+#### 1. Nested Operations
+
+Try updating the generator to support nested routers by:
+
+- Accepting dot notation for the `procedure` input (e.g. `games.query`)
+- Generating a procedure with a name based on reversed dot notation (e.g. `queryGames`)
+- Adding the appropriate nested router (or updating it if it already exists!)
+
+#### 2. Validation
+
+Our generator should defend against potential issues, such as a user selecting a `project` which isn't a tRPC API. Take a look at the `connection` generator for an example of this.
+
+#### 3. Unit Tests
+
+Write some unit tests for the generator. These are quite straightforward to implement, and most follow the general flow:
+
+1. Create an empty workspace tree using `createTreeUsingTsSolutionSetup()`
+2. Add any files that should already exist in the tree (e.g. `project.json` and `src/router.ts` for a tRPC backend)
+3. Run the generator under test
+4. Validate the expected changes are made to the tree
+
+#### 4. End to End Tests
+
+We have a suite of "smoke tests" which run generators in a fresh workspace and make sure that everything builds. At a minimum, your new generator should be added to the generator matrix in `e2e/src/smoke-tests/generator-matrix.ts` so that it's exercised by the smoke tests.
+
+Note that the generator matrix only runs the generators and builds the workspace — it does not instantiate any infrastructure. For generators which deploy infrastructure, consider extending the deployment e2e tests (`e2e/src/smoke-tests/cdk-deploy.spec.ts` and `terraform-deploy.spec.ts`) to actually deploy your resources (via `cdk deploy` / `terraform apply`), then add an assertion to `deploy-invocations.ts` that invokes the deployed resource and verifies it behaves as expected.
+
+If your generator vends a local development server, consider adding it to the local development e2e test (`e2e/src/smoke-tests/local-dev.spec.ts`), which starts the `dev` target and exercises the running server.
+
+### General Guidance to Accelerate Contributing
+
+This section contains some general guidance which can help when working on the Nx Plugin for AWS.
+
+#### Work backwards from a real project
+
+A useful way to build new generators or add features/fixes to an existing generator is to _build it for real first_. This way you can validate your ideas and iterate quickly to achieve the functionality you need. After you've settled on the desired outcome, you can then update the generator.
+
+In practice, this process might look like:
+
+<Steps>
+
+1. Create a new workspace
+
+    <CreateNxWorkspaceCommand workspace="my-project" />
+  
+1. Run any generators that may be prerequisites to your new generator/feature/fix
+1. Commit your changes (`git commit`)
+1. Make your desired changes and test them as needed
+1. Use the `git diff` of your changes to inform what changes should be made to the Nx Plugin for AWS
+1. Perform one final end to end test (linking your `@aws/nx-plugin`) to ensure your generator vends the changes you need
+
+</Steps>