gatsby-source-datocms

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.

Table of Contents

• Install
• Sample project
• How to use
• How to query
  • Accessing records
  • Multiple-paragraph text fields
  • Modular content fields
  • Structured text fields
  • Favicon meta tags
  • SEO meta tags
  • Tree-like collections
  • Single instance models
  • Localized fields
• Integration with Gatsby Image
• Field customisations
• Connecting to multiple DatoCMS projects
• Configuring Content Previews

Install

npm install --save gatsby-source-datocms gatsby-plugin-image

PS. If you're on a Gatsby 2 project, please use version "^2.6.17" of this package. PS. If you're on a Gatsby 3 project, or Gatsby 4 lower than 4.24.0, please use version "^4.0.4" of this package.

Sample projects

We've prepared several projects for you: portfolio, blog, snipcart

How to use

// 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. Make sure to grant both CDA and CMA permissions.
      apiToken: `YOUR_READONLY_API_TOKEN`,

      // The project environment to read from. Defaults to the primary environment:
      environment: `main`,

      // 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 (you probably don't need this!)
      // apiUrl: 'https://site-api.datocms.com',

      // Limits page size and can be used to avoid build timeouts.
      // Default is 500 (also the maximum)
      pageSize: 500,
    },
  },
];

How to query

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
  }
}

Accessing records

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
          }
        }
      }
    }
  }
}

Multiple-paragraph text fields

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 (converting markdown only works with Markdown editor as name suggests):

{
  allDatoCmsBlogPost {
    edges {
      node {
        excerptNode {
          childMarkdownRemark {
            html
            timeToRead
          }
        }
      }
    }
  }
}

If these fields are localized, you can leverage localization arguments to access the field in different languages like explained here.

Modular content fields

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>

Structured text fields

Structured Text fields can be queried this way:

⚠️ IMPORTANT: make sure you add the id: originalId part in both the blocks and links sub-queries, or the <StructuredText> component won't work!

{
  datoCmsBlogPost {
    content {
      value
      links {
        __typename
        ... on DatoCmsArticle {
          id: originalId
          title
          slug
        }
      }
      blocks {
        ... on DatoCmsImage {
          id: originalId
          image {
            url
            alt
          }
        }
      }
    }
  }
}

You can then present your blocks using the <StructuredText> component.

import { StructuredText } from 'react-datocms';

<div>
  {
    <StructuredText
      data={data.blogPost.content}
      renderInlineRecord={({ record }) => {
        switch (record.__typename) {
          case 'DatoCmsArticle':
            return <a href={`/articles/${record.slug}`}>{record.title}</a>;
          default:
            return null;
        }
      }}
      renderLinkToRecord={({ record, children }) => {
        switch (record.__typename) {
          case 'DatoCmsArticle':
            return <a href={`/articles/${record.slug}`}>{children}</a>;
          default:
            return null;
        }
      }}
      renderBlock={({ record }) => {
        switch (record.__typename) {
          case 'DatoCmsImage':
            return <img src={record.image.url} alt={record.image.alt} />;
          default:
            return null;
        }
      }}
    />
  }
</div>;

If you need to generate an excerpt you can use the datocms-structured-text-to-plain-text package to convert the document into plain text:

import { render as toPlainText } from 'datocms-structured-text-to-plain-text';
import ellipsize from 'ellipsize';

ellipsize(toPlainText(data.blogPost.content), 100);

SEO meta tags

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
      }
    }
  }
}

Favicon meta tags

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
      }
    }
  }

Tree-like collections

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
          }
        }
      }
    }
  }
}

Single instance models

You can access to single instance models like this:

{
  datoCmsHomepage {
    title
    content
  }
}

Localized fields

When you're fetching the value of a localized field, by default it will be returned to the project default locale — that is, the first locale in your project settings:

query {
  datoCmsSite {
    locales # -> ["en", "it"]
  }
  allDatoCmsBlogPost {
    title # -> will return the title value in "en" locale
  }
}

To change that, you can add a locale argument to queries to specify another locale:

query {
  allDatoCmsBlogPost(locale: "it") {
    title # -> will return the title value in "it" locale
  }
}

You can also specify a different locale on a per-field basis:

query {
  allDatoCmsBlogPost(locale: "it") {
    title # -> will return the title value in "it" locale
    enTitle: title(locale: "en") # -> will return the title value in "en" locale
  }
}

Locale fallbacks

You can also specify a list of fallback locales together with the locale argument:

query {
  allDatoCmsBlogPost(locale: "it", fallbackLocales: ["en"]) {
    title
  }
}

If the field value for the specified locale is null-ish (null, empty string or empty array), the system will try to find a non null-ish value in each of the localizations specified in the fallbackLocales argument. The order of the elements in the fallbackLocales argument is important, as the system will start from the first element in the array, and go on from there.

Just like the locale argument, you can specify different fallback locales on a per-field basis:

query {
  allDatoCmsBlogPost {
    title(locale: "it", fallbackLocales: ["en"])
  }
}

Integration with Gatsby Image

For Gatsby v3+ (currently in beta)

This plugin is compatible with the new gatsby-plugin-image and the <GatsbyImage /> component released with Gatsby v3:

import React from 'react';
import { GatsbyImage } from 'gatsby-plugin-image';

const About = ({ data }) => (
  <article>
    <GatsbyImage image={data.datoCmsAboutPage.photo.gatsbyImageData} />
  </article>
);

export default About;

export const query = graphql`
  query AboutQuery {
    datoCmsAboutPage {
      photo {
        gatsbyImageData(
          width: 600
          placeholder: BLURRED
          forceBlurhash: false
          imgixParams: { invert: true }
        )
      }
    }
  }
`;

When placeholder is set to BLURRED, the normal behaviour is to use DatoCMS blurhash placeholders, except for PNG files, which might require transparency. If you want to force blurhash placeholders also for PNGs, pass the option forceBlurhash: true.

NOTE: gatsby-plugin-sharp needs to be listed as a dependency if you plan to use placeholder: TRACED_SVG.

Compatibility with the deprecated gatsby-image component

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
          forceBlurhash: false
          imgixParams: { fm: "jpg", auto: "compress" }
        ) {
          ...GatsbyDatoCmsFluid
        }
      }
    }
  }
`;

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
          forceBlurhash: false
          imgixParams: { fm: "jpg", auto: "compress" }
        ) {
          ...GatsbyDatoCmsFixed
        }
      }
    }
  }
`;

Field customisations

If you need to customize the GraphQL response that you get from DatoCMS (e.g augmenting models, manipulating fields), you should include your logic in the createResolvers API.

Read more about how to customise the GraphQL schema in the Gatsby documentation

Connecting to multiple DatoCMS projects

If you need to connect your website to multiple DatoCMS projects, use the instancePrefix option:

// In your gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-datocms`,
      options: {
        apiToken: 'XXX',
        instancePrefix: 'FirstProject',
      },
    },
    {
      resolve: `gatsby-source-datocms`,
      options: {
        apiToken: 'YYY',
        instancePrefix: 'SecondProject',
      },
    },
  ],
};

This will allow you to perform all the queries with a specific token and distinguish between the results:

{
  datoCmsFirstProjectSite {
    name
    internalDomain
    locales
  }

  datoCmsSecondProjectSite {
    name
    internalDomain
    locales
  }

  allDatoCmsFirstProjectBlogPost {
    nodes {
      title
      excerpt
    }
  }

  allDatoCmsSecondProjectBlogPost {
    nodes {
      title
      cover {
        url
      }
    }
  }
}

Configuring Content Previews

Configuration will be handled for you when using DatoCMS Quick Connect on Gatsby Cloud. However, if you'd prefer not to use Quick Connect and manually setup the integration, instructions can be found here.