Illustration by Camille Chauve

Start a new website with Gatsby, Prismic CMS & Netlify

At Source we redesigned our website and decided to try a different technical stack. Based on the same kind of modern technologies like React that we already used for our clients’ web applications. In this tutorial, we chose the blog as an example to show you the power of these complementary tools.

With this goal in mind, we will use :

• Gatsby: Free and open source framework based on React that helps developers build blazing fast websites and apps.
• Prismic: Headless CMS.
• Netlify: Build, deploy, and manage modern web projects.

I will detail each of the services listed above in the following sections.

Find the project sources on Github here.
Preview, the result here: https://gatsby-article.netlify.com.

Step 1: Gatsby initialization

If you like to React, Gatsby is perfect to generate a static website. It offers you a boilerplate with the power of the latest web technologies (React.js, Webpack, modern JavaScript and CSS and more). Moreover, these tools allow us to quickly connect our project with a Headless CMS.

First, you need to get gatsby-cli from NPM. If you have not done so already, you could follow the quick start.

Let’s generate your project :

$ gatsby new my-blog
$ cd my-blog
$ yarn

Now, we install Sass to simplify CSS integration, we will use gatsby-plugin-sass. In this tutorial, I will not talk about CSS but you can find the sources on Github.

$ yarn add node-sass gatsby-plugin-sass

Next, add the plugin in your gatsby-config.js.

// in gatsby-config.js
plugins: [‘gatsby-plugin-sass’]

Note, Gatsby offers a plugin library that will allow you to gain in development time.

Now, we can start the project.

$ gatsby develop

First of all, I recommend you to organize your /src this way.

Gatsby project folder structure

• Components: each of your components with its own style.
• Static: folder static files like images, videos, fonts, etc.
• Pages: Gatsby uses this folder to generate pages. It’s not possible to delete it.
• Style: global stylesheets.

Create your folders with this command.

$ mkdir ./src/static ./src/style

Everyone is free to choose their organization, but this is the one I prefer because it allows me to easily scale my static website with Gatsby.

Step 2: Static integration of the homepage

Let’s start coding! We need to create an article component that will be repeated X times on the homepage when dynamizing the site.

components/article/index.js

Next, go in src/pages/index.js, we need to add this article in the index page, our blog homepage.

pages/index.js

That was easy right? So far everything is static, we’re just getting to the most interesting part. Now, we need the homepage dynamization with Prismic.

Step 3: Prismic initialization

Before getting back to the code for the dynamization, we need to configure a Prismic repository, if you don’t have an account you could create a free one here.

We decided to use Prismic for our website and this tutorial but some alternatives exist: Contentful, Strapi, etc.

Why we chose Prismic?

• Easy to use.
• Multilanguage available with starting plan.
• Don’t need hosting server for database and images.
• Quick setup with Gatsby.

First step with Prismic.

• Create your repository

Prismic setup

• Add your first custom types “article” with repeatable type.
• Now, add three fields: title, image and paragraph (with rich text).

Created your repeatable type Article

Therewith, you can create your articles in the section “content” of Prismic, simply by clicking on the pencil. When you create a new post, make sure you save and publish.

The second step, connect your Gatsby with Prismic.

From this point forward, we will connect Prismic to our Gatsby project. For this, you need to install the following plugin: gatsby-source-prismic.

$ yarn add gatsby-source-prismic

Moreover, go in the Prismic dashboard and get your token.

• Go to your repository’s Settings / API & Security.
• At the bottom find the section called “Generate an Access Token”.
• Add an application name. This doesn’t matter much, you can add something like “My Website” (you can leave the callback field empty).
• Click the “Add this application” button.

Now, add the token in your Gatsby project, we will add an environment file.

$ touch .env

Then, add the token and the name of your Prismic repository :

PRISMIC_REPOSITORY_NAME=XXX
PRISMIC_ACCESS_TOKEN=XXX

Therewith, add the plugin in your gatsby-config.js :

gatsby-config.js

It’s perfect! You have successfully integrated Prismic into your Gatsby project. Relaunch your project to see if it worked, if you have no error and you see Fetch Prismic data: Xms your data have been recovered.

Terminal after running Gatsby command

Step 4: Static site dynamization

Now, you can access all the data in GraphiQL from Prismic.

What’s GraphiQL? GraphiQL is the GraphQL integrated development environment (IDE). It’s a powerful tool you will use often while building Gatsby websites. It will allow you to test easily Prismic GraphQL queries with an interface.

You can access it when your site’s development server is running at http://localhost:8000/___graphql. For example, can try the following query.

GraphQL query to get article information.

So, if in Prismic you used the same field id like me, you can copy and paste this query. But, if you chose a custom id you can use the powerful GraphiQL’s autocomplete, it is very helpful.

Now, we need to add this query into our homepage: page/index.js.

page/index.js

Note, with Gatsby you can only call queries from “pages” files. It’s not possible to get data from a query in components.

Since we are on a page, Gatsby automatically adds the fetched data inside props. Don’t forget to import the GraphQL util from Gatsby. From now on, you can send data with props in the “Article” component.

article/index.js

Good job, the home page is connected.

Now, we need a page for the article detail. So, let’s create a template page named: post.js inside the page folder.

pages/post.js

For the post create an “ArticleDetail” component. The particularity is that we have to use the dangerouslySetInnerHTML property by React because in this section, we retrieve DOM elements from Prismic with paragraph field and we want to insert them directly into our page.

components/articleDetail/index.js

So far we only have a page layout for our articles.

The last step is to tell Gatsby to create static HTML pages from our template with the content of each one of our blog post. The magic will happen inside gatsby-node.js. We use the “allPrismicArticle” query we’ve used in the index page. We use Prismic default slug to create pages path and our template post.js to generate static pages.

gatsby-node.js

Relaunch Gatsby project to create all articles pages.
Good job! Your first blog is created, now it’s time to put it online.

Step 5: Deploy with Netlify

To deploy your website, you need to upload your source code into a development platform like Github, Bitbucket or Gitlab. For this example, I will use Github.

Once you’ve done this step, create a Netlify account here. Now, we connect your Github repository and Netlify by clicking on “New site from Git” in sites section.

Now, follow the next steps :

• In “Continuous Deployment” part click on Github to authorize the connexion.
• Select your repository
• Netlify will recognize the Gatsby configuration. So, we have in the build command “gatsby build” and in the publish directory “public/”.
• Then, click on the button “Deploy site”.
• Go to “Site settings” → “Build & deploy”, then to scroll to “Environnement” and add the Prismic access token and repository name as environment variables (those are the values from your .env file created before).

Netlify → Build & Deploy → Environment

• Return to the deploy page in Netlify and trigger deploy.
• Wait a few minutes. Perfect, your blog is deployed!

Now, we have a connection between Github and Netlify. Each time you will update and push your code, it will trigger a new deploy, but we need a final step for the deployment. We have to connect Prismic and Netlify, to run a new deploy each time you update content in the CMS.

On the Netlify dashboard, go to the section “Build hooks” in “Build & deploy” and create a hook, then copy and paste the URL.

Now, go to Prismic in “Webhooks” in the settings page and paste the URL build hook from Netlify. After saving, test it by clicking on the button “Trigger it”.

Settings → Webhooks

If the deployment is launched on Netlify, the connection works!

Thanks!

Through this, I wanted to show you how fast it is to set up a blog structure with new tools such as Gatsby and a headless CMS like Contentful, Strapi, Dato CMS or Prismic. I hope you found this tutorial helpful, thank you for reading.

You can download the source code on Github here: https://github.com/sourceinteractive/source-demo-blog

If you want to see what we have built, take a look at this demo: https://gatsby-article.netlify.com