GraphQL Mesh: a gateway that turns REST, gRPC and SOAP into one GraphQL schema

The problem GraphQL Mesh solves: services that will never speak GraphQL

Most organizations do not have a clean GraphQL backend. They have an OpenAPI spec for billing, a gRPC service for inventory, a SOAP endpoint that predates the current team, and a PostgreSQL database that a reporting tool reads directly. The README frames the goal plainly: let developers access services written in "gRPC, OpenAPI/Swagger, OData, SOAP/WSDL, Apache Thrift, Mongoose, PostgreSQL, Neo4j, and also GraphQL" through GraphQL queries and mutations.

The audience is therefore backend and platform engineers who own the integration layer, not application developers writing their first query. Someone has to decide how a REST path becomes a field, how a WSDL operation becomes a mutation, and how types from two unrelated specs get linked. GraphQL Mesh puts that work in a configuration file and a build step rather than in hand-written resolver code. The README also notes it can run "as a gateway to other services or run as a local GraphQL schema that aggregates data from remote APIs", which covers two quite different deployment shapes: a shared gateway process and a schema embedded inside one application.

How the schema composition pipeline actually works

The README lists five steps, and they are worth reading as a pipeline rather than a feature list. First, Mesh collects API schema specifications from services. Second, it creates a runtime instance of a fully-typed SDK for those services. Third, it converts the API specs to a GraphQL schema. Fourth, it applies custom schema transformations and extensions. Fifth, it creates a Federation subgraph or a Federation-compatible supergraph.

The second step is the one that shapes everything else. Because Mesh builds an SDK per source, the generated schema is not a thin proxy: each field resolves through code derived from the spec. That is why the README can claim it lets you "modify the output schemas, link types across schemas and merge schema types", and why you can "add custom GraphQL types and resolvers that fit your needs". The transformation step sits between conversion and federation, so a rename or a type link applied there affects the composed result rather than a single source.

The repository layout reflects the same split. Top-level entries include packages/, examples/, e2e/ and website/, and the workspace list in package.json separates packages/legacy/handlers, packages/legacy/transforms, packages/legacy/mergers, packages/cache, packages/plugins, packages/fusion, packages/loaders and packages/transports. Handlers, transforms and mergers are distinct package families, which matches the pipeline: fetch a spec, change a schema, combine schemas.

Getting started with the CLI and a first composed schema

The README points to the documentation rather than printing install commands, and it links a Getting started page plus Supported Source APIs and Schema Transformations pages. The npm badge in the README references the package @graphql-mesh/cli, so that is the package name to look for on npm. The examples directory is the practical starting point: it contains folders such as examples/hello-world, examples/hello-world-esm, examples/grpc-example, examples/grpc-reflection-example, examples/odata-microsoft and examples/json-schema-example.

A Mesh project is driven by a configuration file, and the README does not reproduce its keys. What the repository does show is that handlers, transforms and mergers live in separate package families under packages/, so the config names a source handler and its options. Because the workspace list carries both examples/ and examples/v1-next/ trees and the README links to a /v1 documentation path, check which documentation version you are following before copying a config from an example folder.

The compose command is the build step named in the related searches, and the CLI package is @graphql-mesh/cli. Running it produces the composed schema artifact that the gateway or the local runtime consumes.

yarn mesh compose

After compose finishes, the generated schema is what your clients query. If a source spec is unreachable or a handler is missing, the failure appears at this step rather than at query time, which is the main reason to run compose in CI rather than only on a developer machine.

Where GraphQL Mesh is the wrong tool

The clearest failure case is a backend estate that already speaks GraphQL Federation. Mesh's value comes from converting specs that are not GraphQL into a GraphQL schema. If your subgraphs are already GraphQL, you are paying for a conversion step that converts nothing, and you inherit a build artifact that must be regenerated whenever an upstream spec changes.

The second limitation is spec fidelity. Mesh converts from a specification, so anything the specification does not describe does not exist in the generated schema. A REST endpoint whose real behaviour diverges from its OpenAPI document produces a schema that lies. The README does not document a mechanism for reconciling that gap beyond custom resolvers and transforms, which puts the burden back on you.

The third is operational. The README describes Mesh as "acting as a proxy to your data", and a proxy is another process to run, version and monitor. The repository contains a .dockerignore and examples such as examples/cloudflare-workers and examples/gcp-functions, so several deployment targets are anticipated, but the README itself does not document rollback or schema versioning. Treat the composed schema as a deployable artifact with its own release process, because nothing in the README gives you one.

GraphQL Mesh compared with Apollo Federation

The two are often mentioned in the same breath, and the related searches include a direct comparison. The difference is where the GraphQL schema comes from. Apollo Federation assumes each subgraph is a GraphQL service that declares its own types and contributes them to a supergraph. GraphQL Mesh starts from API specifications that are not GraphQL and generates the GraphQL layer itself.

That makes them complementary rather than interchangeable in a mixed estate. A team with three GraphQL subgraphs and one legacy SOAP service can run Federation for the three and use Mesh to produce a GraphQL surface for the SOAP service, then treat that surface as another subgraph. The README supports this reading directly: Mesh creates "a Federation subgraph or a Federation-compatible supergraph".

The cost of the Mesh path is the specification dependency described above. Federation's cost is that every team must adopt GraphQL and a federation-aware server. If your constraint is organizational rather than technical, and you cannot get four teams to rewrite their services, Mesh is the pragmatic option. If you can, converting the services removes a whole layer.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-16. Recent releases are dated 2026-09-04, 2026-08-24 and 2026-08-20, so the project is being published to regularly. The licence is MIT, declared both in the README badge and in the root package.json, which permits commercial use and modification; that is a statement about the licence text, not legal advice, and you should read the LICENSE file for the terms that apply to you.

The upgrade cost is visible in the repository structure. The workspace list contains both packages/legacy/handlers, packages/legacy/transforms and packages/legacy/mergers and a separate packages/fusion family, and the examples directory carries both examples/ and examples/v1-next/ trees. The README links to a documentation path under /v1. That combination means a version migration is not a dependency bump: handlers, transforms and config format can all move together, and the presence of a legacy package tree tells you the old arrangement is still shipped. Pin your handler and transform versions, and read the changesets in .changeset/ before upgrading, since the repository uses changesets for release notes.

Editorial conclusion

Adopt GraphQL Mesh when you have OpenAPI, gRPC, SOAP, OData or database sources that will not become GraphQL services, and you want one schema and one query language in front of them. Do not adopt it if every backend already speaks GraphQL Federation, because the schema conversion layer adds a build step and a runtime hop for nothing. Before committing, verify two things in your own repository: that the source handlers you need are listed under Supported Source APIs, and that your transforms survive a rebuild of the composed schema, since the README documents no rollback for a schema that composes badly.

Frequently asked questions

Official sources

1. ardatan/graphql-mesh on GitHub
2. License: MIT
3. Project website
4. README
5. Releases