• Docs
  • Getting Started
  • Customize the Mesh server

How to: Customize the Mesh server

GraphQL Mesh provides a reliable and production-ready server implementation built with GraphQL Yoga and Envelop with, out of the box support for:

  • Persisted queries
  • Live queries
  • Files upload
  • Serverless deployment
  • and more...

Customizing your GraphQL Mesh Gateway server can be achieved in 2 ways:

  • Configure and provide Envelop plugins: to add behaviors such as caching, authentication, tracing to your Gateway
  • Provide a standalone server implementation: to completely replace the server used by the Gateway

Configure and provide plugins

Aided by the capabilities of Envelop, you can easily add plugins that helps with security and authentication, advanced caching, error handling, monitoring, logging and much more.

For full list of available plugins, please refer to the plugins section.

Provide a standalone server implementation

Disclaimer: This section explains how to provide a custom server implementation used by mesh serve and mesh dev. If you are looking for solutions to deploy Mesh to Serverless environments or not rely on mesh serve, please refer to the "How to: Deploy a Mesh Gateway" guide.

The following example shows how to replace GraphQL Mesh's default server implementation with Apollo Server.

GraphQL Mesh uses Envelop under the hood, so you need to check other integrations to see how to use getEnveloped with other server frameworks. Envelop Integrations

import { ApolloServer } from 'apollo-server'
import type { ServeMeshOptions } from '@graphql-mesh/runtime'
export default async function ({ getBuiltMesh, logger, argsPort }: ServeMeshOptions): Promise<void> {
  const { schema, getEnveloped } = await getBuiltMesh()
  const apolloServer = new ApolloServer({
    async executor(requestContext) {
      const { schema, execute, contextFactory } = getEnveloped({ req: requestContext.request.http })
      return execute({
        document: requestContext.document,
        contextValue: await contextFactory(),
        variableValues: requestContext.request.variables,
        operationName: requestContext.operationName
  const { url } = await apolloServer.listen(argsPort)
  logger.info(`🚀 Server ready at ${url}`)

Then add the following line to your configuration file:

  customServerHandler: ./myServerHandler
When you use a custom server handler, you won't be able to use configuration options under serve!

Configuration: serve reference

  • fork - - Spawn multiple server instances as node clusters (default: 1) One of:
    • Int
    • Boolean
  • port - - TCP Port to listen (default: 4000) One of:
    • Int
    • String
  • hostname (type: String) - The binding hostname (default: localhost)
  • cors (type: Object) - Configuration for CORS:
    • origin (type: Any)
    • allowedHeaders (type: Array of String)
    • exposedHeaders (type: Array of String)
    • credentials (type: Boolean)
    • maxAge (type: Int)
    • preflightContinue (type: Boolean)
    • optionsSuccessStatus (type: Int)
  • staticFiles (type: String) - Path to your static files you want to be served with GraphQL Mesh HTTP Server
  • playground (type: Boolean) - Show GraphiQL Playground
  • sslCredentials (type: Object) - SSL Credentials for HTTPS Server If this is provided, Mesh will be served via HTTPS:
    • key (type: String, required)
    • cert (type: String, required)
  • endpoint (type: String) - Path to GraphQL Endpoint (default: /graphql)
  • browser - - Path to the browser that will be used by mesh serve to open a playground window in development mode This feature can be disabled by passing false One of:
    • String
    • Boolean
  • customServerHandler (type: String) - If you want to use a custom GraphQL server, you can pass the path of the code file that exports a custom Mesh Server Handler With a custom server handler, you won't be able to use the features of GraphQL Mesh HTTP Server
  • playgroundTitle (type: String) - Title of GraphiQL Playground
  • trustProxy (type: String) - Configure Express Proxy Handling Learn more
Last updated on September 21, 2022