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

1. Open the CodeCatalyst console at https://codecatalyst.aws/.

2. In the CodeCatalyst console, navigate to the space where you want to create a project.

3. On the space dashboard, choose Create project.

4. Choose Start with a blueprint.

5. Choose the PDK - Monorepo blueprint, and then choose Next.

6. 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.

7. 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.

8. (Optional) To preview code that will be generated based on the project parameter selections you made, choose View code from Generate project preview.

9. (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.

10. 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.

1. In the navigation pane of your monorepo project, choose Blueprints, and then choose Add blueprint.

2. Choose the PDK - Type Safe API blueprint, and then choose Next.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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.

8. In the navigation pane, choose Blueprints to confirm that the Status of the PDK - Type Safe API shows Up to date.

1. In the navigation pane of your monorepo project, choose Blueprints, and then choose Add blueprint.

2. Choose the PDK - Cloudscape React Website blueprint, and then choose Next.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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.

8. In the navigation pane, choose Blueprints to confirm that the Status of the PDK - Cloudscape React Website shows Up to date.

1. In the navigation pane of your monorepo project, choose Blueprints, and then choose Add blueprint.

2. Choose the PDK - Infrastructure blueprint, and then choose Next.

3. 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).

4. 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.

5. 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.

6. From the Status column, choose Pending pull request for the PDK - Infrastructure blueprint row, and then choose the link of the open pull request.

7. 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.

8. In the navigation pane, choose Blueprints to confirm that the Status of the PDK - Infrastructure shows Up to date.

1. In the navigation pane of your monorepo project, choose Blueprints, and then choose Add blueprint.

2. Choose the PDK - DevOps blueprint, and then choose Next.

3. 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.

4. 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.

5. 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.

6. From the Status column, choose Pending pull request for the PDK - Infrastructure blueprint row, and then choose the link of the open pull request.

7. 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.

8. In the navigation pane, choose Blueprints to confirm that the Status of the PDK - DevOps shows Up to date.

1. In the navigation pane of your monorepo project, choose CI/CD, and then choose Workflows.

2. 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.

3. 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.

   

4. 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.

5. (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).

   
   

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

1. Navigate to your project.

   Tip

   You can choose which project to view in the top navigation bar.

2. In the navigation pane, choose Project settings.

3. Choose the Members tab.

4. In Project members, choose Invite new member.

5. 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

1. Navigate to your project.

   Tip

   You can choose which project to view in the top navigation bar.

2. Choose the Members + button.

3. 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.

1. Open the CodeCatalyst console at https://codecatalyst.aws/.

2. Navigate to your monorepo project where you want to create an issue.

3. On the project home page, choose Create issue. Alternatively, in the navigation pane, choose Issues.

4. Choose Create issue.

   Note

   You can also add issues inline when using a grid view.

5. Enter a title for the issue.

6. (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.

7. (Optional) Choose a Status, Priority, Estimation for the issue.

8. (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.

9. (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.

10. (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.

11. 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.

To navigate to the source repositories for a project

1. 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.

2. 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.

1. 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.

2. Choose a supported IDE from the drop-down menu. See Supported integrated development environments for Dev Environments for more information.

3. Choose Clone a repository.

4. 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.

5. (Optional) In Alias - optional, enter an alias for the Dev Environment.

6. (Optional) Choose the Dev Environment configuration edit button to edit the Dev Environment's compute, storage, or timeout configuration.

7. (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.

8. 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.

1. 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

2. 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.

3. Rename the /say-hello.smithy filename with one that aligns with your code changes (for example, calculate.smithy).

4. 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
       ]
   }

5. 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

6. 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);

7. 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);
     });
   
   });

8. 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("*", "/*", "*")],
         }),
       );
     }
   }

9. Build the changes by running the following command:

   npx projen build

• Commit and push changes to your feature branch by running the following commands:

  git add .

  git commit -m "my commit message"

  git push

1. 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.

2. 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.

3. In Destination branch, choose the main branch to merge the code into after it is reviewed.

4. In Source branch, choose the feature branch that contains the committed code.

5. In Pull request title, enter a title that helps other users understand what needs to be reviewed and why.

6. (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.

7. 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.

8. (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.

9. (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.

10. 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.

11. 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.

1. In the navigation pane of your monorepo project, choose CI/CD, and then choose Workflows.

2. 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.

3. After the workflow run is successfully complete, choose the last action in the workflow (Deploy-Beta-ap-souteast-2), and then choose Variables.

4. View the deployed website by copying and pasting the link from the MyPDKApiwebsiteDistributionDomainNameXXXXX row into a new browser window.

5. Enter the username and password you created in Step 6: Confirm release workflow and view your website, and then choose Sign in.

6. (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.