Skip to main content

Custom schema directives handling

Use customDirective to render a custom description or badge for the directives applied in your schema.

caution

customDirective is deprecated in favor of decorators, which supersedes it. See migrating from customDirective.

You can select which directives are rendered for the types or locations where they are declared, with a custom description for each.

For example, a query called searchRole should be limited to ADMIN user roles. We can express this by adding a directive called auth with an argument requires to the query.

directive @auth(requires: Roles = ADMIN) on OBJECT | FIELD_DEFINITION

enum Roles {
ADMIN
USER
}

type Query {
searchRole(roles: [Roles!]! = [ADMIN]): Int! @auth
}

Usage​

Add the option customDirective to the GraphQL-Markdown configuration.

The descriptor and tag functions receive 2 arguments:

type DirectiveName = string & { _opaque: typeof DirectiveName };

type CustomDirective = {
[name: DirectiveName]: {
descriptor?: (directive?: GraphQLDirective, node?: unknown): string;
tag?: (directive?: GraphQLDirective, node?: unknown): Badge;
};
};

type Badge = {
text: string | TypeLocale;
classname: string;
};

descriptor​

The descriptor allows rendering the custom directive's description applicable to entities.

.graphqlrc.js
module.exports = {
schema: "./schema.graphql",
extensions: {
"graphql-markdown": {
// ... other options
customDirective: {
auth: {
descriptor: (directive, node) =>
directiveDescriptor(
directive,
node,
"This requires the current user to be in `${requires}` role.",
),
},
// ... other custom directive options
},
},
},
};

The descriptor output is printed as text: MDX special characters ({ } < > _ *) are escaped, so a descriptor cannot inject HTML, JSX or MDX into the page.

tag​

The tag allows rendering custom badges (tags) based on the custom directive applicable to entities.

.graphqlrc.js
module.exports = {
schema: "./schema.graphql",
extensions: {
"graphql-markdown": {
// ... other options
customDirective: {
beta: {
tag: (directive, node) => ({
text: directive.name,
classname: "badge--info",
}),
},
// ... other custom directive options
},
},
},
};

Wildcard​

You can use "*" as a wildcard for the directive name. This will allow all directives not declared with their name under customDirective to be handled by the wildcard descriptor and/or tag.

.graphqlrc.js
const {
directiveDescriptor,
directiveTag,
} = require("@graphql-markdown/helpers");

//...//

module.exports = {
schema: "./schema.graphql",
extensions: {
"graphql-markdown": {
// ... other options
customDirective: {
"*": {
descriptor: directiveDescriptor,
tag: directiveTag,
},
// ... optionally specific custom directive options
},
},
},
};

Helpers​

The packages @graphql-markdown/helpers and @graphql-markdown/graphql provide a few helper functions to quickly start.

@graphql-markdown/helpers is an optional peer dependency, and it needs to be installed before using it.

npm i @graphql-markdown/helpers

@graphql-markdown/helpers​

@graphql-markdown/graphql​