@aws/nx-plugin-mcp 0.119.0 → 0.121.0

package/docs/guides/python-lambda-function.mdx

@@ -0,0 +1,207 @@
+---
+title: Python Lambda Functions
+description: Reference documentation for Python Lambda Functions
+generator: py#lambda-function
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+import NxCommands from '@components/nx-commands.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+The Python Lambda Function generator provides the ability to add a lambda function to an existing python project.
+
+This generator creates a new python lambda handler with AWS CDK or Terraform infrastructure setup. The generated backend uses AWS Lambda for serverless deployment, with optional type-safety using the [Parser from AWS Lambda Powertools](https://docs.powertools.aws.dev/lambda/python/latest/utilities/parser/). It sets up [AWS Lambda Powertools](https://docs.powertools.aws.dev/lambda/python/latest/) for observability, including logging, AWS X-Ray tracing and Cloudwatch Metrics.
+
+## Usage
+
+### Generate a Lambda Function
+
+You can generate a new Lambda Function in two ways:
+
+<RunGenerator generator="py#lambda-function" />
+
+### Options
+
+<GeneratorParameters generator="py#lambda-function" />
+
+## Generator Output
+
+The generator will add the following files to your project:
+
+<FileTree>
+
+- \<module-name>
+  - \<lambda-function>.py Function implementation
+
+</FileTree>
+
+If the `functionPath` option is provided, the generater will add the necessary files to the specified path:
+
+<FileTree>
+
+- \<module-name>
+  - \<custom-path>
+    - \<function-name>.py Function implementation
+
+</FileTree>
+
+### Infrastructure
+
+<Snippet name="shared-constructs" />
+
+The generator creates infrastructure as code for deploying your function based on your selected `iacProvider`:
+
+<Infrastructure>
+<Fragment slot="cdk">
+The generator creates CDK constructs which can be used to deploy your function, which reside in the `packages/common/constructs` directory.
+</Fragment>
+<Fragment slot="terraform">
+The generator creates a Terraform module which can be used to deploy your function, which resides in the `packages/common/terraform/src/app/lambda-functions/<function-name>` directory.
+</Fragment>
+</Infrastructure>
+
+#### Architecture
+
+<Snippet name="lambda-function/architecture" />
+
+## Implementing your Function
+
+The main function implementation is in `<function-name>.py`. Here's an example:
+
+```python
+import os
+
+from aws_lambda_powertools import Logger, Metrics, Tracer
+from aws_lambda_powertools.metrics import MetricUnit
+from aws_lambda_powertools.utilities.parser import event_parser
+from aws_lambda_powertools.utilities.parser.models import EventBridgeModel
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+os.environ["POWERTOOLS_METRICS_NAMESPACE"] = "Foo"
+os.environ["POWERTOOLS_SERVICE_NAME"] = "Foo"
+
+logger: Logger = Logger()
+metrics: Metrics = Metrics()
+tracer: Tracer = Tracer()
+
+@tracer.capture_lambda_handler
+@metrics.log_metrics
+@event_parser(model=EventBridgeModel)
+def lambda_handler(event: EventBridgeModel, context: LambdaContext):
+    logger.info("Received event", extra={"event": event.model_dump() })
+    metrics.add_metric(name="InvocationCount", unit=MetricUnit.Count, value=1)
+
+    try:
+        # TODO: Implement
+        metrics.add_metric(name="SuccessCount", unit=MetricUnit.Count, value=1)
+        # TODO: Implement success response if required
+    except Exception as e:
+        logger.exception(e)
+        metrics.add_metric(name="ErrorCount", unit=MetricUnit.Count, value=1)
+        # TODO: Implement error response if required
+```
+
+The generator sets up several features automatically:
+
+1. AWS Lambda Powertools integration for observability
+2. Metrics collection
+3. Type-safety using `@event_parser`
+
+### Observability with AWS Lambda Powertools
+
+#### Logging
+
+The generator configures structured logging using AWS Lambda Powertools.
+
+```python
+def lambda_handler(event: EventBridgeModel, context: LambdaContext):
+    logger.info("Received event", extra={"event": event.model_dump()})
+```
+
+:::tip[Correlation ID]
+It is recommended to set the correlation id for all unique requests for easier debugging and monitoring. Please refer to the [aws powertools logger](https://docs.powertools.aws.dev/lambda/python/2.22.0/core/logger/#setting-a-correlation-id) documentation for correlation id best practices.
+:::
+
+The logger automatically includes:
+
+- Event requests
+- Lambda context information
+- Cold start indicators
+
+#### Tracing
+
+AWS X-Ray tracing is configured automatically. You can add custom subsegments to your traces:
+
+```python
+def lambda_handler(event: EventBridgeModel, context: LambdaContext):
+    # Creates a new subsegment
+    with tracer.provider.in_subsegment("function-subsegment"):
+        # Your logic here
+        return ....
+```
+
+#### Metrics
+
+CloudWatch metrics are collected automatically for each request. You can add custom metrics:
+
+```python
+def lambda_handler(event: EventBridgeModel, context: LambdaContext):
+    metrics.add_metric(name="NewMetric", unit=MetricUnit.Count, value=1)
+    return ...
+```
+
+Default metrics include:
+
+- Invocation counts
+- Success/failure counts
+- Cold start metrics
+
+### Type Safety
+
+<OptionFilter not when={{ eventSource: 'Any' }} description="Typed eventSource wires @event_parser with a Pydantic model">
+If you chose an `eventSource` when generating your lambda function, your function is instrumented with [`@event_parser` from AWS Lambda Powertools](https://docs.powertools.aws.dev/lambda/python/latest/utilities/parser/). For example:
+
+```python {3}
+@event_parser(model=EventBridgeModel)
+def lambda_handler(event: EventBridgeModel, context: LambdaContext):
+    event.detail_type # <- type-safe with IDE autocompletion
+```
+
+This allows you to define data models using [Pydantic](https://docs.pydantic.dev/latest/), in a similar manner to working with <Link path="guides/fastapi">Fast API</Link>.
+
+:::tip[Custom Event Data]
+If you have custom data nested within an event, for example a DynamoDB stream or EventBridge event, you may benefit from using [Envelopes](https://docs.powertools.aws.dev/lambda/python/latest/utilities/parser/#envelopes) to provide type-safety for that custom data.
+:::
+</OptionFilter>
+
+<OptionFilter when={{ eventSource: 'Any' }} description="eventSource=Any — no parser decorator, event is untyped">
+If you selected `Any` for your `eventSource`, the `@event_parser` decorator is not applied and the handler receives an untyped event dict. Regenerate with a specific `eventSource` if you want Pydantic validation and typed field access.
+</OptionFilter>
+
+## Bundling
+
+The generator automatically configures Python bundling for Lambda deployment packages using [uv](https://docs.astral.sh/uv/):
+
+<NxCommands commands={['bundle <project-name>']} />
+
+:::note[Bundle Behavior]
+This bundles the whole project as the deployment package. To minimise deployment size, you may wish to split multiple lambda functions over multiple Python projects generated with the <Link path="guides/python-project">`py#project`</Link> generator.
+:::
+
+This process uses:
+
+1. [`uv export`](https://docs.astral.sh/uv/reference/cli/#uv-export) to export your Python dependencies to a `requirements.txt` file
+2. [`uv pip install`](https://docs.astral.sh/uv/reference/cli/#uv-pip-install) to install dependencies for the target platform (`x86_64-manylinux_2_28`) for Lambda deployment
+
+:::note[Architecture Changes]
+If you change your [lambda architecture to ARM](https://docs.aws.amazon.com/lambda/latest/dg/foundation-arch.html), you will need to edit your bundle target to use the `aarch64-manylinux_2_28` target.
+:::
+
+## Deploying your Function
+
+<Snippet name="lambda-function/deploying-your-function" parentHeading="Deploying your Function" />

package/docs/guides/python-project.mdx

@@ -0,0 +1,228 @@
+---
+title: Python Projects
+description: Reference documentation for Python Projects
+generator: py#project
+---
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+
+The Python project generator can be used to create a modern [Python](https://www.python.org/) library or application configured with best practices, managed with [UV](https://docs.astral.sh/uv/), a single lockfile and virtual environment in an [UV workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/), [pytest](https://docs.pytest.org/en/stable/) for running tests, [Ruff](https://docs.astral.sh/ruff/) for static analysis, and [ty](https://docs.astral.sh/ty/) for type checking.
+
+## Usage
+
+### Generate a Python Project
+
+You can generate a new Python project in two ways:
+
+<RunGenerator generator="py#project" />
+
+### Options
+
+<GeneratorParameters generator="py#project" />
+
+## Generator Output
+
+The generator will create the following project structure in the `<directory>/<name>` directory:
+
+<FileTree>
+
+  - \<module-name>
+    - \_\_init\_\_.py Module initialisation
+  - tests
+    - \_\_init\_\_.py Module initialisation
+    - conftest.py Test configuration
+    - test_noop.py Placeholder test
+  - project.json Project configuration and build targets
+  - pyproject.toml Packaging configuration file used by UV
+  - .python-version Contains the project's Python version
+
+</FileTree>
+
+You may also notice the following files created/updated in the root of your workspace:
+
+<FileTree>
+
+  - pyproject.toml Workspace level packaging configuration for UV
+  - .python-version Contains the workspace Python version
+  - uv.lock Lockfile for Python dependencies
+
+</FileTree>
+
+## Writing Python Source Code
+
+Add your Python source code in the `<module-name>` directory.
+
+### Importing your Library Code in Other Projects
+
+Use the `add` target to add a dependency to a Python project.
+
+Suppose we have created two python projects, `my_app` and `my_lib`. These will have fully qualified project names of `my_scope.my_app` and `my_scope.my_lib`, and by default will each have module names of `my_scope_my_app` and `my_scope_my_lib`.
+
+For `my_app` to depend on `my_lib`, we can run the following command:
+
+<NxCommands commands={['run my_scope.my_app:add my_scope.my_lib']} />
+
+:::note[Fully Qualified Names]
+We use the fully qualified project name for both the dependant and dependee. We can use the shorthand syntax for the project we want to add the dependency to, but must fully qualify the name of the project to depend on.
+:::
+
+You can then import your library code:
+
+```python title="packages/my_app/my_scope_my_app/main.py"
+from my_scope_my_lib.my_module import my_function
+```
+
+Above, `my_scope_my_lib` is the module name for the lib, `my_module` corresponds to a Python source file `my_module.py`, and `my_function` is a method defined in that file.
+
+### Dependencies
+
+To add dependencies to your project, you can run the `add` target in your Python project, for example:
+
+<NxCommands commands={['run my_scope.my_library:add some-pip-package']} />
+
+This will add the dependency to your project's `pyproject.toml` file, and update the root `uv.lock`.
+
+#### Runtime Code
+
+When you use your Python project as runtime code (for example as the handler for an AWS lambda function), you will need to create a bundle of the source code and all its dependencies. You can achieve this by adding a target such as the following to your `project.json` file:
+
+```json title="project.json"
+{
+  ...
+  "targets": {
+    ...
+    "bundle": {
+      "cache": true,
+      "executor": "nx:run-commands",
+      "outputs": ["{workspaceRoot}/dist/packages/my_library/bundle"],
+      "options": {
+        "commands": [
+          "uv export --frozen --no-dev --no-editable --project packages/my_library --package my_scope.my_library -o dist/packages/my_library/bundle/requirements.txt",
+          "uv pip install -n --no-deps --no-installer-metadata --no-compile-bytecode --python-platform x86_64-manylinux_2_28 --python `uv python pin` --target dist/packages/my_library/bundle -r dist/packages/my_library/bundle/requirements.txt"
+        ],
+        "parallel": false
+      },
+      "dependsOn": ["compile"]
+    },
+  },
+}
+```
+
+### Building
+
+Your Python 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, test and type check 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>/build`
+
+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
+
+[pytest](https://docs.pytest.org/en/stable/) is configured for testing your project.
+
+### Writing Tests
+
+Tests should be written in the `test` directory within your project, in python files prefixed with `test_`, for example:
+
+<FileTree>
+  - my_library
+    - my_module.py
+  - tests
+    - test_my_module.py Tests for my_module.py
+</FileTree>
+
+Tests are methods which begin with `test_` and make assertions to verify expectations, for example:
+
+```python title="tests/test_my_module.py"
+from my_library.my_module import say_hello
+
+def test_say_hello():
+  assert say_hello("Darth Vader") == "Hello, Darth Vader!"
+```
+
+For more details about how to write tests, please refer to the [pytest documentation](https://docs.pytest.org/en/stable/how-to/assert.html#).
+
+### 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 the `-k` flag, specifying either the name of the test file or method:
+
+<NxCommands commands={["test <project-name> -k 'test_say_hello'"]} />
+
+## Type Checking
+
+Python projects use [ty](https://docs.astral.sh/ty/) for type checking.
+
+### Running the Type Checker
+
+Type checking runs as part of the `build` target for your project, but you can also run it separately via the `typecheck` target:
+
+<NxCommands commands={['run <project-name>:typecheck']} />
+
+### Suppressing Type Errors
+
+To suppress a specific diagnostic for a single line, add a `# ty: ignore[<rule>]` comment at the end of the line, for example:
+
+```python
+value: int = "not an int"  # ty: ignore[invalid-assignment]
+```
+
+To configure type checking behaviour across your project, add a `[tool.ty]` section to your project's `pyproject.toml`. Refer to the [ty configuration reference](https://docs.astral.sh/ty/reference/configuration/) for available options.
+
+## Linting
+
+Python projects use [Ruff](https://docs.astral.sh/ruff/) for linting.
+
+### 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 Ruff 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 Ruff 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/react-website-auth.mdx

@@ -0,0 +1,216 @@
+---
+title: React Website Authentication
+description: Reference documentation for React Website Authentication
+generator: ts#react-website#auth
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+The React Website Authentication generator adds authentication to your React website using [Amazon Cognito](https://aws.amazon.com/cognito/).
+
+This generator configures the CDK or Terraform infrastructure to create a Cognito User Pool and associated Identity Pool, as well as a hosted UI for handling user login flows, and its integration with your React website.
+
+## Usage
+
+### Add Authentication to your React Website
+
+You can add authentication to your React website in two ways:
+
+<RunGenerator generator="ts#react-website#auth" />
+
+### Options
+
+<GeneratorParameters generator="ts#react-website#auth" />
+
+## Generator Output
+
+You will find the following changes in your React website:
+
+<FileTree>
+  - src
+    - components
+      - CognitoAuth
+        - index.tsx Main authentication component
+    - main.tsx Updated to instrument the CognitoAuth component
+</FileTree>
+
+### Infrastructure
+
+<Snippet name="shared-constructs" />
+
+You will also find the following infrastructure code generated based on your selected `iacProvider`:
+
+<Infrastructure>
+<Fragment slot="cdk">
+<FileTree>
+  - packages/common/constructs/src
+    - core
+      - user-identity.ts Construct which defines the user pool and identity pool
+</FileTree>
+</Fragment>
+<Fragment slot="terraform">
+<FileTree>
+  - packages/common/terraform/src
+    - core
+      - user-identity
+        - main.tf Module wrapper for the identity configuration
+        - identity
+          - identity.tf Core identity infrastructure including Cognito User Pool and Identity Pool
+        - add-callback-url
+          - add-callback-url.tf Module for adding callback URLs to existing user pool clients
+</FileTree>
+</Fragment>
+</Infrastructure>
+
+#### Architecture
+
+This generator adds an Amazon Cognito user pool (for sign-in) and an identity pool (for federating signed-in users to scoped IAM credentials) to the existing static-website architecture:
+
+```d2 inline=true
+direction: right
+
+browser: Web Browser {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/client.svg
+}
+
+cognito: Cognito\n(User + Identity Pool) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/cognito.svg
+}
+
+iam: Scoped IAM\nCredentials {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/iam.svg
+}
+
+backend: Authenticated\nAWS Resources {
+  shape: rectangle
+}
+
+browser -> cognito: Sign in
+cognito -> iam
+browser -> backend: IAM/Cognito
+```
+
+## Infrastructure Usage
+
+<Infrastructure>
+<Fragment slot="cdk">
+You will need to add the user identity infrastructure to your stack, declaring it _before_ the website:
+
+```ts title="packages/infra/src/stacks/application-stack.ts" {3,9}
+import { Stack } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { MyWebsite, UserIdentity } from ':my-scope/common-constructs';
+
+export class ApplicationStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    new UserIdentity(this, 'Identity');
+
+    new MyWebsite(this, 'MyWebsite');
+  }
+}
+```
+
+The `UserIdentity` construct automatically adds the necessary <Link path="guides/react-website#runtime-configuration">Runtime Configuration</Link> to ensure that your website can point to the correct Cognito User Pool for authentication.
+
+:::note[SMS role retention]
+The User Pool is backed by an IAM role that Cognito assumes to send SMS messages. The role's removal policy mirrors the User Pool's — by default CDK's `UserPool` uses `RemovalPolicy.RETAIN`, so on `cdk destroy` both the User Pool and its SMS role are retained and will need to be cleaned up manually if no longer needed.
+:::
+</Fragment>
+<Fragment slot="terraform">
+You will need to add the user identity module, and ensure your website depends on it:
+
+```hcl title="packages/infra/src/main.tf" {2-4,14-15}
+# Deploy user identity first to add to runtime config
+module "user_identity" {
+  source = "../../common/terraform/src/core/user-identity"
+}
+
+# Deploy website after identity to include runtime config
+module "my_website" {
+  source = "../../common/terraform/src/app/static-websites/my-website"
+
+  providers = {
+    aws.us_east_1 = aws.us_east_1
+  }
+
+  # Ensure identity is deployed first to add to runtime config
+  depends_on = [module.user_identity]
+}
+```
+
+The user identity module automatically adds the necessary <Link path="guides/react-website#runtime-configuration">Runtime Configuration</Link> to ensure that your website can point to the correct Cognito User Pool for authentication.
+</Fragment>
+</Infrastructure>
+
+### Granting Access to Authenticated Users
+
+In order to grant authenticated users access to perform certain actions, such as granting permissions to invoke an API, you can add IAM policy statements to the identity pool authenticated role:
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts title="packages/infra/src/stacks/application-stack.ts" {12}
+import { Stack } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { MyWebsite, UserIdentity, MyApi } from ':my-scope/common-constructs';
+
+export class ApplicationStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    const identity = new UserIdentity(this, 'Identity');
+    const api = new MyApi(this, 'MyApi');
+
+    api.grantInvokeAccess(identity.identityPool.authenticatedRole);
+
+    new MyWebsite(this, 'MyWebsite');
+  }
+}
+```
+</Fragment>
+<Fragment slot="terraform">
+```hcl title="packages/infra/src/main.tf" {16,26}
+module "user_identity" {
+  source = "../../common/terraform/src/core/user-identity"
+}
+
+module "asset_bucket" {
+  source = "../../common/terraform/src/core/asset-bucket"
+}
+
+module "my_api" {
+  source = "../../common/terraform/src/app/apis/my-api"
+
+  asset_bucket_name = module.asset_bucket.bucket_name
+}
+
+# Add permissions for authenticated users to invoke Fast API
+resource "aws_iam_role_policy" "authenticated_fast_api_invoke" {
+  name = "authenticated-user-invoke-my-api"
+  role = module.user_identity.authenticated_role_name
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Action = [
+          "execute-api:Invoke"
+        ]
+        Resource = "${module.my_api.api_execution_arn}/*"
+      }
+    ]
+  })
+}
+```
+</Fragment>
+</Infrastructure>