These days every developer is talking about Gatsby, static site generators and Netlify, so we decided to get our hands dirty and try out these technologies in order to learn and see how easy they are to work with.
Gatsby is a static site generator based on React for quickly building blazing fast static websites. This is made possible by the Gatsby CLI, which is the actual tool that makes it possible to quickly scaffold a static site in no time.
Netlify is the service we'd use for hosting the static site we'd be building with Gatsby. Netlify can integrate with GitHub, GitLab and BitBucket repositories, and this means that we can easily plug into any repository on any of those platforms and deploy from a production branch (usually the master branch) to Netlify content delivery network(CDN).
SETTING UP A GATSBY PROJECT
To set up Gatsby we need to have node and node package manager(npm) installed/updated on our machine, then install the Gatsby CLI tool to be able to build a new Gatsby project. The functionality of the Gatsby CLI tool does not end at scaffolding a new Gatsby application from scratch, the CLI tool also provides Gatsby developers with some utility commands for starting and running the server and building the static assets for the Gatsby site. To install Gatsby CLI from our terminal(command line) we’d run this command:
npm install -g gatsby-cli
This will install Gatsby "globally" and make it possible to use Gatsby commands directly from terminal. To start a new Gatsby project, we’d run the following command:
gatsby new gatsby-netlify
This command creates a new project directory called gatsby-netlify (this is the project name but you can name it whatever your choose) which contains all the required files for our project. The Gatsby new command needs a package manager for installing the packages and dependencies of our scaffolded Gatsby project, so while the command processes, a prompt will appear and require that we select a package manager for installing the required packages. By default we’d be presented with yarn and npm, but for this tutorial we'd be sticking with yarn so you should definitely select yarn (make sure to install yarn if it's not installed on your machine, or you might also opt for NPM but there will be a slight difference in the outputs when comparing the commands you'd run and ours).
Choosing yarn automatically runs the yarn install command which goes on to install all the packages and package dependencies that are needed by our Gatsby project, after the packages are installed, yarn finally builds up the installed packages.
PUSHING TO GITHUB
Our Gatsby project is now ready, but we need to push to GitHub since it integrates amazingly with Netlify and it's needed for deploying to Netlify CDN, also one last reason is to help us version the project. The Git commands that will follow shortly are basic git commands and you only need to have Git installed for now to follow through. If you're new to Git and GitHub there are tons of materials on the internet for learning about Git and GitHub, make sure to check them out to better understand what the commands actually do but for now you can just follow along (some of the commands return meaningful outputs which can give one an idea of what they do, so it's advisable to read them).
Running following commands will enable us setup the gatsby-netlify directory as a git repository and push successfully to GitHub:
git init
The git init command makes or better still initializes the gatsby-netlify directory as a Git repo and a hidden .git folder is added to the directory.
git add –all
The git add –all command stages the files in the directory to the staging area, which makes git track them for a commit.
git commit -m "initial commit"
The git commit -m "initial commit" command is used for taking a snapshot of the current state of the project directory, the "initial commit" message is known as a commit message and it explains what changes where made and why they were made.
We’d login to our GitHub account at https://github.com and create a repository name netlify-demo, set it as a public repository and initialize it without a .gitignore file or README.md file. After the repository has been created successfully, we should see further instructions on how to setup the repository from terminal(command line).
Already, we have ran most of the commands so we just copy the command git remote add origin git@github.com:USERNAME/netlify-demo.git (the USERNAME in the command should be replaced with your GitHub account username) and paste in terminal and hit the enter key, like so:
git remote add origin git@github.com:OPARA-PROSPER/netlify-demo.git
The git remote add origin git@github.com:USERNAME/netlify-demo.git command is used to add a remote repository to a local git repository that does not have a remote copy.
Everything is ready now and we can now push the project files to GitHub by running the following command:
git push -u origin master
This command pushes the contents from the master branch on our local repository to the master branch of the remote repository that was added to the project. Running this command prompts us for our SSH passphrase (the case will be different if you’re using HTTPS), which we enter and everything goes on smoothly.
Now if we check the repository on GitHub, the gatsby-netlify project files should now be in the the Netlify demo repository.
DEPLOYING ON NETLIFY
Netlify provides two interfaces for deploying web projects which includes a web interface and the command line interface. For this tutorial, we would mostly work with the web interface as it's pretty easy to work with and manage.
To begin, we login to our already existing Netlify account (you might need to setup an account if you don't already have one), locate the projects dashboard and setup to access our accounts dashboard (which is usually named using your username and a team keyword e.g opara prosper's team).
Next we locate the new site from Git button, which makes it possible to select a repository from either GitHub, Bitbucket or GitLab platform for continuous deployment. Since we already have our Gatsby site living on GitHub, we then select GitHub. It is important to notice that if you are new to Netlify, you’d need to give Netlify the proper access right to your GitHub account (read only) and GitHub repositories to make Netlify integration with your account possible (if you have previously given Netlify the required rights, then you don’t have to bother with those details again). Also make sure to give Netlify access to the netlify-demo repository.
Setting up the build options comes next after a successful integration with GitHub. Here we make sure that the project is set up with the appropriate team name and details, next we set the branch to deploy to master branch (by design, the master branch is a production ready branch) because Netlify works with a continuous deployment model (this means that Netlify runs the build command for every new push or commit to the deployment branch), setting a deployment branch keeps Netlify from running the build command in branches other than the chosen deployment branch (usually master branch). Also, note that by default Netflify sets the build command to gatsby build which is alright and we leave untouched (also note that this will be different in the future if we use another static site generator other than Gatsby for instance Jekyll). Lastly, the publish directory is set by Netlify to build/ and this we also leave untouched.
Clicking the Deploy site button should start the deployment process which will take a while depending on network latency. From the team's dashboard, we see a site deploy in progress notice and just above it we also notice a Netlify automatically generated deploy name for the project currently deploying to Netlify CDN. After a successful deployment, we should see a Deploy log button which is designed to show the CLI output of all the commands and success reports of the commands Netlify runs under the hood to get the project deployed.
Finally, clicking the preview deploy command would open a new browser tab that routes to the newly deployed Gatsby project on Netlify. Holla! We just deployed our Gatsby application!
DEPLOY PREVIEWS
Deploy previews is an inbuilt feature of Netlify that makes it possible for Netlify to automatically build and deploy every pull request made to the GitHub repository synched to Netlify for the purpose of previewing or checking the changes proposed in the pull request, while this feature is automatically turned off, it can also be turned off in the site settings.
To check out the deploy preview feature, we'd make changes to the repository on the GitHub web repository by editing the src/pages/index.js file, change the 'hello people' to 'hello everyone'. Next, we save the changes, check the create a new branch for this commit and start a pull request radio button, hit the propose changes button, and finally hit the create pull request button to open a pull request for the change we just made.
Creating a pull request makes Netlify automatically run the build command on the pull request for deployment previewing and also spins up some checks on the pull request which are in sync with the build. Navigating back to our Netlify site dashboard, we’d notice that the Deploy previews section now has a Deploy preview #1 hyperlink which when clicked, takes us to a dedicated dashboard for previewing the deployed pull request on the browser, publish Deploy, view the Deploy summary and a Deploy log which contains information on the build commands, success messages and error messages are also not left out from the Deploy log.
It’s important to note that Deploy preview does not replace local testing on localhost, Netlify doesn't take this away from developers, and it's absolutely possible to still test changes locally before deploying to Netlify.
INTEGRATING NETLIFY USING A CONFIGURATION FILE
Deploying to Netlify CDN is not only possible using the web interface, deployment to Netlify can also be achieved with the use of a TOML(Tom’s Obvious, Minimal Language) configuration file usually named netlify.toml.
The major aims for using a TOML configuration file for setting up netlify would be to:
-
Save other persons who use your source code the stress of re-configuring their own environment for deployment using the web interface.
-
Keep track of the changes to the configuration settings when using a version control system like Git.
To begin, we create a netlify.toml file at the root of the netlify-demo repository, then include the following lines of code to the file:
[build]
command = "yarn build"
publish = "dist/"
Open the package.json file in the root directory, locate the scripts key and edit/add the following lines:
"scripts" {
"build": "gatsby build",
"postbuild": "mv public dist",
...
}
Next we stash the changes we have currently made to the repository locally on our computer, then pull the changes we made remotely on GitHub and finally apply the stash to the current state of our project directory. Now we can run the yarn build command to build up the project and get the dist folder which Netlify has being set to deploy from.
After successfully running the build command, we make sure to add the newly created dist folder to the .gitignore file under the Gatsby files comment directly below "public", create and checkout a new branch we’d call chore/toml by running the following git command:
git checkout -b "chore/toml"
Next, we stage the changes, by running the git add –all command, commit the changes by running git commit -m "test if toml works", set an upstream branch for the branch we created to avoid having a fatal git error message by running the following command:
git push –set-upstream origin chore/toml
We can now checkout the repository on GitHub web interface, where we hit the compare & create pull request button to create a pull request for the changes we just pushed. Netlify now picks up the changes and begin to run the build command for the pull request (remember this feature is enabled by the deploy preview feature). Finally, we then merge the pull request to our production branch (master branch).
Navigating back to the Netlify web interface you'd notice the changes to the production deploy section of the dashboard.
WRAP UP
There is definitely more to Netlify and Gatsby that were not covered in this tutorial as our focus was more on quickly setting up these technologies to begin to work with them, other interesting things like Netlify CMS, Netlify CLI. Our Gatsby site has little content and we can go on to add real content, how to install Gatsby plugins, and do things like markdown pages were left out. We’d definitely cover more on Gatsby and Netlify in future yolo brolo series.
Thanks for joining us and learning along.
This post was written by Opara Prosper.
