Official GatsbyJS source plugin to pull content from DatoCMS
Switch branches/tags
Clone or download
Latest commit 0039126 Nov 23, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Add np Jul 25, 2018
.babelrc Add babel-plugin-transform-object-rest-spread May 30, 2018
.gitignore Only export fragments for types we actually have Dec 18, 2017
.npmignore First commit Dec 1, 2017
CHANGELOG.md Bump version Jun 18, 2018
README.md README Oct 24, 2018
package.json v2.0.1 Nov 23, 2018
yarn.lock Update datocms-client dependency Nov 23, 2018

README.md

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

npm install --save gatsby-source-datocms

Sample project

We've prepared a sample Gatsby project for you!

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:
      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',
    },
  },
]

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):

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

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>

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>

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

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

Integration with gatsby-image

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.

Responsive fluid

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

Responsive fixed

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