How to: Deploy a GraphQL Mesh Gateway

Thanks to its flexible architecture and embedded server relying on GraphQL Yoga and Envelop, GraphQL Mesh can be deployed anywhere!

We already saw that mesh dev could be used for local development.

Similarly, Mesh provides a mesh start CLI command for production environments.

mesh start can be used for all environments supporting starting a webserver (Heroku, Digital Ocean, etc).

Setup Mesh on a Serverless environment requires some integration work, detailed below.

Deploy Mesh with mesh start on Node.js

While mesh dev handles the generation of the SDK code, mesh start expects to load the Gateway schema and runtime from the .mesh/ folder.

This mechanism helps:

• reducing the start time of the server: no build step is required
• preventing starting failure if one of the Sources is unreachable: we don't fetch the API definition file at startup, ensuring that the fetched definitions are validated at build time

To deploy a Mesh Gateway, you need to ensure that mesh build is called during the deployment, for example, with a prebuild step:

{
  "scripts": {
    "start": "mesh start",
    // will be run during deployment
    "build": "mesh build"
  }
}

For more information about the embedded Mesh server configuration, please refer to the serve reference documentation.

Deploy Mesh on Serverless

Serverless deployment requires some integration since we cannot keep the mesh start server running.

Deploy Mesh on Vercel with Next.js API Routes

First, let's ensure that mesh build will be run during deployment.

Vercel - list most platforms, and run yarn build for deployment. For this reason, we will add a prebuild step:

{
  "scripts": {
    "start": "mesh start",
    // will be run during deployment
    "prebuild": "mesh build"
  }
}

Now, let's integrate our Mesh Gateway in a Next.js API Routes:

import { createBuiltMeshHTTPHandler } from './.mesh'
 
export default createBuiltMeshHTTPHandler()

A complete example is found at website/src/pages/api/covid/index.ts.

Deploy Mesh on AWS Lambda

Similarly to regular and Vercel deployment, we will need to add the mesh build command in the build step.

Then, we can create a Lambda as it follows:

import type { Handler } from '@aws-cdk/aws-lambda'
import { configure } from '@vendia/serverless-express'
import { createBuiltMeshHTTPHandler } from './.mesh'
 
const app = createBuiltMeshHTTPHandler()
 
export const handler: Handler = configure({
  // Pass Mesh HTTP handler as app
  app,
})

Deploy Mesh on Cloudflare Workers

Similarly to regular and Vercel deployment, we will need to add the mesh build command in the build step.

Then:

import { createBuiltMeshHTTPHandler } from './.mesh'
 
// Pass Mesh's HTTP handler as an event listener
self.addEventListener('fetch', createBuiltMeshHTTPHandler())

You can see the following examples for more details:

• Response Caching on a REST API
• Response Caching on a GraphQL API

Also you can see how to setup KV as a cache storage in GraphQL Mesh here.

Deploy on Node.js

Mesh as an Express route

Similarly to regular and Vercel deployment, we will need to add the mesh build command in the build step.

import { createBuiltMeshHTTPHandler } from './.mesh'
 
const app = express()
app.use('/graphql', createBuiltMeshHTTPHandler())

Mesh as a Fastify route

Similarly to regular and Vercel deployment, we will need to add the mesh build command in the build step.

import { createBuiltMeshHTTPHandler } from './.mesh'
 
const app = fastify()
 
const meshHttp = createBuiltMeshHTTPHandler()
 
app.route({
  url: '/graphql',
  method: ['GET', 'POST', 'OPTIONS'],
  async handler(req, reply) {
    // Second parameter adds Fastify's `req` and `reply` to the GraphQL Context
    const response = await meshHttp.handleNodeRequest(req, {
      req,
      reply,
    })
    response.headers.forEach((value, key) => {
      reply.header(key, value)
    })
 
    reply.status(response.status)
 
    reply.send(response.body)
 
    return reply
  },
})

Mesh as a Node.js request handler

Similarly to regular and Vercel deployment, we will need to add the mesh build command in the build step.

import { createBuiltMeshHTTPHandler } from './.mesh'
import { createServer } from 'node:http'
 
const server = createServer(createBuiltMeshHTTPHandler())
server.listen(4000)

Mesh as a Koa route

Similarly to regular and Vercel deployment, we will need to add the mesh build command in the build step.

import { createBuiltMeshHTTPHandler } from './.mesh'
 
const app = new Koa()
 
const meshHttp = createBuiltMeshHTTPHandler()
app.use(async (ctx) => {
  // Second parameter adds Koa's context into GraphQL Context
  const response = await meshHttp.handleNodeRequest(ctx.req, ctx)
 
  // Set status code
  ctx.status = response.status
 
  // Set headers
  response.headers.forEach((value, key) => {
    ctx.append(key, value)
  })
 
  // Converts ReadableStream to a NodeJS Stream
  ctx.body = response.body
})

Mesh and Sveltekit

Similarly to regular and Vercel deployment, we will need to add the mesh build command in the build step.

import { createBuiltMeshHTTPHandler } from './.mesh'
 
const meshHttp = createBuiltMeshHTTPHandler()
 
export {
  meshHttp as get,
  meshHttp as post,
}

Mesh and Docker

A GraphQL Mesh Gateway should be treated like any Node.js project while keeping in mind that a mesh build step should be added to the deployment steps.