Custom blueprint concepts

Preview bundles

Custom blueprints write out preview bundles as a result of a successful synthesis. A bundle includes folders to help blueprint authors determine where resources should be located. For example, under src/, there can be data that gets deployed as source code, or YAML representations of environments can be located under environments. As a blueprint author, you don’t need to know the format if they are using blueprint components — each component writes to the appropriate location in the bundle. The bundle is used by the CodeCatalyst deployment system to create and seed various CodeCatalyst resources from the blueprint. The bundle is also used by the preview flow to preview the generated code. For more information, see Resynthesis and Three-way merge.

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 that you may have configured.

Resnythesis

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 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 the 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 Three-way merging.

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. To learn more about working with Projen, see the Projen documentation and How to simplify project setup with Projen.