All of this project’s code can be found in the First Look monorepo on my GitHub.
Introduction
GraphQL Helix is a framework and runtime agnostic collection of utility functions for building your own GraphQL HTTP server. Instead of providing a complete HTTP server or middleware plugin function, GraphQL Helix only provides a handful of functions for turning an HTTP request into a GraphQL execution result. You decide how to send back the response.
Motivations and API
Daniel Rearden listed the following reasons pushing him to create Helix, believing that these factors were absent from popular solutions like Apollo Server, express-graphql and Mercurius:
Wanted bleeding-edge GraphQL features like @defer, @stream and @live directives.
Wanted to not be tied down to a specific framework or runtime environment.
Wanted control over how server features like persisted queries were implemented.
Wanted something other than WebSockets (i.e. SSE) for subscriptions.
renderGraphiQL and shouldRenderGraphiQL
renderGraphiQL returns the HTML to render a GraphiQL instance. shouldRenderGraphiQL uses the method and headers in the request to determine whether a GraphiQL instance should be returned instead of processing an API request.
getGraphQLParameters
getGraphQLParameters extracts the GraphQL parameters from the request including the query, variables and operationName values.
processRequest
processRequest takes the schema, request, query, variables, operationName and a number of other optional parameters and returns one of three kinds of results, depending on how the server should respond:
RESPONSE - regular JSON payload
MULTIPART RESPONSE - multipart response (when @stream or @defer directives are used)
PUSH - stream of events to push back down the client for a subscription
The Serverless Framework is an open source framework for building applications on AWS Lambda. It provides a CLI for developing and deploying AWS Lambda functions, along with the AWS infrastructure resources they require.
index.js
The serverless-http package is a piece of middleware that handles the interface between Node applications and the specifics of API Gateway. It allows you to wrap your API for serverless use without needing an HTTP server, port, or socket.
serverless.yml
The resources and functions are defined in a file called serverless.yml which includes:
The provider for the Node runtime and AWS region
The handler and events for your functions.
The handler is named index.start because it is formatted as <FILENAME>.<HANDLER>.
Upload to AWS with sls deploy
Once the project is defined in code it can be deployed with the sls deploy command. This command creates a CloudFormation stack defining any necessary resources such as API gateways or S3 buckets.
Run test queries on GraphQL Helix Serverless
Access your graph by adding /graphql to end of the provided endpoint (cuml5hnx0b.execute-api.us-east-1.amazonaws.com/graphql in my case) and send a hello query.
GraphQL Helix Serverless Final Project Structure
Deploy GraphQL Helix with Amplify
AWS Amplify is a set of tools and services to help frontend web and mobile developers build fullstack applications with AWS infrastructure. It includes a CLI for creating and deploying CloudFormation stacks along with a Console and Admin UI for managing frontend web apps, backend environments, CI/CD, and user data.
The amplify init command creates a boilerplate project that is setup for generating CloudFormation templates.
Create backend with amplify add api
amplify add api configures a Lambda handler and API gateway to serve the function.
index.js
Upload to AWS with amplify push
amplify push uploads the stack templates to an S3 bucket and calls the CloudFormation API to create or update resources in the cloud.
Run test queries on GraphQL Helix Amplify
Access your graph by adding /graphql to the end of the provided endpoint (acj63jadzb.execute-api.us-west-1.amazonaws.com/dev in my case) and send a hello query.
GraphQL Helix Amplify Final Project Structure
Deploy GraphQL Helix with Docker and Fly
Fly is a platform for fullstack applications and databases that need to run globally. Fly executes your code close to users and scales compute in cities where your app is busiest. You can run arbitrary Docker containers and host popular databases like Postgres.
index.js
Dockerfile
Docker can build images automatically by reading the instructions from a Dockerfile. A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image.
For a more in depth explanation of these commands, see my previous article, A First Look at Docker.
.dockerignore
Before the docker CLI sends the context to the docker daemon, it looks for a file named .dockerignore in the root directory of the context.
If this file exists, the CLI modifies the context to exclude files and directories that match patterns in it. This helps avoid sending large or sensitive files and directories to the daemon.
docker-compose.yml
Compose is a tool for defining and running multi-container Docker applications. After configuring your application’s services with a YAML file, you can create and start all your services with a single command.
Run test queries on GraphQL Helix Docker
The docker compose up command aggregates the output of each container. It builds, (re)creates, starts, and attaches to containers for a service.
To test your app, get the port of your app that Docker mapped:
Docker mapped the 8080 port inside of the container to the port 49160 on your machine.