Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: improve custom directives doc with federation #1009

Merged
merged 3 commits into from
Aug 16, 2023
Merged

docs: improve custom directives doc with federation #1009

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
28b8d4e
docs: improve custom directives doc with federation
Puppo Aug 11, 2023
de528dc
docs: improve custom directives doc with federation
Puppo Aug 16, 2023
68a2b5c
docs: improve custom directives doc with federation introduction
Puppo Aug 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 17 additions & 13 deletions docs/custom-directive.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,15 +128,16 @@ app.register(mercurius, {

We have a runnable example on "example/custom-directive.js"

# Federation and Custom Directives
## Federation and Custom Directives

If we are using Federation, we must follow a different approach to create custom directives.
With Federation, we use special syntaxes and custom directives already defined; for instance, `extends` or `@key`. These directives are not defined in the schema but are added by the `buildFederationSchema` function from the `@mercuriusjs/federation` library. Hence, to work with the Federation, we must follow a different approach to maintain the Federation's custom directives and add ours as well.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd suggest phrasing this paragraph like this:

Because schemas involved in GraphQL federation may use special syntax (e.g. extends) and custom directives (e.g. @key) that are not available in non-federated schemas, there's some extra steps that needs to be run to generate the executable schema, involving the use of buildFederationSchema from the @mercuriusjs/federation library and printSchemaWithDirectives from the @graphql-tools/utils library.
To see how this works, we will go through another example where we create a custom directive to uppercase the value of a field in a federated environment.

When I read "we must follow a different approach" I get the impression that I need to do something completely different, but, as I understand it, it's the same approach just with more steps to cater for the fact that we don't work with types but with entities.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I fixed the introduction as you suggested.
Thanks @d4nyll

This approach is not entirely different from the one used before, but some steps are different.

Schema definitions and transformer use the same approach indicated above. But schema generation and transformation have different implementations.
In the following example, we will create a custom directive to uppercase the value of a field in a federated environment.

## Schema Definition
### Schema Definition

The schema definition is the same as the one used in the previous example.
The schema definition is equal to the one used in the previous example. We add the `@upper` directive and we decorate the `name` field with it.

```js
const schema = `
Expand All @@ -153,9 +154,9 @@ const schema = `
}`;
```

## Transformer
### Transformer

Also, the transformer follows the same approach used in the previous example.
The transformer follows the same approach used in the previous example. We declare the uppercase transform function and apply it to the field resolver if they have the `@upper` directive.

```js
const { mapSchema, getDirective, MapperKind } = require("@graphql-tools/utils");
Expand All @@ -174,12 +175,15 @@ const uppercaseTransformer = schema =>
});
```

## Generate executable schema
### Generate executable schema

This section starts to be different. First, we need to create the federation schema using the `buildFederationSchema` function from the `mercurius-federation` library; then, we can use the `makeExecutableSchema` function from the `@graphql-tools/schema` library to create the executable schema.
This section starts to be different. First, we need to create the federation schema using the `buildFederationSchema` function from the `@mercuriusjs/federation` library; then, we can use the `makeExecutableSchema` function from the `@graphql-tools/schema` library to create the executable schema.
Using the `printSchemaWithDirectives`, we can get the schema with all the custom directives applied, and using the `mergeResolvers` function from the `@graphql-tools/merge` library, we can merge the resolvers from the federation schema and the ones we defined.

Following these steps, we can create our executable schema.

```js
const { buildFederationSchema } = require("mercurius-federation");
const { buildFederationSchema } = require("@mercuriusjs/federation");
const {
printSchemaWithDirectives,
getResolversFromSchema,
Expand All @@ -198,7 +202,7 @@ const executableSchema = makeExecutableSchema({
});
```

## Apply transformations to the executable schema
### Apply transformations to the executable schema

To apply the transformation, we have to use the mercurius plugin and pass the options:

Expand All @@ -208,11 +212,11 @@ To apply the transformation, we have to use the mercurius plugin and pass the op
```js
app.register(mercurius, {
schema: executableSchema,
schemaTransforms: [redactionSchemaTransformer],
schemaTransforms: [uppercaseTransformer],
graphiql: true,
});
```

## Example
### Example

We have a runnable example in the Federation repo that you can find here [examples/withCustomDirectives.js](https://github.com/mercurius-js/mercurius-federation/tree/main/examples/withCustomDirectives.js).