I’ve recently been experimenting with code generation for AppSync GraphQL APIs (mainly so I can include it in my Serverless Launchpad package that I set up for new clients). I’ve settled on using the GraphQL Code Generator tool and will give you a brief overview of how I’m using it here.
There are 3 distinct use cases that I want to generate code for (frontend and backend). These are:
- Frontend: Fully typed React hooks for easily invoking every query and mutation defined in the schema from React components.
- Backend Lambdas: TypeScript types and resolver signatures for use in the backend Lambda handlers.
- Backend E2E tests: operation functions for every query and mutation I need to invoke in the backend E2E tests (which call directly to the deployed AppSync endpoint).
In addition to providing the GraphQL schema file as an input, items 1 and 2 above also require an operations.yml file to be specified, where you provide named operations for each query and mutation you wish to generate a function for. This is useful say if your schema has a single GraphQL query which you need to invoke with different parameters/return fields in different UI components or test cases.
You can check out my full codegen.yml config and related files for these three setups here.
The frontend one was the most complex to set up. Since I needed to asynchronously fetch an auth token which was included as a HTTP header in every request, this required me to inject an
api-client TypeScript module (which I authored) with a function that returned a fetcher (where I implemented the async logic to fetch the token and also reference the environment variable where the API URL was specified).
Another feature which I haven’t implemented yet but plan to soon is to logically split my AppSync schema into separate files instead of having one huge file as the application grows. This is possible because the GraphQL Code Generator tool allows you to provide multiple schema files as inputs and also output a single consolidated GraphQL schema file that I can then supply to my AppSync deployment (I use the serverless-appsync-plugin).
I’m always cautious when using code generation since all code is a liability and if it’s generated, I’m also dependent on the tool that generated it and its downstream deps. So I have a few rules:
- All generated code files go into dedicated folders which are excluded from the GitHub repo and cannot be hand-edited by developers
- CI/CD pipelines always run the codegen as part of their build phase
Anyway, if you’re creating AppSync GraphQL APIs and like strongly typed code and dislike boilerplate, you should definitely look into GraphQL Code Generator.
Some further reading:
- How to use TypeScript with AppSync Lambda Resolvers by Benoît Bouré
- Twitter thread with folks discussing how they’re doing GraphQL codegen for AppSync — Paul
P.S. I won’t be sending emails for the rest of this week as I’m going on holiday for a few days. If you have any recommendations on places to visit or eat in Amsterdam, I’d love to hear them! 😃
Indie Cloud Consultant helping small teams learn and build with serverless.
Learn more how I can help you here.
Join daily email list
I publish short emails like this on building software with serverless on a daily-ish basis. They’re casual, easy to digest, and sometimes thought-provoking. If daily is too much, you can also join my less frequent newsletter to get updates on new longer-form articles.