JavaScript Code-First Schemas

This example demonstrates the use of stitching directives to configure type merging, similar to the prior example, but uses code-first schemas instead of SDL.

The @graphql-tools/stitching-directives package provides importable directives definitions that can be used to annotate types and fields within subschemas, a validator to ensure the directives are used appropriately, and a configuration transformer that can be used on the gateway to convert the subschema directives into explicit configuration setting.

It also provides pre-built directives to be used with code-first schemas that do not parse SDL. The validator is configured to read directives from GraphQL entity extensions, which actually take priority when present over the SDL.

The @graphql-tools/utils package also exports a function that can print these “directives within extensions” as actual directives that can be then exposed via subservice to the gateway.

Note: the service setup in this example is based on the official demonstration repository for Apollo Federation.

This example demonstrates:

Use of the @key, @computed and @merge “directives within extensions” to specify type merging configuration.

Sandbox

⬇️ Click ☰ to see the files

You can also see the project on GitHub here.

The following services are available for interactive queries:

Stitched gateway: listening on 4000/graphql
Accounts subservice: listening on 4001/graphql
Inventory subservice: listening on 4002/graphql
Products subservice: listening on 4003/graphql
Reviews subservice: listening on 4004/graphql

Summary

First, try a query that includes data from all services:

query {
  products(upcs: [1, 2]) {
    name
    price
    weight
    inStock
    shippingEstimate
    reviews {
      id
      body
      author {
        name
        username
        totalReviews
      }
      product {
        name
        price
      }
    }
  }
}

Neat, it works! All those merges were configured through schema annotations within schemas!

Accounts subservice

The Accounts subservice showcases how schemas created with vanilla graphql-js can also utilize stitching directives to achieve the benefits of colocating types and their merge configuration, including support for hot-reloading:

Directive usages: implemented as “directives within extensions,” i.e. following the Gatsby/graphql-compose convention of embedding third party directives under the directives key of each GraphQL entity’s extensions property.
Directive declarations: directly added to the schema by using the compiled directives exported by the @graphql-tools/stitching-directives package.

Inventory subservice

The Inventory subservice demonstrates using stitching directives with a schema created using the nexus library:

Directive usages: implemented as “directives within extensions,” i.e. following the Gatsby/graphql-compose convention of embedding third party directives under the directives key of each GraphQL entity’s extensions property.
Directive declarations: nexus does not yet support passing in built graph-js GraphQLDirective objects, but you can easily create a new schema from the nexus schema programatically (using new GraphQLSchema({ ...originalSchema.toConfig(), directives: [...originalSchema.getDirectives(), ...allStitchingDirectives] }).

Products subservice

The Products subservice shows how TypeGraphQL can easily implement third party directives including stitching directives.

Directive usages: implemented using the @Directive decorator syntax, TypeGraphQL’s method of supporting third party directives within its code-first schema.
Directive declarations: directly added to the schema by using the compiled directives exported by the @graphql-tools/stitching-directives package.

Reviews subservice

The Reviews subservice is available for comparison to remind us of how makeExecutableSchema utilizes directives with SDL.

Directive usages: implemented using directives within actual SDL.
Directive declarations: directive type definitions are imported from the @graphql-tools/stitching-directives package.

Overview Ruby