create-react-app is a build cli, it helps you bootstrap a new react app without the need to configure tools. Like Webpack or Babel.

They are preconfigured and hidden so that you can focus on the code.

If you came across gatsby you will notice that there is a lot of similarity between them. In this Blog post I will explain the key difference between the two.

What is Gatsby?

Gatsby is a blazing fast static site generator for React. Actually, it is more than that. Think of it as a PWA (Progressive Web App) Framework with best practices backed in. For example: you get code and data splitting out-of-the-box.

Why Moving to Gatsby?

Gatsby.js let's use modern web stack without the setup headache. With its flexible plugin system it let's you bring your own data source. Like Contentful, Databases or your filesystem.

When you build your Gatsby.js website you will end up with static files. They are easy to deploy on a lot of services like Netlify, Amazon S3 and more.

Gatsby.js provides code and data splitting out-of-the-box. It loads first your critical HTML and CSS. Once that loaded it prefetches resources for other pages. That way clicking around feels so fast.

Gatsby.js uses React component as a view layer so you can share and reuse them across pages/projects. Once it loads the page's javascript code, your website becomes a full React app.

Gatsby.js uses GraphQL to share data across pages. You only get the data you need in the page. At build time Gatsby will resolve the query and embed it in your page.

Gatsby.js project folder structure

├── LICENSE ├── README.md ├── gatsby-config.js ├── gatsby-node.js ├── node_modules ├── package-lock.json ├── package.json ├── src │ ├── layouts │ ├── pages │ └── templates └── static

From React Routes to Gatsby Pages

There are 2 types of routes, static when you know all the part that will define your route like /home . And dynamic when part of your route is only know at runtime like blog/:slug .

Let's assume you have the following static routes in our create-react-app project:

< Route exact path = '/' component = { Home } / > < Route path = '/blog' component = { Blog } / > < Route path = '/contact' component = { Contact } / >

In Gatsby.js, to have these routes you need to create a component with the name like the route path in the pages folder. It create the routes for you. The good news is the react components are already created so it is a matter of copying/pasting them. Except for the home page you need to name it index.js. You will end up with something like this

├── LICENSE ├── README.md ├── gatsby-config.js ├── gatsby-node.js ├── node_modules ├── package-lock.json ├── package.json ├── src │ ├── layouts │ ├── pages │ │ ├── index.js │ │ ├── blog.js │ │ ├── contact.js │ └── templates └── static

Now that you converted your static routes let's tackle the dynamic routes.

I will take an example of blog posts in this case loaded from Contentful. Every blog post has a uniq slug used to load its content.

In a normal react app the route will look something like this.

< Route path = '/blog/:slug' component = { BlogPost } / >

And your BlogPost component will look something like this:

import { getBlogPost } from './contentful-service' import marked from 'marked' class BlogPost extends Component { constructor ( ... args ) { super ( args ) this . state = { status : 'loading' , data : null } } componentDidMount ( ) { getBlogPost ( this . props . match . slug ) . then ( ( data ) => this . setState ( { data } ) ) . catch ( ( error ) => this . setState ( { state : 'error' } ) ) } render ( ) { if ( ! this . state . status === 'error' ) { return < div > Sorry , but the blog post was not found < / div > } return ( < div > < h1 > { this . state . data . title } < / h1 > < div dangerouslySetInnerHTML = { { __html : marked ( this . state . data . content ) } } / > < / div > ) } }

To create pages dynamically in Gatsby.js you need to write some logic in the gatsby-node.js file. To get an idea on what is possible to do at build time checkout the Gatsb.js Node.js API docs.

We will use the createPages function.

Following out Contentful example we need to create a page for each article. To do that first we need to get a list of all blog posts and create pages for them based on their uniq slug.

The code will look like this:

const path = require ( "path" ) ; exports . createPages = ( { graphql , boundActionCreators } ) => { const { createPage } = boundActionCreators return new Promise ( ( resolve , reject ) => { const blogPostTemplate = path . resolve ( ` src/templates/blog-post.js ` ) resolve ( graphql ( ` { allContentfulBlogPost(limit: 1000) { edges { node { slug } } } } ` ) . then ( result => { if ( result . errors ) { reject ( result . errors ) } result . data . allContentfulBlogPost . edges . forEach ( edge => { createPage ( { path : ` ${ edge . node . slug } ` , component : blogPostTemplate , context : { slug : edge . node . slug } , } ) } ) return } ) ) } ) }

Since you already have the BlogPost component, form your react project. Move it to src/template/blog-post.js .

Your Gatbsy project will look like this:

├── LICENSE ├── README.md ├── gatsby-config.js ├── gatsby-node.js ├── node_modules ├── package-lock.json ├── package.json ├── src │ ├── layouts │ ├── pages │ │ ├── index.js │ │ ├── blog.js │ │ ├── contact.js │ └── templates │ │ ├── blog-post.js └── static

You need to make some slight modification to your Blogpost component.

import React from "react" ; class BlogPost extends React . Component { render ( ) { const post = this . props . data . contentfulBlogPost ; return ( < div > < h1 > { post . title } < / h1 > < div dangerouslySetInnerHTML = { { __html : post . content . childMarkdownRemark . html } } / > < / div > ) ; } } export default BlogPost export const pageQuery = graphql ` query BlogPostBySlug($slug: String!) { contentfulBlogPost(fields: { slug: { eq: $slug } }) { title content { childMarkdownRemark { html } } } } `

note the $slug part that's passed through the context when creating the page to be able to use it in the GraphQL query.

Gatsby.js will pick the exported pageQuery const and will know it's a GraphQL query string by the graphql tag.

From the React state to GraphQL

I will not go in depth with how to manage a React state since there is a lot of ways to achieve that. There is the new React 16 Context API or using Redux etc... Using Gatsby.js you can request the data you need using the GraphQL data layer as shown in the previous example. this option is only available in the root components. This will change in v2 using static queries feature. You can still use Redux with Gatsby.js depends on your use if GraphQL is not enough.

Deployment

Since Gatsby.js builds "static" files you can host them on tons of services. One of my favourites is Netlify. There is also AWS S3 and more.

Resources