Gatsby is pretty awesome

Gatsby is pretty awesome

May 29, 2018


Hey there. I bet you're curious about what is gatsby. Well I'm here to tell you.

What is Gatsby?

As they say it is a blazing-fast static site generator for React. I personally have found it incredibly easy to set up and get going FAST. It has all the benefits expected in a modern web application. It does this by rendering dynamic React components into static HTML content via server side rendering at build time. This means that you can get all the benefits from static sites such as SEO friendliness (and simplicity) and speedy load times, without losing the interactivity that is expected of the modern web. In fact gatsby is so simple and fast that this website you see now was developed using gatsby in under 2 hours (minus blogs).

How can I get into this?

Its crazy easy! I'll give you some step by step instructions to get started in what I believe to be the best way to utilize gatsby to its true potential.

Get Started

npm install -g gatsby-cli

Gatsby comes with a great command line interface which contains the functionality of scaffolding out a working site as well as some commands to help with development.

To create a prebuild application and get started:
gatsby new my-blog This command will create the folder my-blog, it will also generate your application in which you can develop upon. There are a few things you will need to know right away. such as gatsby build which will build a production, statically generated version of the project. gatsby develop This will launch the hot-reload development server.

Awesome! We can now begin developing the site. Remember to use gatsby develop to launch the local development server in order to test the progress through the next steps.

Plugins. Plugins. Plugins.

Plugins are great because they either implement some functionality or they extend on Gatsby's webpack configuration adding support for typescript, sass and much more. Here are some handy plugins I think are great to start off with:

  • gatsby-plugin-catch-links
    • This implements the history pushState API, and does not require a page reload on navigating to a different page in the blog.
  • gatsby-plugin-react-helmet
    • react-helmet is a tool that allows for modification of the head tags; Gatsby then statically renders any of these head tags, This is very helpful when it comes to SEO and making each page as optimized as possible. Its also great to get in the habit of whenever you create a new page. Add a new helmet.
  • gatsby-source-filesystem
    • This is a source plugin, a source plugin creates "nodes" which can then be transformed into usable formats usually by a transformer plugin. gatsby-source-filesystem loads a file off disk e.g Markdown files and then specifying a markdown transformer to transform the Markdown into HTML. In our case we will creating each blog content/article using Markdown. So we will need:
  • gatsby-transformer-remark
    • This is our transformer plugin. The remark Markdown parser transforms .md files on disk to HTML; additionally this transformer can optionally take plugins to extend functionality. ie add syntax highlighting with gatsby-remark-prismjs, gatsby-remark-copy-linked-files to copy relative files specified in markdown, gatsby-remark-images to compress images and add responsive images.
  • gatsby-plugin-create-client-paths
    • This plugin I find pretty handy. You can generate client only paths for example: Say you want a page to end with the url /job-posting/developer this is a client only path. Where we want to show a page for that specific url. Say we want to have a template for anything that has /job-posting/* where * is any title. Using this plugin will allow you to do this. by placing your file in the following structure
  • gatsby-plugin-postcss-sass
    • This plugin is pretty straightforward. It will convert sass files to css. Which lets be serious is great.

    Alright now lets add these plugins:
    yarn add gatsby-plugin-catch-links gatsby-plugin-react-helmet gatsby-source-filesystem gatsby-transformer-remark gatsby-plugin-create-client-paths gatsby-plugin-postcss-sass

    One more thing that I think is important, and also pretty handy to know. Use autoprefixer. This is not a gatsby plugin but can be used with a gatsby plugin. Autoprefixer is a CSS post processor. It goes through your compiled css files and adds vendor prefixes like -webkit and -moz. Cross browser support is the best. yarn add autoprefixer Please note that this is not 100% perfect, things like css-grid will not always work out the way you want it for things like IE10, IE11 and Edge. In order to counter that mixins are always great.

    After installing all these plugins and libraries we need to edit gatsby-config.js, which Gatsby loads at build-time to implement the functionality of these plugins.

    const autoprefixer = require('autoprefixer');
    module.exports = {
      siteMetadata: {
          siteMetadata: {
            title: `Test`,
            siteUrl: ``,
            description: `Test Blog website`,
      plugins: [
          resolve: `gatsby-source-filesystem`,
          options: {
            path: `${__dirname}/markdown`,
            name: "markdown-pages",
          resolve: `gatsby-transformer-remark`,
          options: {
            plugins: [] // any remark plugins mentioned above here
          resolve: `gatsby-plugin-postcss-sass`,
          options: {
            postCssPlugins: [
                browsers: ['last 2 versions', 'not ie 10'], //I dont normally support ie10 now adays
                grid: true,
            precision: 8
          resolve: `gatsby-plugin-create-client-paths`,
          options: { prefixes: [] }, //If you want specific paths add things like this '/job-posting/*' 

    For this section the only thing you really need to know is that this:

    { resolve: `gatsby-source-filesystem`, options: { path: `${__dirname}/markdown`, name: "markdown-pages", }, }, tells us where we will be placing our markdown files.

    Now Before I get into the nitty gritty details, I'd like to explain GraphQL.

    For the sake of this I'll just use it to handle markdown files. So to start create a new folder within your src directory and call it templates In here lets create a file called blogTemplate.js. Then add the following:

    import React from "react";
    import mainImage from '../images/mainImageNoTitle.png'
    import Helmet from 'react-helmet'
    export default function Template({
      data, // this prop will be injected by the GraphQL query below.
    }) {
      const { markdownRemark } = data; // data.markdownRemark holds our post data
      const { frontmatter, html } = markdownRemark;
      return (
          <div className='container'>
                    { name: 'description', content: frontmatter.description },
                    { name: 'keywords', content: frontmatter.keywords },
            <div className="blog-post-container">
                <div className="blog-post">
                    <h1 className="blog-title">{frontmatter.title}</h1>
                        dangerouslySetInnerHTML={{ __html: html }}

    export const pageQuery = graphql` query BlogPostByPath($path: String!) {  markdownRemark(frontmatter: { path: { eq: $path } }) {   html   frontmatter {    date(formatString: "MMMM DD, YYYY")    path    title    description    keywords   }  } }`;

    What we are doing here is writing a graphQL query. I'm adding description, keywords and title to the Helmet so that I can give each of my blog posts a nice SEO. Frontmatter is what we use to direct the path that we pass into our md file and that will be the url to the blog. The data property we pass into the react component is the pageQuery we write at the bottom. We are telling frontmatter that we will be getting date, path, title, description and keywords back from the markdown file. We can also format the date right away so we always have a nice looking date.

    Now for the markdown files. Lets create a folder in our root directory. NOT in our src. Lets call it markdown. Inside that folder lets create our first blogpost markdown file. So create new file in /markdown and name it

    Here lets write some fun stuff:

      path: "/blog/first-blog"
      date: "2018-05-29"
      title: "My first Blog Post"
      description: "Here is my first blog post"
      keywords: "gatsby, javascript, react, tutorial"
      <h1> Hello World<h1/>

    Here we set the url path we want our blog post, date, title, description and keywords as well as some nice html that we will set inside our div

    There you go. You have created your first blog post using graphQL and gatsby