Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md).
# Set up CodeCatalyst projects with blueprints
Blueprints are arbitrary code generators that represent an architectural component of a CodeCatalyst project. The component can consist of anything from a workflow in a single file to the entire project complete with sample code. Blueprints take an arbitrary set of options and use those to generate an arbitrary set of output code that gets forwarded into a project. As the blueprint gets updated with the latest best practices or new options, it can regenerate the relevant parts of your codebase in projects containing that blueprint.
You can use an Amazon CodeCatalyst blueprint to create a full project with a source repository, sample source code, CI/CD workflows, build and test reports, and integrated issue tracking tools. A CodeCatalyst blueprint generates resources and source code based on configuration parameters set. When using a CodeCatalyst-managed blueprint, the blueprint you choose determines which resources are added to your project, as well as the tools that CodeCatalyst creates or configures, so you can track and use your project resources. As a blueprint user, you can create a project with a blueprint or add them to an existing CodeCatalyst project. You can add multiple blueprints in your project, and each can be applied as an independent component. For example, you can have project that was created with a web application blueprint, and then you add a security blueprint at a later time. When one of the blueprints are updated, you can incorporate the changes or fixes in your project through lifecycle management. For more information, see [Creating a comprehensive project with CodeCatalyst blueprintsCreating a comprehensive project with blueprints](project-blueprints.md) and [Working with lifecycle management as a blueprint user](lifecycle-management-user.md).
As a blueprint author, you can also create and publish custom blueprints for your CodeCatalyst space members to use your project resources. The custom blueprints can be developed to meet specified needs for your space's projects. After adding a custom blueprint to your space's blueprints catalog, you can manage the blueprint and continue to make updates so your space's projects stay up to date with the latest best practices. For more information, see [Standardizing projects with custom blueprints in CodeCatalystStandardizing projects with custom blueprints](custom-blueprints.md). To view the blueprints SDK and sample blueprints, see the [open-source GitHub repository](https://github.com/aws/codecatalyst-blueprints).
You may already have standardization and best practices in place. Instead of creating and developing a custom blueprint from scratch, you can choose to convert an existing source repository with source code into a custom blueprint. For more information, see [Converting source repositories to custom blueprints](convert-bp.md).
**Topics**
+ [Creating a project with a blueprint](create-project-with-bp.md)
+ [Adding a blueprint in a project to integrate resources](apply-bp.md)
+ [Disassociating a blueprint from a project to stop updates](disassociate-bp.md)
+ [Changing blueprint versions in a project](update-bp.md)
+ [Editing a desciption for a blueprint in a project](update-settings-bp.md)
+ [Working with lifecycle management as a blueprint user](lifecycle-management-user.md)
+ [Creating a comprehensive project with CodeCatalyst blueprints](project-blueprints.md)
+ [Standardizing projects with custom blueprints in CodeCatalyst](custom-blueprints.md)
+ [Quotas for blueprints in CodeCatalyst](blueprints-quotas.md)
# Creating a project with a blueprint
You can quickly create a project using a blueprint from the Amazon CodeCatalyst blueprints catalog or your team's space catalog with custom blueprints. Depending on the blueprint, your project is created with specific resources. You can also collaborate with Amazon Q, a generative AI assistant, when creating new projects or adding components to existing projects. You can provide Amazon Q with requirements for your project by interacting with it in a chat-like interface. Based on your requirements, Amazon Q suggests a blueprint and also outlines requirements that can’t be met. You can then proceed with Amazon Q’s suggestion if you’re satisfied, and it will create the necessary resources such as a source repository with code for your requirement. For more information, see [Creating a project with a blueprint](projects-create.md#projects-create-console-template), [Best practices when using Amazon Q to create projects or add functionality with blueprints](projects-create.md#projects-create-amazon-q), and [Creating a comprehensive project with CodeCatalyst blueprintsCreating a comprehensive project with blueprints](project-blueprints.md).
After creating a project, you can add additional blueprints to your CodeCatalyst project from the CodeCatalyst catalog or your space's catalog with custom blueprints. Blueprints represent architectural components, so multiple blueprints can be used together in your project to incorporate your team's best practices. This also gives you the ability to make sure your project is up to date with the latest changes to the evolving components. To learn more about working with blueprints in your project, see [Working with lifecycle management as a blueprint user](lifecycle-management-user.md).
# Adding a blueprint in a project to integrate resources
You can add multiple blueprints in a project to incorporate functional components, resources, and governance. Your projects can support various elements that are managed independently in separate blueprints. Adding blueprints to a project reduces the need to manually create resources and make software components functional. Your projects can also stay current as requirements evolve. To learn more about adding blueprints in your project, see [Working with lifecycle management as a blueprint user](lifecycle-management-user.md).
While configuring a blueprint's details, you can also choose to store the blueprint's source code in a preferred third-party repository, where you can still manage the blueprint and utilize the lifecycle management capabilities to keep your project up to date. For more information, see [Add functionality to projects with extensions in CodeCatalystAdd functionality to projects with extensions](extensions.md) and [Working with lifecycle management as a blueprint user](lifecycle-management-user.md).
**Important**
To add a blueprint in your CodeCatalyst project, you must be signed in with an account that has the **Space administrator**, **Power user**, or **Project administrator** role in the space.
**Tip**
After adding a blueprint to your project, you can configure your email and Slack notifications to provide updates for the latest changes to the blueprint. For more information, see [Sending notifications from CodeCatalyst](notifications.md).
**To add a blueprint to your project**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space, and then choose the project where you want to add a blueprint.
1. In the navigation pane, choose **Blueprints**, and then choose **Add blueprint**.
**Tip**
You can choose to add a blueprint by giving **Amazon Q** your project requirements to have Amazon Q suggest a blueprint to you. For more information, see [Using Amazon Q to choose a blueprint when creating a project or adding functionality](getting-started-project-assistance.md#getting-started-project-assistance-create-apply-bp) and [Best practices when using Amazon Q to create projects or add functionality with blueprints](projects-create.md#projects-create-amazon-q). This feature is only available in the US West (Oregon) Region.
This functionality requires that generative AI features are enabled for the space. For more information, see [Managing generative AI features](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-generative-ai-features.html).
1. Choose a blueprint from the **CodeCatalyst blueprints** tab or a custom blueprint from the **Space blueprints** tab, and then choose **Next**.
1. Under **Blueprint details**, choose a blueprint version from the **Target version** dropdown menu. The latest catalog version is automatically selected.
1. (Optional) By default, the source code created by the blueprint is stored in a CodeCatalyst repository. Alternatively, you can choose to store the blueprint's source code in a third-party repository. For more information, see [Add functionality to projects with extensions in CodeCatalystAdd functionality to projects with extensions](extensions.md).
Do one of the following depending on the third-party repository provider you want to use:
+ **GitHub repositories**: Connect a GitHub account.
Choose the **Advanced** dropdown menu, choose GitHub as the repository provider, and then choose the GitHub account where you want to store the source code created by the blueprint.
**Note**
If you're using a connection to a GitHub account, you must create a personal connection to establish identity mapping between your CodeCatalyst identity and your GitHub identity. For more information, see [Personal connections](concepts.md#personal-connection-concept) and [Accessing GitHub resources with personal connections](ipa-settings-connections.md).
+ **Bitbucket repositories**: Connect a Bitbucket workspace.
Choose the **Advanced** dropdown menu, choose Bitbucket as the repository provider, and then choose the Bitbucket workspace where you want to store the source code created by the blueprint.
+ **GitLab repositories**: Connect a GitLab user.
Choose the **Advanced** dropdown menu, choose GitLab as the repository provider, and then choose the GitLab user where you want to store the source code created by the blueprint.
1. Under **Configure blueprint**, configure the blueprint parameters. Depending on the blueprint, you may have the option to name the source repository.
1. Review the differences between the current blueprint version and your updated version. The difference displayed in a pull request shows the changes between the current version and the latest version, which is the desired version at the time the pull request was created. If no changes display, the versions might be identical, or you might have chosen the same version for both the current version and the desired version.
1. When you’re satisfied that the pull request contains the code and changes that you want reviewed, choose **Add blueprint**. After you create the pull request, 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 resourcesuch as filesby 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](pull-requests-review.md) and [Merging a pull request](pull-requests-merge.md).
Blueprint authors can also add a custom blueprint to projects in specified spaces that don't have the blueprint available to create new projects or add to existing projects. For more information, see [Publishing and adding a custom blueprint in specified spaces and projects](publish-bp.md#publish-preview-existing-project-bp).
If you no longer want to receive updates for a blueprint, you can disassociate the blueprint from your project. For more information, see [Disassociating a blueprint from a project to stop updatesDisassociating a blueprint from a project](disassociate-bp.md).
# Disassociating a blueprint from a project to stop updates
If you don't want new updates from a blueprint, you can disassociate the blueprint from your project. Resources and functional software components added to your project from the blueprint will remain in your project.
**Important**
To disassociate a blueprint from your CodeCatalyst project, you must be signed in with an account that has the **Space administrator**, **Power user**, or **Project administrator** role in the space.
**To disassociate a blueprint from your project**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space, and then choose the project where you want to disassociate a blueprint.
1. In the navigation pane, choose **Blueprints**.
1. Choose the blueprint with the resources your want to disassociate, choose the **Actions** dropdown menu, and then choose **Disassociate blueprint**.
1. Enter `confirm` to confirm the disassociation.
1. Choose **Confirm**.
# Changing blueprint versions in a project
If you created a project with a blueprint or added a blueprint to an existing project, then you're notified of new versions of the blueprint. Before the blueprint version is updated through an approved pull request, you can view the code changes and affected environments. Lifecycle management allows you to change versions of one or more applied blueprints in your project, so each blueprint version can be changed without impacting other areas of your project. You can also override blueprint updates. For more information, see [Working with lifecycle management as a blueprint user](lifecycle-management-user.md).
**Important**
To change the version of a blueprint in your CodeCatalyst project, you must be signed in with an account that has the **Space administrator**, **Power user**, or **Project administrator** role in the space.
**Tip**
After adding a blueprint to your project, you can configure your email and Slack notifications to provide updates for the latest changes to the blueprint. For more information, see [Sending notifications from CodeCatalyst](notifications.md).
**To update a blueprint to the latest version**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to update a blueprint's version.
1. On the space dashboard, choose the project with the blueprint that you want to update.
1. In the navigation pane, choose **Blueprints**.
1. In the **Status** column, choose the link to change the catalog version (for example, **Change catalog version 0.3.109)**.
1. Choose the **Actions** dropdown menu, and then choose **Update version**. The latest version is automatically selected.
1. (Optional) Under **Configure blueprint**, configure the blueprint parameters.
1. (Optional) In the **Code changes** tab, review the differences between the current blueprint version and the updated version. The difference displayed in a pull request is the changes between the current version and the latest version, which is the desired version at the time the pull request is created. If no changes display, the versions might be identical, or you might have chosen the same version for both the current version and the desired version.
1. When you’re satisfied that the pull request contains the code and changes that you want reviewed, choose **Apply update**. After you create the pull request, you can add comments. Comments can be added to the pull request or to individual lines in files and to the overall pull request. You can add links to resources such as files by using the `@` sign, followed by the name of the file.
**Note**
The blueprint won’t update until the pull request is approved and merged. For more information, see [Reviewing a pull request](pull-requests-review.md) and [Merging a pull request](pull-requests-merge.md).
**Note**
If you have existing pull requests open for updating a blueprint version, close the previous pull requests before creating a new one. When you choose **Update version**, you will be directed to the list of pending pull requests for the blueprint. You can also view pending pull requests from the **Blueprints** tab in the project **Settings** and the project summary page. For more information, see [Viewing pull requests](pull-requests-view.md).
**To change a blueprint version**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to update a blueprint's version.
1. On the space dashboard, choose the project with the blueprint that you want to update.
1. In the navigation pane, choose **Blueprints**, and then choose the radio button for the blueprint you want to update.
1. Choose the **Actions** dropdown menu, and then choose **Configure blueprint**.
1. From the **Target version** dropdown menu, choose the version that you want to use. The latest version is automatically selected.
1. (Optional) Under **Configure blueprint**, configure the blueprint parameters.
1. (Optional) In the **Code changes** tab, review the differences between the current blueprint version and the updated version. The difference displayed in a pull request is the changes between the current version and the latest version, which is the desired version at the time the pull request is created. If no changes display, the versions might be identical, or you might have chosen the same version for both the current version and the desired version.
1. When you’re satisfied that the pull request contains the code and changes that you want reviewed, choose **Apply update**. After you create the pull request, you can add comments. Comments can be added to the pull request or to individual lines in files and to the overall pull request. You can add links to resources such as files by using the `@` sign, followed by the name of the file.
**Note**
The blueprint won’t update until the pull request is approved and merged. For more information, see [Reviewing a pull request](pull-requests-review.md) and [Merging a pull request](pull-requests-merge.md).
**Note**
If you have existing pull requests open for updating a blueprint version, close the previous pull requests before creating a new one. When you choose **Update version**, you will be directed to the list of pending pull requests for the blueprint. You can also view pending pull requests from the **Blueprints** tab in the project **Settings** and the project summary page. For more information, see [Viewing pull requests](pull-requests-view.md).
# Editing a desciption for a blueprint in a project
You can edit the description of a blueprint that you used to create a project or applied after a project was created. A blueprint can be used more than once in a project. To differentiate the purpose of blueprints in your project, you can use descriptions for those blueprints. Descriptions can also be used to identify the components that you're adding from a specific blueprint.
**Important**
To edit a custom blueprint's description in your space, you must be signed in with an account that has the **Space administrator**, **Power user**, or **Project administrator** role in the space.
**To edit a blueprint's description in your project**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to your space, and then choose the project with the blueprint settings that you want to update.
1. In the navigation pane, choose **Blueprints**.
1. Choose the blueprint with the description that you want to update, choose the **Actions** dropdown menu, and then choose **Settings**.
1. In the **Blueprint description** text input field, enter a description to identify the blueprint in your project.
1. Choose **Save**.
# Working with lifecycle management as a blueprint user
Lifecycle management is the ability to regenerate a codebase from updated options or versions of a blueprint. This allows a blueprint author to centrally manage the software development lifecycle of every project that contains a particular blueprint. For example, pushing a security fix to a web application blueprint will allow every project containing or created from the web application blueprint to pick up that fix automatically. This same management framework also allows you as a blueprint user to change blueprint options after they have been selected.
**Topics**
+ [Using lifecycle management on existing projects](#using-lm-existing-projects)
+ [Using lifecycle management on multiple blueprints in a project](#using-lm-multiple-bp)
+ [Working with conflicts in lifecycle pull requests](#lm-conflicts)
+ [Opting out of lifecycle management changes](#opt-out-lm)
+ [Overriding a blueprint's lifecycle management in a project](#override-updates-lm)
## Using lifecycle management on existing projects
You can use lifecycle management for projects created from blueprints or on existing projects not associated with any blueprints. For example, you can add a standard security practices blueprint into a five-year-old Java application that was never created from a blueprint. The blueprint generates a security scanning workflow and other related code. That portion of the codebase in the Java application will now be kept up to date automatically with your team’s best practices any time changes are made to the blueprint.
## Using lifecycle management on multiple blueprints in a project
Because blueprints represent architectural components, multiple blueprints can often be used together in the same project. For example, a project could be made up of a central web API blueprint built by a company platform engineer, along with a release check blueprint built by the app-security team. Each of those blueprints can be updated independently and will remember merge resolutions applied to them in the past.
**Note**
As arbitrary architectural components, not all blueprints make sense together or will logically work together, even though they will still attempt to merge into each other.
## Working with conflicts in lifecycle pull requests
Occasionally, lifecycle pull requests might generate merge conflicts. These can be manually resolved. Resolutions are remembered on subsequent blueprint updates.
## Opting out of lifecycle management changes
Users can remove a blueprint from a project to disassociate all references to the blueprint and opt out of lifecycle updates. For safety reasons, this doesn’t remove or impact any of the project’s code or resources, including what was added from the blueprint. For more information, see [Disassociating a blueprint from a project to stop updatesDisassociating a blueprint from a project](disassociate-bp.md).
## Overriding a blueprint's lifecycle management in a project
If you want to to override a blueprint’s updates to specific files in your project, you can include an ownership file in your repository. [GitLab’s Code Owners](https://docs.gitlab.com/ee/user/project/codeowners/) spec is the recommended guidelines. The blueprint always respects the code owners file over everything else and can generate a sample one like the following:
```
new BlueprintOwnershipFile(sourceRepo, {
resynthesis: {
strategies: [
{
identifier: 'dont-override-sample-code',
description: 'This strategy is applied accross all sample code. The blueprint will create sample code, but skip attempting to update it.',
strategy: MergeStrategies.neverUpdate,
globs: [
'**/src/**',
'**/css/**',
],
},
],
},
});
```
This generates a `.ownership-file` with the following contents:
```
[dont-override-sample-code] @amazon-codecatalyst/blueprints.import-from-git
# This strategy is applied accross all sample code. The blueprint will create sample code, but skip attempting to update it.
# Internal merge strategy: neverUpdate
**/src/**
**/css/**
```
# Creating a comprehensive project with CodeCatalyst blueprints
When you create a project using a blueprint, CodeCatalyst creates a full project with a source repository, sample source code, CI/CD workflows, build and test reports, and integrated issue tracking tools. A project blueprint uses code to provision cloud infrastructure, resources, and sample source artifacts for different types of applications and frameworks.
For more information, see [Creating a project](projects-create.md). You must be the Space administrator to create a project.
**Topics**
+ [Available blueprints](#projects-list)
+ [Finding project blueprint information](#projects-templates-viewing)
## Available blueprints
| Blueprint name | Blueprint description |
| --- | --- |
| ASP.NET Core web API | This blueprint creates a .NET 6 ASP.NET Core web API application. The blueprint uses the AWS Deployment tool for .NET and provides an option to configure Amazon Elastic Container Service, AWS App Runner, or AWS Elastic Beanstalk as a deployment target. |
| AWS Glue ETL | This blueprint creates a sample extract transform load (ETL) reference implementation using AWS CDK, AWS Glue, AWS Lambda, and Amazon Athena to convert comma-separated values (CSVs) to Apache Parquet. |
| DevOps deployment pipeline | This blueprint creates a deployment pipeline using the AWS Deployment Pipeline Reference Architecture that deploys a reference application to AWS across multiple stages. |
| Java API with AWS Fargate | This blueprint creates a containerized web service project. The project uses [AWS Copilot CLI](https://aws.amazon.com/containers/copilot/) to build and deploy a containerized [Spring Boot](https://spring.io/projects/spring-boot) Java web service backed by Amazon DynamoDB on Amazon ECS. The project deploys a containerized app to an Amazon ECS cluster on AWS Fargate serverless compute. The app stores data in a DynamoDB table. After your workflow runs successfully, the sample web service is publicly available through the Application Load Balancer. |
| Modern three-tier web application | This blueprint generates code in Python for the application layer and Vue front-end framework to build and deploy a well-architected 3-tier modern web application. |
| .NET serverless application | This blueprint creates AWS Lambda functions using .NET CLI Lambda tools. The blueprint provides options for the AWS Lambda functions, including a choice of C\$1 or F\$1. |
| Node.js API with AWS Fargate | This blueprint creates a containerized web service project. The project uses [AWS Copilot CLI](https://aws.amazon.com/containers/copilot/) to build and deploy a containerized [Express/Node.js](https://expressjs.com/) web service on Amazon Elastic Container Service. The project deploys a containerized app to an Amazon ECS cluster on AWS Fargate serverless compute. After your workflow runs successfully, the sample web service is publicly available through the Application Load Balancer. |
| Serverless Application Model (SAM) | This blueprint creates a project that uses a serverless application model (SAM) to create and deploy an API. You can choose SDK for Java, TypeScript, or SDK for Python as the programming language. |
| Serverless RESTful microservice | This blueprint creates a REST API that uses AWS Lambda and Amazon API Gateway with a To Do service reference. You can choose SDK for Java, TypeScript, or SDK for Python as the programming language. |
| Single-page application | This blueprint creates a single-page application (SPA) that uses React, Vue, and Angular frameworks. For hosting, choose from AWS Amplify Hosting or Amazon CloudFront and Amazon S3. |
| Static website | This blueprint creates a static website using [Hugo](https://gohugo.io/) or [Jekyll](https://jekyllrb.com/) static site generators. Static site generators use text input files (such as Markdown) to generate static web pages. They are ideal for rarely-changing, informative content, such as product pages, documentation, and blogs. The blueprint uses the AWS CDK to deploy static web pages to either AWS Amplify or Amazon S3 \$1 CloudFront. |
| To Do web application | This blueprint creates a To Do serverless web application with frontend and backend components. You can choose SDK for Java, TypeScript, or SDK for Python as the programming language. |
| Subscribe to external blueprint | This blueprint creates a workflow for each imported package. These workflows run once a day to check NPM for new versions of the packages. If a new version exists, the workflow attempts to add it to your CodeCatalyst space as a custom blueprint. The action will fail if a package can’t be found or isn’t a blueprint. The target package must be on NPM, and the package must be a blueprint. The space must be subscribed at a tier that supports custom blueprints. |
| Bedrock GenAI chatbot | This blueprint creates a generative AI chatbot with [Amazon Bedrock](https://aws.amazon.com/bedrock/) and [Anthropic’s Claude](https://www.anthropic.com/index/claude-2). With this blueprint, you can build and deploy your own secure, login-protected LLM playground that can be customized to your data. For more information, see the [Bedrock GenAI Chatbot documentation](https://github.com/aws/codecatalyst-blueprints/blob/main/packages/blueprints/gen-ai-chatbot/README.md). |
## Finding project blueprint information
Several project blueprints are available in CodeCatalyst. For each blueprint, there is an accompanying summary and README file. The summary describes the resources that are installed by the blueprint, while the README file explains the blueprint in detail and provides instructions on how to use it.
# Standardizing projects with custom blueprints in CodeCatalyst
You can standardize the development and best practices for your CodeCatalyst space's projects with custom blueprints. Custom blueprints can be used to define various aspects of a CodeCatalyst project, such as workflow definitions and application code. After a custom blueprint is used to create a new project or applied to existing projects, any changes to the blueprint are available to those projects as pull request updates. As a blueprint author, you can view details about which projects are using your blueprints throughout your space, so you can see how standards are being applied across projects. Lifecycle mangement of a blueprint allows you to centrally manage the software development lifecycle of every project, giving you ability to make sure the projects in your space continue to follow best practices with the latest changes or fixes. For more information, see [Working with lifecycle management as a blueprint author](lifecycle-management-dev.md).
Custom blueprints provide the ability to update blueprint versions against the prior project through resynthesis. Resynthesis is the process of rerunning blueprint synthesis with updated versions or the ability to incorporate fixes and changes into existing projects. For more information, see [Custom blueprints concepts](custom-bp-concepts.md).
You may already have standardization and best practices in place. Instead of creating and developing a custom blueprint from scratch, you can choose to convert an existing source repository with source code into a custom blueprint. For more information, see [Converting source repositories to custom blueprints](convert-bp.md).
To view the blueprints SDK and sample blueprints, see the [open-source GitHub repository](https://github.com/aws/codecatalyst-blueprints).
**Topics**
+ [Custom blueprints concepts](custom-bp-concepts.md)
+ [Getting started with custom blueprints](getting-started-bp.md)
+ [Tutorial: Creating and updating a React application](blueprint-getting-started-tutorial.md)
+ [Converting source repositories to custom blueprints](convert-bp.md)
+ [Working with lifecycle management as a blueprint author](lifecycle-management-dev.md)
+ [Developing a custom blueprint to meet project requirements](develop-bp.md)
+ [Publishing a custom blueprint to a space](publish-bp.md)
+ [Setting publishing permissions for a custom blueprint](manage-permissions-bp.md)
+ [Adding a custom blueprint to a space blueprints catalog](add-bp.md)
+ [Changing catalog versions for a custom blueprint](mange-version-bp.md)
+ [Viewing details, versions, and projects of a custom blueprint](view-bp.md)
+ [Removing a custom blueprint from a space blueprints catalog](remove-bp.md)
+ [Deleting a published custom blueprint or version](delete-bp.md)
+ [Handling dependencies, mismatches, and tooling](dependencies-tooling-bp.md)
+ [Contribute](contribute-bp.md)
# Custom blueprints concepts
Here are some concepts and terms that you should know when working with custom blueprints in CodeCatalyst.
**Topics**
+ [Blueprint project](#blueprint-project-concept)
+ [Space blueprints](#space-blueprints-concept)
+ [Space blueprints catalog](#blueprint-catalog-concept)
+ [Synthesis](#synthesis-concept)
+ [Resynthesis](#resynthesis-concept)
+ [Partial options](#partial-options-concept)
+ [Projen](#projen-concept)
## Blueprint project
A blueprint project gives you the ability to develop and publish blueprints to your space. A source repository is created during the project creation process, and the name of the repository is the one you chose when entering the **Project resources** details. During the blueprint creation process, if you choose to generate a workflow release, a publishing workflow is created in your blueprint with the **Blueprint Builder** blueprint. The workflow automatically publishes your latest version.
## Space blueprints
You can view and manage all blueprints from the **Space blueprints** table when you navigate to the **Blueprints** section of your space. After blueprints are published to your space, they are made available as a space blueprint to be added and removed from your space's blueprints catalog. You can also manage publishing permissions and delete blueprints from in the **Blueprints** section of your space. For more information, see [Viewing details, versions, and projects of a custom blueprint](view-bp.md).
## Space blueprints catalog
You can view all added custom blueprints from a space's blueprints catalog. This is where a space member can choose your custom blueprint to create a new project. This catalog is different to the CodeCatalyst catalog, which already has available blueprints for all space members. For more information, see [Creating a comprehensive project with CodeCatalyst blueprintsCreating a comprehensive project with blueprints](project-blueprints.md).
## Synthesis
Synthesis is the process of generating a CodeCatalyst project bundle that represents the source code, configuration, and resources in a project. The bundle is then used by CodeCatalyst deployment API operations to deploy into a project. The process can be run locally while developing your custom blueprint to emulate project creation without having to create a project in CodeCatalyst. The following commands can be used to perform synthesis:
```
yarn blueprint:synth # fast mode
yarn blueprint:synth --cache # wizard emulation mode
```
The blueprint starts itself by calling the main `blueprint.ts` class with that option merged on `defaults.json`. A new project bundle is generated under the `synth/synth.[options-name]/proposed-bundle/` folder. The output includes the project bundle that a custom blueprint generates, given the options you set, including the [partial options](#partial-options-concept) that you may have configured.
## Resynthesis
Resynthesis is the process of regenerating a blueprint with different blueprint options or blueprint versions of existing projects. As a blueprint author, you can define custom merge strategies in the custom blueprint code. You can also define ownership boundaries in an `.ownership-file` to specify in which parts of the codebase a blueprint is permitted to be updated. While the custom blueprint can propose updates to the `.ownership-file`, project developers using the custom blueprint can determine ownership boundaries for their projects. You can run resynthesis locally, and test and update before publishing your custom blueprint. Use the following commands to perform resynthesis:
```
yarn blueprint:resynth # fast mode
yarn blueprint:resynth --cache # wizard emulation mode
```
The blueprint starts itself by calling the main `blueprint.ts` class with that option merged on `defaults.json`. A new project bundle is generated under the `synth/resynth.[options-name]/` folder. The output includes the project bundle that a custom blueprint generates, given the options you set, including the [partial options](#partial-options-concept) that you may have configured.
The following contents are created after the synthesis and resynthesis processes:
+ **proposed-bundle** - The output of synthesis when it is run with new options for the target blueprint version.
+ **existing-bundle** - A mock of your existing project. If there's nothing in this folder, it's generated with the same output as he `proposed-bundle`.
+ **ancestor-bundle** - A mock of what your blueprint would generate when run with either a prior version, prior options, or a combination. If there's nothing in this folder, it's generated with the same output as the `proposed-bundle`.
+ **resolved-bundle** - The bundle is always regenerated and defaults to a three-way merge between the `proposed-bundle`, `existing-bundle`, and the `ancestor-bundle`. This bundle provides an emulation of what a resynthesis would output locally.
To learn more about blueprint output bundles, see [Generating files with resynthesis](merge-strategies-lm.md#three-way-merge-lm).
## Partial options
You can add option variations under `src/wizard-configuration/` that don't have to enumerate the entirety of the `Options` interface, and the options are merged on top of the `defaults.json` file. That allows you to tailor test cases across particular options.
**Example:**
`Options` interface:
```
{
language: "Python" | "Java" | "Typescript",
repositoryName: string
...
}
```
`defaults.json` file:
```
{
language: "Python",
repositoryName: "Myrepo"
...
}
```
Additional configuration tests:
+
```
#wizard-config-typescript-test.json
{
language: "Typescript",
}
```
+
```
#wizard-config-java-test.json
{
language: "Java",
}
```
## Projen
Projen is an open-source tool that custom blueprints use to keep themselves updated and consistent. Blueprints come as Projen packages because this framework provides you with the ability to build, bundle, and publish projects, and you can use the interface to manage a project's configurations and settings.
You can use Projen to update blueprints at scale, even after they're created. The Projen tool is the underlying technology behind the blueprint synthesis that generates a project bundle. Projen owns the configuration for a project, and it shouldn't impact you as a blueprint author. You can run `yarn projen` to regenerate the configuration of your project after adding dependencies, or you can change options in the `projenrc.ts` file. Projen is also the underlying generation tool for custom blueprints to synthesize a project. For more information, see the [projen GitHub page](https://github.com/projen/projen). To learn more about working with Projen, see the [Projen documentation](http://projen.io/).
# Getting started with custom blueprints
During the process of creating a blueprint, you can configure the blueprint and generate a preview of the project resources. Each custom blueprint is managed by a CodeCatalyst project, which contains a workflow by default for publishing to the space's blueprints catalog.
While configuring your custom blueprint's details, you can also choose to store your blueprint's source code in a third-party repository, where you can still manage the custom blueprint and utilize the lifecycle management capabilities to keep your space's projects synchronized when the custom blueprint is modified. For more information, see [Add functionality to projects with extensions in CodeCatalystAdd functionality to projects with extensions](extensions.md) and [Working with lifecycle management as a blueprint author](lifecycle-management-dev.md).
If you already have a source repository with standardization and best practices in place, you can choose to convert that source repository into a custom blueprint. For more information, see [Converting source repositories to custom blueprints](convert-bp.md).
**Topics**
+ [Prerequisites](#prerequisites-bp)
+ [Step 1: Create a custom blueprint in CodeCatalyst](#getting-started-create-bp)
+ [Step 2: Develop a custom blueprint with components](#getting-started-develop-bp)
+ [Step 3: Preview a custom blueprint](#getting-started-publish-bp)
+ [(Optional) Step 4: Publish a custom blueprint preview version](#getting-started-add-bp)
## Prerequisites
Before creating a custom blueprint, consider the following requirements:
+ Your CodeCatalyst space must be the **Enterprise** tier. For more information, see [Managing billing](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-billing-view-plan.html) in the Amazon CodeCatalyst Administrator Guide.
+ You need to have the **Space administrator** or the **Power user** role to create custom blueprints. For more information, see [Granting access with user roles](ipa-roles.md).
## Step 1: Create a custom blueprint in CodeCatalyst
When you create a custom blueprint from your space's settings, a repository is created for you. The repository includes all the required resources that you must have to develop your blueprint before publishing it to the space's blueprints catalog.
**To create a custom blueprint**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to create a custom blueprint.
1. On the space dashboard, choose the **Settings** tab, and then choose **Blueprints**.
1. Choose **Create blueprint**.
1. Under **Name your blueprint**, enter the name that you want to assign to your project and its associated resource names. The name must be unique within your space.
1. (Optional) By default, the source code created by the blueprint is stored in a CodeCatalyst repository. Alternatively, you can choose to store the blueprint's source code in a third-party repository. For more information, see [Add functionality to projects with extensions in CodeCatalystAdd functionality to projects with extensions](extensions.md).
Do one of the following depending on the third-party repository provider you want to use:
+ **GitHub repositories**: Connect a GitHub account.
Choose the **Advanced** dropdown menu, choose GitHub as the repository provider, and then choose the GitHub account where you want to store the source code created by the blueprint.
**Note**
If you're using a connection to a GitHub account, you must create a personal connection to establish identity mapping between your CodeCatalyst identity and your GitHub identity. For more information, see [Personal connections](concepts.md#personal-connection-concept) and [Accessing GitHub resources with personal connections](ipa-settings-connections.md).
+ **Bitbucket repositories**: Connect a Bitbucket workspace.
Choose the **Advanced** dropdown menu, choose Bitbucket as the repository provider, and then choose the Bitbucket workspace where you want to store the source code created by the blueprint.
+ **GitLab repositories**: Connect a GitLab user.
Choose the **Advanced** dropdown menu, choose GitLab as the repository provider, and then choose the GitLab user where you want to store the source code created by the blueprint.
1. Under **Blueprint details**, do the following:
1. In the **Blueprint display name** text input field, enter a name that will appear in your space's blueprints catalog.
1. In the **Description** text input field, enter a description for your custom blueprint.
1. In the **Author name** text input field, enter an author name for your custom blueprint.
1. (Optional) Choose the **Advanced settings**.
1. Choose **\$1 Add** to add tags that are added to the `package.json` file.
1. Choose the **License** dropdown menu, and then choose a license for your custom blueprint.
1. In the **Blueprint package name** text input field, enter a name to identify your blueprint package.
1. By default, a release workflow is generated using a publishing blueprint within your project called **Blueprint Builder**. The workflow publishes the latest blueprint version to your space when you push changes since publishing permissions are enabled by the release workflow. To turn off the workflow generation, uncheck the **Release workflow** checkbox.
1. (Optional) A blueprint project comes with predefined code to support the publishing of the blueprint to the space's blueprints catalog. To view definition files with updates based on the project parameter selections you made, choose **View code** or **View workflow** from **Generate blueprint preview**.
1. Choose **Create blueprint**.
If you didn't turn off the workflow generation for your custom blueprint, the workflow automatically begins to run when your blueprint is created. When the workflow run is complete, your custom blueprint is available to be added to your space's blueprints catalog by default. You can turn off publishing permissions if you don't want the latest blueprint version to be published automatically to your space. For more information, see [Setting publishing permissions for a custom blueprint](manage-permissions-bp.md) and [Running a workflow](workflows-working-runs.md).
Since the publishing workflow called `blueprint-release` is created using a blueprint, the blueprint can be found as an applied blueprint in your project. For more information, see [Adding a blueprint in a project to integrate resources](apply-bp.md) and [Disassociating a blueprint from a project to stop updatesDisassociating a blueprint from a project](disassociate-bp.md).
## Step 2: Develop a custom blueprint with components
A blueprint wizard is generated when you create a custom blueprint, and it can be modified with components when developing the custom blueprint. You can update the `src/blueprints.js` and `src/defaults.json` files to modify the wizard.
**Important**
If you want to use blueprint packages from external sources, consider the risks that may come with those packages. You're responsible for the custom blueprints that you add to your space and the code they generate.
Create a Dev Environment in your CodeCatalyst project with a supported integrated development environment (IDE) before configuring your blueprint code. A Dev Environment is necessary to work with the required tools and packages.
**To create a Dev Environment**
1. In the navigation pane, do one of the following:
1. Choose **Overview**, and then navigate to the **My Dev Environments** section.
1. Choose **Code**, and then choose **Dev Environments**.
1. Choose **Code**, choose **Source repositories**, and choose the repository that you created when creating your blueprint.
1. Choose **Create Dev Environment**.
1. Choose a supported IDE from the dropdown menu. See [Supported integrated development environments for Dev Environments](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment-create.html#devenvironment-supported-ide) for more information.
1. Choose **Work in existing branch**, and from the **Existing branch** dropdown menu, choose the feature branch you created.
1. (Optional) In the **Alias - *optional*** text input field, enter an alias to identify the Dev Environment.
1. Choose **Create**. While your Dev Environment is being created, the Dev Environment status column displays **Starting**, and the status column displays **Running** when the Dev Environment has been created.
For more information, see [Write and modify code with Dev Environments in CodeCatalystWrite and modify code with Dev Environments](devenvironment.md).
**To develop your custom blueprint**
1. In a working terminal, use the following `yarn` command to install dependencies:
```
yarn
```
The required tools and packages are made available through the CodeCatalyst Dev Environment, including Yarn. If you're working on a custom blueprint without a Dev Environment, install Yarn to your system first. For more information, see [Yarn's installation documentation](https://classic.yarnpkg.com/en/docs/install#mac-stable).
1. Develop your custom blueprint so that it's configured to your preferences. You can modify your blueprint's wizard by adding components. For more information, see [Developing a custom blueprint to meet project requirements](develop-bp.md), [Modifying blueprint features with a front-end wizard](wizard-bp.md), and [Publishing a custom blueprint to a space](publish-bp.md).
## Step 3: Preview a custom blueprint
After setting up and developing your custom blueprint, you can preview and publish the preview version of your blueprint to your space. A preview version gives you the ability to check that the blueprint is what you want before it's used to create new projects or applied to existing projects.
**To preview a custom blueprint**
1. In a working terminal, use the following `yarn` command:
```
yarn blueprint:preview
```
1. Navigate to the `See this blueprint at:` link provided to preview your custom blueprint.
1. Check that the UI, including text, appears as you expected based on your configuration. If you want to change your custom blueprint, you can edit the `blueprint.ts` file, resynthesize the blueprint, and then publish a preview version again. For more information, see [Resynthesis](custom-bp-concepts.md#resynthesis-concept).
## (Optional) Step 4: Publish a custom blueprint preview version
You can publish a preview version of your custom blueprint to your space if you want to add it to your space's blueprints catalog. This allows you to view the blueprint as a user before adding the non-preview version to the catalog. The preview version allows you to publish without taking up an actual version. For example, if you work on a `0.0.1` version, you can publish and add a preview version, so new updates for a second version can be published and added as `0.0.2`.
**To publish a preview version of a custom blueprint**
Navigate to the `Enable version [version number] at:` link provided to enable your custom blueprint. This link is provided when running the `yarn` command in [Step 3: Preview a custom blueprint](#getting-started-publish-bp).
After creating, developing, previewing, and publishing your custom blueprint, you can publish and add the final blueprint version to your space's blueprints catalog. For more information, see [Publishing a custom blueprint to a space](publish-bp.md) and [Adding a custom blueprint to a space blueprints catalog](add-bp.md).
# Tutorial: Creating and updating a React application
As a blueprint author, you can develop and add custom blueprints to your space's blueprints catalog. These blueprints can then be used by space members to create new projects or add them to existing projects. You can continue to make changes to your blueprints that are then made available as updates through pull requests.
This tutorial provides a walkthrough from a blueprint author's perspective and a blueprint user's perspective. The tutorial shows how to create a React single-page web application blueprint. The blueprint is then used to create a new project. When the blueprint is updated with changes, the project created from the blueprint incorporates those changes through a pull request.
**Topics**
+ [Prerequisites](#blueprint-getting-started-prerequisites)
+ [Step 1: Create a custom blueprint](#react-bluprint-tutorial-create-bp)
+ [Step 2: View release workflow](#blueprint-getting-started-view-workflow)
+ [Step 3: Add blueprint to catalog](#blueprint-getting-started-add-to-catalog)
+ [Step 4: Create project with blueprint](#blueprint-getting-started-create-project)
+ [Step 5: Update blueprint](#blueprint-getting-started-update-blueprint)
+ [Step 6: Update the blueprint's published catalog version to the new version](#blueprint-getting-started-update-catalog-version)
+ [Step 7: Update project with new blueprint version](#blueprint-getting-started-update-project)
+ [Step 8: View the changes in the project](#blueprint-getting-started-view-changes)
## Prerequisites
To create and update a custom blueprint, you must have completed the tasks in [Set up and sign in to CodeCatalystSet up and sign in to CodeCatalyst](setting-up-topnode.md) 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](spaces-create.md), [Granting users space permissions](spaces-members.md), and [Space administrator role](ipa-role-types.md#ipa-role-space-admin).
## Step 1: Create a custom blueprint
When you create a custom blueprint, a CodeCatalyst project is created that contains your blueprint source code and development tools and resources. Your project is where you will develop, test, and publish the blueprint.
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to create a blueprint.
1. Choose **Settings** to navigate to the space settings.
1. In the **Space settings** tab, choose **Blueprints** and choose **Create blueprint**.
1. Update the fields in the blueprint creation wizard with the following values:
+ In **Blueprint name**, enter `react-app-blueprint`.
+ In **Blueprint Display Name**, enter `react-app-blueprint`.
1. Optionally, choose **View code** to preview the blueprint source code for your blueprint. Likewise, choose **View workflow** to preview the workflow that will be created in the project that builds and publishes the blueprint.
1. Choose **Create blueprint**.
1. Once your blueprint is created, you are taken to the blueprint's project. This project contains the blueprint source code, along with the tools and resources you need to develop, test, and publish the blueprint. A release workflow was generated and it automatically published your blueprint to the space.
1. Now that your blueprint and blueprint project is created, the next step is to configure it by updating the source code. You can use Dev Environments to open and edit your source repository directly in your browser.
In the navigation pane, choose **Code**, and then choose **Dev Environments**.
1. Choose **Create Dev Environment** and then choose **AWS Cloud9 (in browser)**.
1. Keep the default settings and choose **Create**.
1. In the AWS Cloud9 terminal, navigate to your blueprint project directory by running the following command:
```
cd react-app-blueprint
```
1. A `static-assets` folder is created and filled automatically when a blueprint is created. In this tutorial, you will delete the default folder and generate a new one for a react app blueprint.
Delete the static-assets folder by running the following command:
```
rm -r static-assets
```
AWS Cloud9 is built on a Linux-based platform. If you're using a Windows operating system, you can use the following command instead:
```
rmdir /s /q static-assets
```
1. Now that the default folder is deleted, create a `static-assets` folder for a react-app blueprint by running the following command:
```
npx create-react-app static-assets
```
If prompted, enter `y` to proceed.
A new react application was created in the `static-assets` folder with necessary packages. The changes need to pushed to your remote CodeCatalyst source repository.
1. Ensure you have the latest changes, and then commit and push the changes to the blueprint's CodeCatalyst source repository by running the following commands:
```
git pull
```
```
git add .
```
```
git commit -m "Add React app to static-assets"
```
```
git push
```
When a change is pushed to the blueprint's source repository, the release workflow is automatically started. This workflow increments the blueprint version, builds the blueprint, and publishes it to your space. In the next step, you'll navigate to the release workflow run to see how it's doing.
## Step 2: View release workflow
1. In the CodeCatalyst console, in the navigation pane, choose **CI/CD**, and then choose **Workflows**.
1. Choose the **blueprint-release** workflow.
1. You can see the workflow has actions to build and publish the blueprint.
1. Under **Latest run**, choose the workflow run link to view the run from the code change you made.
1. Once the run is completed, your new blueprint version is published. Published blueprint versions can be seen in your space **Settings**, but can't be used in projects until it's added to the space's blueprints catalog. In the next step, you'll add the blueprint to the catalog.
## Step 3: Add blueprint to catalog
Adding a blueprint to the space's blueprints catalog makes the blueprint available for use in all projects in a space. Space members can use the blueprint to create new projects or add them to existing projects.
1. In the CodeCatalyst console, navigate back to the space.
1. Choose **Settings**, and then choose **Blueprints**.
1. Choose **react-app-blueprint**, and then choose **Add to catalog**.
1. Choose **Save**.
## Step 4: Create project with blueprint
Now that the blueprint is added to the catalog, it can be used in projects. In this step, you'll create a project with the blueprint you just created. In a later step, you'll update this project by updating and publishing a new version of the blueprint.
1. Choose the **Projects** tab and then choose **Create project**.
1. Choose **Space blueprints**, and then choose **react-app-blueprint**.
**Note**
Once the blueprint is chosen, you can see the contents of the blueprint's `README.md` file.
1. Choose **Next**.
1.
**Note**
The contents of this project creation wizard can be configured in the blueprint.
Enter the project name as a blueprint user. For this tutorial, enter `react-app-project`. For more information, see [Developing a custom blueprint to meet project requirements](develop-bp.md).
Next, you'll make an update to the blueprint and add the new version to the catalog, which you will use to update this project.
## Step 5: Update blueprint
After a blueprint is used to create a new project or applied to existing projects, you can continue to make updates as a blueprint author. In this step, you'll make changes to the blueprint and automatically publish a new version to the space. The new version can then be added as the catalog version.
1. Navigate to the **react-app-blueprint** project created in [Tutorial: Creating and updating a React application](#blueprint-getting-started-tutorial).
1. Open the Dev Environment created in [Tutorial: Creating and updating a React application](#blueprint-getting-started-tutorial).
1. In the navigation pane, choose **Code**, and then choose **Dev Environments**.
1. From the table, find the Dev Environment, and then choose **Open in AWS Cloud9 (in browser)**.
1. When the blueprint release workflow was run, it incremented the blueprint version by updating the `package.json` file. Pull that change in by running the following command in the AWS Cloud9 terminal:
```
git pull
```
1. Navigate to the `static-assets` folder by running the following command:
```
cd /projects/react-app-blueprint/static-assets
```
1. Create a `hello-world.txt` file in `static-assets` folder by running the following command:
```
touch hello-world.txt
```
AWS Cloud9 is built on a Linux-based platform. If you're using a Windows operating system, you can use the following command instead:
```
echo > hello-world.text
```
1. In the left-hand navigation, double-click the `hello-world.txt` file to open it in the editor, and add the following contents:
```
Hello, world!
```
Save the file.
1. Ensure you have the latest changes, and then commit and push the changes to the blueprint's CodeCatalyst source repository by running the following commands:
```
git pull
```
```
git add .
```
```
git commit -m "prettier setup"
```
```
git push
```
Pushing the changes started the release workflow, which will automatically publish the new version of the blueprint to the space.
## Step 6: Update the blueprint's published catalog version to the new version
After a blueprint is used to create a new project or applied to existing projects, you can still update the blueprint as a blueprint author. In this step, you'll make changes to the blueprint and change the blueprint's catalog version.
1. In the CodeCatalyst console, navigate back to the space.
1. Choose **Settings**, and then choose **Blueprints**.
1. Choose **react-app-blueprint**, and then choose **Manage catalog version**.
1. Choose the new version, and then choose **Save**.
## Step 7: Update project with new blueprint version
A new version is now available in the space's blueprints catalog. As a blueprint user, you can update the version for the project created in [Step 4: Create project with blueprint](#blueprint-getting-started-create-project). This ensures you have the latest changes and fixes needed to meet best practices.
1. In the CodeCatalyst console, navigate to **react-app-project** project created in [Step 4: Create project with blueprint](#blueprint-getting-started-create-project).
1. In the navigation pane, choose **Blueprints**.
1. Choose **Update blueprint** in the info box.
1. In the right-side **Code changes** panel, you can see the `hello-world.txt` and `package.json` updates.
1. Choose **Apply update**.
Choosing **Apply update** creates a pull request in the project with the changes from the updated blueprint version. To make the updates to the project, you must merge the pull request. For more information, see [Reviewing a pull request](pull-requests-review.md) and [Merging a pull request](pull-requests-merge.md).
1. In the **Blueprints** table, find the blueprint. In the **Status** column, choose **Pending pull request**, and then choose the link to the open pull request.
1. Review the pull request, and then choose **Merge**.
1. Choose **Fast forward merge** to keep the the default values, and then choose **Merge**.
## Step 8: View the changes in the project
Changes to the blueprint are now available in your project after [Step 7: Update project with new blueprint version](#blueprint-getting-started-update-project). As a blueprint user, you can view the changes in the source repository.
1. In the navigation pane, choose **Source repositories**, and then choose the name of the source repository created when the project was created.
1. Under **Files**, you can view the `hello-world.txt` file that was created in [Step 5: Update blueprint](#blueprint-getting-started-update-blueprint).
1. Choose the `hello-world.txt` to view the file's content.
Lifecycle management provides blueprint authors the ability centrally manage the software development lifecycle of every project that contains a particular blueprint. As seen in this tutorial, you can push updates to the blueprint that can then be incorporated by projects that used the blueprint to create a new project or applied it to an existing project. For more information, see [Working with lifecycle management as a blueprint author](lifecycle-management-dev.md).
# Converting source repositories to custom blueprints
Custom blueprints allow you to incorporate best practices or new options across multiple projects in a CodeCatalyst space. While you can create and develop a new custom blueprint from scratch, you can also convert an existing CodeCatalyst or third-party source repository with code and established best practices into a blueprint project. You can avoid copying relevant artifacts from that existing repository into a blueprint project. After converting a source repository into a custom blueprint, you can update, publish, and add the blueprint just like any other custom blueprint.
After converting a source repository into a custom blueprint, the source repository is restructured to be a blueprint project, the contents of the repository are moved into a `static-assets` folder within the repository, and relevant assets needed for a blueprint are added into the repository. When the custom blueprint is used to create projects or added to an existing project, workflow definitions stored in the converted source repository is also added to projects by the blueprint.
**Note**
Resources such as environments and secrets aren't included when converting a source repository into a custom blueprint. You need to manually copy or add those resources after converting a source repository into a custom blueprint.
**Important**
To convert a source repository into a custom blueprint, you must be signed in with an account that has the **Project administrator**, **Space administrator**, or **Power user** role in the space.
**To convert a source repository into a custom blueprint from the source repository list**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space, and then choose the project where you want to convert a source repository into a custom blueprint.
1. In the navigation pane, choose **Code**, choose **Source repositories**, and then choose the radio button of the source repository you want to convert into a custom blueprint.
1. Choose **Convert to blueprint** to convert your source repository into a custom blueprint.
You can also convert CodeCatalyst repositories into custom blueprints from the source repository page in the CodeCatalyst console.
**To convert a source repository into a custom blueprint from the source repository page**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space, and then choose the project where you want to convert a source repository into a custom blueprint.
1. In the navigation pane, choose **Code**, choose **Source repositories**, and then choose the name of the CodeCatalyst source repository you want to convert into a custom blueprint.
1. Choose the **More** dropdown menu, and then choose **Convert to blueprint** to convert your source repository into a custom blueprint.
Once your source repository is converted into a custom blueprint, a release workflow is automatically run. After the run is successfully complete, the custom blueprint is published to your space's custom blueprints list. From there, you can add your converted custom blueprint to your space's catalog to create new projects or to be added to existing projects. For more information, see [Publishing a custom blueprint to a space](publish-bp.md) and [Adding a custom blueprint to a space blueprints catalog](add-bp.md).
**Important**
To add a custom blueprint to your space's blueprints catalog, you must be signed in with an account that has the **Space administrator** or **Power user** role in the space.
# Working with lifecycle management as a blueprint author
Lifecycle management allows you to keep a large number of projects synchronized from a single common source of best-practices. This scales the propagation of fixes and the maintenance of any number of projects across their entire software development lifecycle. Lifecycle management streamlines internal campaigns, security fixes, audits, runtime upgrades, changes in best practices, and other maintenance practices because those standards are defined in one place and automatically kept up to date centrally when new standards are published.
When a new version of your blueprint is published, all projects containing that blueprint are prompted to update to the latest version. As a blueprint author, you can also see the version of a particular blueprint that each project contains for compliance purposes. When there are conflicts in an existing source repository, lifecycle management creates pull requests. For all other resources, such as Dev Environment, all lifecycle management updates strictly create new resources. Users are free to merge or not merge those pull requests. When the pending pull requests are merged, the version of the blueprint, including options, used in your project are then updated. To learn about working with lifecycle management as a blueprint user, see [Using lifecycle management on existing projects](lifecycle-management-user.md#using-lm-existing-projects) and [Using lifecycle management on multiple blueprints in a project](lifecycle-management-user.md#using-lm-multiple-bp).
**Topics**
+ [Testing lifecycle management for bundle outputs and merge conflicts](test-lm.md)
+ [Using merge strategies to generate bundles and specifying files](merge-strategies-lm.md)
+ [Accessing context objects for project details](context-objects-lm.md)
# Testing lifecycle management for bundle outputs and merge conflicts
You can locally test your blueprint’s lifecycle management and merge conflict resolution. A series of bundles under the `synth/` directory that represent the various phases of a lifecycle update is generated. To test the lifecycle management, you can run the following yarn command on your blueprint:`yarn blueprint: resynth`. To learn more about resynthesis and bundles, see [Resynthesis](custom-bp-concepts.md#resynthesis-concept) and [Generating files with resynthesis](merge-strategies-lm.md#three-way-merge-lm).
# Using merge strategies to generate bundles and specifying files
You can use merge strategies to generate bundles with resynthesis and specify files for lifecycle management updates of custom blueprints. By leveraging resythensis and merge strategies, you can manage updates and control which files get updated during deployments. You can also write your own strategies to control how changes are merged into existing CodeCatalyst projects.
**Topics**
+ [Generating files with resynthesis](#three-way-merge-lm)
+ [Using merge strategies](#vended-merge-strategies-lm)
+ [Specifying files for lifecycle management updates](#specify-files-lm-updates)
+ [Writing merge strategies](#write-merge-strategies-lm)
## Generating files with resynthesis
Resynthesis can merge the source code produced by a blueprint with source code that was previously generated by same the blueprint, allowing changes to a blueprint to be propagated to existing projects. Merges are run from the `resynth()` function across blueprint output bundles. Resynthesis first generates three bundles representing different aspects of the blueprint and project state. It can be manually run locally with the `yarn blueprint:resynth` command, which will create the bundles if they don’t already exist. Manually working with the bundles will allow you to mock and test resynthesis behavior locally. By default, blueprints only run resynthesis across the repositories under `src/*` since only that portion of the bundle is typically under source control. For more information, see [Resynthesis](custom-bp-concepts.md#resynthesis-concept).
+ `existing-bundle` - This bundle is a representation of the existing project state. This is artificially constructed by the synthesis compute to give the blueprint context about what's in the project it’s deploying into (if anything). If something already exists at this location when running resynthesis locally, it will be reset and respected as a mock. Otherwise, it will be set to the contents of the `ancestor-bundle`.
+ `ancestor-bundle` - This is the bundle that represents the blueprint output if it was synthesized with some previous options and/or version. If this is the first time this blueprint is being added to a project, then the ancestor doesn’t exist, so it’s set to the same contents as the `existing-bundle`. Locally, if this bundle already exists at this location, it will be respected as a mock.
+ `proposed-bundle` - This is the bundle that mocks the blueprint if it was synthesized with some new options and/or version. This is the same bundle that would be produced by the `synth()` function. Locally, this bundle is always overridden.
Each bundle is created during a resynthesis phase that can be accessed from the blueprint class under `this.context.resynthesisPhase`.
+ `resolved-bundle` - This is the final bundle, which is a representation of what gets packaged and deployed to a CodeCatalyst project. You can view which files and diffs are sent to the deployment mechanisms. This is the output of the `resynth()` function resolving merges between the three other bundles.
Three-way merge is applied by taking the difference between the `ancestor-bundle` and `proposed-bundle` and adding that to the `existing-bundle` to generate the `resolved-bundle`. All merge strategies resolve files to the `resolved-bundle`. Resynthesis resolves reach of these bundles with the blueprint’s merge strategies during `resynth()` and produces the resolved bundle from the result.
## Using merge strategies
You can use a merge strategy vended by the blueprints library. These strategies provide ways to resolve file outputs and conflicts for files mentioned in the [Generating files with resynthesis](#three-way-merge-lm) section.
+ `alwaysUpdate` - A strategy that always resolves to the proposed file.
+ `neverUpdate` - A strategy that always resolves to the existing file.
+ `onlyAdd` - A strategy that resolves to the proposed file when an existing file doesn't exist already. Otherwise, resolves to the existing file.
+ `threeWayMerge` - A strategy that performs a three-way merge between the existing, proposed, and common ancestor files. The resolved file may contain conflict markers if the files can't be cleanly merged. The provided files' contents must be UTF-8 encoded in order for the strategy to produce meaningful output. The strategy attempts to detect if the input files are binary. If the strategy detects a merge conflict in a binary file, it always returns the proposed file.
+ `preferProposed` - A strategy that performs a three-way merge between the existing, proposed, and common ancestor files. This strategy resolves conflicts by selecting the proposed file's side of each conflict.
+ `preferExisting` - A strategy that performs a three-way merge between the existing, proposed, and common ancestor files. This strategy resolves conflicts by selecting the existing file's side of each conflict.
To view the source code for the merge strategies, see the [open-source GitHub repository](https://github.com/aws/codecatalyst-blueprints/blob/main/packages/blueprints/blueprint/src/resynthesis/merge-strategies/merge-strategies.ts#L17).
## Specifying files for lifecycle management updates
During resynthesis, blueprints control how changes are merged into an existing source repository. However, you might not want to push updates to every single file in your blueprint. For example, sample code like CSS stylesheets are intended to be project specific. The three-way merge strategy is the default option if you don't specify another strategy. Blueprints can specify which files they own and which files they don’t by specifying merge strategies on the repository construct itself. Blueprints can update their merge strategies, and the latest strategies can be used during resynthesis.
```
const sourceRepo = new SourceRepository(this, {
title: 'my-repo',
});
sourceRepo.setResynthStrategies([
{
identifier: 'dont-override-sample-code',
description: 'This strategy is applied accross all sample code. The blueprint will create sample code, but skip attempting to update it.',
strategy: MergeStrategies.neverUpdate,
globs: [
'**/src/**',
'**/css/**',
],
},
]);
```
Multiple merge strategies can be specified, and the last strategy takes precedence. Uncovered files default to a three-way-merge similar to Git. There are several merge strategies provided through the `MergeStrategies` construct, but you can write your own. The provided strategies adhere to the [git merge strategy](https://git-scm.com/docs/merge-strategies) driver.
## Writing merge strategies
In addition to using one of the provided build merge strategies, you can also write your own strategies. Strategies must adhere to a standard strategy interface. You must write a strategy function that takes versions of a file from the `existing-bundle`, `proposed-bundle`, and `ancestor-bundle`, and merges them into a single resolved file. For example:
```
type StrategyFunction = (
/**
* file from the ancestor bundle (if it exists)
*/
commonAncestorFile: ContextFile | undefined,
/**
* file from the existing bundle (if it exists)
*/
existingFile: ContextFile | undefined,
/**
* file from the proposed bundle (if it exists)
*/
proposedFile: ContextFile | undefined,
options?: {})
/**
* Return: file you'd like in the resolved bundle
* passing undefined will delete the file from the resolved bundle
*/
=> ContextFile | undefined;
```
If the files don’t exist (are undefined), then that file path doesn’t exist in that particular location bundle.
**Example**:
```
strategies: [
{
identifier: 'dont-override-sample-code',
description: 'This strategy is applied across all sample code. The blueprint will create sample code, but skip attempting to update it.',
strategy: (ancestor, existing, proposed) => {
const resolvedfile = ...
...
// do something
...
return resolvedfile
},
globs: [
'**/src/**',
'**/css/**',
],
},
],
```
# Accessing context objects for project details
As a blueprint author, you can access context from the blueprint’s project during synthesis to get information like space and project names, or existing files in a project’s source repository. You can also get details like the phase of resynthesis that the blueprint is generating. For example, you can access context to know if you’re resynthesizing to generate an ancestor bundle or proposed bundle. Existing code context can then be used to transform your code in your repository. For example, you can write your own resynthesis strategy to set specific code standards. The strategy can be added to the `blueprint.ts` file for small blueprints, or you can create a separate file for strategies.
The following example shows how you can find files in a project's context, set a workflow builder, and set a blueprint-vended resynthesis strategy for a particular file:
```
const contextFiles = this.context.project.src.findAll({
fileGlobs: ['**/package.json'],
});
// const workflows = this.context.project.src.findAll({
// fileGlobs: ['**/.codecatalyst/**.yaml'],
// });
const security = new WorkflowBuilder(this, {
Name: 'security-workflow',
});
new Workflow(this, repo, security.getDefinition());
repo.setResynthStrategies([
{
identifier: 'force-security',
globs: ['**/.codecatalyst/security-workflow.yaml'],
strategy: MergeStrategies.alwaysUpdate,
},
]);
for (const contextFile of contextFiles) {
const packageObject = JSON.parse(contextFile.buffer.toString());
new SourceFile(internalRepo, contextFile.path, JSON.stringify({
...packageObject,
}, null, 2));
}
}
```
# Developing a custom blueprint to meet project requirements
Before publishing a custom blueprint, you can develop the blueprint to meet specific requirements. You can develop your custom blueprint and test the blueprint by creating a project when previewing. You can develop the custom blueprint to include project components, such as specific source code, account connections, workflows, issues, or any other component that can be created in CodeCatalyst.
**Important**
If you want to use blueprint packages from external sources, consider the risks that may come with those packages. You're responsible for the custom blueprints that you add to your space and the code they generate.
**Important**
To develop a custom blueprint in your CodeCatalyst space, you must be signed in with an account that has the **Space administrator** or **Power user** role in the space.
**To develop or update a custom blueprint**
1. Resume your Dev Environment. For more information, see [Resuming a Dev Environment](devenvironment-resume.md).
If you don't have a Dev Environment, you must first create one. For more information, see [Creating a Dev Environment](devenvironment-create.md).
1. Open a working terminal in your Dev Environment.
1. If you opted in for a release workflow when creating your blueprint, the latest blueprint version is automatically published. Pull the changes to make sure the `package.json` file has the incremented version. Use the following command:
```
git pull
```
1. In the `src/blueprint.ts` file, edit the options of your custom blueprint. The `Options` interface is interpreted by the CodeCatalyst wizard dynamically to generate a selection user interface (UI). You can develop your custom blueprint by adding components and supported tags. For more information, see [Modifying blueprint features with a front-end wizard](wizard-bp.md), [Adding environment components to a blueprint](comp-env-bp.md), [Adding region components to a blueprint](region-comp-bp.md), [Adding repository and source code components to a blueprint](comp-repo-source-bp.md), [Adding workflow components to a blueprint](comp-workflow-bp.md), and [Adding Dev Environments components to a blueprint](comp-dev-env-bp.md).
You can also view the blueprints SDK and sample blueprints for additional support when developing your custom blueprint. For more information, see the [open-source GitHub repository](https://github.com/aws/codecatalyst-blueprints).
Custom blueprints provide preview bundles as a result of a successful synthesis. The project bundle represents the source code, configuration, and resources in a project, and it's used by CodeCatalyst deployment API operations to deploy into a project. If you want to continue developing your custom blueprint, rerun the blueprint synthesis process. For more information, see [Custom blueprints concepts](custom-bp-concepts.md).
# Modifying blueprint features with a front-end wizard
A blueprint selection wizard on CodeCatalyst is auto-generated by the `Options` interface in the `blueprint.ts` file. The front-end wizard supports modifications and features of a blueprint's `Options` using [JSDOC style comments and tags](https://jsdoc.app/about-getting-started.html). You can use JSDOC style comments and tags to perform tasks. For example, you can select the text displayed above an option, enable features such as input validation, or make an option collapsible. The wizard works by interpreting an abstract syntax tree (AST) generated from the TypeScript type from the `Options` interface. The wizard configures itself automatically to the type described as best as it can. Not all types are supported. Other supported types include the region selector and environment selector.
The following is an example of a wizard that uses JSDOC comments and tags with blueprint's `Options`:
```
export interface Options {
/**
* What do you want to call your new blueprint?
* @validationRegex /^[a-zA-Z0-9_]+$/
* @validationMessage Must contain only upper and lowercase letters, numbers and underscores
*/
blueprintName: string;
/**
* Add a description for your new blueprint.
*/
description?: string;
/**
* Tags for your Blueprint:
* @collapsed true
*/
tags?: string[];
}
```
The display name of each option of the `Options` interface appears in `camelCase` by default. Plain text in the JSDOC style comment is displayed as text above the option in the wizard.
**Topics**
+ [Supported tags](#supported-tags-bp)
+ [Supported TypeScript types](#supported-typescript-bp)
+ [Communicating to the user during synthesis](#communication-mid-synthesis)
## Supported tags
The following JSDOC tags are supported by a custom blueprint's `Options` in the front-end wizard.
### @inlinePolicy ./path/to/policy/file.json
+ **Requires** - Option to be a type `Role`.
+ **Usage** - Allows you to communicate the inline policies a role needs. The `policy.json` path is expected to be under source code. Use this tag when you need a custom policy for a role.
+ **Dependencies** - `blueprint-cli 0.1.12` and above
+ **Example** - `@inlinePolicy ./deployment-policy.json`
```
environment: EnvironmentDefinition{
awsAccountConnection: AccountConnection{
/**
* @inlinePolicy ./path/to/deployment-policy.json
*/
cdkRole: Role[];
};
};
```
### @trustPolicy ./path/to/policy/file.json
+ **Requires** - Option to be a type `Role`.
+ **Usage** - Allows you to communicate the trust policies a role needs. The `policy.json` path is expected to be under source code. Use this tag when you need a custom policy for a role.
+ **Dependencies** - `blueprint-cli 0.1.12` and above
+ **Example** - `@trustPolicy ./trust-policy.json`
```
environment: EnvironmentDefinition{
awsAccountConnection: AccountConnection{
/**
* @trustPolicy ./path/to/trust-policy.json
*/
cdkRole: Role[];
};
};
```
### @validationRegex Regex expression
+ **Requires** - Option to be a string.
+ **Usage** - Performs input validation on the option by using the given regex expression and displays `@validationMessage`.
+ **Example** - `@validationRegex /^[a-zA-Z0-9_]+$/`
+ **Recommendation** - Use with `@validationMessage`. Validation message is empty by default.
### @validationMessage string
+ **Requires** - `@validationRegex` or other errors to review usage.
+ **Usage** - Displays validation message on `@validation*` failure.
+ **Example** - `@validationMessage Must contain only upper and lowercase letters, numbers, and underscores`.
+ **Recommendation** - Use with `@validationMessage`. Validation message is empty by default.
### @collapsed boolean (optional)
+ **Requires** - N/A
+ **Usage** - Boolean that allows a suboption to be collapsible. If the collapsed annotation is present, its default value is true. Setting the value to `@collapsed false` creates a collapsible section that is initially open.
+ **Example** - `@collapsed true`
### @displayName string
+ **Requires** - N/A
+ **Usage** - Changes option display name. Allows formats other than camelCase for the display name.
+ **Example** - `@displayName Blueprint Name`
### @displayName string
+ **Requires** - N/A
+ **Usage** - Changes option display name. Allows formats other than [camelCase](https://en.wikipedia.org/wiki/Camel_case) for the display name.
+ **Example** - `@displayName Blueprint Name`
### @defaultEntropy number
+ **Requires** - Option to be a string.
+ **Usage** - Appends a randomized alphanumeric string of a specified length to the option.
+ **Example** - `@defaultEntropy 5`
### @placeholder string (optional)
+ **Requires** - N/A
+ **Usage** - Changes default text field placeholder.
+ **Example** - `@placeholder type project name here`
### @textArea number (optional)
+ **Requires** - N/A
+ **Usage** - Converts string input into a text area component for larger sections of text. Adding a number defines the number of rows. The default is five rows.
+ **Example** - `@textArea 10`
### @hidden boolean (optional)
+ **Requires** - N/A
+ **Usage** - Hides file from user unless validation check fails. Default value is true.
+ **Example** - `@hidden`
### @button boolean (optional)
+ **Requires** - N/A
+ **Usage** - Annotation must be on a Boolean property. Adds a button that will synthesize as true when chosen. Not a toggle.
+ **Example** - `buttonExample: boolean;`
```
/**
* @button
*/
buttonExample: boolean;
```
### @showName boolean (optional)
+ **Requires** - N/A
+ **Usage** - Can only be used on an account connection type. Shows hidden name input. Defaults to `default_environment`.
+ **Example** - `@showName true`
```
/**
* @showName true
*/
accountConnection: AccountConnection<{
...
}>;
```
### @showEnvironmentType boolean (optional)
+ **Requires** - N/A
+ **Usage** - Can only be used on an account connection type. Shows hidden environment type dropdown menu. All connections default to `production`. Options are **Non-production** or **Production**.
+ **Example** - `@showEnvironmentType true`
```
/**
* @showEnvironmentType true
*/
accountConnection: AccountConnection<{
...
}>;
```
### @forceDefault boolean (optional)
+ **Requires** - N/A
+ **Usage** - Uses the default value provided by the blueprint author instead of the value that was used previously by the user.
+ **Example** - `forceDeafultExample: any;`
```
/**
* @forceDefault
*/
forceDeafultExample: any;
```
### @requires blueprintName
+ **Requires** - Annotates the `Options` interface.
+ **Usage** - Warns user to add specified `blueprintName` to project as a requirement for the current blueprint.
+ **Example** - `@requires '@amazon-codecatalyst/blueprints.blueprint-builder'`
```
/*
* @requires '@amazon-codecatalyst/blueprints.blueprint-builder'
*/
export interface Options extends ParentOptions {
...
```
### @filter regex
+ **Requires** - Annotates the `Selector` or `MultiSelect` interface.
+ **Usage** - Filters dropdown in wizard to options matching the specified regex.
+ **Example** - `@filter /blueprintPackageName/`
```
/**
* @filter /myPackageName/
*/
blueprintInstantiation?: Selector;
...
```
## Supported TypeScript types
The following TypeScript types are supported by a custom blueprint's `Options` in the front-end wizard.
### Number
+ **Requires** - Option to be a type `number`.
+ **Usage** - Generate a number input field.
+ **Example** - `age: number`
```
{
age: number
...
}
```
### String
+ **Requires** - Option to be a type `string`.
+ **Usage** - Generate a string input field.
+ **Example** - `name: string`
```
{
age: string
...
}
```
### String list
+ **Requires** - Option to be an array of type `string`.
+ **Usage** - Generate a string list input.
+ **Example** - `isProduction: boolean`
```
{
isProduction: boolean
...
}
```
### Checkbox
+ **Requires** - Option to be a `boolean`.
+ **Usage** - Generate a checkbox.
+ **Example** - `isProduction: boolean`
```
{
isProduction: boolean
...
}
```
### Radio
+ **Requires** - Option to be a union of three or fewer strings.
+ **Usage** - Generate a radio selected.
**Note**
When there are four or more items, this type renders as a dropdown.
+ **Example** - `color: 'red' | 'blue' | 'green'`
```
{
color: 'red' | 'blue' | 'green'
...
}
```
### Dropdown
+ **Requires** - Option to be a union of four or more strings.
+ **Usage** - Generate a dropdown.
+ **Example** - `runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'`
```
{
runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'
...
}
```
### Expandable section
+ **Requires** - Option to be an object.
+ **Usage** - Generate an expandable section. Options in the object will be nested inside the expandable section in the wizard.
+ **Example** -
```
{
expandableSectionTitle: {
nestedString: string;
nestedNumber: number;
}
}
```
### Tuple
+ **Requires** - Option to be of type `Tuple`.
+ **Usage** - Generate a key-value paid input.
+ **Example** - `tuple: Tuple[string, string]>`
```
{
tuple: Tuple[string, string]>;
...
}
```
### Tuple list
+ **Requires** - Option to be an array of type `Tuple`.
+ **Usage** - Generate a tuple list input.
+ **Example** - `tupleList: Tuple[string, string]>[]`
```
{
tupleList: Tuple[string, string]>[];
...
}
```
### Selector
+ **Requires** - Option to be of type `Selector`.
+ **Usage** - Generate a dropdown of source repositories or blueprints applied to a project.
+ **Example** - `sourceRepo: Selector`
```
{
sourceRepo: Selector;
sourceRepoOrAdd: Selector;
blueprintInstantiation: Selector;
...
}
```
### Multiselect
+ **Requires** - Option to be of type `Selector`.
+ **Usage** - Generate a multiselect input.
+ **Example** - `multiselect: MultiSelect['A' | 'B' | 'C' | 'D' | 'E']>`
```
{
multiselect: MultiSelect['A' | 'B' | 'C' | 'D' | 'E']>;
...
}
```
## Communicating to the user during synthesis
As a blueprint author, you can communicate back to users beyond only validation messages. For example, a space member might view a combination of options that produces a blueprint that isn't clear. Custom blueprints supports the ability to communicate error messages back to users by invoking the synthesis. The base blueprint implements a `throwSynthesisError(...)` function that expects a clear error message. You can invoke the message by using the following:
```
//blueprint.ts
this.throwSynthesisError({
name: BlueprintSynthesisErrorTypes.BlueprintSynthesisError,
message: 'hello from the blueprint! This is a custom error communicated to the user.'
})
```
# Generating inputs and rerendering front-end wizard elements
You can generate wizard inputs with the DynamicKVInput and dynamically create front-end wizard elements for your custom blueprint.
**Topics**
+ [Creating development environments](#dynamickvinput-bp)
+ [Dynamically creating wizard elements](#create-wizard-elements-bp)
## Creating development environments
The DynamicKVInput type can be used to generate front-end wizard inputs using your custom bluerpint's defaults. To view the most up-to-date schema, see the [DynamicKVInput definition](https://github.com/aws/codecatalyst-blueprints/blob/main/packages/blueprints/blueprint/src/ui-selectors/dynamic-kv-input.ts).
The following example shows how you can use `Options` to shape an object:
```
import { DynamicKVInput } from '@amazon-codecatalyst/blueprints.blueprint';
export interface Options extends ParentOptions {
parameters: DynamicKVInput[];
}
```
The following example shows how you canset default parameters with several properties:
```
{
"parameters": [
{
"key": "AWS_REGION",
"value": "us-west-2",
"displayType": "region",
"possibleValues": [
"us-west-1",
"us-west-2",
"us-east-1",
"us-east-2"
],
"displayName": "AWS Region",
"description": "AWS Region to deploy the solution to."
},
{
"key": "SchedulingActive",
"value": "Yes",
"displayType": "dropdown",
"possibleValues": [
"Yes",
"No"
],
"displayName": "Scheduling Active",
"description": "Activate or deactivate scheduling."
},
{
"key": "ScheduledServices",
"value": "Both",
"displayType": "dropdown",
"possibleValues": [
"EC2",
"RDS",
"Both"
],
"displayName": "Scheduled Services",
"description": "Services to schedule."
},
{
"key": "ScheduleRdsClusters",
"value": "No",
"displayType": "dropdown",
"possibleValues": [
"Yes",
"No"
],
"displayName": "Schedule RDS Clusters",
"description": "Enable scheduling of Aurora clusters for RDS service."
},
{
"key": "CreateRdsSnapshot",
"value": "No",
"displayType": "dropdown",
"possibleValues": [
"Yes",
"No"
],
"displayName": "Create RDS Snapshot",
"description": "Create snapshot before stopping RDS instances (does not apply to Aurora Clusters)."
},
{
"key": "MemorySize",
"value": "128",
"displayType": "dropdown",
"possibleValues": [
"128",
"384",
"512",
"640",
"768",
"896",
"1024",
"1152",
"1280",
"1408",
"1536"
],
"displayName": "Memory Size",
"description": "Size of the Lambda function running the scheduler, increase size when processing large numbers of instances."
},
{
"key": "UseCloudWatchMetrics",
"value": "No",
"displayType": "dropdown",
"possibleValues": [
"Yes",
"No"
],
"displayName": "Use CloudWatch Metrics",
"description": "Collect instance scheduling data using CloudWatch metrics."
},
{
"key": "LogRetentionDays",
"value": "30",
"displayType": "dropdown",
"possibleValues": [
"1",
"3",
"5",
"7",
"14",
"30",
"60",
"90",
"120",
"150",
"180",
"365",
"400",
"545",
"731",
"1827",
"3653"
],
"displayName": "Log Retention Days",
"description": "Retention days for scheduler logs."
},
{
"key": "Trace",
"value": "No",
"displayType": "dropdown",
"possibleValues": [
"Yes",
"No"
],
"displayName": "Trace",
"description": "Enable debug-level logging in CloudWatch logs."
},
{
"key": "EnableSSMMaintenanceWindows",
"value": "No",
"displayType": "dropdown",
"possibleValues": [
"Yes",
"No"
],
"displayName": "Enable SSM Maintenance Windows",
"description": "Enable the solution to load SSM Maintenance Windows, so that they can be used for EC2 instance Scheduling."
},
{
"key": "DefaultTimezone",
"value": "UTC",
"displayType": "string",
"displayName": "Default Timezone",
"description": "Default timezone to use for scheduling."
},
{
"key": "Regions",
"value": "us-west-2",
"displayType": "string",
"displayName": "Regions",
"description": "List of regions in which instances should be scheduled, leave blank for current region only."
},
{
"key": "UsingAWSOrganizations",
"value": "No",
"displayType": "dropdown",
"possibleValues": [
"Yes",
"No"
],
"displayName": "Using AWS Organizations",
"description": "Use AWS Organizations to automate spoke account registration."
},
{
"key": "Principals",
"displayType": "string",
"optional": false,
"displayName": "Principals",
"description": "(Required) If using AWS Organizations, provide the Organization ID. Eg. o-xxxxyyy. Else, provide a comma separated list of spoke account ids to schedule. Eg.: 1111111111, 2222222222 or {param: ssm-param-name}"
},
{
"key": "Namespace",
"value": "Default",
"displayType": "string",
"displayName": "Namespace",
"description": "Provide unique identifier to differentiate between multiple solution deployments (No Spaces). Example: Dev"
},
{
"key": "SchedulerFrequency",
"value": 5,
"displayType": "number",
"displayName": "Scheduler Frequency",
"description": "Scheduler running frequency in minutes."
}
]
}
```
## Dynamically creating wizard elements
The same schema as creating wizard inputs can be used to dynamically rerender a wizard during synthesis. That can be used to address follow-up questions by a user when necessary.
```
//blueprint.ts
export interface Options extends ParentOptions {
...
dynamicOptions: OptionsSchemaDefinition<'optionsIdentifier', KVSchema>;
}
```
The wizard can then be set during synthesis period by using an `Options` component.
```
import {
OptionsSchemaDefinition,
OptionsSchema,
} from '@amazon-codecatalyst/blueprints.blueprint';
...
// dynamically renders a number in the place where 'optionsIdentifier' was set in the original options type.
new OptionsSchema(this, 'optionsIdentifier', [
{
"key": "SchedulerFrequency",
"value": 5,
"displayType": "number",
"displayName": "Scheduler Frequency",
"description": "Scheduler running frequency in minutes."
}
]);
```
# Adding environment components to a blueprint
The custom blueprint wizard is dynamically generated from the `Options` interface exposed through the wizard. Blueprints support generating user-interface (UI) components from exposed types.
**To import Amazon CodeCatalyst blueprints environment components**
In your `blueprint.ts` file, add the following:
```
import {...} from '@amazon-codecatalyst/codecatalyst-environments'
```
**Topics**
+ [Creating development environments](#create-dev-env-bp)
+ [List of environments](#list-env-bp)
+ [Mock interface examples](#examples-comp-env-bp)
## Creating development environments
The following example shows how to deploy your application to the cloud:
```
export interface Options extends ParentOptions {
...
myNewEnvironment: EnvironmentDefinition{
thisIsMyFirstAccountConnection: AccountConnection{
thisIsARole: Role['lambda', 's3', 'dynamo'];
};
};
}
```
The interface generates a UI component that asks for a new environment (`myNewEnvironment`) with a single account connection (`thisIsMyFirstAccountConnection`. A role on the account connection (`thisIsARole`) is also generated with `['lambda', 's3', 'dynamo']` as the minimum required role capabilities. Not all users have account connections, so you should check for the case where a user doesn't connect an account or doesn't connect an account with a role. Roles can also be annotated with `@inlinePolicies`. For more information, see [@inlinePolicy ./path/to/policy/file.json](wizard-bp.md#inline-policy-tag).
The environment component requires a `name` and `environmentType`. The following code is the minimum required default shape:
```
{
...
"myNewEnvironment": {
"name": "myProductionEnvironment",
"environmentType": "PRODUCTION"
},
}
```
The UI component then prompts you for various fields. As you fill in the fields, the blueprint gets a fully expanded shape. It can be helpful for you to include the full mock in the `defaults.json` file for testing and development purposes.
## List of environments
Specifying an array of type `EnvironmentDefinition` will generate a list of environments in the wizard UI.
```
export interface Options extends ParentOptions {
...
/**
@showName readOnly
*/
myEnvironments: EnvironmentDefinition<{
thisIsMyFirstAccountConnection: AccountConnection<{
thisIsARole: Role<['lambda', 's3', 'dynamo']>;
}>;
}>[];
}
```
The following example shows the defaults for an environment list:
```
{
...
"myEnvironments": [
{
"name": "myProductionEnvironment",
"environmentType": "PRODUCTION"
},
{
"name": "myDevelopmentEnvironment",
"environmentType": "DEVELOPMENT"
},
]
}
```
## Mock interface examples
### Simple mock interface
```
{
...
"thisIsMyEnvironment": {
"name": "myProductionEnvironment",
"environmentType": "PRODUCTION",
"thisIsMySecondAccountConnection": {
"id": "12345678910",
"name": "my-account-connection-name",
"secondAdminRole": {
"arn": "arn:aws:iam::12345678910:role/ConnectedQuokkaRole",
"name": "ConnectedQuokkaRole",
"capabilities": [
"lambda",
"s3",
"dynamo"
]
}
}
}
}
```
### Complex mock interface
```
export interface Options extends ParentOptions {
/**
* The name of an environment
* @displayName This is a Environment Name
* @collapsed
*/
thisIsMyEnvironment: EnvironmentDefinition{
/**
* comments about the account that is being deployed into
* @displayName This account connection has an overriden name
* @collapsed
*/
thisIsMyFirstAccountConnection: AccountConnection{
/**
* Blah blah some information about the role that I expect
* e.g. here's a copy-pastable policy: [to a link]
* @displayName This role has an overriden name
*/
adminRole: Role['admin', 'lambda', 's3', 'cloudfront'];
/**
* Blah blah some information about the second role that I expect
* e.g. here's a copy-pastable policy: [to a link]
*/
lambdaRole: Role['lambda', 's3'];
};
/**
* comments about the account that is being deployed into
*/
thisIsMySecondAccountConnection: AccountConnection{
/**
* Blah blah some information about the role that I expect
* e.g. here's a copy-pastable policy: [to a link]
*/
secondAdminRole: Role['admin', 'lambda', 's3', 'cloudfront'];
/**
* Blah blah some information about the second role that I expect
* e.g. here's a copy-pastable policy: [to a link]
*/
secondLambdaRole: Role['lambda', 's3'];
};
};
}
```
### Complete mock interface
```
{
...
"thisIsMyEnvironment": {
"name": "my-production-environment",
"environmentType": "PRODUCTION",
"thisIsMySecondAccountConnection": {
"id": "12345678910",
"name": "my-connected-account",
"secondAdminRole": {
"name": "LambdaQuokkaRole",
"arn": "arn:aws:iam::12345678910:role/LambdaQuokkaRole",
"capabilities": [
"admin",
"lambda",
"s3",
"cloudfront"
]
},
"secondLambdaRole": {
"name": "LambdaQuokkaRole",
"arn": "arn:aws:iam::12345678910:role/LambdaQuokkaRole",
"capabilities": [
"lambda",
"s3"
]
}
},
"thisIsMyFirstAccountConnection": {
"id": "12345678910",
"name": "my-connected-account",
"adminRole": {
"name": "LambdaQuokkaRole",
"arn": "arn:aws:iam::12345678910:role/LambdaQuokkaRole",
"capabilities": [
"admin",
"lambda",
"s3",
"cloudfront"
]
},
"lambdaRole": {
"name": "LambdaQuokkaRole",
"arn": "arn:aws:iam::12345678910:role/LambdaQuokkaRole",
"capabilities": [
"lambda",
"s3"
]
}
}
},
}
```
# Adding secrets components to a blueprint
Secrets can be used in CodeCatalyst to store sensitive data that can be referenced in workflows. You can add a secret to your custom blueprint and reference it in your workflow. For more information, see [Masking data using secrets](workflows-secrets.md).
**To import Amazon CodeCatalyst blueprints region type**
In your `blueprint.ts` file, add the following:
```
import { Secret, SecretDefinition } from '@amazon-codecatalyst/blueprint-component.secrets'
```
**Topics**
+ [Creating a secret](#comp-create-secrets-bp)
+ [Referencing a secret in a workflow](#comp-reference-secrets-bp)
## Creating a secret
The following example creates a UI component that prompts the user to enter a secret value and optional description:
```
export interface Options extends ParentOptions {
...
mySecret: SecretDefinition;
}
export class Blueprint extends ParentBlueprint {
constructor(options_: Options) {
new Secret(this, options.secret);
}
```
The secret component requires a `name`. The following code is the minimum required default shape:
```
{
...
"secret": {
"name": "secretName"
},
}
```
## Referencing a secret in a workflow
The following example blueprint creates a secret and a workflow that references the secret value. For more information, see [Referencing a secret in a workflow](workflows-secrets.using.md#workflows-using-secrets.using-identifier).
```
export interface Options extends ParentOptions {
...
/**
*
* @validationRegex /^\w+$/
*/
username: string;
password: SecretDefinition;
}
export class Blueprint extends ParentBlueprint {
constructor(options_: Options) {
const password = new Secret(this, options_.password);
const workflowBuilder = new WorkflowBuilder(this, {
Name: 'my_workflow',
});
workflowBuilder.addBuildAction({
actionName: 'download_files',
input: {
Sources: ['WorkflowSource'],
},
output: {
Artifacts: [{ Name: 'download', Files: ['file1'] }],
},
steps: [
`curl -u ${options_.username}:${password.reference} https://example.com`,
],
});
new Workflow(
this,
repo,
workflowBuilder.getDefinition(),
);
}
```
To learn more about using secrets in CodeCatalyst, see [Masking data using secrets](workflows-secrets.md).
# Adding region components to a blueprint
The region type can be added to your custom blueprint's `Options` interface to generate a component in the blueprint wizard you can input one or more AWS gions. The gion type can be imported from your base blueprint in your `blueprint.ts` file. For more information, see [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/).
**To import Amazon CodeCatalyst blueprints region type**
In your `blueprint.ts` file, add the following:
```
import { Region } from '@amazon-codecatalyst/blueprints.blueprint'
```
The region type parameter is an array of AWS region codes to choose from, or you can use `*` to include all supported AWS regions.
**Topics**
+ [Annotations](#region-annotations-bp)
+ [Region components examples](#region-components-examples)
## Annotations
JSDoc tags can be added to each field in the `Options` interface to customize how a field appears and behaves in the wizard. For the region type, the following tags are supported:
+ The `@displayName` annotation can be used to change the field's label in the wizard.
Example: `@displayName AWS Region`
+ The `@placeholder` annotation can be used to change the select/multiselect component's placeholder.
Example: `@placeholder Choose AWS Region`
## Region components examples
### Choosing a region from a specified list
```
export interface Options extends ParentOptions {
...
/**
* @displayName Region
*/
region: Region<['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2']>;
}
```
### Choosing one or more regions from a specified list
```
export interface Options extends ParentOptions {
...
/**
* @displayName Regions
*/
multiRegion: Region<['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2']>[];
}
```
### Choosing one AWS egion
```
export interface Options extends ParentOptions {
...
/**
* @displayName Region
*/
region: Region<['*']>;
}
```
### Choosing one or more regions from a specified list
```
export interface Options extends ParentOptions {
...
/**
* @displayName Regions
*/
multiRegion: Region<['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2']>[];
}
```
# Adding repository and source code components to a blueprint
A repository is used by Amazon CodeCatalyst to store code. The repository takes a name as an input. Most components are stored in a repository, such as source code files, workflows, and other components like managed development environments (MDE). The source repository component also exports components used for managing files and static assets. Repositories have name constraints. For more information, see [Store and collaborate on code with source repositories in CodeCatalystStore and collaborate on code with source repositories](source.md).
```
const repository = new SourceRepository(this, {
title: 'my-new-repository-title',
});
```
**To import Amazon CodeCatalyst blueprints repository and source code components**
In your `blueprint.ts` file, add the following:
```
import {...} from '@caws-blueprint-component/caws-source-repositories'
```
**Topics**
+ [Adding a file](#repo-add-file-bp)
+ [Adding a generic file](#repo-add-generic-file-bp)
+ [Copying files](#repo-copy-file-bp)
+ [Targeting multiple files](#target-multiple-files-bp)
+ [Creating a new repository and adding files](#repo-code-examples-bp)
## Adding a file
You can write a text file to a repository with the `SourceFile` construct. The operation is one of the most common use cases and takes a repository, a filepath, and text contents. If the file path doesn't exist within a repository, the component creates all the required folders.
```
new SourceFile(repository, `path/to/my/file/in/repo/file.txt`, 'my file contents');
```
**Note**
If you write two files to the same location within the same repository, the most recent implementation overwrites the previous one. You can use the feature to layer generated code, and it's especially useful for extending over the code that the custom blueprints may have generated.
## Adding a generic file
You can write arbitrary bits to your repository. You can read from a buffer and use the `File` construct.
```
new File(repository, `path/to/my/file/in/repo/file.img`, new Buffer(...));
new File(repository, `path/to/my/file/in/repo/new-img.img`, new StaticAsset('path/to/image.png').content());
```
## Copying files
You can get started with generated code by copying and pasting starter code and then generating more code on top of that base. Place the code inside the `static-assets` directory, and then target that code with the `StaticAsset` construct. The path in this case always begins at the root of the `static-assets` directory.
```
const starterCode = new StaticAsset('path/to/file/file.txt')
const starterCodeText = new StaticAsset('path/to/file/file.txt').toString()
const starterCodeRawContent = new StaticAsset('path/to/image/hello.png').content()
const starterCodePath = new StaticAsset('path/to/image/hello.png').path()
// starterCodePath is equal to 'path/to/image/hello.png'
```
A subclass of `StaticAsset` is `SubstitutionAsset`. The subclass functions exactly the same, but instead you can run a mustache substitution over the file instead. It can be useful for performing copy-and-replace style generation.
Static asset substitution uses a mustache templating engine to render the static files that are seeded into the generated source repository. Mustache templating rules are applied during the rendering, which means that all values are HTML-encoded by default. To render unescaped HTML, use the triple mustache syntax `{{{name}}}`. For more information, see the [mustache templating rules](https://github.com/janl/mustache.js?tab=readme-ov-file#variables).
**Note**
Running a substitute over files that aren't text-interpretable can produce errors.
```
const starterCodeText = new SubstitionAsset('path/to/file/file.txt').subsitite({
'my_variable': 'subbed value1',
'another_variable': 'subbed value2'
})
```
## Targeting multiple files
Static assets support glob targeting through a static function on `StaticAsset` and its subclasses called `findAll(...)`, which returns a list of static assets preloaded with their paths, contents, and more. You can chain the list with `File` constructions to copy and paste contents in the `static-assets` directory.
```
new File(repository, `path/to/my/file/in/repo/file.img`, new Buffer(...));
new File(repository, `path/to/my/file/in/repo/new-img.img`, new StaticAsset('path/to/image.png').content());
```
## Creating a new repository and adding files
You can use a repository component to create a new repository in a generated project. You can then add files or workflows to the created repository.
```
import { SourceRepository } from '@amazon-codecatalyst/codecatalyst-source-repositories';
...
const repository = new SourceRepository(this, { title: 'myRepo' });
```
The following example shows how to add files and workflows to an existing repository:
```
import { SourceFile } from '@amazon-codecatalyst/codecatalyst-source-repositories';
import { Workflow } from '@amazon-codecatalyst/codecatalyst-workflows';
...
new SourceFile(repository, 'README.md', 'This is the content of my readme');
new Workflow(this, repository, {/**...workflowDefinition...**/});
```
Combining the two pieces of code generates a single repository named `myRepo` with a source file `README.md` and a CodeCatalyst workflow at the root.
# Adding workflow components to a blueprint
A workflow is used by Amazon CodeCatalyst projects to run actions based on triggers. You can use workflow components to build and put together workflow YAML files. For more information, see [Workflow YAML definition](workflow-reference.md).
**To import Amazon CodeCatalyst blueprints workflows components**
In your `blueprint.ts` file, add the following:
```
import { WorkflowBuilder, Workflow } from '@amazon-codecatalyst/codecatalyst-workflows'
```
**Topics**
+ [Workflow components examples](#comp-workflows-examples-bp)
+ [Connecting to an environment](#comp-workflows-connect-env-bp)
## Workflow components examples
### WorkflowBuilder component
You can use a class to build a workflow definition. The definition can be given to a workflow component for rendering in a repository.
```
import { WorkflowBuilder } from '@amazon-codecatalyst/codecatalyst-workflows'
const workflowBuilder = new WorkflowBuilder({} as Blueprint, {
Name: 'my_workflow',
});
// trigger the workflow on pushes to branch 'main'
workflowBuilder.addBranchTrigger(['main']);
// add a build action
workflowBuilder.addBuildAction({
// give the action a name
actionName: 'build_and_do_some_other_stuff',
// the action pulls from source code
input: {
Sources: ['WorkflowSource'],
},
// the output attempts to autodiscover test reports, but not in the node modules
output: {
AutoDiscoverReports: {
Enabled: true,
ReportNamePrefix: AutoDiscovered,
IncludePaths: ['**/*'],
ExcludePaths: ['*/node_modules/**/*'],
},
},
// execute some arbitrary steps
steps: [
'npm install',
'npm run myscript',
'echo hello-world',
],
// add an account connection to the workflow
environment: convertToWorkflowEnvironment(myEnv),
});
```
### Workflow Projen component
The following example shows how a Projen component can be used to write a workflow YAML to a repository:
```
import { Workflow } from '@amazon-codecatalyst/codecatalyst-workflows'
...
const repo = new SourceRepository
const blueprint = this;
const workflowDef = workflowBuilder.getDefinition()
// creates a workflow.yaml at .aws/workflows/${workflowDef.name}.yaml
new Workflow(blueprint, repo, workflowDef);
// can also pass in any object and have it rendered as a yaml. This is unsafe and may not produce a valid workflow
new Workflow(blueprint, repo, {... some object ...});
```
## Connecting to an environment
Many workflows need to run in an AWS account connection. Workflows handle this by allowing actions to connect to environments with account and role name specifications.
```
import { convertToWorkflowEnvironment } from '@amazon-codecatalyst/codecatalyst-workflows'
const myEnv = new Environment(...);
// can be passed into a workflow constructor
const workflowEnvironment = convertToWorkflowEnvironment(myEnv);
// add a build action
workflowBuilder.addBuildAction({
...
// add an account connection to the workflow
environment: convertToWorkflowEnvironment(myEnv),
});
```
# Adding Dev Environments components to a blueprint
Managed development environments (MDE) are used to create and stand up MDE Workspaces in CodeCatalyst. The component generates a `devfile.yaml` file. For more information, see [Introduction to Devfile](https://redhat-developer.github.io/devfile/) and [Editing a repository devfile for a Dev Environment](devenvironment-devfile-moving.md).
```
new Workspace(this, repository, SampleWorkspaces.default);
```
**To import Amazon CodeCatalyst blueprints workspaces components**
In your `blueprint.ts` file, add the following:
```
import {...} from '@amazon-codecatalyst/codecatalyst-workspaces'
```
# Adding issues components to a blueprint
In CodeCatalyst, you can monitor features, tasks, bugs, and any other work involved in your project. Each piece of work is kept in a distinct recordcalled an issue. Each issue can have a description, assignee, status, and other properties, which you can search for, group and filter on. You can view your issues using the default views, or you can create your own views with custom filtering, sorting, or grouping. For more information about concepts related to issues, see [Issues concepts](issues-concepts.md) and [Quotas for issues in CodeCatalyst](issues-quotas.md).
The issue component generates a JSON representation of an issue. The component takes in an ID field and issue definition as input.
**To import Amazon CodeCatalyst blueprints issues components**
In your `blueprint.ts` file, add the following:
```
import {...} from '@amazon-codecatalyst/blueprint-component.issues'
```
**Topics**
+ [Issues components examples](#comp-issues-examples-bp)
## Issues components examples
### Creating an issue
```
import { Issue } from '@amazon-codecatalyst/blueprint-component.issues';
...
new Issue(this, 'myFirstIssue', {
title: 'myFirstIssue',
content: 'This is an example issue.',
});
```
### Creating a high-priority issue
```
import { Workflow } from '@amazon-codecatalyst/codecatalyst-workflows'
...
const repo = new SourceRepository
const blueprint = this;
const workflowDef = workflowBuilder.getDefinition()
// Creates a workflow.yaml at .aws/workflows/${workflowDef.name}.yaml
new Workflow(blueprint, repo, workflowDef);
// Can also pass in any object and have it rendered as a yaml. This is unsafe and may not produce a valid workflow
new Workflow(blueprint, repo, {... some object ...});
```
### Creating a low-priority issue with labels
```
import { Issue } from '@amazon-codecatalyst/blueprint-component.issues';
...
new Issue(this, 'myThirdIssue', {
title: 'myThirdIssue',
content: 'This is an example of a low priority issue with a label.',
priority: 'LOW',
labels: ['exampleLabel'],
});
```
# Working with blueprint tooling and CLI
The [blueprint CLI](https://www.npmjs.com/package/@amazon-codecatalyst/blueprint-util.cli) provides tooling to manage and work with your custom blueprints.
**Topics**
+ [Working with blueprint tooling](#working-with-bp-cli)
+ [Image upload tool](#image-upload-tool)
## Working with blueprint tooling
**To work with the blueprint tools**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Resume your Dev Environment. For more information, see [Resuming a Dev Environment](devenvironment-resume.md).
If you don't have a Dev Environment, you must first create one. For more information, see [Creating a Dev Environment](devenvironment-create.md).
1. In a working terminal, run the following the command to install the blueprint CLI:
```
npm install -g @amazon-codecatalyst/blueprint-util.cli
```
1. In the `blueprint.ts` file, import the tools you want to use in the following format:
```
import { } from '@amazon-codecatalyst/blueprint-util.cli/lib//;
```
**Tip**
You can to the [https://github.com/aws/codecatalyst-blueprints/tree/main/packages/utils/blueprint-cli](https://github.com/aws/codecatalyst-blueprints/tree/main/packages/utils/blueprint-cli) to find the name of the tooling you want to use.
**If you want to use the image uploading tool, add the following to your script:**
```
import { uploadImagePublicly } from '@amazon-codecatalyst/blueprint-util.cli/lib/image-upload-tool/upload-image-to-aws';
```
**Examples**
+ **If you want to use the publishing function, add the following to your script:**
```
import { publish } from '@amazon-codecatalyst/blueprint-util.cli/lib/publish/publish';
```
+ **If you want to use the image uploading tool, add the following to your script:**
```
import { uploadImagePublicly } from '@amazon-codecatalyst/blueprint-util.cli/lib/image-upload-tool/upload-image-to-aws';
```
1. Call the function.
**Examples:**
+ **If you want to use the publishing function, add the following to your script:**
```
await publish(logger, config.publishEndpoint, {});
```
+ **If you want to use the image uploading tool, add the following to your script:**
```
const {imageUrl, imageName} = await uploadImagePublicly(logger, 'path/to/image'));
```
## Image upload tool
The image upload tool provides you with the ability to upload your own image to an S3 bucket in your AWS account and then distribute that image publicly behind CloudFront. The tool takes an image path in the local storage (and optional bucket name) as input, and returns the URL to the image that is publicly available. For more information, see [What is Amazon CloudFront?](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) and [What is Amazon S3?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html)
**To work with the image upload tool**
1. Clone the [open-source blueprints GitHub repository](https://github.com/aws/codecatalyst-blueprints) that provides access to the blueprints SDK and sample blueprints. In a working terminal, run the following command:
```
git clone https://github.com/aws/codecatalyst-blueprints.git
```
1. Run the following command to navigate to the blueprints GitHub repository:
```
cd codecatalyst-blueprints
```
1. Run the following command to install dependencies:
```
yarn && yarn build
```
1. Run the following command to make sure the latest blueprint CLI version is installed:
```
yarn upgrade @amazon-codecatalyst/blueprint-util.cli
```
1. Log in to the AWS account with the S3 bucket you want to upload your image to. For more information, see [Configure the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html), and [Sign in through the AWS Command Line Interface](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html).
1. Run the following command from the root of your CodeCatalyst repository to navigate to the directory with the blueprint CLI:
```
cd packages/utils/blueprint-cli
```
1. Run the following command to upload your image to an S3 bucket:
```
yarn blueprint upload-image-public <./path/to/your/image>
```
A URL to your image is generated. The URL won’t be available immediately since it requires some time for the CloudFront distribution to be deployed. Check the distribution status to get the latest deployment status. For more information, see [Working with distributions](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-working-with.html).
# Assessing interface changes with snapshot testing
Generated snapshot tests across multiple configurations of your blueprint are supported.
Blueprints support [snapshot testing](https://jestjs.io/docs/snapshot-testing) on configurations provided by you as a blueprint author. The configurations are partial overrides that are merged on top of the defaults.json file at the root of a blueprint. When snapshot testing is enabled and configured, the build and test process synthesizes the given configurations and verifies that the synthesized outputs haven’t changed from the reference snapshot. To view the snapshot testing code, see the [CodeCatalyst blueprints GitHub repository](https://github.com/aws/codecatalyst-blueprints/blob/main/packages/utils/projen-blueprint/src/test-snapshot.ts#L12).
**To enable snapshot testing**
1. In the `.projenrc.ts` file, update the input object to ProjenBlueprint with the files you want to snapshot. For example:
```
{
....
blueprintSnapshotConfiguration: {
snapshotGlobs: ['**', '!environments/**', '!aws-account-to-environment/**'],
},
}
```
1. Resynthesize the blueprint to create TypeScript files in your blueprint project. Don’t edit the source files since they’re maintained and regenerated by Projen. Use the following command:
```
yarn projen
```
1. Navigate to the `src/snapshot-configurations` directory to view the `default-config.json` file with an empty object. Update or replace the file with one or more of your own test configurations. Each test configuration is then merged with the project’s `defaults.json` file, synthesized, and compared to snapshots when testing. Use the following command to test:
```
yarn test
```
The first time you use a test command, the following message is displayed: `Snapshot Summary › NN snapshots written from 1 test suite`. Subsequent test runs verify that the synthesized output hasn’t changed from the snapshots and display the following message: `Snapshots: NN passed, NN total`.
If you intentionally change your blueprint to produce a different output, then run the following command to update the reference snapshots:
```
yarn test:update
```
Snapshots expect synthesized outputs to be constant between each run. If your blueprint generates files that vary, you must exclude those files from the snapshot testing. Update the `blueprintSnapshotConfiguration` object of your `ProjenBluerpint` input object to add the `snapshotGlobs` property. The `snapshotGlobs` property is an array of [globs](https://github.com/isaacs/node-glob#glob-primer) that determines which files are included or excluded from snapshotting.
**Note**
There is a default list of globs. If you specify your own list, you may need to explicitly bring back the default entries.
# Publishing a custom blueprint to a space
Before you can add a custom blueprint to your space's blueprints catalog, you must publish it to the space. You can also view the blueprint in the CodeCatalyst console before publishing. You can publish a preview version or a normal version of your blueprint.
**Important**
If you want to use blueprint packages from external sources, consider the risks that may come with those packages. You're responsible for the custom blueprints that you add to your space and the code they generate.
**Important**
To publish a custom blueprint to your CodeCatalyst space, you must be signed in with an account that has the **Space administrator** or **Power user** role in the space.
**Topics**
+ [Viewing and publishing a preview version of a custom blueprint](#publish-preview-bp)
+ [Viewing and publishing a normal version of a custom blueprint](#publish-normal-bp)
+ [Publishing and adding a custom blueprint in specified spaces and projects](#publish-preview-existing-project-bp)
## Viewing and publishing a preview version of a custom blueprint
You can publish a preview version of your custom blueprint to your space if you want to add it to your space's blueprints catalog. This allows you to view the blueprint as a user before adding the non-preview version to the catalog. The preview version allows you to publish without taking up an actual version. For example, if you work on a `0.0.1` version, you can publish and add a preview version, so new updates for a second version can be published and added as `0.0.2`.
After making changes, rebuild your custom blueprint's package by running the `package.json` file, and preview your changes.
**To view and publish a preview version of a custom blueprint**
1. Resume your Dev Environment. For more information, see [Resuming a Dev Environment](devenvironment-resume.md)
1. Open a working terminal in your Dev Environment.
1. (Optional) In a working terminal, install necessary dependencies for your project if you didn't install them already. Use the following command:
```
yarn
```
1. (Optional) If you made changes to the `.projenrc.ts` file, regenerate the configuration of your project before building and previewing your blueprint. Use the following command:
```
yarn projen
```
1. Rebuild and preview your custom blueprint using the following command. Use the following command:
```
yarn blueprint:preview
```
Navigate to the `See this blueprint at:` link provided to preview your custom blueprint. Check that the UI, including text, appears as you expected based on your configuration. If you want to change your custom blueprint, you can edit the `blueprint.ts` file, resynthesize the blueprint, and then publish a preview version again. For more information, see [Resynthesis](custom-bp-concepts.md#resynthesis-concept).
1. (Optional) You can publish a preview version of your custom blueprint, which can then be added to your space's blueprints catalog. Navigate to the `Enable version [preview version number] at:` link to publish a preview version to your space.
You can emulate project creation without having to create a project in CodeCatalyst. To synthesize your project, use the following command:
```
yarn blueprint:synth
```
A blueprint is generated in the `synth/synth.[options-name]/proposed-bundle/` folder. For more information, see [Synthesis](custom-bp-concepts.md#synthesis-concept).
If you're updating your custom blueprint, instead, use the following command to resynthesize your project:
```
yarn blueprint:resynth
```
A blueprint is generated in the `synth/synth.[options-name]/proposed-bundle/` folder. For more information, see [Resynthesis](custom-bp-concepts.md#resynthesis-concept).
After publishing your preview version, you can then add the blueprint so space members can use it to create new projects or add in existing projects. For more information, see [Adding a custom blueprint to a space blueprints catalog](add-bp.md).
## Viewing and publishing a normal version of a custom blueprint
After you're done developing and previewing your custom blueprint, you can view and publish the new version that you want to add to your space's blueprints catalog. The release workflow generated when creating a project automatically publishes changes that are pushed. If you turned off the workflow generation when creating the blueprint, your blueprint isn't automatically made available to be added to your space's blueprints catalog. You can still publish your custom blueprint to your space after running a `yarn` command.
**To view and publish a custom blueprint**
1. Resume your Dev Environment. For more information, see [Resuming a Dev Environment](devenvironment-resume.md)
1. Open a working terminal in your Dev Environment.
1.
+ If you opted out of the release workflow generation when creating your blueprint, use the following command:
```
yarn blueprint:release
```
You can still navigate to the `See this blueprint at:` link provided to view your custom blueprint.
Publish the updated version of your custom blueprint, which can then be added to your space's blueprints catalog. Navigate to the `Enable version [release version number] at:` link to publish the latest version to your space.
+ If you opted in for a release workflow when creating your blueprint, the latest blueprint version is automatically published when changes are pushed. Use the following commands:
```
git add .
```
```
git commit -m "commit message"
```
```
git push
```
After publishing your normal version, you can then add the blueprint so space members can use it to create new projects or add in existing projects. For more information, see [Adding a custom blueprint to a space blueprints catalog](add-bp.md).
## Publishing and adding a custom blueprint in specified spaces and projects
By default, the `blueprint:preview` and `blueprint:release` commands publish into the CodeCatalyst space you created the blueprint in. If you have multiple Enterprise spaces, you can preview and publish the same blueprint in those spaces as well. You can also add a blueprint to an existing project of another space.
**To publish or add a custom blueprint in a specified space**
1. Resume your Dev Environment. For more information, see [Resuming a Dev Environment](devenvironment-resume.md).
1. Open a working terminal in your Dev Environment.
1. (Optional) Install necessary dependencies for your project if you didn't install them already. Use the following command:
```
yarn
```
1. Use the `--space` tag to publish a preview or normal version to a specified space. For example:
+
```
yarn blueprint:preview --space my-awesome-space # publishes under a "preview" version tag to 'my-awesome-space'
```
Example output:
```
Enable version 0.0.1-preview.0 at: https://codecatalyst.aws/spaces/my-awesome-space/blueprints
Blueprint applied to [NEW]: https://codecatalyst.aws/spaces/my-awesome-space/blueprints/%40amazon-codecatalyst%2Fmyspace.my-blueprint/publishers/1524817d-a69b-4abe-89a0-0e4a9a6c53b2/versions/0.0.1-preview.0/projects/create
```
+
```
yarn blueprint:release --space my-awesome-space # publishes normal version to 'my-awesome-space'
```
Example output:
```
Enable version 0.0.1 at: https://codecatalyst.aws/spaces/my-awesome-space/blueprints
Blueprint applied to [NEW]: https://codecatalyst.aws/spaces/my-awesome-space/blueprints/%40amazon-codecatalyst%2Fmyspace.my-blueprint/publishers/1524817d-a69b-4abe-89a0-0e4a9a6c53b2/versions/0.0.1/projects/create
```
Use the `--project` to add a preview version of a custom blueprint to an existing project in a specified space. For example:
```
yarn blueprint:preview --space my-awesome-space --project my-project # previews blueprint application to an existing project
```
Example output:
```
Enable version 0.0.1-preview.1 at: https://codecatalyst.aws/spaces/my-awesome-space/blueprints
Blueprint applied to [my-project]: https://codecatalyst.aws/spaces/my-awesome-space/projects/my-project/blueprints/%40amazon-codecatalyst%2FmySpace.my-blueprint/publishers/1524817d-a69b-4abe-89a0-0e4a9a6c53b2/versions/0.0.1-preview.1/add
```
# Setting publishing permissions for a custom blueprint
By default, a custom blueprint's permission is enabled if a workflow release was generated during project creation. When publishing permissions are enabled, the blueprint can be published to the space. You can disable the permission so that the blueprint can't be published. When the permission is disabled, the release workflow that is generated during blueprint creation doesn't run. New changes to a blueprint can't be published unless the blueprint's permissions are enabled.
**Important**
To enable or disable a custom blueprint project’s publishing permissions, you must be signed in with an account that has the **Space administrator** or **Power user** role in the space.
**To set a blueprint project's publishing permissions**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to manage a custom blueprint's publishing permissions.
1. On the space dashboard, choose the **Settings** tab, and then choose **Blueprints**.
1. Choose the **Project publishing permissions** tab to view the publishing permissions for all your space's blueprints.
1. Choose the blueprint that you want to manage, and then choose **Enable** or **Disable** to change the publishing permissions. If you're enabling the permissions, review the permission change details, and then choose **Enable blueprint publishing** to confirm the change.
# Adding a custom blueprint to a space blueprints catalog
After you publish a custom blueprint to your space, it can be added to your space's blueprints catalog. If you add a custom blueprint to your CodeCatalyst space’s blueprints catalog, then the blueprint is available to all space members to use when creating a project or adding it to an existing project. Before adding a custom blueprint to the space’s blueprints catalog, the blueprint’s publishing permission must be enabled. If you opted in for workflow release generation, then publishing permissions are enabled by default. For more information, see [Setting publishing permissions for a custom blueprint](manage-permissions-bp.md) and [Publishing a custom blueprint to a space](publish-bp.md).
**Important**
To add a custom blueprint to your CodeCatalyst space's blueprints catalog, you must be signed in with an account that has the **Space administrator** or **Power user** role in the space.
**To add a blueprint to the space's blueprints catalog**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. The blueprint can only be added from the default branch of the source repository. If you developed the blueprint on a feature branch, merge your feature branch with the changes to the default branch. Create a pull request to merge any changes to the default branch. For more information, see [Reviewing code with pull requests in Amazon CodeCatalyst](source-pull-requests.md).
1. In the CodeCatalyst console, navigate to the space dashboard with your custom blueprint.
1. On the space dashboard, choose the **Settings** tab, and then choose **Blueprints**.
1. Choose the blueprint name you want to add, and then choose **Add to catalog**. If you have more than one version, choose a version from the **Catalog version** dropdown menu
1. Choose **Save**.
# Changing catalog versions for a custom blueprint
As a blueprint author, you can manage the version that you want to publish to the space’s blueprints catalog. Changing the catalog version of a blueprint doesn’t affect the projects that are using a different blueprint version.
**Important**
To change catalog versions for a custom blueprint in your Amazon CodeCatalyst space's blueprints catalog, you must be signed in with an account that has the **Space administrator** or **Power user** role in the space.
**To manage a custom blueprint version**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to change a custom blueprint's version.
1. On the space dashboard, choose the **Settings** tab, and then choose **Blueprints**.
1. On **Space blueprints** table, choose the radio button for the custom blueprint that you want to manage.
1. Choose **Make catalog version**, and then choose the a version from the **Catalog version** dropdown menu.
1. Choose **Save**.
# Viewing details, versions, and projects of a custom blueprint
You can view your space’s published custom blueprints, including a blueprint’s details, versions, and the projects that are created with or adding the blueprint.
**Topics**
+ [Viewing a space's custom blueprints](#view-all-bp)
+ [Viewing projects created with or added custom blueprints](#view-projects-using-bp)
## Viewing a space's custom blueprints
**To view a space's custom blueprints**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to view a custom blueprint.
1. On the space dashboard, choose the **Settings** tab, and then choose **Blueprints** to view the **Space blueprints**. The following details are displayed in the table:
+ **Name** - Name of the custom blueprint.
+ **Catalog status** - Whether the custom blueprint is published to the space's blueprints catalog.
+ **Latest version** - The atest version of the custom blueprint.
+ **Latest modified** - The date when the space blueprint was last updated.
## Viewing projects created with or added custom blueprints
**To view projects created with or added custom blueprints**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to view a custom blueprint.
1. On the space dashboard, choose the **Settings** tab, and then choose **Blueprints**.
1. From the **Space blueprints** table, choose the name of a custom blueprint to view the **Projects using blueprint** and **Projects not using blueprint** tables.
# Removing a custom blueprint from a space blueprints catalog
A custom blueprint can be removed from your space's blueprints catalog if you no longer want it being used to create new projects or applied to existing projects.
**Note**
If you remove a custom blueprint from a space's blueprints catalog, it doesn't affect a project created from the blueprint or a project that applied the blueprint. Resources of the blueprint aren't removed from the project.
**Important**
To remove a custom blueprint from your CodeCatalyst space's blueprints catalog, you must be signed in with an account that has the **Space administrator** or **Power user** role in the space.
**To remove a custom blueprint from a space blueprints catalog**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space dashboard with your custom blueprint
1. On the space dashboard, choose the **Settings** tab, and then choose **Blueprints**.
1. Choose the blueprint name you want to remove, and then choose **Remove blueprint from catalog**.
# Deleting a published custom blueprint or version
When you delete a custom blueprint’s version or the blueprint itself from your Amazon CodeCatalyst space, all your access is removed to the resources of the blueprint project or blueprint version. When you have deleted a blueprint version or the blueprint, project members will be unable to access project resources, and any workflows that are prompted by third-party source repositories will be stopped.
**Note**
If you delete a blueprint, it doesn’t affect a project that is applied the blueprint. Resources of the blueprint aren't removed from the project.
If a blueprint version is published to the space’s blueprint catalog, choose a new version for the catalog before you delete the published version.
**Important**
To delete a published custom blueprint or a custom blueprint's catalog version from your space, you must be signed in with an account that has the **Space administrator** or **Power user** role in the space.
**To delete a custom blueprint's catalog version**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to delete a custom blueprint's catalog version.
1. On the space dashboard, choose the **Settings** tab, and then choose **Blueprints**.
1. Choose the name of the blueprint with the catalog version that you want to delete.
1. Choose the radio button for the catalog version that you want to delete, and then choose **Delete version**.
1. Review the details, and then choose another blueprint version from the **Choose a new blueprint catalog version** dropdown menu.
1. Enter `delete` to confirm the deletion of the blueprint catalog version.
1. Choose **Delete**.
If a blueprint version isn't in the space’s blueprints catalog, you can delete the version without choosing a new version.
**To delete a custom blueprint version**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to delete a custom blueprint version.
1. On the space dashboard, choose the **Settings** tab, and then choose **Blueprints**.
1. Choose the name of the blueprint with the version that you want to delete.
1. Choose the radio button for the version that you want to delete, and then choose **Delete version**.
1. Enter `delete` to confirm the blueprint version deletion.
1. Choose **Delete**.
Deleting a blueprint from the space's blueprints catalog deletes all versions of the blueprint. The space's projects that are using the blueprint aren't affected by the deletion.
**To delete a custom blueprint version**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to delete a custom blueprint.
1. On the space dashboard, choose the **Settings** tab, and then choose **Blueprints**.
1. On the **Space blueprints** table, choose the radio button for the custom blueprint that you want to delete, and then choose **Delete blueprint**.
1. Enter `delete` to confirm the custom blueprint deletion.
1. Choose **Delete**.
# Handling dependencies, mismatches, and tooling
Incorrect dependency management can lead to build failures and runtime issues for those using your custom blueprints. Outdated tooling and components may prevent blueprint users from accessing the latest features and bug fixes. You can manage dependencies, handle dependency mismatches, as well as upgrade toolings and components to ensure all dependencies rely on the same component versions and components are synchornized.
**Topics**
+ [Adding dependencies](#add-dependencies)
+ [Handling dependency type mismatches](#handle-dependency-mismatches)
+ [Using yarn and npm](#use-yarn-npm)
+ [Upgrading tooling and components](#upgrade-tooling-components)
## Adding dependencies
As a blueprint author, you might need to add packages to your blueprint, such as `@amazon-codecatalyst/blueprint-component.environments`. You need to update the `projen.ts` file with that package, and then regenerate the configuration of your project with [Projen](https://github.com/projen/projen). Projen acts as the project model for each blueprint codebase, which provides the ability to push backwards-compatible tooling updates by changing the way that the model renders configuration files. The `package.json` file is a file that is partially owned by the Projen model. Projen acknowledges dependency versions included in the package.json file, but other options need to originate from the model.
**To add a dependency and update a `projenrc.ts` file**
1. In the `projen.ts` file, navigate to the deps section.
1. Add the dependency you want to use in your blueprint.
1. Use the following command to regenerate the configuration of your project:
```
yarn projen && yarn
```
## Handling dependency type mismatches
After a [Yarn](https://yarnpkg.com/) update, you might get the following error regarding a repository parameter:
```
Type 'SourceRepository' is missing the following properties from type 'SourceRepository': synthesisSteps, addSynthesisStep
```
The error is due a dependency mismatch that happens when one component relies on a newer version of another component, but the relying component is pinned to an older version. The error can be fixed by making all your components rely on the same version so that the version synchronized between them. It’s best to keep al blueprint-vended packages under the same latest version (`0.0.x`), unless you’re certain about how you’re handling the versions. The following example shows how the `package.json` file can be configured so all the dependencies rely on the same version:
```
...
"@caws-blueprint-component/caws-environments": "^0.1.12345",
"@caws-blueprint-component/caws-source-repositories": "^0.1.12345",
"@caws-blueprint-component/caws-workflows": "^0.1.12345",
"@caws-blueprint-component/caws-workspaces": "^0.1.12345",
"@caws-blueprint-util/blueprint-utils": "^0.1.12345",
...
"@caws-blueprint/blueprints.blueprint": "*",
```
After configuring the versions for all dependencies, use the following command:
```
yarn install
```
## Using yarn and npm
Blueprints use [Yarn](https://yarnpkg.com/) for tooling. Using [npm](https://www.npmjs.com/) and Yarn will cause tooling problems because the way that dependency trees are resolved by each is different. To avoid such issues, it’s best to use Yarn only.
If you accidentally installed dependencies using npm, you can remove the generated `package-lock.json` file, and make sure your `.projenrc.ts` file is updated with the dependencies you need. You regenerate the configuration of your project with Projen.
Use the following to regenerate from the model:
```
yarn projen
```
After making sure your .projenrc.ts file is updated with the necessary dependencies, use the following command:
```
yarn
```
## Upgrading tooling and components
Occasionally, you might want to upgrade your tooling and components to bring in new features available. You’re recommended to keep all the components on the same version unless you’re certain about how you’re handling the versions. Versions are synchronized between components, so the same versions for all components ensures proper dependency between them.
### Using Yarn workspace monorepo
Use the following command to upgrade utils and components from the root of a custom blueprint’s repository:
```
yarn upgrade @amazon-codecatalyst/*
```
Use the following command if you’re not using a monorepo:
```
yarn upgrade —pattern @amazon-codecatalyst/*
```
Other options you can use to upgrade tooling and components:
+ Use npm view `@caws-blueprint-component/` to get the latest version.
+ Manually increase to the latest version by setting the version in your package.json file and using the following command:`yarn`. All components and utils should have the same version.
# Contribute
The blueprints software development kit (SDK) is an open-source library that you can contribute to. As a contributor, consider the contribution guidelines, feedback, and defects. For more information, see the [blueprints GitHub repository](https://github.com/aws/codecatalyst-blueprints).
# Quotas for blueprints in CodeCatalyst
The following table describes quotas and limits for blueprints in Amazon CodeCatalyst. For more information about quotas in Amazon CodeCatalyst, see [Quotas for CodeCatalyst](quotas.md).
| | |
| --- |--- |
| Maximum number of blueprints applied per CodeCatalyst project | 100 |