Amplify-cli: RFC - BYOTransformer

[mikeparisstuff]

RFC - BYOTransformer

The goal of this document is to outline a process that would allow users to write their own GraphQL Transformer using JS/TS/etc. This feature will allow users to write their own transformers that implement reproducible patterns found in their own applications, distribute those patterns via npm, and ideally benefit from a set of community maintained transformers.

Configuration details

The transform now has a file 'transform.conf.json' that we could use to store transform specific configuration. Currently, it is only used to persist migration information so that the CLI does not delete any tables/ES domains created by the CLI v1. We could add a section to this file:

"transformers": [
    "name-of-an-npm-package",
    // or "file://path/to/my/transformer"
]

By convention packages listed here are expected to have a default export that points to a class that extends the Transformer base class (https://github.com/aws-amplify/amplify-cli/blob/master/packages/graphql-transformer-core/src/Transformer.ts#L47).

Loading custom transformers

The GraphQLTransform class that serves as the root of the project is used like this:

const defaultTransformers = [
    new DynamoDBModelTransformer(),
    new ModelConnectionTransformer(),
    new VersionedModelTransformer(),
    new ModelAuthTransformer()
];
// We can add code to require user defined modules dynamically.
const customerTransformers = loadCustomerTransformersOrThrow(config.transformers);

const transformer = new GraphQLTransform({ 
  transformers: [
    ...defaultTransformers,
    ...customerTransformers
  ]
});

// and used like this
const project = transformer.transform('type Post @model @custom { id: ID! title: String }');
// You can take project, upload to s3, and call create/updateStack with project.root

We can augment the current CLI behavior such that it will look for and dynamically load user defined transformers during project compilation. This will allow users to write their own transformers and reference them directly from their machine (using file://) or distribute and use community transformers from npm. The module loading behavior would match that of npm and would iteratively look higher up the node_module hierarchy on your machine to fine the transformer module. If the transform detects any issues with a custom transformer, it will do its best to gracefully fail with a useful error message.

Request for comments

If this sounds useful to you or if you would like to see this done some other way please comment below.

[chrisco255]

Love the idea of encouraging these as independent npm packages to make them easily shareable. I feel like the community could quickly package up and share some of the most common patterns needed!

When I looked into building a custom directive for my project, I found the current documentation a little sparse. Having one or two walkthroughs of how to implement a custom directive (and maybe explaining what's happening behind the scenes each step) would go really far.

[brunodunbar]

This gonna be very helpful! 👏

[pauloeli]

I'm waiting for this :pray:

[ambientlight]

Created PR https://github.com/aws-amplify/amplify-cli/pull/1396 which introduces base custom transformers support as well as base CLI support for enabling / disabling / scanning for custom transformer.

@mikeparisstuff: Please take a look and let me know your thoughts

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically closed because of inactivity. Please open a new issue if you are still encountering problems.