https://github.com/directus/gatsby-source-directus
Source plugin for pulling data into Gatsby from a Directus API.
https://github.com/directus/gatsby-source-directus
Last synced: 6 months ago
JSON representation
Source plugin for pulling data into Gatsby from a Directus API.
- Host: GitHub
- URL: https://github.com/directus/gatsby-source-directus
- Owner: directus
- Created: 2022-07-09T11:40:07.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-10-19T10:56:14.000Z (about 2 years ago)
- Last Synced: 2025-06-25T13:59:17.268Z (7 months ago)
- Language: JavaScript
- Size: 607 KB
- Stars: 11
- Watchers: 12
- Forks: 14
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Funding: .github/funding.yml
Awesome Lists containing this project
README
# gatsby-source-directus
Source plugin for pulling data into the [Gatsby GraphQL Data Layer](https://www.gatsbyjs.com/docs/reference/graphql-data-layer/) from a Directus API.
## 5️⃣ Installation for gatsby 4 and 5
Depending on the `gatsby` version you are using you will need to include the following dependencies to your project on these respective versions: `@4`if you are using `gatsby@4` and `@5` if you are using `gatsby@5`.
### gatsby@4 dependencies
```bash
npm install --save gatsby-source-graphql@4 gatsby-source-filesystem@4
```
### gatsby@5 dependencies
```bash
npm install --save gatsby-source-graphql@5 gatsby-source-filesystem@5
```
### Install the package
```bash
npm install --save @directus/gatsby-source-directus
```
## Usage
1. Go to `gatsby-config.js` on your Gatsby project
2. Add new entry to plugins properly configured with your settings
```js
module.exports = {
// ... some gatsby configuration
plugins: [
// ... some gatsby plugins
// You can take advantage of the following plugins with gatsby-source-directus
// `gatsby-plugin-image`,
// `gatsby-transformer-sharp`,
// `gatsby-plugin-sharp`,
// Finally our plugin
{
resolve: '@directus/gatsby-source-directus',
options: {
url: `https://myproject.directus.cloud`, // Fill with your Directus instance address
auth: {
token: 'my_secret_token', // You can use a static token from an user
// Or you can use the credentials of an user
// email: "johndoe@directus.cloud",
// password: "mysecretpassword",
},
},
},
],
};
```
3. Request your data
```graphql
query {
# if you change `type.name`, remember to also rename following field
directus {
# the collection you want to query
articles {
# the fields you want to query from above collection
title
files {
# since this is a M2M relationship, we need to reference the junction field
directus_files_id {
# `id` is required to be fetched in order to be used with `gatsby-transformer-sharp`
id
imageFile {
# when using the plugin 'gatsby-transformer-sharp', you can query images with transformations
childImageSharp {
gatsbyImageData(width: 200)
}
}
}
}
}
}
# it's also possible to query system collections
directus_system {
users {
email
}
files {
id
imageFile {
childImageSharp {
gatsbyImageData(width: 200)
}
}
}
}
}
```
**Note**: When using with `gatsby-transformer-sharp` you will need to query `id` of the asset (specified on
`DirectusData_directus_files` type).
## Options
- `url` [*Required*] - should be a valid URL to your Directus instance
- `auth` [*Optional*] - defines if requests will have authentication or not. You should define this if you want access
to non-public content.
[View more about permissions](https://docs.directus.io/configuration/users-roles-permissions/#users-roles-permissions)
- `auth.token` [*Optional*] - should be the static token of the user which will make the requests. You can define one
on user detail page.
- `auth.email` [*Optional, but required with password and ignored if `auth.token` defined*] - should be the email of
the user which will make the requests.
- `auth.password` [*Optional, but required with email and ignored if `auth.token` defined\*] - should be the password
of the user which will make the requests.
- `type` [*Optional*] - defines the type and field name to be used on GraphQL. If you are using multiple instances of
Directus, please ensure you have unique type and field names per instance.
- `type.name` [*Optional, defaults to `DirectusData`*] - defines the GraphQL type name to be used for user defined
collections
- `type.field` [*Optional*, defaults to `directus`] - defines the GraphQL field name to query user defined
collections. If you change this property, remember to query the proper field inside `query`.
- `type.system_name` [*Optional, defaults to `DirectusSystemData`*] - defines the GraphQL type name to be used for
Directus defined collections, i.e., `directus_users`, `directus_files`, etc.
- `type.system_field` [*Optional*, defaults to `directus_system`] - defines the GraphQL field name to query Directus
defined collections.
- `dev` [*Optional*] - defines options for development environments
- `dev.refresh` [*Optional, defaults to 15s*] - tells the refresh rate in seconds of the schema. Should be a number in
seconds or a string supported by [ms](https://github.com/vercel/ms)
- `graphql` [*Optional*] - defines extra options to be passed into `gatsby-source-graphql`. Useful for advanced use
cases.
- `concurrency` [*Optional, defaults to `10`*] - tells how much images tries to download concurrently
## How to query
The default way to query data is to fetch items from `directus` field.
```graphql
query {
directus {
items {
my_collection {
some_field
other_field
}
}
}
}
```
If you specify the `type.field`, you must query from that field instead.
```graphql
query {
# In this case `type.field` is "blog"
blog {
items {
posts {
id
title
slug
status
}
}
}
# While in this case `type.field` is "portal"
portal {
items {
pages {
id
title
slug
status
}
}
}
}
```
## Docs
[View more about Directus](https://docs.directus.io/)