Prerequisites Step 1: Create a monorepo project Step 2: Add Type Safe API to the project Step 3: Add a Cloudscape React Website for the project Step 4: Generate the infrastructure to deploy the application to AWS cloud Step 5: Set up a DevOps workflow to deploy your project Step 6: Confirm release workflow and view your website Collaborate and iterate on the PDK project

Tutorial: Creating a full-stack application with composable PDK blueprints

Amazon CodeCatalyst provides a number of different blueprints to help you get started with your projects quickly. A project created with a blueprint includes the resources that you need, including a source repository, sample source code, CI/CD workflows, build and test reports, and integrated issue tracking tools. However, sometimes you might want to gradually build out a project, or add functionality to an existing project created by a blueprint. You can also do this with blueprints. This tutorial demonstrates how you can get started with a a single blueprint that sets a foundation and allows you to store all your project code in a single repository. From there, you have the flexibility to incorporate additional resources and infrastructure by adding other blueprints on top of the initial blueprint at your convenience. Through this building-block method, you can address specific requirements across multiple projects.

This tutorial shows how to compose multiple AWS Project Development Kit (AWS PDK) blueprints together to create an application comprising of a React website, Smithy API, and the supporting CDK infrastructure to deploy it to AWS. The AWS PDK provides building blocks for common patterns along with development tools to manage and build your projects. For more information, see the AWS PDK GitHub source repository.

The following PDK blueprints are designed to be used with each other to build an application in a composable fashion:

Monorepo - Creates a root-level project that manages interdependencies between projects within the monorepo. The project also provides build caching and dependency visualization.
Type Safe API - Creates an API that can be defined in either Smithy or OpenAPI v3, and manages build-time code generation to allow you to implement and interact with your API in a type-safe manner. Vends a CDK construct that manages deploying your API to API Gateway and configures automatic input validation.
Cloudscape React website - Creates a React-based website built using Cloudscape that comes preintegrated with Cognito Auth and (optionally) your created API, which provides you with the ability to call your API securely.
Infrastructure - Creates a project that sets up all CDK-related infrastructure needed to deploy your application. It also comes preconfigured to generate a diagram based on your CDK code every time you build.
DevOps - Creates DevOps workflows compatible with constructs found in the AWS Project Development Kit (AWS PDK).

The tutorial also includes steps on how to view the deployed application, invite other users to work on it, and make changes to the code with pull requests that are automatically built and deployed to resources in the connected AWS account when the pull request is merged.

When you create a project comprised of PDK blueprints, your project is created with the following resources in a CodeCatalyst project:

A source repository configured as a monorepo.
A workflow that runs static code analysis and license checking, as well as builds and deploys the sample code whenever a change is made to the default branch. An architecture diagram is generated each time you make changes to the code.
An issues board and backlog that you can use to plan and track work.
A test report suite with automated reports.

Topics

Prerequisites
Step 1: Create a monorepo project
Step 2: Add Type Safe API to the project
Step 3: Add a Cloudscape React Website for the project
Step 4: Generate the infrastructure to deploy the application to AWS cloud
Step 5: Set up a DevOps workflow to deploy your project
Step 6: Confirm release workflow and view your website
Collaborate and iterate on the PDK project

Prerequisites

To create and update a project, you must have completed the tasks in Set up and sign in to CodeCatalyst as follows:

Have an AWS Builder ID for signing in to CodeCatalyst.
Belong to a space and have the Space administrator or Power user role assigned to you in that space. For more information, see Creating a space, Granting users space permissions, and Space administrator role.
Have an AWS account associated with your space and have the IAM role you created during sign-up. For example, during sign-up, you have the option to choose to create a service role with a role policy called the CodeCatalystWorkflowDevelopmentRole-spaceName role policy. The role will have a name CodeCatalystWorkflowDevelopmentRole-spaceName with a unique identifier appended. For more information about the role and role policy, see Understanding the CodeCatalystWorkflowDevelopmentRole-spaceName service role. For the steps to create the role, see Creating the CodeCatalystWorkflowDevelopmentRole-spaceName role for your account and space.

Step 1: Create a monorepo project

Begin with the PDK - Monorepo blueprint to create your monorepo codebase that acts as the foundation, allowing you to add additional PDK blueprints.

To create a project using the PDK - Monorepo blueprint

Open the CodeCatalyst console at https://codecatalyst.aws/.
In the CodeCatalyst console, navigate to the space where you want to create a project.
On the space dashboard, choose Create project.
Choose Start with a blueprint.
Choose the PDK - Monorepo blueprint, and then choose Next.
Under Name your project, enter the name that you want to assign to your project and its associated resource names. The name must be unique within your space.
Under Project resources, do the following:
1. Under Primary programming language, choose a language you want to develop your project code in. You can choose from TypeScript, Java, or Python.
2. Choose Code Configuration
3. In the Source Repository text input field, enter the name of a source repository, which will create a new repository, or select from an existing linked repository. The existing repository must be empty. For more information, see Linking a source repository.
4. (Optional) From the Package Manager dropdown menu, choose a package manager. This is only necessary if you selected TypeScript as your Primary programming language.
(Optional) To preview code that will be generated based on the project parameter selections you made, choose View code from Generate project preview.
(Optional) Choose View details from the blueprint's card to view specific details about the blueprint, such as an overview of the blueprint's architecture, required connections and permissions, and the kind of resources the blueprint creates.
Choose Create project to create your monorepo project. The root-level project created manages interdependencies between projects within the monorepo, as well as provides build caching and dependency management.

For more information about project blueprints, see Creating a comprehensive project with CodeCatalyst blueprints.

The PDK - Monorepo blueprint only generates the foundation of the project. To create a workable application using the blueprint, you need to add other PDK blueprints such as Type Safe API, Cloudscape React Website, Infrastructure, or DevOps. In the next step, you'll add a Type Safe API to the project.

Step 2: Add Type Safe API to the project

The PDK - Type Safe API blueprint allows you to define an API using Smithy or OpenAI v3. It generates runtime packages from your API definition, which include clients for interacting with your API and server-side code for implementing your API. The blueprint also generates a CDK construct with type safety for every API operation. You can add the blueprint to an existing PDK monorepo project to add API capabilities to the project.

To add the PDK - Type Safe API blueprint

In the navigation pane of your monorepo project, choose Blueprints, and then choose Add blueprint.
Choose the PDK - Type Safe API blueprint, and then choose Next.
Under Configure blueprint, configure the blueprint parameters:
- Under Model Language, choose the language the API model is defined in.
- In the Namespace text input field, enter a namespace for your API.
- In the API name text input field, enter a name for your API.
- Under CDK language, choose your preferred language to write CDK infrastructure to deploy the API in.
- Choose the Handler language(s) dropdown menu, and then choose the languages you want to implement handlers for API operations in.
- Choose the Documentation format(s) dropdown menu, and then choose the formats you want for generating API documentation.
In the Code changes tab, review the proposed changes. The difference displayed in a pull request shows the changes to your project at the time the pull request was created.
When you’re satisfied with the proposed changes that will be made when the blueprint is applied, choose Add blueprint.

After a pull request is created, you can add comments. Comments can be added to the pull request or to individual lines in files as well as to the overall pull request. You can add links to resource such as files by using the @ sign, followed by the name of the file.

Note
The blueprint won’t be applied until the pull request is approved and merged. For more information, see Reviewing a pull request and Merging a pull request.
From the Status column, choose Pending pull request for the PDK - Type Safe API blueprint row, and then choose the link of the open pull request.
Choose Merge, choose your preferred merge strategy, and then choose Merge to incorporate changes from the applied blueprint.

After the pull request is merged, a new packages/apis/mypdkapi folder is generated within your monorepo project, which contains all of the API related source code for your configured Type Safe API.
In the navigation pane, choose Blueprints to confirm that the Status of the PDK - Type Safe API shows Up to date.

Step 3: Add a Cloudscape React Website for the project

The PDK - Cloudscape React Website blueprint generates a website. You can associate an optional parameter (Type Safe APIs) to automatically configure your website to set up authenticated type safe clients along with an interactive API explorer to test your various API's.

To add the PDK - Cloudscape React Website blueprint

In the navigation pane of your monorepo project, choose Blueprints, and then choose Add blueprint.
Choose the PDK - Cloudscape React Website blueprint, and then choose Next.
Under Configure blueprint, configure the blueprint parameters:
- In the Website name text input field, enter a name for your website.
- Choose the Type Safe APIs dropdown menu, and then choose the API blueprints you want to integrate within the website. Passing in an API sets up authenticated clients and adds the required dependencies, API explorer, and other capabilities.
In the Code changes tab, review the proposed changes. The difference displayed in a pull request shows the changes to your project at the time the pull request was created.
When you’re satisfied with the proposed changes that will be made when the blueprint is applied, choose Add blueprint.

After a pull request is created, you can add comments. Comments can be added to the pull request or to individual lines in files as well as to the overall pull request. You can add links to resource such as files by using the @ sign, followed by the name of the file.

Note
The blueprint won’t be applied until the pull request is approved and merged. For more information, see Reviewing a pull request and Merging a pull request.
From the Status column, choose Pending pull request for the PDK - Cloudscape React Website blueprint row, and then choose the link of the open pull request.
Choose Merge, choose your preferred merge strategy, and then choose Merge to incorporate changes from the applied blueprint.

After the pull request is merged, a new packages/websites/my-website-name folder is generated within your monorepo project, which contains all the source code for your new website.
In the navigation pane, choose Blueprints to confirm that the Status of the PDK - Cloudscape React Website shows Up to date.

Next, you'll add the PDK - Infrastructure blueprint to generate the infrastructure to deploy your website to the AWS cloud.

Step 4: Generate the infrastructure to deploy the application to AWS cloud

The PDK - Infrastructure blueprint sets up a package containing all of your CDK code to deploy your website and API. It also provides diagram generation and conformance to the prototyping nag pack by default.

To add the PDK - Infrastructure blueprint

In the navigation pane of your monorepo project, choose Blueprints, and then choose Add blueprint.
Choose the PDK - Infrastructure blueprint, and then choose Next.
Under Configure blueprint, configure the blueprint parameters:
- Under CDK language, choose the language you want to develop your infrastructure with.
- In the Stack name text input field, enter a name of the CloudFormation stack generated for your blueprint.
  
  Note
  Keep note of this stack name for the next step, where you'll be setting a DevOps workflow.
- Choose the Type Safe APIs dropdown menu, and then choose the API blueprints you want to integrate within the website.
- Choose the Cloudscape React TS Websites dropdown menu, and then choose website blueprints you want to deploy within your infrastructure (for example, PDK - Cloudscape React Website).
In the Code changes tab, review the proposed changes. The difference displayed in a pull request shows the changes to your project at the time the pull request was created.
When you’re satisfied with the proposed changes that will be made when the blueprint is applied, choose Add blueprint.

After a pull request is created, you can add comments. Comments can be added to the pull request or to individual lines in files as well as to the overall pull request. You can add links to resource such as files by using the @ sign, followed by the name of the file.

Note
The blueprint won’t be applied until the pull request is approved and merged. For more information, see Reviewing a pull request and Merging a pull request.
From the Status column, choose Pending pull request for the PDK - Infrastructure blueprint row, and then choose the link of the open pull request.
Choose Merge, choose your preferred merge strategy, and then choose Merge to incorporate changes from the applied blueprint.

After the pull request is merged, a new packages/infra folder is generated within your monorepo project, which contains the infrastructure that will deploy your project into the AWS cloud.
In the navigation pane, choose Blueprints to confirm that the Status of the PDK - Infrastructure shows Up to date.

Next, you'll add the PDK - DevOps blueprint to deploy your application.

Step 5: Set up a DevOps workflow to deploy your project

The PDK - DevOps blueprint generates the required DevOps workflows to build and deploy your project using the AWS account and role specified in the configuration.

To add the PDK - DevOps blueprint

In the navigation pane of your monorepo project, choose Blueprints, and then choose Add blueprint.
Choose the PDK - DevOps blueprint, and then choose Next.
Under Configure blueprint, configure the blueprint parameters:
- Choose Bootstrap CDK in the current environemnt.
- In the Stack name text input field, enter a name of the CloudFormation stack you want to deploy. This should match the stack name configured in Step 4: Generate the infrastructure to deploy the application to AWS cloud for the PDK - Infrastructure blueprint.
- Choose the AWS account connection dropdown menu, and then choose the AWS account you want to use for the resources. For more information, see Adding an AWS account to a space.
- Choose The role to use for deploying your application dropdown menu, and then choose the IAM role you want to use for deploying your project application.
  
  Note
  When creating an IAM role, restrict the SourceArn to the current ProjectID found within project settings. For more information, see Understanding the CodeCatalystWorkflowDevelopmentRole-spaceName service role.
- Choose the Region dropdown menu, and then choose the region you want to deploy your monorepo project. Deployment only works in regions where the required AWS services exist. For more information, see AWS Services by Region.
In the Code changes tab, review the proposed changes. The difference displayed in a pull request shows the changes to your project at the time the pull request was created.
When you’re satisfied with the proposed changes that will be made when the blueprint is applied, choose Add blueprint.

After a pull request is created, you can add comments. Comments can be added to the pull request or to individual lines in files as well as to the overall pull request. You can add links to resource such as files by using the @ sign, followed by the name of the file.

Note
The blueprint won’t be applied until the pull request is approved and merged. For more information, see Reviewing a pull request and Merging a pull request.
From the Status column, choose Pending pull request for the PDK - Infrastructure blueprint row, and then choose the link of the open pull request.
Choose Merge, choose your preferred merge strategy, and then choose Merge to incorporate changes from the applied blueprint.

After the pull request is merged, a new .codecatalyst/workflows folder is generated within your monorepo project.
In the navigation pane, choose Blueprints to confirm that the Status of the PDK - DevOps shows Up to date.

Note

The PDK - DevOps blueprint and all subsequent changes to PDK blueprints will be significantly slower from this point on because behind the scenes lockfiles are generated to ensure that builds and deployments are repeatable in future. It'll generate lockfiles for all packages across any of the supported languages.

Step 6: Confirm release workflow and view your website

Once you have completed the previous steps, you can confirm the release workflow to ensure the project is being built.

To confirm the release workflow and view your website

In the navigation pane of your monorepo project, choose CI/CD, and then choose Workflows.
For the release workflow, choose the latest workflow run to view the details. For more information, see Viewing the status and details of a single run.
After the workflow run is successfully complete, choose the last action in the workflow (for example, Deploy-Beta-ap-souteast-2, and then choose Variables.
View the deployed website by copying and pasting the link found in the Variables table (for example, MyPDKApiwebsiteDistributionDomainNameXXXXX) into a new browser window.

You need an Amazon Cognito account to log in to your website. By default, the user pool isn't set up to allow self-registration.
1. Navigate to the AWS Cognito console.
2. From the User pools table, choose the User pool name that matches the user pool created by the PDK - DevOps blueprint, which can be found in the Variables table (for example, infracalculatebetaUserIdentityinfracalculatebetaUserIdentityIdentityPoolIdXXXXX. For more information, see Getting started with user pools.
3. Choose Create user.
4. Configure the User information parameters:
  - Under Invitation message, choose Send an email invitation.
  - In the User name text input field, enter a username.
  - In the Email address text input field, enter a username.
  - Under Temporary password, choose Generate a password.
5. Choose Create user.
6. Navigate to the email account you entered for the User information parameters, open an email with a temporary password. Keep note of the password.
7. Navigate back to the deployed website, enter the username you created and the temporary password you received, and then choose Sign in.
(Optional) After the workflow run is successfully complete, you can also view the generated diagram. Choose the Artifacts tab in CodeCatalyst, choose Download for the Diagram row, and then open the downloaded file(s).

Collaborate and iterate on the PDK project

After your project is set up, you can make changes to the source code. You can also invite other space members to work on the project. PDK blueprints allow you to build your application iteratively, only adding on what you need, when you need it, while retaining full control of each blueprint’s configuration.

Topics

Step 1: Invite members to your project
Step 2: Create issues to collaborate and track work
Step 3: View your source repository
Step 4: Create a Dev Environment and make code changes
Step 5: Push and merge code changes

Step 1: Invite members to your project

You can use the console to invite users to your project. You can invite members of your space or add names from outside your space.

To invite users to your project, you must be signed in with the Project administrator or Space administrator role.

You do not need to invite a user with the Space administrator role to your project because they already have implicit access to all projects in the space.

When you invite a user to your project (without assigning the Space administrator role), the user will show in the Project members table under projects and in the Project members table under spaces.

To invite a member to your project from the Project settings tab

Navigate to your project.

Tip
You can choose which project to view in the top navigation bar.
In the navigation pane, choose Project settings.
Choose the Members tab.
In Project members, choose Invite new member.
Type the new member's email address, choose the role for this member, and then choose Invite. For more information about roles, see Granting access with user roles.

To invite a member to your project from the Project overview page

Navigate to your project.

Tip
You can choose which project to view in the top navigation bar.
Choose the Members + button.
Type the new member's email address, choose the role for this member, and then choose Invite. For more information about roles, see Granting access with user roles.

Step 2: Create issues to collaborate and track work

CodeCatalyst helps you track features, tasks, bugs, and any other work involved in your project with issues. You can create issues to track needed work and ideas. By default, when you create an issue it is added to your backlog. You can move issues to a board where you track work in progress. You can also assign an issue to a specific project member. In this step, create an issue to make changes to your PDK project.

To create an issue

Open the CodeCatalyst console at https://codecatalyst.aws/.
Navigate to your monorepo project where you want to create an issue.
On the project home page, choose Create issue. Alternatively, in the navigation pane, choose Issues.
Choose Create issue.

Note
You can also add issues inline when using a grid view.
Enter a title for the issue.
(Optional) Enter a Description. For this issue, enter the following description: a change in the src/mysfit_data.json file.. You can use Markdown to add formatting.
(Optional) Choose a Status, Priority, Estimation for the issue.
(Optional) Add an existing label or create a new label and add it by choosing + Add label.
1. To add an existing label, choose the label from the list. You can enter a search term in the field to search all labels containing that term in the project.
2. To create a new label and add it, enter the name of the label you want to create in the search field and press enter.
(Optional) Add an assignee by choosing + Add an assignee. You can quickly add yourself as the assignee by choosing + Add me.

Tip
You can choose to assign an issue to Amazon Q to have Amazon Q try to solve the issue. For more information, see Tutorial: Using CodeCatalyst generative AI features to speed up your development work.
This functionality requires that generative AI features are enabled for the space. For more information, see Managing generative AI features.
(Optional) Add an existing custom field or create a new custom field. Issues can have multiple custom fields.
1. To add an existing custom field, choose the custom field from the list. You can enter a search term in the field to search all custom fields containing that term in the project.
2. To create a new custom field and add it, enter the name of the custom field you want to create in the search field and press enter. Then choose the type of custom field you want to create and set a value.
Choose Create issue. A notification appears in the lower right corner: If the issue was created successfully, a confirmation message appears saying the issue was successfully created. If the issue was not created successfully, an error message with the reason for the failure appears. You can then choose Retry to edit and retry creating the issue, or choose Discard to discard the issue. Both options will dismiss the notification.

Note
You can't link a pull request to an issue when you create it. However, you can edit it after you create it to add links to pull requests.

For more information, see Track and organize work with issues in CodeCatalyst.

Step 3: View your source repository

You can view the source repositories associated with a project in Amazon CodeCatalyst. For source repositories in CodeCatalyst, the overview page for a repository provides a quick overview of information and activity in that repository, including:

The description of the repository, if any
The number of branches in the repository
The number of open pull requests for the repository
The number of related workflows for the repository
The files and folders in the default branch, or the branch that you choose
The title, author, and date of the last commit to the displayed branch
The contents of the README.md file rendered in Markdown, if any README.md file is included

This page also provides links to the commits, branches, and pull requests for the repository, as well as a quick way to open, view, and edit individual files.

Note

You can't view this information about linked repositories in the CodeCatalyst console. To view information about linked repositories, choose the link in the list of repositories to open that repository in the service that hosts it.

To navigate to the source repositories for a project

Navigate to your project, and do one of the following:
- On the summary page for your project, choose the repository you want from the list, and then choose View repository.
- In the navigation pane, choose Code, and then choose Source repositories. In Source repositories, choose the name of the repository from the list. You can filter the list of repositories by typing part of the repository name in the filter bar.
On the home page for the repository, view the contents of the repository and information about the associated resources such as the number of pull requests and workflows. By default, the contents for the default branch are shown. You can change the view by choosing a different branch from the drop-down list.

Tip

You can also quickly navigate to your project's repositories by choosing See project code from the project summary page.

Step 4: Create a Dev Environment and make code changes

In this step, create a Dev Environment and make code changes that are then merged into the main branch. While this tutorial walks you through a simple AWS PDK project, you can also follow a more complex example provided in the AWS PDK GitHub repository.

To create a Dev Environment with a new branch

In the navigation pane of your monorepo project, do one of the following:
- Choose Overview, and then navigate to the My Dev Environments section.
- Choose Code, and then choose Dev Environments.
- Choose Code, choose Source repositories, and then choose the monorepo repository for which you want to create a Dev Environment.
Choose a supported IDE from the drop-down menu. See Supported integrated development environments for Dev Environments for more information.
Choose Clone a repository.
Choose the repository to clone, choose Work in new branch, enter a branch name into the Branch name field, and choose a branch off of which to create the new branch from the Create branch from drop-down menu.

Note
If you create a Dev Environment from the Source repositories page or from a specific source repository, you don't need to choose a repository. The Dev Environment will be created from the source repository you chose from the Source repositories page.
(Optional) In Alias - optional, enter an alias for the Dev Environment.
(Optional) Choose the Dev Environment configuration edit button to edit the Dev Environment's compute, storage, or timeout configuration.
(Optional) In Amazon Virtual Private Cloud (Amazon VPC) - optional, select a VPC connection that you'd like to associate with your Dev Environment from the drop-down menu.

If a default VPC is set for your space, your Dev Environments will run connected to that VPC. You can override this by associating a different VPC connection. Also, note that VPC-connected Dev Environments don’t support AWS Toolkit.

Note
When you create a Dev Environment with a VPC connection, a new network interface is created inside the VPC. CodeCatalyst interacts with this interface using the associated VPC role. Also, make sure that your IPv4 CIDR block is not configured to the 172.16.0.0/12 IP address range.
Choose Create. While your Dev Environment is being created, the Dev Environment status column will display Starting, and the status column will display Running once the Dev Environment has been created.

After your Dev Environment is running, you can work with your generated sample application in CodeCatalyst by making changes to the code with pull requests that are automatically built and deployed to resources in the connected AWS account when the pull request is merged. The monorepo vends a devfile so all required global dependecies and runtimes are present automatically.

To change code in your project

In a working terminal of your Dev Environment, navigate to your monorepo project, and then install your project dependencies by running the following command:
```
npx projen install
```
Navigate to the packages/apis/mypdkapi/model/src/main/smithy/operations/say-hello.smithy, which defines an example API operation. In this tutorial, you'll build a simple Calculate operation that adds two numbers together. Make a change to the code to define this operation, including its input and output.

Example:
```
$version: "2"
namespace com.aws

@http(method: "POST", uri: "/calculate")
@handler(language: "typescript")
operation Calculate {
    input := {
        @required
        numberA: Integer
        @required
        numberB: Integer
    }
    output := {
        @required
        result: Integer
    }
}
```
The @handler trait tells Type Safe API that you'll implement this operation as an AWS Lambda handler written in TypeScript. The Type Safe API will generate a stub for this operation for you to implement in TypeScript. The @required trait is added, which means it'll be enforced at runtime by the API gateway that gets deployed. For more information, see the Smithy documentation.
Rename the /say-hello.smithy filename with one that aligns with your code changes (for example, calculate.smithy).

Navigate to the packages/apis/mypdkapi/model/src/main/smithy/main.smithy, and make a change to the code to hook up the operation. You can expose the Calculate operation defined in the /calculate.smithy by listing it in the operations field of this file.

Example:


$version: "2"
namespace com.aws

use aws.protocols#restJson1

/// A sample smithy api
@restJson1
service MyPDKApi {
    version: "1.0"
    operations: [Calculate]
    errors: [
      BadRequestError
      NotAuthorizedError
      InternalFailureError
    ]
}

Build the changes by running the following command:
```
npx projen build
```
Note
Optionally, you can pass in --parallel X flag, which will distribute the build across X cores.

Since the @handler trait was added, the following files are generated after the build is complete:
- /packages/apis/mypdkapi/handlers/typescript/src/calculate.ts
- /packages/apis/mypdkapi/handlers/typescript/test/calculate.test.ts

Navigate to the packages/apis/mypdkapi/handlers/typescript/src/calculate.ts, and make changes to the code. This file is the server handler that is invoked for the API.


import {
  calculateHandler,
  CalculateChainedHandlerFunction,
  INTERCEPTORS,
  Response,
  LoggingInterceptor,
} from 'mypdkapi-typescript-runtime';

/**
 * Type-safe handler for the Calculate operation
 */
export const calculate: CalculateChainedHandlerFunction = async (request) => {
  LoggingInterceptor.getLogger(request).info('Start Calculate Operation');

  const { input } = request;

  return Response.success({
    result: input.body.numberA + input.body.numberB,
  });
};

/**
 * Entry point for the AWS Lambda handler for the Calculate operation.
 * The calculateHandler method wraps the type-safe handler and manages marshalling inputs and outputs
 */
export const handler = calculateHandler(...INTERCEPTORS, calculate);

Navigate to the /packages/apis/mypdkapi/handlers/typescript/test/calculate.test.ts file, and make changes to the code to update the unit tests.

Example:


import {
  CalculateChainedRequestInput,
  CalculateResponseContent,
} from 'mypdkapi-typescript-runtime';
import {
  calculate,
} from '../src/calculate';

// Common request arguments
const requestArguments = {
  chain: undefined as never,
  event: {} as any,
  context: {} as any,
  interceptorContext: {
    logger: {
      info: jest.fn(),
    },
  },
} satisfies Omit<CalculateChainedRequestInput, 'input'>;

describe('Calculate', () => {

  it('should return correct sum', async () => {
    const response = await calculate({
      ...requestArguments,
      input: {
        requestParameters: {},
        body: {
          numberA: 1,
          numberB: 2
        }
      },
    });

    expect(response.statusCode).toBe(200);
    expect((response.body as CalculateResponseContent).result).toEqual(3);
  });

});

Navigate to the /packages/infra/main/src/constructs/apis/mypdkapi.ts file, and make changes to the code to add an integration for the Calculate operation in your CDK infrastructure. The API construct has an integrations property, where you can pass in the implementation you added previously. Since you're using the @handler trait in your Smithy model for the Calculate operation, you can use the generated CalculateFunction CDK construct, which is preconfigured, to point to your handler implementation.

Example:


import { UserIdentity } from "@aws/pdk/identity";
import { Authorizers, Integrations } from "@aws/pdk/type-safe-api";
import { Stack } from "aws-cdk-lib";
import { Cors } from "aws-cdk-lib/aws-apigateway";
import {
  AccountPrincipal,
  AnyPrincipal,
  Effect,
  PolicyDocument,
  PolicyStatement,
} from "aws-cdk-lib/aws-iam";
import { Construct } from "constructs";
import { Api, CalculateFunction } from "calculateapi-typescript-infra";

/**
 * Api construct props.
 */
export interface CalculateApiProps {
  /**
   * Instance of the UserIdentity.
   */
  readonly userIdentity: UserIdentity;
}

/**
 * Infrastructure construct to deploy a Type Safe API.
 */
export class CalculateApi extends Construct {
  /**
   * API instance
   */
  public readonly api: Api;

  constructor(scope: Construct, id: string, props?: CalculateApiProps) {
    super(scope, id);

    this.api = new Api(this, id, {
      defaultAuthorizer: Authorizers.iam(),
      corsOptions: {
        allowOrigins: Cors.ALL_ORIGINS,
        allowMethods: Cors.ALL_METHODS,
      },
      integrations: {
        calculate: {
          integration: Integrations.lambda(new CalculateFunction(this, "CalculateFunction"))
        }
      },
      policy: new PolicyDocument({
        statements: [
          // Here we grant any AWS credentials from the account that the prototype is deployed in to call the api.
          // Machine to machine fine-grained access can be defined here using more specific principals (eg roles or
          // users) and resources (ie which api paths may be invoked by which principal) if required.
          // If doing so, the cognito identity pool authenticated role must still be granted access for cognito users to
          // still be granted access to the API.
          new PolicyStatement({
            effect: Effect.ALLOW,
            principals: [new AccountPrincipal(Stack.of(this).account)],
            actions: ["execute-api:Invoke"],
            resources: ["execute-api:/*"],
          }),
          // Open up OPTIONS to allow browsers to make unauthenticated preflight requests
          new PolicyStatement({
            effect: Effect.ALLOW,
            principals: [new AnyPrincipal()],
            actions: ["execute-api:Invoke"],
            resources: ["execute-api:/*/OPTIONS/*"],
          }),
        ],
      }),
    });

    // Grant authenticated users access to invoke the api
    props?.userIdentity.identityPool.authenticatedRole.addToPrincipalPolicy(
      new PolicyStatement({
        effect: Effect.ALLOW,
        actions: ["execute-api:Invoke"],
        resources: [this.api.api.arnForExecuteApi("*", "/*", "*")],
      }),
    );
  }
}

Build the changes by running the following command:
```
npx projen build
```

After your project is finished building, you can view the updated generated diagram, which can be found in the /packages/infra/main/cdk.out/cdkgraph/diagram.png. The diagram shows how the function is added and hooked up to the API created. As the CDK code is modified, this diagram is also updated.

You can now deploy your changes by pushing and merging them to your repository's main branch.

Step 5: Push and merge code changes

Commit and push your code changes, which can then be merged into your source repository's main branch.

To push changes to your feature branch

Commit and push changes to your feature branch by running the following commands:
```
git add .
```
```
git commit -m "my commit message"
```
```
git push
```

Pushing changes triggers a new workflow run for your feature branch, which you can view in the CodeCatalyst console. You can then create a pull request to merge the changes to your source repository's main branch. Merging the feature branch to your main branch triggers the release workflow. You can also link the pull request to your issue.

To create a pull request and link it to your issue

In your monorepo project, do one of the following:
- In the navigation pane, choose Code, choose Pull requests, and then choose Create pull request.
- On the repository home page, choose More, and then choose Create pull request.
- On the project page, choose Create pull request.
In Source repository, make sure that the specified source repository is the one that contains the committed code. This option only appears if you didn't create the pull request from the repository's main page.
In Destination branch, choose the main branch to merge the code into after it is reviewed.
In Source branch, choose the feature branch that contains the committed code.
In Pull request title, enter a title that helps other users understand what needs to be reviewed and why.
(Optional) In Pull request description, provide information such as a link to issues or a description of your changes.

Tip
You can choose Write description for me to have CodeCatalyst automatically generate a description of the changes contained in the pull request. You can make changes to the automatically generated description after you add it to the pull request.
This functionality requires that generative AI features are enabled for the space. For more information, see Managing generative AI features in Amazon CodeCatalyst.
In Issues, choose Link issues, and then choose the issue you created in Step 2: Create issues to collaborate and track work. To unlink an issue, choose the unlink icon.
(Optional) In Required reviewers, choose Add required reviewers. Choose from the list of project members to add them. Required reviewers must approve the changes before the pull request can be merged into the destination branch.

Note
You can't add a reviewer as both a required reviewer and an optional reviewer. You can't add yourself as a reviewer.
(Optional) In Optional reviewers, choose Add optional reviewers. Choose from the list of project members to add them. Optional reviewers do not have to approve the changes as a requirement before the pull request can be merged into the destination branch.
Your pull request must reviewed and merged into the main branch by reviewers or yourself. For more information, see Merging a pull request.

When your changes are merged into the main branch of your source repository, a new workflow is automatically triggered.
After the merge is complete, you can move your issue to Done.
1. In the navigation pane, choose Issues.
2. Choose the issue created in Step 2: Create issues to collaborate and track work, choose the Status dropdown, and then choose Done.

The release workflow deploys your application after a successful run, so you can view the changes.

To confirm the release workflow and view your website

In the navigation pane of your monorepo project, choose CI/CD, and then choose Workflows.
For the release workflow, choose the latest workflow run to view the details. For more information, see Viewing the status and details of a single run.
After the workflow run is successfully complete, choose the last action in the workflow (Deploy-Beta-ap-souteast-2), and then choose Variables.
View the deployed website by copying and pasting the link from the MyPDKApiwebsiteDistributionDomainNameXXXXX row into a new browser window.
Enter the username and password you created in Step 6: Confirm release workflow and view your website, and then choose Sign in.
(Optional) Test the changes in your application.
1. Choose the POST dropdown menu.
2. Enter two values for numberA and number B, and then choose Execute.
3. Confirm the results in Response body.

Over time, the PDK blueprints' catalog versions can change. You can change your project's blueprints to the catalog versions to stay up to date with the latest changes. You can view the code changes and affected environments before changing your project's blueprint versions. For more information, see Changing blueprint versions in a project.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Tutorial: Using generative AI features

Organize resources with spaces