We might need to customise our schema by decorating parts of it or operations to add new reusable features to these elements. To do that, we can use a GraphQL concept called **Directive**. A GraphQL directive is a special syntax used to provide additional information to the GraphQL execution engine about how to process a query, mutation, or schema definition. Directives can be used to modify the behaviour of fields, arguments, or types in your schema. A custom directive is composed of 2 parts: - schema definitions - transformer ## Schema Definition Let's explore the custom directive creation process by creating a directive to redact some fields value, hiding a phone number or an email. First of all, we must define the schema ```js const schema = ` directive @redact(find: String) on FIELD_DEFINITION type Document { excerpt: String! @redact(find: "email") text: String! @redact(find: "phone") } type Query { documents: [Document] }`; ``` To define a custom directive, we must use the directive keyword, followed by its name prefixed by a `@`, the arguments (if any), and the locations where it can be applied. ``` directive @redact(find: String) on FIELD_DEFINITION ``` According to the graphql specs the directive can be applied in multiple locations. See the list on [the GraphQL spec page](https://spec.graphql.org/October2021/#sec-Type-System.Directives). ## Transformer Every directive needs its transformer. A transformer is a function that takes an existing schema and applies the modifications to the schema and resolvers. To simplify the process of creating a transformer, we use the `mapSchema` function from the `@graphql-tools` library. In this example we are refering to [graphqltools 8.3.20](https://www.npmjs.com/package/graphql-tools/v/8.3.20) The `mapSchema` function applies each callback function to the corresponding type definition in the schema, creating a new schema with the modified type definitions. The function also provides access to the field resolvers of each object type, allowing you to alter the behaviour of the fields in the schema. ```js const { mapSchema, getDirective, MapperKind } = require("@graphql-tools/utils"); // Define the regexp const PHONE_REGEXP = /(?:\+?\d{2}[ -]?\d{3}[ -]?\d{5}|\d{4})/g; const EMAIL_REGEXP = /([^\s@])+@[^\s@]+\.[^\s@]+/g; const redactionSchemaTransformer = schema => mapSchema(schema, { // When parsing the schema we find a FIELD [MapperKind.FIELD]: fieldConfig => { // Get the directive information const redactDirective = getDirective(schema, fieldConfig, "redact")?.[0]; if (redactDirective) { // Extract the find attribute from the directive, this attribute will // be used to chose which replace strategy adopt const { find } = redactDirective; // Create a new resolver fieldConfig.resolve = async (obj, _args, _ctx, info) => { // Extract the value of the property we want redact // getting the field name from the info parameter. const value = obj[info.fieldName]; // Apply the redaction strategy and return the result switch (find) { case "email": return value.replace(EMAIL_REGEXP, "****@*****.***"); case "phone": return value.replace(PHONE_REGEXP, m => "*".repeat(m.length)); default: return value; } }; } }, }); ``` As you can see in the new resolver function as props, we receive the `current object`, the `arguments`, the `context` and the `info`. Using the field name exposed by the `info` object, we get the field value from the `obj` object, object that contains lots of helpful informations like - fieldNodes - returnType - parentType - operation ## Generate executable schema To make our custom directive work, we must first create an executable schema required by the `mapSchema` function to change the resolvers' behaviour. ```js const executableSchema = makeExecutableSchema({ typeDefs: schema, resolvers, }); ``` ## Apply transformations to the executable schema Now it is time to transform our schema. ```js const newSchema = redactionSchemaTransformer(executableSchema); ``` and to register mercurius inside fastify ```js app.register(mercurius, { schema: newSchema, graphiql: true, }); ``` ## Example We have a runnable example on "example/custom-directive.js" ## Federation and Custom Directives 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 are some extra steps that need to be run to generate the executable schema using the `@mercuriusjs/federation` library. When mercurius applies `schemaTransforms`, the internal `mapSchema` recreates every `GraphQLObjectType`. Since `resolveReference` is a non-standard runtime property set by federation, it gets lost in this process. The `@mercuriusjs/federation` library provides the `federationSchemaTransformer` utility to preserve `resolveReference` functions during schema transformations. 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. ### Schema Definition 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 = ` directive @upper on FIELD_DEFINITION extend type Query { me: User } type User @key(fields: "id") { id: ID! name: String @upper username: String }`; ``` ### Transformer 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"); const { defaultFieldResolver } = require("graphql"); function upperDirectiveTransformer(schema) { return mapSchema(schema, { [MapperKind.FIELD]: (fieldConfig) => { const upperDirective = getDirective(schema, fieldConfig, "upper")?.[0]; if (upperDirective) { const { resolve = defaultFieldResolver } = fieldConfig; fieldConfig.resolve = async function (obj, args, ctx, info) { const result = await resolve(obj, args, ctx, info); return typeof result === "string" ? result.toUpperCase() : result; }; return fieldConfig; } }, }); } ``` ### Register the schema There are two ways to use custom directives with federation. #### Option 1: Using mercuriusFederationPlugin (recommended) The simplest approach is to use `mercuriusFederationPlugin` from `@mercuriusjs/federation`. The plugin automatically wraps transformers with `federationSchemaTransformer`, so `resolveReference` functions are preserved without any extra steps. ```js const { mercuriusFederationPlugin } = require("@mercuriusjs/federation"); app.register(mercuriusFederationPlugin, { schema, resolvers, schemaTransforms: [upperDirectiveTransformer], }); ``` #### Option 2: Using buildFederationSchema with mercurius If you need more control over the schema building process, you can use `buildFederationSchema` together with mercurius directly. In this case, you **must** wrap your transformers with `federationSchemaTransformer` to preserve `resolveReference` functions. ```js const mercurius = require("mercurius"); const { buildFederationSchema, federationSchemaTransformer, } = require("@mercuriusjs/federation"); app.register(mercurius, { schema: buildFederationSchema(schema), resolvers, schemaTransforms: federationSchemaTransformer([upperDirectiveTransformer]), }); ``` > **Warning:** Without `federationSchemaTransformer`, `resolveReference` is lost during schema transformation and `_entities` queries will return `null` for entity fields: > ```js > // ⚠️ This will NOT work correctly — resolveReference is lost! > app.register(mercurius, { > schema: buildFederationSchema(schema), > resolvers, > schemaTransforms: [upperDirectiveTransformer], > }); > ``` ### 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).