Open-Source Pattern Library Tutorial: Part 2 — Deploying to Netlify & Netlify-CMS
- Part 1 — Setting Up Your Gatsby Application
- Part 2 — Deploying to Netlify & Netlify-CMS
- Part 3 — Building Pattern Pages
- Part 4 — Searchable List
- Part 5 — Card View
In this part of the tutorial we’re going to deploy our application to Netlify, set up our Netlify-CMS backend, and create our first pattern!
Deploying to Netlify
First things first, to make sure that things are actually working when we start to set up our Netlify-CMS backend, we need to deploy the repo we created in Part 1 to Netlify.
Make your way to (netlify.com) and login, or sign up with your GitHub account if don’t already have a Netlify account. Once you’re logged in you should see a button that says “New site from Git”. That will bring you to a page where you choose which Git provider your project is hosted on. For us that will be GitHub, so click GitHub and you should be greeted with a page that looks like this:
If it says “No repositories found” like it does here, then you’ll have to install Netlify on your repo. You can do this by clicking the “Configure Netlify on GitHub” button on that page. That will cause a prompt to open up in a new window that should look like this:
Here you will check “Only select repositories” (unless you want to give Netlify access to all your repos for whatever reason) and then choose the repo we created in Part 1 and click “Install”.
Now you should see your repo where it previously said “No repositories found”. Click on it and you should be greeted with some deploy settings. Make sure that your deploy settings look like this:
Now click “Deploy” and boom! Your site will start deploying right away! Now whenever your master branch gets changed, Netlify will automatically deploy master to your site. After hitting “Deploy” you will be brought to your site’s Netlify dashboard.
Here you can configure a multitude of settings for your deployed site, but for now, we’re just going to click on “Site settings” and in the first group of options, “Site information”, you should see a “Change site name” button. Click that and change the name of your site to whatever you like.
Netlify-CMS
Now it’s time to set up the backend for our site. To provide our site with its content, we are using Netlify-CMS. Netlify-CMS is an open-source content manager that will allow us to create and edit content and data and automatically stores them on your repo. To set this up, the first thing we need to do is install some packages that Netlify-CMS will need to run in our Gatsby project:
yarn add netlify-cms-app
yarn add gatsby-plugin-netlify-cmsNow go to your gatsby-config.js and add gatsby-plugin-netlify-cms to the plugins array. When you're done it should look something like this:
module.exports = {
siteMetadata: {
title: `Pattern Library Tutorial`,
description: `A tutorial to show how to build a pattern library using Gatsby and Netlify-CMS`,
author: `@marcello.paiva`,
},
plugins: [
`gatsby-plugin-react-helmet`,
`gatsby-plugin-material-ui`,
`gatsby-plugin-netlify-cms`,
{
resolve: `gatsby-source-filesystem`,
options: {
name: `images`,
path: `${__dirname}/src/images`,
},
},
`gatsby-transformer-sharp`,
`gatsby-plugin-sharp`,
{
resolve: `gatsby-plugin-manifest`,
options: {
name: `gatsby-starter-default`,
short_name: `starter`,
start_url: `/`,
background_color: `#663399`,
theme_color: `#663399`,
display: `minimal-ui`,
icon: `src/images/gatsby-icon.png`, // This path is relative to the root of the site.
},
},
// this (optional) plugin enables Progressive Web App + Offline functionality
// To learn more, visit: https://gatsby.dev/offline
// `gatsby-plugin-offline`,
],
}Now that that’s all set, we need to create the config file for Netlify-CMS itself. Create in your root directory a static/ directory and within that a directory called admin/. Within static/admin/ create a file named config.yml. Now in your static/admin/config.yml file paste in the following code:
backend:
name: git-gateway
publish_mode: editorial_workflow
media_folder: static/assets
public_folder: assets
collections:
- name: pattern
label: Pattern
folder: src/pattern
create: true
fields:
- { name: title, label: Title }
- { name: date, label: Date, widget: datetime }
- label: Category
name: category
widget: select
options: ["Getting input", "Navigation", "Dealing with data", "Social", "Miscellaneous", "Onbaording"]
- { name: subcategory, label: Subcategory, widget: string}
- label: Tags
name: tags
widget: list
field: { name: tag, label: Tag }
- { name: caption, label: Caption, widget: string}
- { name: problem, label: Problem, widget: markdown }
- { name: solution, label: Solution, widget: markdown }
- { name: usage, label: Usage, widget: markdown }
- { name: accessibility, label: Accessibility, widget: markdown }
- label: Assets
required: false
name: assets
widget: list
fields:
- label: Asset
required: false
name: asset
widget: object
fields:
- {label: Image, name: image, widget: image, required: false}
- {label: Caption, name: caption, widget: string, required: false}
- label: References
required: false
name: references
widget: list
fields:
- label: Reference
required: false
name: reference
widget: object
fields:
- {label: Title, name: title, required: false}
- {label: Description, name: description, widget: text, required: false}
- {label: URL, name: url, widget: string, required: false}This file acts as the configuration file for our CMS and creates the template for our content, AKA our patterns. This is the template that my team and I chose for our pattern library, but feel free to configure the fields however you like in your own pattern library.
It is worth noting, however, that if you do choose to change your template from the above configuration now, and you want to continue the tutorial, you’ll have to account for those changes when we start querying our pattern files for data later in the tutorial.
Netlify Identity
Finally, we need to go to our Netlify site’s dashboard to enable Netlify Identity, so that we can actually log into our CMS backend. You can get your site’s dashboard by logging into Netlify.com and logging in. Once you’re there, click the “Indentity” tab and click the “Enable Identity” button on the page you’re brought to.
Now that you have it enabled, click the “Settings and usage” button on the Identity page. Scroll to the bottom of the resulting page and you should see a section called “Git Gateway”. Click the “Enable Git Gateway” button. What this does is it allows Netlify-CMS to have access to the GitHub API, thus enabling it to automatically push the markdown files we create to our repo so we can query the data within them.
Netlify Identity also has a slew of other settings that let you configure things like making your backend invite-only, setting up external OAuth providers for login, user roles, and custom email templates. I won’t be going into these in this tutorial but take the time to look at the options it provides and see what works best for you and your team.
Adding a Pattern
Now that our Netlify-CMS backend is all set, push your changes to the repo and wait for Netlify to deploy your changes. Once your site is deployed with all of the changes we just made, go to your deployed site and append /admin/ to the URL. So your URL should look something like this: https://your-site-name.netlify.com/admin/
You should be presented with a page with a button in the middle that says “Login with Netlify Identity”. Since this will be your first time logging in, you’ll want to sign up as a user for your Netlify-CMS backend. After that you should receive a confirmation email with a link to activate your account and bring you back to your site. Go to the admin portion of your site and log in and now you should be greeted with a page that looks like this:
Click the “New Pattern” button and you’ll see a form with all of the fields that we configured in our config.yml file. Go ahead and take a moment to familiarize yourself with the form and create your first pattern for your project. Once you're done, click the "Save" button at the top of the page. You should be redirected to page you saw above.
Now click on the “Workflow” tab at the top of the page. You should see a kanban board with three columns: Drafts, In Review, and Ready. Whenever you create a or edit a pattern, it will be put in the Drafts column.To push the content to our repo, we need to drag the pattern to the Ready column and click “Publish new entry”.
Now if you go back to the “Contents” tab, you should see your pattern listed there, and if you go to the src/pattern/ directory in your repo, you should see the markdown file of the pattern you just created!
That will conclude this part of the tutorial. In part 3 of this tutorial series, we will work on creating the pages for our patterns in our application and begin querying for their data.
If you are having issues or want to look at the source code for this part, you can checkout the part2 branch of the plib-tutorial repo:
