@aws/nx-plugin-mcp 0.120.0 → 0.121.0

package/docs/guides/typescript-project.mdx

@@ -0,0 +1,312 @@
+---
+title: TypeScript Projects
+description: Reference documentation for TypeScript projects
+generator: ts#project
+---
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import InstallCommand from '@components/install-command.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import Link from '@components/link.astro';
+
+The TypeScript project generator can be used to create a modern [TypeScript](https://www.typescriptlang.org/) library or application configured with best practices such as [ECMAScript Modules (ESM)](https://www.typescriptlang.org/docs/handbook/modules/reference.html), TypeScript [project references](https://www.typescriptlang.org/docs/handbook/project-references.html), [Vitest](https://vitest.dev/) for running tests and [ESLint](https://eslint.org/) for static analysis.
+
+## Usage
+
+### Generate a TypeScript Project
+
+You can generate a new TypeScript project in two ways:
+
+<RunGenerator generator="ts#project" />
+
+### Options
+
+<GeneratorParameters generator="ts#project" />
+
+## Generator Output
+
+The generator will create the following project structure in the `<directory>/<name>` directory:
+
+<FileTree>
+
+  - src TypeScript source code
+    - index.ts
+  - project.json Project configuration and build targets
+  - tsconfig.json Base TypeScript configuration for this project (extends workspace root tsconfig.base.json)
+  - tsconfig.lib.json TypeScript configuration for your library (your runtime or packaged source)
+  - tsconfig.spec.json TypeScript configuration for your tests
+  - vitest.config.mts Configuration for Vitest
+  - eslint.config.mjs Configuration for ESLint
+
+</FileTree>
+
+:::tip[No package.json Needed]
+Notice that no `package.json` file is created for this project! You can find out why [below](#dependencies).
+:::
+
+You will also notice some changes to the following files in your workspace root:
+
+<FileTree>
+
+  - nx.json Nx configuration is updated to configure the @nx/js/typescript plugin for your project
+  - tsconfig.base.json a TypeScript alias is set up for your project so that it can be imported by other projects in your workspace
+  - tsconfig.json a TypeScript project reference is added for your project
+
+</FileTree>
+
+## Writing TypeScript Source Code
+
+Add your TypeScript code in the `src` directory.
+
+### ESM Import Syntax
+
+Since your TypeScript project is an ES Module, be sure to write your import statements with the correct ESM syntax, explicitly referencing the file extension:
+
+```ts title="index.ts" ".js"
+import { sayHello } from './hello.js';
+```
+
+:::note[TypeScript References]
+Even though we're using TypeScript, and `sayHello` is defined in `hello.ts`, we use the `.js` file extension in our import. You can read more about this [here](https://www.typescriptlang.org/docs/handbook/modules/reference.html).
+:::
+
+### Exporting for Other TypeScript Projects
+
+The entry point for your TypeScript project is `src/index.ts`. You can add exports here for anything you'd like other projects to be able to import:
+
+```ts title="src/index.ts"
+export { sayHello } from './hello.js';
+export * from './algorithms/index.js';
+```
+
+### Importing your Library Code in Other Projects
+
+[TypeScript aliases](https://www.typescriptlang.org/docs/handbook/modules/reference.html#paths) for your project are configured in your workspace `tsconfig.base.json`, which allows you to reference your TypeScript project from other TypeScript projects:
+
+```ts title="packages/my-other-project/src/index.ts"
+import { sayHello } from ':my-scope/my-library';
+```
+
+:::note[Project Aliases]
+Aliases for your TypeScript projects begin with a `:` rather than the traditional `@`, since this avoids the possibility of name conflicts between local packages in your workspace and remote packages in [NPM](https://www.npmjs.com/).
+:::
+
+When you add an import statement for a new project in your workspace for the first time, you will likely see an error in your IDE similar to the below:
+
+<details>
+<summary>Import error</summary>
+
+```bash wrap
+File '/path/to/my/workspace/packages/my-library/src/index.ts' is not under 'rootDir' '/path/to/my/workspace/packages/my-consumer'. 'rootDir' is expected to contain all source files.
+  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6059)
+File '/path/to/my/workspace/packages/my-library/src/index.ts' is not listed within the file list of project '/path/to/my/workspace/packages/my-consumer/tsconfig.lib.json'. Projects must list all files or use an 'include' pattern.
+  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6307)
+```
+
+</details>
+
+This is because a [project reference](https://www.typescriptlang.org/docs/handbook/project-references.html) has not yet been set up.
+
+TypeScript projects are configured with the Nx TypeScript Sync generator out of the box, saving you from needing to manually configure the project reference. Simply run the following command and Nx will add the required configuration:
+
+<NxCommands commands={['sync']} />
+
+After this, the error in your IDE should be gone and you are ready to use your library.
+
+:::tip[Build Shortcut]
+You can also just build your project and you'll be prompted with a message such as:
+
+```bash wrap
+[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.
+
+This will result in an error in CI.
+
+? Would you like to sync the identified changes to get your workspace up to date?
+Yes, sync the changes and run the tasks
+No, run the tasks without syncing the changes
+```
+
+Select `Yes` to allow Nx to update your project references.
+:::
+
+### Keeping Path Aliases In Sync
+
+If you add custom `compilerOptions.paths` entries in a project's `tsconfig.json`, TypeScript stops inheriting the workspace aliases defined in `tsconfig.base.json`. The hidden `ts#sync` generator runs before the `compile` target (configured in `nx.json`) to copy any missing base aliases into `tsconfig.json`, `tsconfig.lib.json` and `tsconfig.app.json` files that already declare `paths`. To opt out, remove `@aws/nx-plugin:ts#sync` from `targetDefaults.compile.syncGenerators` in `nx.json`.
+
+### Dependencies
+
+You will notice that your TypeScript project does not have a `package.json` file, which might be unexpected if you are used to traditional TypeScript monorepos.
+
+To add a dependency for any TypeScript package in your monorepo, simply add the dependency to the `package.json` in the root of your workspace. You can do this via the command line for your package manager:
+
+<InstallCommand pkg="some-npm-package" />
+
+The dependency is then available for any of the TypeScript projects in your workspace to use.
+
+#### Runtime Code
+
+When you use your TypeScript project as runtime code (for example as the handler for an AWS Lambda function), it's recommended that you use a tool such as [Rolldown](https://rolldown.rs/) to bundle your project, since this can [tree-shake](https://rolldown.rs/in-depth/why-bundlers) to ensure that only the dependencies your project actually references are included.
+
+You can achieve this by adding a target such as the following to your `project.json` file:
+
+```json
+{
+  ...
+  "targets": {
+    ...
+    "bundle": {
+      "cache": true,
+      "executor": "nx:run-commands",
+      "outputs": ["{workspaceRoot}/dist/packages/my-library/bundle"],
+      "options": {
+        "command": "rolldown -c rolldown.config.ts"
+      }
+    },
+  },
+}
+```
+
+And adding the `rolldown.config.ts` file as follows:
+
+```ts
+// rolldown.config.ts
+import { defineConfig } from 'rolldown';
+
+export default defineConfig([
+  {
+    input: 'src/index.ts',
+    output: {
+      file: '../../dist/packages/my-library/bundle/index.js',
+      format: 'cjs',
+      inlineDynamicImports: true,
+    },
+  },
+]);
+```
+
+:::note[Bundle Configuration]
+Note that in the above target, we chose `src/index.ts` as our entrypoint for the bundle, which means that code exported from this file will be included in the bundle, along with all of its dependencies.
+:::
+
+:::tip[Lambda Functions]
+If you're building an AWS Lambda function, check out the <Link path="/guides/ts-lambda-function">`ts#lambda-function`</Link> generator as this configures bundling for you, as well as generating infrastructure and adding observability and type-safety.
+:::
+
+#### Publishing to NPM
+
+If you are publishing your TypeScript project to NPM, you must create a `package.json` file for it.
+
+This must declare the dependencies that your project references. Since at build time your project will resolve dependencies installed via the workspace root `package.json`, it's recommended to configure the [Nx Dependency Checks ESLint Plugin](https://nx.dev/nx-api/eslint-plugin/documents/dependency-checks) to ensure that your published project's `package.json` includes all dependencies you use in your project.
+
+### Building
+
+Your TypeScript project is configured with a `build` target (defined in `project.json`), which you can run via:
+
+<NxCommands commands={['build <project-name>']} />
+
+Where `<project-name>` is the fully qualified name of your project.
+
+The `build` target will compile, lint and test your project.
+
+Build output can be found in the root `dist` folder in your workspace, inside a directory for your package and target, for example `dist/packages/<my-library>/tsc`
+
+To build all of the projects in your workspace, run:
+
+<NxCommands commands={['run-many --target build']} />
+
+Or use the shorthand command:
+
+<PackageManagerShortCommand commands={["build"]} />
+
+## Testing
+
+[Vitest](https://vitest.dev/) is configured for testing your project.
+
+### Writing Tests
+
+Tests should be written in `.spec.ts` or `.test.ts` files, co-located in your project's `src` folder.
+
+For example:
+
+<FileTree>
+  - src
+    - hello.ts Library source code
+    - hello.spec.ts Tests for hello.ts
+</FileTree>
+
+Vitest provides Jest-like syntax for defining tests, with utilities such as `describe`, `it`, `test` and `expect`.
+
+```ts title="hello.spec.ts"
+import { sayHello } from './hello.js';
+
+describe('sayHello', () => {
+
+  it('should greet the caller', () => {
+    expect(sayHello('Darth Vader')).toBe('Hello, Darth Vader!');
+  });
+
+});
+
+```
+
+For more details about how to write tests, and features such as mocking dependencies, refer to the [Vitest documentation](https://vitest.dev/guide/#writing-tests)
+
+### Running Tests
+
+Tests will run as part of the `build` target for your project, but you can also run them separately by running the `test` target:
+
+<NxCommands commands={['test <project-name>']} />
+
+You can run an individual test or suite of tests using Vitest's `-t` flag. Pass it after a `--` separator so Nx forwards it to Vitest rather than consuming it as its own `--target` option:
+
+<NxCommands commands={["test <project-name> -- -t 'sayHello'"]} />
+
+:::tip[VSCode Integration]
+If you are a VSCode user, we recommend installing the [Vitest Runner for VSCode that actually works](https://marketplace.visualstudio.com/items?itemName=rluvaton.vscode-vitest) extension, which allows you to run, watch or debug tests from your IDE.
+:::
+
+## Linting
+
+TypeScript projects use [ESLint](https://eslint.org/) for linting, along with [Prettier](https://prettier.io/) for formatting.
+
+We recommend configuring ESLint in the workspace root `eslint.config.mjs` file, as changes to this will apply to all TypeScript projects in your workspace and ensure consistency.
+
+Likewise, you can configure Prettier in the root `.prettierrc` file.
+
+### Running the Linter
+
+To invoke the linter to check your project, you can run the `lint` target.
+
+<NxCommands commands={["lint <project-name>"]} />
+
+### Fixing Lint Issues
+
+The majority of linting or formatting issues can be fixed automatically. You can tell ESLint to fix lint issues by running with the `--configuration=fix` argument.
+
+<NxCommands commands={["lint <project-name> --configuration=fix"]} />
+
+Similarly if you would like to fix all lint issues in all packages in your workspace, you can run:
+
+<NxCommands commands={["run-many --target lint --all --configuration=fix"]} />
+
+:::tip[Shorthand Command]
+This has a shorthand command from the root of your workspace:
+
+<PackageManagerShortCommand commands={["lint"]} />
+:::
+
+### Skipping Lint Issues
+
+To avoid linting issues slowing you down during development (particularly if you have non auto-fixable issues in your project), you can run a build with the `skip-lint` configuration:
+
+<NxCommands commands={["run-many --target build --configuration=skip-lint"]} />
+
+This will still run ESLint as part of the build, but the lint target will always be considered successful.
+
+:::tip[Shorthand Command]
+This has a shorthand command from the root of your workspace:
+
+<PackageManagerShortCommand commands={["build:skip-lint"]} />
+:::

package/docs/guides/workspace.mdx

@@ -0,0 +1,181 @@
+---
+title: Workspace
+description: Reference documentation for workspaces
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import NxCommands from '@components/nx-commands.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+
+When you create a new workspace with `@aws/nx-plugin`, the preset generator sets up an [Nx monorepo](https://nx.dev) with sensible defaults for building on AWS.
+
+## Creating a Workspace
+
+<CreateNxWorkspaceCommand workspace="my-project" />
+
+### Options
+
+<GeneratorParameters generator="preset" />
+
+### Workspace Structure
+
+<FileTree>
+  - packages/ Your projects live here
+  - package.json Root package.json for your monorepo
+  - nx.json Nx configuration (common targets, sync generators, caching)
+  - tsconfig.base.json Root TypeScript configuration
+  - aws-nx-plugin.config.mts Nx Plugin for AWS configuration
+  - .git-secrets/ Vendored git-secrets bash script for credential scanning
+  - .husky/ Git hooks
+</FileTree>
+
+## Nx
+
+Nx is a language-agnostic build system for monorepos, managing dependencies between projects written in any programming language and the tasks to build them. You can learn more on the [Nx website](https://nx.dev/getting-started/intro).
+
+### Projects
+
+An Nx monorepo is made up of one or more projects, each with a `project.json` file. The `project.json` defines a project's tasks, known as _targets_, which define how a project is built, run locally, tested, etc. It also defines dependencies between targets within or across projects.
+
+For example, a `project.json` might define a `build` target that depends on all upstream projects being built first:
+
+```json title="packages/my-project/project.json"
+{
+  "name": "@my-workspace/my-project",
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "dependsOn": ["^build"]
+    },
+    "test": {
+      "command": "vitest run"
+    }
+  }
+}
+```
+
+:::tip
+For projects in languages not directly supported by the Nx Plugin for AWS, you can often find a generator in the [Nx Plugin Registry](https://nx.dev/plugin-registry) to help. It's simple to add a project of any language into your monorepo however — just add a `project.json` file and define its `build` target to run the specific build command for a project of that language.
+:::
+
+For details on how TypeScript and Python projects are set up, refer to the <Link path="guides/typescript-project">ts#project</Link> and <Link path="guides/python-project">py#project</Link> generator guides.
+
+### Caching
+
+Nx caches the output of previously executed targets and replays them when the inputs haven't changed. This dramatically speeds up builds, tests, and linting — especially in CI. If you encounter stale or unexpected behaviour, reset the cache with:
+
+<NxCommands commands={['reset']} />
+
+For more details, see the [Nx caching documentation](https://nx.dev/features/cache-task-results).
+
+## 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 projects.
+
+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, 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 has its 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.
+
+## Common Commands
+
+### Build
+
+Build all projects in the workspace:
+
+<PackageManagerShortCommand commands={["build"]} />
+
+### Lint
+
+Lint and auto-fix all projects:
+
+<PackageManagerShortCommand commands={["lint"]} />
+
+### Test
+
+Run tests across all projects:
+
+<PackageManagerShortCommand commands={["test"]} />
+
+### Dev
+
+If you have a <Link path="guides/react-website">website</Link>, start it and all connected components locally:
+
+<PackageManagerShortCommand commands={["dev"]} />
+
+### Sync
+
+Run any [sync generators](https://nx.dev/concepts/sync-generators), which for example synchronise TypeScript project references (refer to the <Link path="guides/typescript-project">ts#project</Link> generator guide for more details):
+
+<NxCommands commands={['sync']} />
+
+### Run Specific Targets
+
+You can run specific targets for specific projects with:
+
+<NxCommands commands={['<target> <project>']} />
+
+For example:
+
+<NxCommands commands={['build website']} />
+
+This will run the chosen target as well as the targets it depends on.
+
+## What's Included
+
+### Linting
+
+New workspaces are configured with [ESLint](https://eslint.org/) for static analysis and [Prettier](https://prettier.io/) for code formatting. Running `lint` applies both to all projects.
+
+### Git Secrets
+
+New workspaces include [git-secrets](https://github.com/awslabs/git-secrets) pre-commit hooks that scan staged files for AWS credential patterns before each commit. This prevents accidentally committing access keys, secret keys, and other sensitive values.
+
+#### Suppressing False Positives
+
+Patterns in git-secrets use [egrep-compatible regular expressions](https://github.com/awslabs/git-secrets#options-for-add). If git-secrets blocks a commit that does not contain real credentials:
+
+```sh
+# Allow a specific regex pattern
+git secrets --add --allowed 'my-regex-pattern'
+
+# Allow a literal string (special characters are escaped)
+git secrets --add --allowed --literal 'my-literal+string'
+```
+
+You can also create a `.gitallowed` file at the repository root with one egrep-compatible regex per line (shared with your team via version control):
+
+```text title=".gitallowed"
+# Allow test fixtures
+tests/fixtures/.*
+# Allow a specific string
+EXAMPLE[A-Z]{16}
+```
+
+For full details on managing patterns, see the [git-secrets documentation](https://github.com/awslabs/git-secrets#readme).
+
+## Nx Plugin for AWS Configuration
+
+The workspace ships with an `aws-nx-plugin.config.mts` file at the root. Generators read this file to pick sensible defaults so you don't have to pass the same flags every time. Two settings are particularly useful:
+
+```typescript
+// aws-nx-plugin.config.mts
+import { AwsNxPluginConfig } from '@aws/nx-plugin';
+
+export default {
+  iac: {
+    provider: 'CDK', // or 'Terraform'
+  },
+  containers: {
+    engine: 'docker', // or 'finch'
+  },
+} satisfies AwsNxPluginConfig;
+```
+
+- **`iac.provider`** — the default infrastructure-as-code provider (`CDK` or `Terraform`) used by generators that emit infrastructure (e.g. `ts#infra`, `ts#trpc-api`, `py#fast-api`). Generators that accept an `--iacProvider` flag default to `Inherit`, which reads this value.
+- **`containers.engine`** — the container CLI (`docker` or `finch`) baked into generated build/push/login commands. CDK image-asset builds also pick this up via the `CDK_DOCKER` environment variable. See the <Link path="guides/docker-bundling">Docker bundling guide</Link> for details.
+
+You can edit either setting at any time — subsequent generator runs will pick up the new value.

package/docs/snippets/agent/architecture.mdx

@@ -0,0 +1,72 @@
+---
+title: Agent Architecture
+---
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+<Tabs syncKey="computeType">
+<TabItem label="Bedrock AgentCore Runtime" _filter={{ computeType: 'BedrockAgentCoreRuntime' }}>
+
+When deployed to [Bedrock AgentCore Runtime](https://aws.amazon.com/bedrock/agentcore/), the agent is built into a container image, pushed to Amazon ECR and run in AgentCore Runtime. Clients invoke the AgentCore Runtime data plane endpoint, which forwards requests to your agent. The agent calls Amazon Bedrock for model inference and may invoke tools, MCP servers, or downstream APIs.
+
+```d2 inline=true
+direction: right
+
+client: Client {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/client.svg
+}
+
+ecr: ECR {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/ecr.svg
+}
+
+agentcore: Strands Agent\n(AgentCore Runtime) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore.svg
+}
+
+bedrock: Bedrock\n(Model Inference) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/bedrock.svg
+  near: top-right
+}
+
+cw: CloudWatch\n(Logs, Metrics) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/cloudwatch.svg
+  near: bottom-right
+}
+
+client -> agentcore
+ecr -> agentcore: Container\nimage
+agentcore -> bedrock: InvokeModel
+agentcore -> cw
+```
+</TabItem>
+<TabItem label="None (local only)" _filter={{ computeType: 'None' }}>
+
+With `computeType: None`, no AWS infrastructure is generated. The agent runs as a local process and calls Amazon Bedrock for model inference.
+
+```d2 inline=true
+direction: right
+
+client: Client {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/client.svg
+}
+
+agent: Strands Agent\n(local process) {
+  shape: rectangle
+}
+
+bedrock: Bedrock\n(Model Inference) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/bedrock.svg
+}
+
+client -> agent
+agent -> bedrock: InvokeModel
+```
+</TabItem>
+</Tabs>