DEV Community: alex-vladut

How to generate Typescript types for GraphQL queries in a React app

alex-vladut — Tue, 25 Apr 2023 15:34:36 +0000

In this article, we'll walk you through the steps for updating the configuration of a frontend React app to generate Typescript types for GraphQL queries based on your API schema. By the end of this tutorial, you'll be able to import .graphql files and get fully typed data returned by useQuery so that your IDE can show you autocomplete suggestions for the fields that can be accessed.

To get started, create a simple React application named users using Vite for running and building the app. You can create it any way you want (e.g. CRA or Next.js).

Let's start by defining the type of experience we would like to have, and then we'll work our way up to adding all the configuration in place.

Create a GraphQL file named getUser.graphql and add the following query to it:

query User($id: ID!) {
  getUser(id: $id) {
    id
    name
  }
}

Next, create a simple React component that will fetch the user and display their name.

import { useQuery } from '@apollo/client';

import { UserDocument } from './getUser.graphql';

type Props = {
  id: string
}

export function User({ id }: Props) {
  const { data, loading, error } = useQuery(UserDocument, { variables: { id } });

  if (loading) return <Spinner />;
  if (error) return <Error />;

  return <span>{data.getUser.name}</span>;
}

For this example, we are using the Apollo GraphQL client, but the same example will work just fine with any other client (e.g. URQL) that supports TypeDocumentNodes.

To enable such a development experience, we need to install the following NPM dependencies:

npm i -D @lente/vite-plugin-graphql @graphql-codegen/typescript-operations @graphql-codegen/typed-document-node @babel/preset-typescript @babel/preset-react

At the top level of your project, add a .graphql-let.yml file with the following content:

schema:
  - schema.graphql

documents:
  - '**/*.graphql'

plugins:
  - typescript-operations
  - typed-document-node

Under the hood, @lente/vite-plugin-graphql uses graphql-let, and .graphql-let.yml is where we define where the GraphQL schema is located and how to identify the GraphQL files to be parsed. Check out this repo for more details on the options available https://github.com/piglovesyou/graphql-let.

Finally, add the configuration to vite.config.ts for loading the .graphql files:

import { defineConfig } from 'vite';

import graphql from '@lente/vite-plugin-graphql';

export default defineConfig({
  ...
  plugins: [
    ...
    graphql({
      include: /\.(graphqls?|gql)$/i,
      babel: {
        presets: ['@babel/preset-typescript', '@babel/preset-react'],
      },
      rootContext: __dirname, // path to directory containing `graphql-let.yml`
    }),
  ],
  ...
});

Now you can start the application, and it should automatically parse the GraphQL files and generate the corresponding types.

You can check out this GitHub repository https://github.com/alex-vladut/vite-graphql-example.

Deploy AWS Amplify GraphQL Transformers with AWS CDK

alex-vladut — Sun, 13 Mar 2022 14:50:19 +0000

AWS Amplify provides a set of tools and libraries to enable rapid web and native application development. By making use of their tools you can get an application up and running very quickly and with minimal knowledge of the underlying AWS infrastructure. AWS Amplify CLI is one of the tools offered by AWS Amplify in their toolchain. The CLI provides an interactive experience to adding backend capabilities to your application such as GraphQL or RESTful API, authentication, storage, etc. Those configurations are compiled by AWS Amplify CLI into CloudFormation stacks that could be easily deployed to AWS. As an example, the auth capability provided by AWS Amplify is translated to a CloudFormation stack defining a Cognito User Pool with the properties selected interactively during the setup process. This is an exempt from AWS Amplify's docs showing how you will be guided step-by-step in configuring the authentication:

$ amplify add auth  ## "amplify update auth" if already configured
$ Do you want to use the default authentication and security configuration? 
❯ Default configuration 
  Default configuration with Social Provider (Federation) 
  Manual configuration 
  I want to learn more.

As mentioned above, the AWS Amplify CLI worked great for getting started with a fully working application and even having it deployed very easily, but there are a few limitations I came across along the way that made me look for alternatives. For example, I encountered a few situations when upgrading to a newer version of the AWS Amplify CLI broke my deployment and I had to recreate all the resources from scratch, which is not acceptable for an application running in production. On top of that, performing more advanced configurations requires you to dive into the JSON CloudFormation templates which could be tedious. AWS Amplify is expecting to own the whole structure of your project and as a result, I had a hard time configuring the Lambda functions' code at a different location to use the same linting rules and bundling tools as for the rest of the project, as well as to share some code with the other applications. As AWS CDK was released, I found it to provide a much better experience and flexibility. All the infrastructure resources could be defined in the same programming language as the rest of your code, and you get nice features such as code auto-completion suggestions. The main part of AWS Amplify that I still find useful is the Appsync GraphQL transformers. It is a significant productivity boost as it automatically generates many of the queries and mutations needed by the application. As a result, I was looking around for options to integrate the AWS Amplify GraphQL transformers into a project deployed with AWS CDK, and it turns out the Amplify code is modular enough and it is not as hard as I feared it would be to accomplish this goal.

Note: A GitHub repository is available to demonstrate the full implementation. Check it out here. The starting point for this article is a project already having AWS CDK configured, which is effectively the result of my previous article https://dev.to/alexvladut/how-to-add-aws-cdk-to-an-existing-project-2d30. This article assumes you're already familiar with how AWS Amplify GraphQL transformers work, but you can find more details in this section of the documentation https://docs.amplify.aws/cli/graphql/overview/.

AWS Amplify code is open-sourced and could be found on GitHub at https://github.com/aws-amplify/amplify-cli. We could make use of the NPM packages deployed independently to recreate the functionality offered by the AWS Amplify CLI regarding the GraphQL transformers. The entry point for generating the Appsync resolvers could be found here and the class we are interested in is GraphQLTransform which takes as a parameter all the individual transformers and iterates over them to generate the GraphQL resolvers and the associated CloudFormation stacks for deploying those resolvers.

This article is split into two parts. First, we'll look into implementing a script for transforming the GraphQL schema with the end goal being to generate the Appsync resolvers and all the associated CloudFormation stacks to deploy the GraphQL API into the cloud. Next, we'll see how we can import the GraphQL stacks from AWS CDK and perform the deployment to AWS.

Applying the GraphQL transformers

Let's get started by creating a simple GraphQL schema that will be used as the base for generating the resolvers and associated CloudFormation stacks. Inside the infra directory create a new file called schema.graphql and add the following content to it:

type User @model @auth(rules: [{ allow: owner, ownerField: "id" }]) {
  id: ID! @primaryKey
  name: String!
  email: AWSEmail!
  phone: AWSPhone
  createdAt: AWSDateTime!
  updatedAt: AWSDateTime!
}

Add the following NPM packages to your project's package.json:

+  "dependencies": {
+    "@aws-amplify/graphql-auth-transformer": "^0.7.7",
+    "@aws-amplify/graphql-default-value-transformer": "^0.5.17",
+    "@aws-amplify/graphql-function-transformer": "^0.7.11",
+    "@aws-amplify/graphql-http-transformer": "^0.8.11",
+    "@aws-amplify/graphql-index-transformer": "^0.11.2",
+    "@aws-amplify/graphql-model-transformer": "^0.13.2",
+    "@aws-amplify/graphql-predictions-transformer": "^0.6.11",
+    "@aws-amplify/graphql-relational-transformer": "^0.7.7",
+    "@aws-amplify/graphql-searchable-transformer": "^0.13.3",
+    "@aws-amplify/graphql-transformer-core": "^0.16.2",
+    "amplify-provider-awscloudformation": "^5.9.8",

These are all the GraphQL transformers that Amplify makes available at this point, while amplify-provider-awscloudformation is used to write the resulting CloudFormation stacks to disk.

Now create a new JavaScript file in your project where we'll implement the logic for loading the GraphQL schema and apply the transformers to it. Our process consists of the following high level steps:

async function graphqlTransformerExecutor(options) {
  const schema = await getSchemaDocs(path.normalize(options.schemaPath));

  const transformer = await createTransformer(options);
  const deployment = transformer.transform(schema);

  await writeDeploymentToDisk(
    deployment,
    options.outputPath,
    'appsync.cloudformation.json',
    {}
  );
};

In the project, I created you can find the full implementation in this file https://github.com/alex-vladut/aws-amplify-cdk/blob/main/tools/executors/graphql/impl.js. The logic consists of the following steps:

read the GraphQL schema from a given location
create an instance of the GraphqlTranform and pass all the transformers available
run the schema through the transformers to generate the Appsync resolvers and CloudFormation stacks associated (holding this metadata in memory at this point)
write the Cloudformation stacks and Appsync resolvers to disk

The logic for loading the schema files was inspired by the logic found here. I will not fully describe it here as it only consists of reading some files from a particular location, so there is nothing that interesting to it.

Next an instance of GraphqlTranform will be created like this:

async function createTransformer(options) {
  const modelTransformer = new ModelTransformer()
  const indexTransformer = new IndexTransformer()
  const hasOneTransformer = new HasOneTransformer()
  const authTransformer = new AuthTransformer({
    adminRoles: options.adminRoles ?? [],
    identityPoolId: options.identityPoolId,
  })

  const transformerList = [
    modelTransformer,
    new FunctionTransformer(),
    new HttpTransformer(),
    new PredictionsTransformer(options?.storageConfig),
    new PrimaryKeyTransformer(),
    indexTransformer,
    new BelongsToTransformer(),
    new HasManyTransformer(),
    hasOneTransformer,
    new ManyToManyTransformer(
      modelTransformer,
      indexTransformer,
      hasOneTransformer,
      authTransformer
    ),
    new DefaultValueTransformer(),
    authTransformer,
  ]

  if (options?.addSearchableTransformer) {
    transformerList.push(new SearchableModelTransformer())
  }

  const transformer = new GraphQLTransform({
    transformers: transformerList,
    authConfig,
    stacks: {},
    resolverConfig: {
      project: {
        ConflictHandler: ConflictHandlerType.AUTOMERGE,
        ConflictDetection: 'VERSION',
      },
    },
    sandboxModeEnabled: false,
    featureFlags,
  })
  return transformer
}

The original implementation in Amplify CLI code could be found here. All I did here was to copy the code from that file and strip out all the unnecessary logic, such as importing custom transformers. Now that we have full control, we could import any custom transformer directly here similarly to all the other transformers.

If you run this script it will automatically parse the schema.graphql file and generate the Appsync resolvers under the dist/infra/build directory. Alongside the CloudFormation stacks for deploying those resources in AWS are generated as well. The directory structure will look as follows:

- resolvers
- stacks
appsync.cloudformation.json
parameters.json
schema.graphql

This is the standard structure of the artifacts generated by Amplify regarding Appsync resources. resolvers include all the VTL Appsync resolvers, stacks will include one nested stack per model (i.e. here you will find a single CloudFormation stack called User.json), appsync.cloudformation.json is the entry stack holding all the other nested stacks, parameters.json is something used in general by Amplify to pass some parameters to the stack (won't need it) and schema.graphql is the GraphQL schema derived from our higher-level schema.

Once these resources are generated we're ready to continue with the second part, importing the CloudFormation stack from AWS CDK and deploying the resources to AWS.

Importing CloudFormation stacks from AWS CDK

We will start by defining a stack for creating Cognito User Pool as it will be used as an authentication mechanism:

import { Construct } from 'constructs';
import * as cdk from 'aws-cdk-lib';
import * as cognito from 'aws-cdk-lib/aws-cognito';

export class AuthStack extends cdk.NestedStack {
  public readonly userPool: cognito.UserPool;
  public readonly userPoolClient: cognito.UserPoolClient;

  constructor(scope: Construct, id: string, props?: cdk.NestedStackProps) {
    super(scope, id, props);

    this.userPool = new cognito.UserPool(this, 'CognitoUserPool', {
      signInAliases: { email: true, phone: true },
      selfSignUpEnabled: true,
      signInCaseSensitive: false,
      standardAttributes: {
        email: { required: true, mutable: true },
        familyName: { required: true, mutable: true },
        givenName: { required: true, mutable: true },
      },
    });

    this.userPoolClient = this.userPool.addClient('CognitoUserPoolClient');
  }
}

Another stack will be implemented to define an S3 bucket where the VTL resolvers will be deployed and from there will be referenced by Appsync:

import { Construct } from 'constructs';
import * as cdk from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as s3deploy from 'aws-cdk-lib/aws-s3-deployment';

import { normalize, join } from 'path';
import { readFileSync } from 'fs';
import { createHash } from 'crypto';

export class GraphQlApiDeploymentStack extends cdk.NestedStack {
  public readonly bucket: s3.Bucket;
  public readonly appsyncFilesKey: string;

  constructor(scope: Construct, id: string, props?: cdk.NestedStackProps) {
    super(scope, id, props);

    this.bucket = new s3.Bucket(this, 'AppsyncDeploymentBucket');

    const path = normalize(join(__dirname, 'build', 'schema.graphql'));
    this.appsyncFilesKey = `appsync-files/${generateHashForFile(path)}`;

    new s3deploy.BucketDeployment(this, 'AppsyncFilesDeployment', {
      sources: [s3deploy.Source.asset(normalize(join(__dirname, 'build')))],
      destinationBucket: this.bucket,
      destinationKeyPrefix: this.appsyncFilesKey,
      memoryLimit: 2048,
    });
  }
}

function generateHashForFile(path: string) {
  const file = readFileSync(path);
  const hash = createHash('sha256');
  hash.update(file);
  return hash.digest('hex');
}

I used the logic defined in this helper library created by AWS to help with importing the CloudFormation resources generated by AWS Amplify https://github.com/aws-amplify/amplify-cli-export-construct. It cannot be used per se due to it requiring all the other resources being available, not only the Appsync related ones, but still, it provides good inspiration.

Next let's define the nested stack responsible for importing the Appsync CloudFormation stack:

import { Construct } from 'constructs';
import * as cdk from 'aws-cdk-lib';
import * as cfninc from 'aws-cdk-lib/cloudformation-include';

import { readdirSync } from 'fs';
import { normalize, join } from 'path';

interface NestedStacksReferences {
  [key: string]: cfninc.IncludedNestedStack;
}

export class GraphQlApiStack extends cdk.NestedStack {
  public readonly graphqlApiId: string;
  public readonly graphqlApiEndpoint: string;
  public readonly nestedStacks: NestedStacksReferences;

  constructor(scope: Construct, id: string, props?: cdk.NestedStackProps) {
    super(scope, id, props);

    new cdk.CfnParameter(this, 'cognitoUserPoolId', {
      type: 'String',
      description: 'Auth Cognito User Pool ID',
    });
    new cdk.CfnParameter(this, 'authenticatedRoleName', {
      type: 'String',
      description:
        'Reference to the name of the Auth Role created for the project',
    });
    new cdk.CfnParameter(this, 'unauthenticatedRoleName', {
      type: 'String',
      description:
        'Reference to the name of the Unauthenticated Role created for the project',
    });
    new cdk.CfnParameter(this, 's3DeploymentBucket', {
      type: 'String',
      description: 'S3 bucket containing all the Appsync deployment artefacts',
    });
    new cdk.CfnParameter(this, 's3DeploymentRootKey', {
      type: 'String',
      description: 'S3 deployment rook key',
    });

    const apiNestedStacks = readdirSync(
      normalize(join(__dirname, 'build', 'stacks'))
    ).reduce(
      (aggregate, file) => ({
        ...aggregate,
        [file.replace('.json', '')]: {
          templateFile: normalize(join(__dirname, 'build', 'stacks', file)),
          preserveLogicalIds: true,
          parameters: {},
        },
      }),
      {}
    );
    const graphQlApiStack = new cfninc.CfnInclude(this, 'GraphqlApi', {
      templateFile: normalize(
        join(__dirname, 'build', 'appsync.cloudformation.json')
      ),
      preserveLogicalIds: true,
      loadNestedStacks: apiNestedStacks,
      parameters: {
        AppSyncApiName: 'aws-amplify-cdk',
        AuthCognitoUserPoolId: props.parameters.cognitoUserPoolId,
        authRoleName: props.parameters.authenticatedRoleName,
        unauthRoleName: props.parameters.unauthenticatedRoleName,
        S3DeploymentBucket: props.parameters.s3DeploymentBucket,
        S3DeploymentRootKey: props.parameters.s3DeploymentRootKey,
        DynamoDBEnablePointInTimeRecovery: 'true',
        DynamoDBEnableServerSideEncryption: 'true',
        env: 'dev',
      },
    });
    this.graphqlApiId = graphQlApiStack.getOutput('GraphQLAPIIdOutput').value;
    this.graphqlApiEndpoint = graphQlApiStack.getOutput(
      'GraphQLAPIEndpointOutput'
    ).value;

    // includes all the relevant nested stacks so that could be referenced from the parent stack
    this.nestedStacks = Object.keys(apiNestedStacks).reduce(
      (stacks, name) => ({
        ...stacks,
        [name]: graphQlApiStack.getNestedStack(name),
      }),
      {}
    );
  }
}

Now we'll import all the nested stacks from our main stack and link them together:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';

import { AuthStack } from './auth.stack';
import { GraphQlApiDeploymentStack } from './graphql-api-deployment.stack';
import { GraphQlApiStack } from './graphql-api.stack';

export class CdkStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const authStack = new AuthStack(this, 'AuthStack');
    const graphqlApiDeploymentStack = new GraphQlApiDeploymentStack(
      this,
      'GraphQlApiDeploymentStack'
    );
    const graphqlApiStack = new GraphQlApiStack(this, 'GraphQlApiStack', {
      parameters: {
        cognitoUserPoolId: authStack.userPool.userPoolId,
        authenticatedRoleName: authStack.authenticatedRole.roleName,
        unauthenticatedRoleName: authStack.unauthenticatedRole.roleName,
        s3DeploymentBucket: graphqlApiDeploymentStack.bucket.bucketName,
        s3DeploymentRootKey: graphqlApiDeploymentStack.appsyncFilesKey,
      },
    });

    new cdk.CfnOutput(this, 'CognitoIdentityPoolId', {
      value: authStack.identityPool.ref,
    });
    new cdk.CfnOutput(this, 'UserPoolId', {
      value: authStack.userPool.userPoolId,
    });
    new cdk.CfnOutput(this, 'UserPoolWebClientId', {
      value: authStack.userPoolClient.userPoolClientId,
    });
    new cdk.CfnOutput(this, 'AppsyncResolversBucketName', {
      value: graphqlApiDeploymentStack.bucket.bucketName,
    });
    new cdk.CfnOutput(this, 'AppsyncResolversKey', {
      value: graphqlApiDeploymentStack.appsyncFilesKey,
    });

    new cdk.CfnOutput(this, 'oauth', { value: '{}' });
    new cdk.CfnOutput(this, 'GraphqlApiId', {
      value: graphqlApiStack.graphqlApiId,
    });
    new cdk.CfnOutput(this, 'GraphqlApiEndpoint', {
      value: graphqlApiStack.graphqlApiEndpoint,
    });
  }
}

Future improvements

A better development experience would be provided if the AWS CDK stack created by AWS Amplify could be directly imported from your project. There are currently a couple of limitations that would need to be addressed to accomplish this goal:

AWS Amplify assigns a new scope to the AWS CDK stack created for the Appsync resources. See this proposal for more details #9254,
AWS Amplify uses AWS CDK v1, so even if the issue above was addressed, this still won't work if you already migrated to v2.

This approach won't be optimal either, due to AWS Amplify CLI generating both the Appsync resolvers and the associated resources for deploying those resolvers (e.g. the CloudFormation stacks for defining the DynamoDB tables, Appsync API). A further step would require architectural changes of the AWS Amplify GraphQL transformers code to decouple the generation of the resolvers from the creation of the deployment resources.

Conclusion

In this article, we have looked into how the AWS Amplify GraphQL transformers capability could be used with AWS CDK. This approach provides a much better experience as you can define the infrastructure in Typescript instead of working directly with the CloudFormation templates. In addition to that, you will get more flexibility in defining your infrastructure resources and overall it offers a smoother integration with other development tools of your choice.

How to add AWS CDK to an existing project

alex-vladut — Sun, 06 Mar 2022 15:52:08 +0000

AWS Cloud Development Kit (AWS CDK) provides an appealing approach to developers for defining the infrastructure through the programming languages they are already familiar with. You can check out the docs to find out more about the tool here https://aws.amazon.com/cdk/.

The initialization command of the AWS CDK CLI will create an independent project and, while this is great for quickly getting up and running and learning about a technology, most often than not you will want to integrate it into an already established setup. In that way, you will be able to enforce the same coding guidelines and apply the same build process as for the rest of the code. In this project, we'll go through the steps required to integrate AWS CDK into an existing monorepo workspace managed with Nrwl Nx. I will not dive into the details of how Nx works as this is not relevant for this article and the same steps are valid for different types of projects, but you could find out more about it at https://nx.dev/.

Initial setup

The starting point of the project is a monorepo Nx workspace with a single app called infra generated at the root directory. Here is a GitHub repo with the complete setup https://github.com/alex-vladut/aws-amplify-cdk.

Generate an AWS CDK application

To generate a new AWS CDK application run the following command at the root of your project:

npx cdk init app --language=typescript

which will result in an error:

cdk init cannot be run in a non-empty directory!

To go around this issue we'll have to create a new empty directory e.g. mkdir cdk (could name it whatever you want), move inside it cd cdk, and then rerun the command above for initializing an AWS CDK app. This time it should run successfully and generate a bunch of files for you.

Configuration

Now that the AWS CDK app is generated, we'll want to move some of the files from the cdk directory and adjust them to be properly integrated into our existing project. First, go ahead and move the file /cdk/cdk.json to the root directory and then update it to point to a different entry point AWS CDK CLI will use for synthesizing and deploying your resources:

-  "app": "npx ts-node --prefer-ts-exts bin/cdk.ts",
+  "app": "dist/infra/main.js",

Rather than relying on AWS CDK to build the code, we'll do it through our tools along with all the other apps. In this case, dist directory is the default destination where projects built with Nx will land, but in the same manner, it could be updated to point to a different location.
Next also remove the following lines from the cdk.json file as won't be required:

  ...
-  "watch": {
-    "include": [
-      "**"
-    ],
-    "exclude": [
-      "README.md",
-      "cdk*.json",
-      "**/*.d.ts",
-      "**/*.js",
-      "tsconfig.json",
-      "package*.json",
-      "yarn.lock",
-      "node_modules",
-      "test"
-    ]
-  },
  ...

Let's add the AWS CDK npm packages to our project:

npm i --save-dev aws-cdk
npm i aws-cdk-lib constructs

Then copy the content of the file cdk/bin/cdk.ts into infra/src/main.ts. Copy the file cdk/lib/cdk-stack.ts to infra/src/main/app and update the import in main.ts to correctly point to it.

And with that, we're done with all the configuration required, feel free to delete the cdk directory as none of the remaining files will be needed anymore. Everything should be set up now, so we can go ahead and deploy our resources into the cloud with AWS CDK CLI.

Deployment

Build the infra project to pick up the latest changes:

npm run build infra

and then deploy it by running the following command:

cdk deploy

A quick note here: if it's the first time you're using AWS CDK, before running cdk deploy you'll have to run cdk bootstrap first.

And that's it, your dummy CDK stack should be deployed to the cloud and now you're ready to add more resources to it.