Source plugin for pulling models and records into Gatsby from DatoCMS administrative areas. It creates links between records so they can be queried in Gatsby using GraphQL.
IMPORTANT: If you use this plugin, you will not be able to write queries as described in the DatoCMS Content Delivery API documentation. Content will be exposed using Gatsby's schema-generation. If you want to directly use our GraphQL API in Gatsby, consider using the gatsby-source-graphql plugin instead.
npm install --save gatsby-source-datocms
We've prepared a sample Gatsby project for you!
// In your gatsby-config.js
plugins: [
{
resolve: `gatsby-source-datocms`,
options: {
// You can find your read-only API token under the Settings > API tokens
// section of your administrative area:
apiToken: `YOUR_READONLY_API_TOKEN`,
// If you are working on development/staging environment, you might want to
// preview the latest version of records instead of the published one:
previewMode: false,
// Disable automatic reloading of content when some change occurs on DatoCMS:
disableLiveReload: false,
// Custom API base URL
apiUrl: 'https://site-api.datocms.com',
// Setup locale fallbacks
// In this example, if some field value is missing in Italian, fall back to English
localeFallbacks: {
it: ['en'],
},
},
},
]
Two standard data types will be available from DatoCMS: DatoCmsModel
and DatoCmsSite
. You can query model nodes created from DatoCMS like the following:
{
allDatoCmsModel {
edges {
node {
apiKey
name
fields {
apiKey
fieldType
}
}
}
}
}
Your site global settings can be queried like this:
{
datoCmsSite {
name
internalDomain
locales
}
}
Non-standard data types, i.e. models you define in DatoCMS, will also be
available in Gatsby. They'll be created in your site's GraphQL schema under
datoCms{modelApiKey}
and allDatoCms{modelApiKey}
. For example,
if you have a blog_post
model, you will be able to query it like the following:
{
allDatoCmsBlogPost(sort: { fields: [publicationDate], order: DESC }, limit: 5) {
edges {
node {
title
excerpt
publicationDate(formatString: "MM-DD-YYYY")
author {
name
avatar {
url
}
}
}
}
}
}
Fields of type Multiple-paragraph text will be available both as simple
strings (ie. excerpt
) and nodes (ie. excerptNode
). You can use the latter
if you want to apply further transformations, like converting markdown with gatsby-transformer-remark
):
{
allDatoCmsBlogPost {
edges {
node {
excerptNode {
childMarkdownRemark {
html
timeToRead
}
}
}
}
}
}
Modular-content fields can be queried this way:
{
datoCmsBlogPost {
title
content {
... on DatoCmsText {
model { apiKey }
text
}
... on DatoCmsImage {
model { apiKey }
image {
url
}
}
}
}
}
You can then present your blocks in a similar manner:
<div>
{
data.datoCmsBlogPost.content.map((block) => (
<div key={block.id}>
{
block.model.apiKey === 'text' &&
<div>{block.text}</div>
}
{
block.model.apiKey === 'image' &&
<img src={block.image.url} />
}
</div>
))
}
</div>
All records have a seoMetaTags
field that you can use to build SEO meta tags
for your record's pages:
{
allDatoCmsBlogPost {
edges {
node {
title
seoMetaTags {
tags {
tagName
content
attributes {
property
content
name
}
}
}
}
}
}
}
This package exposes a HelmetDatoCms
component and a GatsbyDatoCmsSeoMetaTags
GraphQL fragment to make it easier use these information in your website:
PS. Due to a limitation of GraphiQL,
you can not currently use the GatsbyDatoCmsSeoMetaTags
fragment in the GraphiQL IDE.
import React from 'react'
import Link from 'gatsby-link'
import { HelmetDatoCms } from 'gatsby-source-datocms'
const About = ({ data }) => (
<article className="sheet">
<HelmetDatoCms seo={data.datoCmsAboutPage.seoMetaTags} />
<h1>{data.datoCmsAboutPage.title}</h1>
<p>{data.datoCmsAboutPage.subtitle}</p>
</article>
)
export default About;
export const query = graphql`
query AboutQuery {
datoCmsAboutPage {
title
subtitle
seoMetaTags {
...GatsbyDatoCmsSeoMetaTags
}
}
}
If you need to pass additional meta tags to the underlying Helmet
component, you can add them as children and props to HelmetDatoCms
:
<HelmetDatoCms seo={data.datoCmsAboutPage.seoMetaTags}>
<link rel="alternate" href="http://www.mysite.com/it/" hreflang="it" />
<link rel="alternate" href="http://www.mysite.com/fr/" hreflang="fr" />
</HelmetDatoCms>
The datoCmsSite
global settings has also the globalSeo
field that contains the fallback fields:
{
datoCmsSite {
globalSeo {
siteName
titleSuffix
twitterAccount
facebookPageUrl
fallbackSeo {
title
description
image {
url
}
twitterCard
}
}
}
}
You can get the complete set of meta tags related to your site favicon this way:
{
datoCmsSite {
faviconMetaTags {
tagName
attributes {
rel
sizes
href
name
content
type
}
}
}
}
Similarly to what happens with SEO meta tags, you can use the HelmetDatoCms
component with the GatsbyDatoCmsFaviconMetaTags
fragment to make it easier use these information in your website:
import React from 'react'
import Link from 'gatsby-link'
import { HelmetDatoCms } from 'gatsby-source-datocms'
const TemplateWrapper = ({ data }) => (
<article className="sheet">
<HelmetDatoCms favicon={data.datoCmsSite.faviconMetaTags} />
<h1>{data.datoCmsAboutPage.title}</h1>
<p>{data.datoCmsAboutPage.subtitle}</p>
</article>
)
export default TemplateWrapper
export const query = graphql`
query LayoutQuery {
datoCmsSite {
faviconMetaTags {
...GatsbyDatoCmsFaviconMetaTags
}
}
}
If you have a model configured as a tree, you can navigate the hierarchy with
treeChildren
and treeParent
this way:
{
allDatoCmsCategory(filter: { root: { eq: true } }) {
edges {
node {
title
treeChildren {
title
treeChildren {
title
}
}
}
}
}
}
You can access to single instance models like this:
{
datoCmsHomepage {
title
content
}
}
If your site is multi-lingual, records will be duplicated for every locale
available, so you can query them like this. The same applies for the DatoCmsSite
node:
{
allDatoCmsBlogPost(filter: { locale: { eq: "it" } }) {
edges {
node {
title
excerpt
}
}
}
datoCmsHomepage(locale: { eq: "it" }) {
title
content
}
}
If you need to get every locale for a specific field, you can use the _all<FIELD>Locales
query:
{
allDatoCmsBlogPost(filter: { locale: { eq: "en" } }) {
edges {
node {
_allTitleLocales {
locale
value
}
_allExcerptLocales {
locale
value
}
}
}
}
}
Images coming from DatoCMS can be queried so that they can be used with gatsby-image, a React component specially designed to work seamlessly with Gatsby's GraphQL queries that implements advanced image loading techniques to easily and completely optimize image loading for your sites.
This GraphQL option allows you to generate responsive images that automatically respond to different device screen resolution and widths. E.g. a smartphone browser will download a much smaller image than a desktop device.
Instead of specifying a width and height, with fluid
you specify a maxWidth
, the max width the container of the images reaches.
import React from 'react'
import Img from 'gatsby-image'
const About = ({ data }) => (
<article>
<Img fluid={data.datoCmsAboutPage.photo.fluid} />
</article>
)
export default About
export const query = graphql`
query AboutQuery {
datoCmsAboutPage {
photo {
fluid(maxWidth: 600, imgixParams: { fm: "jpg", auto: "compress" }) {
...GatsbyDatoCmsFluid
}
}
}
}
`
The fragments you can use are:
GatsbyDatoCmsFluid
: "blur-up" technique to show a preview of the image while it loads;GatsbyDatoCmsFluid_tracedSVG
: "traced placeholder" SVG technique to show a preview of the image while it loads;GatsbyDatoCmsFluid_noBase64
: no preview effects.
gatsby-image
will automatically use WebP images when the browser supports the file format. If the browser doesn’t support WebP, gatsby-image
will fall back to the default image format.
If you make queries with resolutions then Gatsby automatically generates images with 1x, 1.5x, 2x, and 3x versions so your images look great on whatever screen resolution of device they're on. If you're on a retina class screen, notice how much sharper these images are.
import React from 'react'
import Img from 'gatsby-image'
const About = ({ data }) => (
<article>
<Img fixed={data.datoCmsAboutPage.photo.fixed} />
</article>
)
export default About
export const query = graphql`
query AboutQuery {
datoCmsAboutPage {
photo {
fixed(width: 200, imgixParams: { fm: "jpg", auto: "compress" }) {
...GatsbyDatoCmsFixed
}
}
}
}
`
The fragments you can use are:
GatsbyDatoCmsFixed
: "blur-up" technique to show a preview of the image while it loads;GatsbyDatoCmsFixed_tracedSVG
: "traced placeholder" SVG technique to show a preview of the image while it loads;GatsbyDatoCmsFixed_noBase64
: no preview effects.
gatsby-image
will automatically use WebP images when the browser supports the file format. If the browser doesn’t support WebP, gatsby-image
will fall back to the default image format.