@aws/nx-plugin-mcp 0.120.0 → 0.121.0

package/docs/guides/nx-generator.mdx

@@ -0,0 +1,588 @@
+---
+title: Nx Generator Generator
+description: Generates an Nx Generator
+generator: ts#nx-generator
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Drawer from '@components/drawer.astro';
+import Link from '@components/link.astro';
+
+Adds an [Nx Generator](https://nx.dev/recipes/generators/local-generators) to a TypeScript project, to help you automate repetitive tasks such as scaffolding components or enforcing particular project structures.
+
+## Usage
+
+### Generate a Generator
+
+You can generate a generator in two ways:
+
+<RunGenerator generator="ts#nx-generator" />
+
+:::tip[Recommended Setup]
+We recommend using the <Link path="/guides/ts-nx-plugin">`ts#nx-plugin`</Link> generator as the base project for any generators you create, since it also provides an MCP Server which helps AI to use your generators.
+:::
+
+### Options
+
+<GeneratorParameters generator="ts#nx-generator" />
+
+## Generator Output
+
+The generator will create the following project files within the given `project`:
+
+<FileTree>
+  - src/\<name>/
+    - schema.json Schema for input to your generator
+    - schema.d.ts TypeScript types for your schema
+    - generator.ts Stub generator implementation
+    - generator.spec.ts Tests for your generator
+    - README.md Documentation for your generator
+  - generators.json Nx configuration to define your generators
+  - package.json Created or updated to add a "generators" entry
+  - tsconfig.json Updated to use CommonJS
+</FileTree>
+
+:::warning[Project Modification]
+This generator will update the selected `project` to use CommonJS, as Nx Generators only support CommonJS at present ([refer to this GitHub issue for ESM support](https://github.com/nrwl/nx/issues/15682)).
+:::
+
+## Local Generators
+
+:::tip[Dedicated Plugin Project]
+We recommend generating a dedicated TypeScript project for all your generators using the `ts#nx-plugin` generator first. For example:
+
+<RunGenerator generator="ts#nx-plugin" requiredParameters={{ name: 'nx-plugin', directory: 'tools' }} />
+:::
+
+Select your local `nx-plugin` project when running the `ts#nx-generator` generator, and specify a name and optional directory and description.
+
+### Defining the Schema
+
+The `schema.json` file defines the options that your generator accepts. It follows the [JSON Schema](https://json-schema.org/) format with [Nx-specific extensions](https://nx.dev/extending-nx/recipes/generator-options).
+
+#### Basic Structure
+
+A schema.json file has the following basic structure:
+
+```json
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "YourGeneratorName",
+  "title": "Your Generator Title",
+  "description": "Description of what your generator does",
+  "type": "object",
+  "properties": {
+    // Your generator options go here
+  },
+  "required": ["requiredOption1", "requiredOption2"]
+}
+```
+
+#### Simple Example
+
+Here's a simple example with a few basic options:
+
+```json
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "ComponentGenerator",
+  "title": "Create a Component",
+  "description": "Creates a new React component",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Component name",
+      "x-priority": "important"
+    },
+    "directory": {
+      "type": "string",
+      "description": "Directory where the component will be created",
+      "default": "src/components"
+    },
+    "withTests": {
+      "type": "boolean",
+      "description": "Whether to generate test files",
+      "default": true
+    }
+  },
+  "required": ["name"]
+}
+```
+
+#### Interactive Prompts (CLI)
+
+You can customise the prompts displayed when running your generator via the CLI by adding the `x-prompt` property:
+
+```json
+"name": {
+  "type": "string",
+  "description": "Component name",
+  "x-prompt": "What is the name of your component?"
+}
+```
+
+For boolean options, you can use a yes/no prompt:
+
+```json
+"withTests": {
+  "type": "boolean",
+  "description": "Whether to generate test files",
+  "x-prompt": "Would you like to generate test files?"
+}
+```
+
+#### Dropdown Selections
+
+For options with a fixed set of choices, use `enum` so that users can select from one of the options.
+
+```json
+"style": {
+  "type": "string",
+  "description": "The styling approach to use",
+  "enum": ["css", "scss", "styled-components", "none"],
+  "default": "css"
+}
+```
+
+#### Project Selection Dropdown
+
+A common pattern is to let users select from existing projects in the workspace:
+
+```json
+"project": {
+  "type": "string",
+  "description": "The project to add the component to",
+  "x-prompt": "Which project would you like to add the component to?",
+  "x-dropdown": "projects"
+}
+```
+
+The `x-dropdown: "projects"` property tells Nx to populate the dropdown with all projects in the workspace.
+
+#### Positional Arguments
+
+You can configure options to be passed as positional arguments when running the generator from the command line:
+
+```json
+"name": {
+  "type": "string",
+  "description": "Component name",
+  "x-priority": "important",
+  "$default": {
+    "$source": "argv",
+    "index": 0
+  }
+}
+```
+
+This allows users to run your generator like `nx g your-generator my-component` instead of `nx g your-generator --name=my-component`.
+
+#### Setting Priorities
+
+Use the `x-priority` property to indicate which options are most important:
+
+```json
+"name": {
+  "type": "string",
+  "description": "Component name",
+  "x-priority": "important"
+}
+```
+
+Options can have priorities of `"important"` or `"internal"`. This helps Nx to order properties in the Nx VSCode extension and Nx CLI.
+
+#### Default Values
+
+You can provide default values for options:
+
+```json
+"directory": {
+  "type": "string",
+  "description": "Directory where the component will be created",
+  "default": "src/components"
+}
+```
+
+#### More Information
+
+For more details on schemas, refer to the [Nx Generator Options documentation](https://nx.dev/extending-nx/recipes/generator-options).
+
+#### TypeScript Types with schema.d.ts
+
+Along with `schema.json`, the generator creates a `schema.d.ts` file that provides TypeScript types for your generator options:
+
+```typescript
+export interface YourGeneratorSchema {
+  name: string;
+  directory?: string;
+  withTests?: boolean;
+}
+```
+
+This interface is used in your generator implementation to provide type safety and code completion:
+
+```typescript
+import { YourGeneratorSchema } from './schema';
+
+export default async function (tree: Tree, options: YourGeneratorSchema) {
+  // TypeScript knows the types of all your options
+  const { name, directory = 'src/components', withTests = true } = options;
+  // ...
+}
+```
+
+:::caution[Schema Changes]
+Whenever you modify `schema.json`, you must update `schema.d.ts` to match. This includes:
+
+- Adding or removing properties
+- Changing property types
+- Making properties required or optional (use the `?` suffix for optional properties)
+
+The TypeScript interface should accurately reflect the structure defined in your JSON schema.
+:::
+
+### Implementing a Generator
+
+After creating the new generator as above, you can write your implementation in `generator.ts`.
+
+A generator is a function which mutates a virtual filesystem (the `Tree`), reading and writing files to make the desired changes. Changes from the `Tree` are only written to disk once the generator finishes executing, unless it is run in "dry-run" mode. An empty generator looks as follows:
+
+```ts
+export const myGenerator = async (tree: Tree, options: MyGeneratorSchema) => {
+  // Use the tree to apply changes
+};
+
+export default myGenerator;
+```
+
+Here are some common operations you might want to perform in your generator:
+
+#### Reading and Writing Files
+
+```typescript
+// Read a file
+const content = tree.read('path/to/file.ts', 'utf-8');
+
+// Write a file
+tree.write('path/to/new-file.ts', 'export const hello = "world";');
+
+// Check if a file exists
+if (tree.exists('path/to/file.ts')) {
+  // Do something
+}
+```
+
+#### Generating Files from Templates
+
+You can generate files with the `generateFiles` utility from `@nx/devkit`. This allows you to define templates in [EJS](https://ejs.co/) syntax, and substitute variables.
+
+```typescript
+import { generateFiles, joinPathFragments } from '@nx/devkit';
+
+// Generate files from templates
+generateFiles(
+  tree,
+  joinPathFragments(__dirname, 'files'), // Template directory
+  'path/to/output', // Output directory
+  {
+    // Variables to replace in templates
+    name: options.name,
+    nameCamelCase: camelCase(options.name),
+    nameKebabCase: kebabCase(options.name),
+    // Add more variables as needed
+  },
+);
+```
+
+#### Code Transforms with GritQL
+
+You can use [GritQL](https://docs.grit.io/) to declaratively search and transform source code in your generators. GritQL supports multiple languages including TypeScript, JavaScript, Python, HCL (Terraform), and more — so you can use the same pattern syntax across your entire stack.
+
+The Nx Plugin for AWS exposes two helpers:
+
+- `applyGritQL(tree, filePath, pattern)` — applies a GritQL rewrite pattern to a file and returns `Promise<boolean>` indicating whether changes were made
+- `matchGritQL(tree, filePath, pattern)` — checks whether a GritQL pattern matches anywhere in a file and returns `Promise<boolean>`
+
+```typescript
+import { applyGritQL, matchGritQL } from '@aws/nx-plugin/sdk/utils/ast';
+
+// Replace a function call
+await applyGritQL(
+  tree,
+  'src/app.ts',
+  '`console.log($msg)` => `logger.info($msg)`',
+);
+
+// Add an element to an array only if not already present
+await applyGritQL(
+  tree,
+  'src/plugins.ts',
+  '`plugins: [$items]` => `plugins: [$items, myPlugin()]` where { $items <: not contains `myPlugin` }',
+);
+
+// Check if a pattern exists before making changes
+if (!(await matchGritQL(tree, filePath, '`import { Auth } from "./auth"`'))) {
+  // Add the import
+}
+```
+
+GritQL patterns also work on non-TypeScript files. Prefix your pattern with `language <name>` to target other languages:
+
+```typescript
+// Python: replace print statements with logging calls
+await applyGritQL(
+  tree,
+  'src/handler.py',
+  'language python\n`print($msg)` => `logger.info($msg)`',
+);
+```
+
+GritQL patterns use backtick-delimited code snippets with `$metavariables` as wildcards. Use `=>` for rewrites and `where` clauses for conditions.
+
+:::tip[GritQL Playground]
+You can try out GritQL patterns in the [GritQL Playground](https://docs.grit.io/playground), or install the GritQL CLI locally to test patterns against your files:
+
+```bash
+npm install -g @getgrit/cli
+grit apply '`console.log($msg)` => `logger.info($msg)`' --dry-run
+```
+:::
+
+:::tip[AI Coding Agents]
+If you use an AI coding agent to help write generators, add the [Context7 MCP server](https://context7.com/) to give it up-to-date documentation. Prompt it to look up `gritql` and `docs.grit.io` for GritQL pattern syntax reference, and provide access to the GritQL CLI so it can test patterns directly.
+:::
+
+#### Adding Dependencies
+
+```typescript
+import { addDependenciesToPackageJson } from '@nx/devkit';
+
+// Add dependencies to package.json
+addDependenciesToPackageJson(
+  tree,
+  {
+    'new-dependency': '^1.0.0',
+  },
+  {
+    'new-dev-dependency': '^2.0.0',
+  },
+);
+```
+
+:::note[Package Dependencies]
+If you add dependencies to a package.json, you can then install them for the user as part of the generator callback:
+
+```ts
+import { installPackagesTask } from '@nx/devkit';
+
+// Generators return a callback which can run any post-generation tasks, such as installing dependencies
+return () => {
+  installPackagesTask(tree);
+};
+```
+:::
+
+#### Formatting Generated Files
+
+```typescript
+import { formatFilesInSubtree } from '@aws/nx-plugin/sdk/utils/format';
+
+// Format all files that were modified
+await formatFilesInSubtree(tree, 'optional/path/to/format');
+```
+
+#### Reading and Updating JSON Files
+
+```typescript
+import { readJson, updateJson } from '@nx/devkit';
+
+// Read a JSON file
+const packageJson = readJson(tree, 'package.json');
+
+// Update a JSON file
+updateJson(tree, 'tsconfig.json', (json) => {
+  json.compilerOptions = {
+    ...json.compilerOptions,
+    strict: true,
+  };
+  return json;
+});
+```
+
+#### Extending a Generator from the Nx Plugin for AWS
+
+You can import generators from the Nx Plugin for AWS, and extend or compose them as you wish, for example you might wish to create a generator which builds on top of a TypeScript project:
+
+```ts
+import { tsProjectGenerator } from '@aws/nx-plugin/sdk/ts';
+
+export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
+  const callback = await tsProjectGenerator(tree, { ... });
+
+  // Extend the TypeScript project generator here
+
+  // Return the callback to ensure dependencies are installed.
+  // You can wrap the callback if you wish to perform additional operations in the generator callback.
+  return callback;
+};
+```
+
+#### OpenAPI Generators
+
+You can use and extend the generators we use for TypeScript clients and hooks in a similar way to the above:
+
+```ts
+import { openApiTsClientGenerator } from '@aws/nx-plugin/sdk/open-api';
+
+export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
+  await openApiTsClientGenerator(tree, { ... });
+
+  // Add additional files here
+};
+```
+
+We also expose a method which allows you to build a data structure that can be used to iterate over operations in an OpenAPI specification and therefore instrument your own code generation, for example:
+
+```ts
+import { buildOpenApiCodeGenerationData } from '@aws/nx-plugin/sdk/open-api.js';
+
+export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
+  const data = await buildOpenApiCodeGenerationData(tree, 'path/to/spec.json');
+
+  generateFiles(
+    tree,
+    joinPathFragments(__dirname, 'files'), // Template directory
+    'path/to/output', // Output directory
+    data,
+  );
+};
+```
+
+Which then allows you to write templates such as:
+
+```ejs
+// files/my-operations.ts.template
+export const myOperationNames = [
+<%_ allOperations.forEach((op) => { _%>
+  '<%- op.name %>',
+<%_ }); _%>
+];
+```
+
+Refer to the [codebase on GitHub](https://github.com/awslabs/nx-plugin-for-aws/) for more complex example templates.
+
+### Running Your Generator
+
+You can run your generator in two ways:
+
+<RunGenerator namespace="@my-project/nx-plugin" generator="my-generator" />
+
+:::note[Generator Not Showing]
+If you don't see your generator in the VSCode plugin UI, you can refresh your Nx Workspace with:
+
+<NxCommands commands={['reset']} />
+:::
+
+### Testing Your Generator
+
+Unit tests for generators are straightforward to implement. Here's a typical pattern:
+
+```typescript
+import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
+import { yourGenerator } from './generator';
+
+describe('your generator', () => {
+  let tree;
+
+  beforeEach(() => {
+    // Create an empty workspace tree
+    tree = createTreeWithEmptyWorkspace();
+
+    // Add any files that should already exist in the tree
+    tree.write(
+      'project.json',
+      JSON.stringify({
+        name: 'test-project',
+        sourceRoot: 'src',
+      }),
+    );
+
+    tree.write('src/existing-file.ts', 'export const existing = true;');
+  });
+
+  it('should generate expected files', async () => {
+    // Run the generator
+    await yourGenerator(tree, {
+      name: 'test',
+      // Add other required options
+    });
+
+    // Check that files were created
+    expect(tree.exists('src/test/file.ts')).toBeTruthy();
+
+    // Check file content
+    const content = tree.read('src/test/file.ts', 'utf-8');
+    expect(content).toContain('export const test');
+
+    // You can also use snapshots
+    expect(tree.read('src/test/file.ts', 'utf-8')).toMatchSnapshot();
+  });
+
+  it('should update existing files', async () => {
+    // Run the generator
+    await yourGenerator(tree, {
+      name: 'test',
+      // Add other required options
+    });
+
+    // Check that existing files were updated
+    const content = tree.read('src/existing-file.ts', 'utf-8');
+    expect(content).toContain('import { test } from');
+  });
+
+  it('should handle errors', async () => {
+    // Expect the generator to throw an error in certain conditions
+    await expect(
+      yourGenerator(tree, {
+        name: 'invalid',
+        // Add options that should cause an error
+      }),
+    ).rejects.toThrow('Expected error message');
+  });
+});
+```
+
+Key points for testing generators:
+
+- Use `createTreeWithEmptyWorkspace()` to create a virtual file system
+- Set up any prerequisite files before running the generator
+- Test both the creation of new files and updates to existing files
+- Use snapshots for complex file content
+- Test error conditions to ensure your generator fails gracefully
+
+## Contributing Generators to @aws/nx-plugin
+
+You can also use `ts#nx-generator` to scaffold a generator within `@aws/nx-plugin`.
+
+When this generator is run in our repository, it'll generate the following files for you:
+
+<FileTree>
+  - packages/nx-plugin/src/\<name>/
+    - schema.json Schema for input to your generator
+    - schema.d.ts TypeScript types for your schema
+    - generator.ts Generator implementation
+    - generator.spec.ts Tests for your generator
+  - docs/src/content/docs/guides/
+    - \<name>.mdx Documentation page for your generator
+  - packages/nx-plugin/generators.json Updated to include your generator
+</FileTree>
+
+You can then start to implement your generator.
+
+:::tip[Contributing Generators]
+For a more in-depth guide regarding contributing to the Nx Plugin for AWS, please refer to the <Link path="get_started/tutorials/contribute-generator">tutorial here</Link>.
+:::