Skip to main content
View plugin on GitHub
See starters using this

Gatsby Source Directus

:warning: This project is under heavy development, so breaking changes may occur on our road to a stable v1.0.0. Any bug report will be highly appreciated.


A Gatsby source plugin to pull content from a Directus CMS backend.

Inspired by the gatsby-source-directus7 plugin by Joonas Palosuo


  • Exposes all custom content types & associated records created in Directus as distinct nodes in the Gatsby GraphQL layer
  • Mirrors O2M, M2O, M2M, and “File” relations between content types in Directus in the Graph QL layer
  • Downloads files hosted in Directus for usage with other Gatsby transformer plugins


Installing the plugin is no different than installing other Gatsby source plugins.

Create a gatsby project using Gatsby quick start guide.

Install the plugin:

# using npm
npm install --save @directus/gatsby-source-directus
# using yarn
yarn add @directus/gatsby-source-directus

Configure the plugin by editing your gatsby-config.js. See below for details.


Known Limitations

For the a collection type to exist in the GraphQL layer, there must be at least one record processed by the plugin belonging to the collection.

E.g. if either no records exist for the collection, or they are all filtered by the plugin configuration, that collection will not appear in the GraphQL layer, and any attempts to query against it will throw an error.

Similarly, for a field defined as a M2O, O2M, M2M, or File(s) relation to exist in the GraphQL schema for a given collection, there must exist at least one record that has a non-null value for that field. Attempts to query fields where no relations have been defined in Directus will throw an error.

E.g. if we have a products collection in Directus that has a reviews field defined as a O2M relation to a review collection, if all products have no reviews, the reviews field will not be available in the directusProducts GraphQL schema, and attempts to execute a query { directusProducts { reviews { ... } } } query will throw an error.


The project is written in TypeScript. You can clone the repo and use the command yarn dev to start TypeScript in watch-mode. yarn build builds the project.


Running the linter is as simple as:

yarn lint

# Fix formatting
yarn format


Some simple unit tests can be run using the following command:

yarn test

In order to run e2e tests, we rely on docker and docker-compose for setting up a Directus API.

Start the docker environment:

docker-compose up -d

Usually wait few seconds before the docker environment is ready to accept requests and you can run e2e tests:

yarn e2e

Please see docker and docker-compose documentation websites for more details.