© Joe Attardi 2020
J. AttardiUsing Gatsby and Netlify CMShttps://doi.org/10.1007/978-1-4842-6297-9_3

3. Setting Up the Example Project

Joe Attardi1 
(1)
Billerica, MA, USA
 

Throughout this book, we will build a website for a coffee shop using Gatsby and Netlify CMS. It will include an index page, a menu, and a blog. We will deploy the site on Netlify via GitHub.

Prerequisites

Before we can set up the project, there are a few prerequisite steps required.

Install Git

To work with the example project and deploy it to Netlify, you will need to have Git installed on your system. Installation steps vary depending on your operating system. See https://git-scm.com/ to download and install Git.

If your operating system has a package manager, chances are there is a Git package for it. If you’re on a Mac or Linux system, Git may already be installed.

Install Node.js

To install dependencies and run the build process, you will need Node.js installed on your system. If you don’t have it installed already, you can download it from https://nodejs.org. You can download either the current or LTS (long-term support) version - either will work for this project.

Installing Node.js will also install the npm package manager tool, which we’ll use to install dependencies.

Install the Gatsby command line interface

The Gatsby command line interface, or CLI, is how we interact with Gatsby. It can create new projects, run a development server, or build the final artifacts to deploy a site. The CLI is published as an npm package called gatsby-cli. To install it, open a terminal and run the following command:
npm install -g gatsby-cli

The -g argument to the npm install command installs the gatsby-cli package globally. After the package is installed, the gatsby command will be available on your system.

Sign up for GitHub

We will deploy the project to Netlify via GitHub, and the starter code is stored there, so you’ll need a GitHub account if you don’t already have one. To sign up, you can go to https://github.com/join.

Create a new repository with the starter code

You won’t need to start from scratch for this project. There is a GitHub template repository with the starter code that you can use to create your own repository to work in.

The starter code is located at https://github.com/joeattardi/coffee-shop-starter. To set up your repository, visit this URL. Make sure you are logged in to your GitHub account, then click the green “Use this template” button, as shown in the screenshot in Figure 3-1.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig1_HTML.jpg
Figure 3-1

The starter code repository

When you click this button, you will be prompted for the desired name of your repository. Enter something like “coffee-shop” and click “Create repository from template.”
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig2_HTML.jpg
Figure 3-2

Creating the new repository

Clone the repository

After a brief delay, you will be taken to your new repository page. From this page, click the green “Clone or download” button, then click the clipboard icon to copy the URL to your clipboard.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig3_HTML.jpg
Figure 3-3

Getting the clone URL for your repository

Now, we can clone the repository to our system. From the terminal, change into the directory that you want the code to be stored in, then type this command:
git clone <your URL>

The repository should be cloned locally to a directory called coffee-shop.

Install dependencies and test it out

Once the clone has completed, change into the coffee-shop directory, and type npm install. This will install all of the project’s dependencies from npm.

When the install operation is finished, we are ready to try the starter code. When we installed the Gatsby CLI, a gatsby command was added to the system path. We can start a development server by typing this command:
gatsby develop
The development server listens on port 8000 by default. Once the server has finished starting, open your web browser and navigate to http://localhost:8000. The Joe’s Coffee Shop site should load. A screenshot is shown in Figure 3-4.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig4_HTML.jpg
Figure 3-4

The example project

So far, this is little more than a landing page. We will use this as a starting point and will add functionality to the site over the next several chapters.

Deploy on Netlify

The next step is to get the example project deployed on Netlify.

Sign up

If you don’t already have a Netlify account, we will set one up in this section and link it to our GitHub account. Feel free to skip the sign-up section if you already have an account linked to GitHub.

Open your browser and go to https://netlify.com, and click the “Sign up” link. You will be prompted to select a sign-up method, as shown in Figure 3-5.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig5_HTML.jpg
Figure 3-5

Selecting a sign-up method

Click the “GitHub” button to continue. You will then be redirected to GitHub, where you will be prompted to authorize Netlify. Click the green “Authorize netlify” button, shown in Figure 3-6, to complete the sign-up process.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig6_HTML.jpg
Figure 3-6

Authorizing Netlify with GitHub

You will then be redirected to the Netlify dashboard, where you will be logged in, as shown in Figure 3-7.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig7_HTML.jpg
Figure 3-7

The Netlify dashboard

Create a new site

Next, we’ll create a new site for the example project and point it at our GitHub repository. From the dashboard, click the “New site from Git” button. Under “Continuous Deployment,” click the “GitHub” button.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig8_HTML.jpg
Figure 3-8

Selecting the GitHub provider

You will again be redirected to GitHub, where you will be prompted to give Netlify permission to access your repositories. Click the green “Authorize Netlify by Netlify” button.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig9_HTML.jpg
Figure 3-9

Authorizing Netlify

Once you have authorized Netlify, you will be prompted to install the Netlify GitHub app on your account. You can grant Netlify access to all of your repositories or just the coffee-shop repository, if you prefer.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig10_HTML.jpg
Figure 3-10

Installing the Netlify app

Once the app is installed, you will be redirected back to Netlify, where you will be prompted to choose which repository to use for the new site. Click the coffee-shop repository.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig11_HTML.jpg
Figure 3-11

Selecting the repository

Next, the build and deploy settings will be shown. You can leave the defaults selected, as these are correct for a Gatsby site. Whenever commits are pushed to the master branch, Netlify will run the gatsby build command and publish the files that go in the public directory.

Finally, click the “Deploy site” button.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig12_HTML.jpg
Figure 3-12

The site deploy settings

You will be taken to the overview page for the new site, with a status of “Site deploy in progress,” as shown in Figure 3-13.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig13_HTML.jpg
Figure 3-13

Site deploy in progress

You might notice that your site has a strange name. In Figure 3-13, the site name is epic-mayer-e7d538. This is an automatically generated name assigned by Netlify to your site, to make sure it has a unique URL. Let’s change the site name to something easier to remember. To change the site’s name, click the “Site settings” button shown in Figure 3-13. The site settings will appear, starting out in the General tab. Under “Site details”: “Site information,” click the “Change site name” button, as shown in Figure 3-14.
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig14_HTML.jpg
Figure 3-14

The site settings

A dialog will then appear, where you can edit the site name. To make the site name easier to remember, we’ll change it to <your-username>-coffee-shop. Enter that new site name in the text field provided, and click “Save.”
../images/502348_1_En_3_Chapter/502348_1_En_3_Fig15_HTML.jpg
Figure 3-15

Changing the site name

Finally, let’s try out the live site. In the browser, navigate to https://<your-username>-coffee-shop.netlify.app, and the landing page should appear. We have successfully deployed the project to Netlify. In the future, any time we push commits to the master branch in GitHub, Netlify will build and deploy the new version of the site here.

A tour of the example project

So far, the example project is little more than a landing page. It was created with the gatsby-starter-hello-world Gatsby starter, which is a template for creating new Gatsby sites. Initially, there are no plugins installed in our site. Throughout this book, however, we will install several Gatsby plugins.

Directory structure

There are just a few directories:

  • src: Source files.

  • src/components: Reusable components, used by pages.

  • src/pages: The site’s pages. For now, there is just an index page.

  • static: Static resources such as images.

The Layout component

The only component in the project so far is the Layout component. This is a common pattern in Gatsby sites. Layout contains common content such as the page header and title. This is so that we don’t need to duplicate this content in each page we create.

CSS modules

There are several different approaches to styling in Gatsby sites (and React applications in general). Some of these include plain CSS, CSS modules, or a CSS-in-JS framework like styled-components. For the example project, we will use CSS modules, mostly to keep things simple.

Each component or page will have a corresponding CSS module file. For example, the Layout component in Layout.js has its styles defined in Layout.module.css. In a CSS module file, you define CSS rules like you usually do in a style sheet. Listing 3-1 shows a simple example CSS module file, Sample.module.css.
.header {
  background: red;
}
.footer {
  background: blue;
}
Listing 3-1

A simple CSS module

A CSS module is imported into a JavaScript file. The class names from the CSS are exported from the CSS module, which can be used by the component that imports it. This is demonstrated in Listing 3-2, the source code for the corresponding component, Sample.js.
import styles from './Sample.module.css';
export default function Sample() {
  return (
    <div>
      <header className={styles.header}>Header</header>
      <footer className={styles.footer}>Footer</footer>
    </div>
  );
}
Listing 3-2

Consuming a CSS module

The class names used by the elements in the Sample component are not strings but rather references to the exported class names. This is an important distinction, because when the final CSS is built, there will be no selectors for the classes header or footer.

Instead, these class names will have a unique identifier added to them to effectively scope the styles to the component. The exports from the CSS module provide a mapping between the class name in the source CSS and the generated class names at build time.

For example, the header class selector will be rendered as something like Sample-module—header—3zaAq. The HTML rendered by the React component will also reference these generated class names. This ensures that the styles in the CSS module will only apply to the React component importing it.

Without CSS modules, style rules could apply to other parts of the page outside of the component, producing unintended effects.

Special Gatsby files

The project also contains some special Gatsby files:

  • gatsby-browser.js: An entry point to utilize the Gatsby Browser APIs. Here, we simply use it to import a style sheet containing some global styles.

  • gatsby-config.js: The main Gatsby configuration file. Here is where plugins are configured.

So far, the site’s configuration is pretty bare bones. It currently only contains the site name, as shown in Listing 3-3.
module.exports = {
  siteMetadata: {
    title: 'The Coffee Blog'
  }
};
Listing 3-3

The initial Gatsby configuration

Summary

In this chapter, we

  • Installed required tools

  • Set up our development environment

  • Created our project repository from the starter code

  • Deployed the initial project to Netlify

We also took a brief look at the initial project code and got an introduction to CSS Modules.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.191.208.203