Using the Gatsby File System Route API with GraphCMS

It wasn't too long ago Gatsby introduced the File System Route API to a handful of users to test. Since then, this feature landed in Gatsby for all, and you use it to significantly reduce boilerplate when creating pages programmatically.

In most cases, you can get by without ever needing to create another gatsby-node.js file in your project, if all you are doing is building pages from data.

In this short post, we'll explore using "collection routes" to build pages for our blog posts.

The easiest way to follow along with this post is to create a new GraphCMS project using the "Blog Starter" template.

Next, you'll want to configure a new API token for accessing DRAFT, or PUBLISHED entries, or both.

Inside of your Gatsby project, or if you're starting from scratch, install the gatsby-source-graphcms dependency:

npm install -E gatsby-source-graphcms

Then add the plugin, along with your API endpoint + token to gatsby-config.js:

require("dotenv").config();

module.exports = {
  plugins: [
    {
      resolve: "gatsby-source-graphcms",
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        token: process.env.GRAPHCMS_TOKEN,
        stages: ["DRAFT"],
      },
    },
  ],
};

You'll notice we're using ENV variables above. You should create the file .env.local and add the values there, in the format of:

GRAPHCMS_ENDPOINT=...
GRAPHCMS_TOKEN=...

At this point, you can open GraphiQL to explore the generated docs, but if we stick to the default fragments the plugin creates for us, we can continue...

Inside the directory src/pages, create the file {graphCmsPost.slug}.js - here we're using dot notation to reference our GraphQL type graphCmsPost and the field slug.

Inside the file, we can export a page query that fetches our blog post by slug. The slug variable is passed from the file name (route) to our query.

Add the following query to the file:

import React from "react";
import { graphql } from "gatsby";

export const pageQuery = graphql`
  query PostPageQuery($slug: String!) {
    graphCmsPost(slug: { eq: $slug }) {
      title
      date
      content {
        html
      }
      author {
        name
      }
    }
  }
`;

Then all that's left to do is render something to the page with our title, date, content, and author.

export default function PostPage({ data: { graphCmsPost } }) {
  return (
    <React.Fragment>
      <h1>{graphCmsPost.title}</h1>
      <p>
        By {graphCmsPost.author.name} on {graphCmsPost.date}
      </p>
      <div dangerouslySetInnerHTML={{ __html: graphCmsPost.content.html }} />
    </React.Fragment>
  );
}

That's it! See this example over on GitHub to learn more.