cloudformation-cli-typescript-plugin

AWS CloudFormation Resource Provider Typescript Plugin

We're excited to share our progress with adding new languages to the CloudFormation CLI!

AWS CloudFormation Resource Provider TypeScript Plugin

The CloudFormation CLI (cfn) allows you to author your own resource providers that can be used by CloudFormation.

This plugin library helps to provide TypeScript runtime bindings for the execution of your providers by CloudFormation.

Usage

If you are using this package to build resource providers for CloudFormation, install the CloudFormation CLI TypeScript Plugin - this will automatically install the CloudFormation CLI! A Python virtual environment is recommended.

Prerequisites

• Python version 3.6 or above
• SAM CLI
• Your choice of TypeScript IDE

Installation

pip3 install cloudformation-cli-typescript-plugin

Refer to the CloudFormation CLI User Guide for the CloudFormation CLI for usage instructions.

Howto

Example run:

$ cfn init
Initializing new project
What's the name of your resource type?
(Organization::Service::Resource)
>> Foo::Bar::Baz
Select a language for code generation:
[1] java
[2] typescript
(enter an integer):
>> 2
Use docker for platform-independent packaging (Y/n)?
This is highly recommended unless you are experienced
with cross-platform Typescript packaging.
>> y
Initialized a new project in <>
$ cfn submit --dry-run
$ sam local invoke --event sam-tests/create.json TestEntrypoint

Development

For changes to the plugin, a Python virtual environment is recommended. Check out and install the plugin in editable mode:

python3 -m venv env
source env/bin/activate
pip3 install -e /path/to/cloudformation-cli-typescript-plugin

You may also want to check out the CloudFormation CLI if you wish to make edits to that. In this case, installing them in one operation works well:

pip3 install \
  -e /path/to/cloudformation-cli \
  -e /path/to/cloudformation-cli-typescript-plugin

That ensures neither is accidentally installed from PyPI.

For changes to the typescript library "@amazon-web-services-cloudformation/cloudformation-cli-typescript-lib" pack up the compiled javascript:

npm run build
npm pack

You can then install this in a cfn resource project using:

npm install ../path/to/cloudformation-cli-typescript-plugin/amazon-web-services-cloudformation-cloudformation-cli-typescript-lib-1.0.1.tgz

Linting and running unit tests is done via pre-commit, and so is performed automatically on commit after being installed (pre-commit install). The continuous integration also runs these checks. Manual options are available so you don't have to commit:

# run all hooks on all files, mirrors what the CI runs
pre-commit run --all-files
# run unit tests only. can also be used for other hooks, e.g. black, flake8, pylint-local
pre-commit run pytest-local

License

This library is licensed under the Apache 2.0 License.