Skip to main content

Using Klotho with GraphQL Yoga and Express

Overview​

This tutorial shows how to leverage Klotho's existing support for Express to create a cloud-ready GraphQL application using GraphQL Yoga.

Getting Started​

Prerequisites​

Repository​

Clone our sample apps git repo and install the npm packages for the ts-graphql-yoga app.

git clone https://github.com/klothoplatform/sample-apps.git
cd sample-apps/ts-graphql-yoga
npm install

Application Overview​

The GraphQL Yoga sample application is an Express app that exposes a GraphQL Yoga server on its /graphql route. The server's schema includes a single query, hello, that returns "Hello from Klotho!" when executed.

This application utilizes the following annotations:

Wiring the Application for Compilation with Klotho​

To wire the GraphQL Yoga application for compilation with Klotho, first a GraphQL Yoga server, graphQLServer, is created.

import { createServer } from "@graphql-yoga/node";

const graphQLServer = createServer({
  schema: {
    ... // the schema is included in the complete sample application
  },
});
...

Then an Express app is created and graphQLServer is mounted as a route handler on its /graphql route.

...
import * as express from "express";

const app = express();

app.use('/graphql', graphQLServer)

Finally, the application listens for requests to the Express app with an invocation of app.listen annotated with @kotho::expose.

/* @klotho::expose {
 *   target = "public"
 *   id = "graphql-yoga-gateway"
 * }
 */
app.listen(3000, async () => {
  console.log(
    'Running GraphQL Yoga API Server at http://localhost:3000/graphql'
  );
});

Compiling the Application with Klotho​

Start by compiling the typescript application into javascript.

npx tsc

The compiled output will be located in the ./dist directory.

Then compile the application with Klotho.

klotho . --app ts-graphql-yoga --provider aws
██╗  ██╗██╗      ██████╗ ████████╗██╗  ██╗ ██████╗
██║ ██╔╝██║     ██╔═══██╗╚══██╔══╝██║  ██║██╔═══██╗
█████╔╝ ██║     ██║   ██║   ██║   ███████║██║   ██║
██╔═██╗ ██║     ██║   ██║   ██║   ██╔══██║██║   ██║
██║  ██╗███████╗╚██████╔╝   ██║   ██║  ██║╚██████╔╝
╚═╝  ╚═╝╚══════╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝ ╚═════╝

Adding resource input_file_dependencies:
Adding resource exec_unit:main
index.js: Adding in catchall route for prefix '/graphql' for middleware 'graphQLServer'
Found 2 route(s) for middleware 'graphQLServer'
Adding resource gateway:graphql-yoga-gateway
Adding resource topology:ts-graphql-yoga
Adding resource infra_as_code:Pulumi (AWS)

In the ./compiled folder, you will find the Infrastructure-as-Code (IaC) for your cloud-native application ready for deployment. You will also find a file called ts-graphql-yoga.png, visualizing the topology output of your compiled application:

topology diagram showing an API Gateway targeting a AWS Lambda function

The topology diagram shows that Klotho has generated IaC targeting AWS to deploy an API Gateway that invokes a Lambda function serving the application.

Deploying the application​

Once the IaC has been generated, you can deploy the cloud-native version of the application with Pulumi.

First, use the Pulumi CLI to set the region aws:region setting for the application's Pulumi stack. This is the AWS region that Pulumi will deploy the application to.

pulumi config set aws:region <region> --cwd './compiled' --stack ts-graphql-yoga

Press ENTER (⏎) to confirm that you want to create the ts-graphql-yoga Pulumi stack.

If you would like to create this stack now, please press <ENTER>, otherwise press ^C:
Created stack 'ts-graphql-yoga'

Next, change the current working directory to ./compiled and install the dependencies of the Pulumi application generated by Klotho.

cd compiled
npm install

Then deploy the application by running pulumi up.

pulumi up

Pulumi will display a preview of all the cloud resources it will create as part of the deployment.

Previewing update (ts-graphql-yoga)

     Type                             Name                                  Plan
 +   pulumi:pulumi:Stack              ts-graphql-yoga-ts-graphql-yoga       create..
 +   ├─ awsx:ecr:Repository           ts-graphql-yoga                       create
 +   │  └─ aws:ecr:LifecyclePolicy    ts-graphql-yoga                       create
 +   ├─ aws:ecr:Repository                   ts-graphql-yoga                       create
 +   ├─ aws:apigateway:RestApi               graphql-yoga-gateway                  create
 +   │  ├─ aws:apigateway:Resource           graphql-yoga-gatewaygraphql/          create
 +   │  │  └─ aws:apigateway:Method          ANY-graphql-e6862                     create
 +   │  │     └─ aws:apigateway:Integration  lambda-ANY-graphql-e6862              create
 +   │  ├─ aws:apigateway:Resource           graphql-yoga-gatewaygraphql/{rest+}/  create
 +   │  │  └─ aws:apigateway:Method          ANY-rest-d5c2f                        create
 +   pulumi:pulumi:Stack                     ts-graphql-yoga-ts-graphql-yoga       create
 +   │  └─ aws:apigateway:Deployment         graphql-yoga-gateway-deployment       create
 +   │     └─ aws:apigateway:Stage           graphql-yoga-gateway-stage            create
 +   ├─ aws:iam:Role                         ts-graphql-yoga_0d6e4_LambdaExec      create
 +   │  ├─ aws:iam:Policy                    ts-graphql-yoga-main-exec             create
 +   │  └─ aws:iam:RolePolicyAttachment      ts-graphql-yoga-main-exec             create
 +   ├─ aws:cloudwatch:LogGroup              main-function-api-lg                  create
 +   ├─ aws:iam:RolePolicyAttachment         ts-graphql-yoga-main-lambdabasic      create
 +   ├─ aws:s3:Bucket                                                              create
 +   ├─ aws:lambda:Function                  main                                  create
 +   ├─ aws:lambda:Permission                ANY-graphql-permission                create
 +   └─ aws:lambda:Permission                ANY-graphqlrest-permission            create

Outputs:
    apiUrls         : [
        [0]: output<string>
    ]
    deploymentPortal: "None - Opted out of topology upload by default"

Resources:
    + 22 to create

Do you want to perform this update?  [Use arrows to move, enter to select, type to filter]
> yes
  no
  details

Select yes from the displayed options to start the deployment process and then wait until Pulumi has completed the deploying the application's stack. This usually takes 3 minutes.

When Pulumi has finished deploying, you will see the completion status and the AWS provided API Gateway URL for your API:

Outputs:
    apiUrls         : [
        [0]: "https://<gateway_id>.execute-api.<region>.amazonaws.com/stage"
    ]
    deploymentPortal: "None - Opted out of topology upload by default"

Resources:
    + 22 created

Duration: 2m31s

Testing the Deployed Application​

To test the application one it has been deployed to the cloud, use your browser to navigate to the generated API Gateway's /graphql route.

https://<gateway_id>.execute-api.<aws_region>.amazonaws.com/stage/graphql

This will load the GraphiQL, an in-browser GraphQL IDE which we can use to execute the hello query.

screenshot of executing the hello query in GraphiQL and the resulting output: hello from Klotho

Copy the hello query to your GraphiQL window and try it out for yourself!

query {
  hello
}

Cleanup​

When you're done with the tutorial, you can destroy the created resources by running pulumi destroy from the ./compiled directory and selecting yes when prompted.

pulumi destroy