Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
89 lines (61 loc) · 3.5 KB

DEVELOPMENT.md

File metadata and controls

89 lines (61 loc) · 3.5 KB
Raw

Developing AWSX components

Prerequisites

Essentials:

  • NodeJS
  • Go
  • Make

For building the SDKs:

  • Dotnet
  • Python

Project Structure

  • awsx: the provider, written in TypeScript
  • awsx-classic: the original typescript-only version of AWSX
  • examples: multi-lang examples which are executed as acceptance tests
  • examples_legacy: examples of awsx-classic (no longer run as acceptance tests)
  • provider/pkg/schemagen: Go code for generating the schema and SDKs
  • sdk: Generated SDKs in each language

Development Workflow

Common Targets

  • make builds the provider and all SDKs and installs for testing (same as make build)
  • make development is an alias for make build for backwards compatibility
  • make build builds the provider and all SDKs and installs them
  • make test_provider runs the AWSX TypeScript/Jest tests (no AWS required)
  • GOTESTARGS="-run TEST_NAME" make test runs matching acceptance tests
  • make clean removes all build artifacts ready for a clean build
  • make install_sdks installs all SDKs
  • make test runs all acceptance tests; use CI for the full suite

Implementing New Components

The schema (schema.json) is generated by schemagen logic under provider/pkg/schemagen/. Amend the Go code there to generate the schema for the component with its inputs, outputs, and relevant types. Run make schema to test your changes.

From the schema.json we generate provider types (awsx/schema-types.ts) which describe the interfaces that the provider must implement. Running make provider will automatically re-generate this as needed.

To implement a new provider resource:

  1. Define a class for your resource in an appropriate folder which:

    • Inherits from the appropriate schema-types abstract class
    • Uses the schema-types 'Args' object for the constructor args
    • Sets all provider output members in the constructor

  2. Register the new component implementation in awsx/resources.ts.

The SDKs are also generated from the schema.json using the schemagen program. This can be done by calling make build.

Testing Workflow

Before testing, make sure you are authenticated with Pulumi and AWS in your terminal.

For running TypeScript examples locally:

  1. make provider install_nodejs_sdk - prep provider and Node.js SDK for local use
  2. cd examples/YOUR_EXAMPLE
  3. yarn && yarn link @pulumi/awsx - install dependencies, but use local version of @pulumi/awsx
  4. PATH=~/YOUR_DEV_FOLDER/pulumi-awsx/bin/:$PATH pulumi up

AI Review Workflow

AWSX-specific review guidance lives in REVIEW.md. The shared gh-aw review plugin is sourced from pulumi-labs/gh-aw-internal; do not make repo-specific edits to the imported shared review plugin here.

This repository includes these gh-aw workflow sources:

  • .github/workflows/gh-aw-pr-review.md
  • .github/workflows/gh-aw-pr-rereview.md

They compile to:

  • .github/workflows/gh-aw-pr-review.lock.yml
  • .github/workflows/gh-aw-pr-rereview.lock.yml
  • .github/aw/actions-lock.json

Behavior:

  • Auto review runs on pull_request opened events.
  • Re-review runs on maintainer slash command /review-again in PR comment/review-comment context.
  • Uses gh-aw pull request defaults (same-repo PRs unless forks is configured) with GitHub MCP lockdown disabled.
  • Uses Claude as the engine and posts GitHub-native PR review artifacts via safe outputs.

When updating the workflow source, recompile and validate:

  • gh aw compile --validate .github/workflows/gh-aw-pr-review.md .github/workflows/gh-aw-pr-rereview.md