Schema loading

GraphQL-Markdown use external loaders for loading GraphQL schemas (see full list).

You can declare as many loaders as you need using a LoaderOption map:

type LoaderOption = {
  [name: ClassName]: PackageName | PackageConfig;
};

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

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

type PackageConfig = {
  module: PackageName;
  options?: PackageOptionsConfig;
};

type RootTypes = { query?: string; mutation?: string; subscription?: string };

type PackageOptionsConfig = BaseLoaderOptions & RootTypes;

Local schema (file)

Use @graphql-tools/graphql-file-loader if you want to load a local schema:

shell

npm install @graphql-tools/graphql-file-loader

Once done, you can declare the loader in the GraphQL-Markdown configuration:

.graphqlrc

schema: ./schema.graphql
extensions:
  graphql-markdown:
    loaders:
      GraphQLFileLoader: "@graphql-tools/graphql-file-loader"

Remote schema (url)

Use @graphql-tools/url-loader, if you want to load a schema from a URL:

shell

npm install @graphql-tools/url-loader

Once done, you can declare the loader in the GraphQL-Markdown configuration:

.graphqlrc

schema: ./schema.graphql
extensions:
  graphql-markdown:
    loaders:
      UrlLoader:
        module: "@graphql-tools/url-loader"
        options:
          headers:
            Authorization: "<API_KEY>" # replace with your key if the gateway needs an auth key

tip

See our Troubleshooting section in case of error 'UrlLoader' does not exist in type 'LoaderOption'.ts.

Code-first schema (TypeScript/JavaScript)

For teams using a code-first approach, use @graphql-tools/code-file-loader to load a schema exported directly from a TypeScript or JavaScript file:

shell

npm install @graphql-tools/code-file-loader

Once done, you can declare the loader in the GraphQL-Markdown configuration:

.graphqlrc

schema: ./src/**/graphql/*.ts
extensions:
  graphql-markdown:
    loaders:
      CodeFileLoader: "@graphql-tools/code-file-loader"

The schema file must export a GraphQLSchema instance as its default or named export. This works with any code-first library that produces a GraphQLSchema — including makeExecutableSchema (graphql-tools), Pothos, TypeGraphQL, and NestJS.