Handbook
Other integrations
Subservice languages
JavaScript

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 (opens in a new tab) for Apollo Federation (opens in a new tab).

This example demonstrates:

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

Sandbox

You can also see the project on GitHub here (opens in a new tab).

The following services are available for interactive queries:

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.
OverviewRuby