Gatsby Source Plugins — Pulling Data from Files and CMS

In this tutorial, you will learn about Gatsby Source Plugins. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Gatsby source plugins for pulling data from filesystems, headless CMS platforms, databases, and external APIs into the GraphQL layer.

In this lesson, you'll understand how source plugins work, configure common source plugins, and combine multiple data sources.

What You'll Learn

How source plugins create GraphQL nodes, how to configure gatsby-source-filesystem, gatsby-source-contentful, and gatsby-source-graphql.

Why It Matters

Source plugins determine what data is available in your Gatsby site. The right source plugin configuration makes any data source accessible through GraphQL.

flowchart LR
    A[Source Plugins] --> B[Filesystem]
    A --> C[Contentful CMS]
    A --> D[WordPress]
    A --> E[GraphQL API]
    B --> F[GraphQL Nodes]
    C --> F
    D --> F
    E --> F
    style A fill:#639,color:#fff

gatsby-source-filesystem

The most common source plugin — reads files from the local filesystem:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-filesystem',
      options: {
        name: 'posts',
        path: `${__dirname}/content/posts/`
      }
    },
    {
      resolve: 'gatsby-source-filesystem',
      options: {
        name: 'images',
        path: `${__dirname}/src/images/`
      }
    },
    {
      resolve: 'gatsby-source-filesystem',
      options: {
        name: 'data',
        path: `${__dirname}/src/data/`
      }
    }
  ]
};

Output: Every file in the configured directories becomes a File node in GraphQL. The name option identifies the source instance, useful for filtering.

gatsby-source-contentful

Pull content from Contentful headless CMS:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-contentful',
      options: {
        spaceId: process.env.CONTENTFUL_SPACE_ID,
        accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
        downloadLocal: false
      }
    }
  ]
};

Query Contentful data:

query {
  allContentfulBlogPost(sort: { createdAt: DESC }) {
    nodes {
      title
      slug
      publishedDate(formatString: "MMMM D, YYYY")
      body {
        childMarkdownRemark {
          html
        }
      }
      heroImage {
        gatsbyImageData(width: 800)
      }
    }
  }
}

Output: Contentful content types become GraphQL types. Each entry becomes a node with its fields available for querying.

gatsby-source-graphql

Connect to any GraphQL API:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-graphql',
      options: {
        typeName: 'GitHub',
        fieldName: 'github',
        url: 'https://api.github.com/graphql',
        headers: {
          Authorization: `Bearer ${process.env.GITHUB_TOKEN}`
        }
      }
    }
  ]
};

Query external GraphQL data:

query {
  github {
    viewer {
      name
      repositories(first: 5) {
        nodes {
          name
          description
          stargazerCount
        }
      }
    }
  }
}

Output: External GraphQL APIs are wrapped under the github field. You can query GitHub data alongside local filesystem data.

gatsby-source-WordPress

Connect to WordPress as a headless CMS:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-wordpress',
      options: {
        url: 'https://example.com/graphql'
      }
    }
  ]
};

Query WordPress data:

query {
  allWpPost(sort: { date: DESC }) {
    nodes {
      title
      slug
      excerpt
      featuredImage {
        node {
          localFile {
            childImageSharp {
              gatsbyImageData(width: 600)
            }
          }
        }
      }
    }
  }
}

Output: WordPress posts, pages, media, and custom post types become available in Gatsby's GraphQL layer with automatic image processing.

Combining Multiple Sources

Query data from all sources in one page:

query Dashboard {
  # From filesystem
  localPosts: allMarkdownRemark(limit: 5) {
    nodes { frontmatter { title } }
  }

  # From Contentful
  cmsPosts: allContentfulBlogPost(limit: 5) {
    nodes { title slug }
  }

  # From WordPress
  wpPosts: allWpPost(limit: 5) {
    nodes { title slug }
  }
}

Output: A dashboard page displays content from all three sources. Each source is accessed through its GraphQL type prefix.

Common Mistakes

1. Not restarting after configuring plugins: Plugin changes in gatsby-config.js require restarting the dev server.
2. Hardcoding API keys in config: Use environment variables with Process.env.API_KEY and .env files.
3. Missing .env files: Ensure .env.development and .env.production exist and are loaded with dotenv.
4. Installing source plugin without transformer: A source plugin creates raw nodes. You need transformer plugins to convert them to usable formats.
5. Over-fetching in queries: Query only the fields you need. Each field adds to build time and bundle size.

Practice Questions

1. What do source plugins do? Answer: They fetch data from external sources (filesystem, CMS, APIs) and create GraphQL nodes representing that data.

2. How do you configure multiple filesystem sources? Answer: Add multiple gatsby-source-filesystem instances with different name and path options. Use sourceInstanceName to filter in queries.

3. What is the fieldName option in gatsby-source-graphql? Answer: It defines the top-level field name for the external API in your GraphQL schema. Example: github makes the API accessible at query { github { ... } }.

4. Why combine gatsby-source-contentful with gatsby-transformer-remark? Answer: To convert Contentful's rich text fields (which come as JSON) into HTML for rendering in React components.

Challenge

Create a Gatsby site that sources data from three different sources: local Markdown files, Contentful blog posts, and GitHub Repository data via gatsby-source-graphql. Display all three in a unified dashboard.

Mini Project

Set up a headless CMS-driven site with gatsby-source-contentful. Create 5 content types (Blog Post, Author, Category, Product, Testimonial) in Contentful and build pages for each.

FAQ

What's Next

Learn about Gatsby Transformer Plugins to transform raw data nodes into usable formats like HTML and optimized images.