What's the big deal with images?

The way GatsbyJS works is by compiling our blog's assets into static content. The assets include things like the React components, CSS, and any images we directly include in the components or CSS. So when you run your build, your page component /about.js will become an HTML file in the static folder.

But when it comes to images queried by the GraphQL, Gatsby doesn't automatically copy these assets into our static build. If you try and link to a local file, you'll find it doesn't exist on your development or production server.

There's a whole page of the GatsbyJS docs that talks about the implementation of this feature -- but they seem forgotten, exchanged in favor for a few plugins that accomplish the task of copying media assets. The plugins work fantastically, and implement the functionality we need with an approachable API.

Lets get building.

If you haven't already, make sure to complete the first part of this tutorial or download a starter from Github here.

The plugins

We'll need to install 4 plugins:

• gatsby-plugin-sharp - This plugin allows us to use the Sharp image processing library to resize and compress our images.
• gatsby-transformer-sharp - This plugin allows us to query the images on GraphQL through special ImageSharp nodes.
• gatsby-remark-copy-linked-files - This plugin does the magic of grabbing any files we link in our Markdown, like images or even PDFs, and copies them to the ./public folder.
• gatsby-remark-images - This plugin makes all the images responsive, giving us access to a <Img /> component that automatically scales depending on the user's device size.

Let's install them all:

npm i --save gatsby-remark-images gatsby-plugin-sharp gatsby-remark-copy-linked-files gatsby-transformer-sharp

Then add this to your gatsby-config.js file to let Gatsby know we have new plugins (and how to use some of them):

{
  plugins: [
    `gatsby-remark-copy-linked-files`,
    `gatsby-transformer-sharp`,
    `gatsby-plugin-sharp`,
    {
      resolve: `gatsby-remark-images`,
      options: {
        maxWidth: 1080,
      },
    },
  ],
}

You can set the maxWidth of your images in the options to the size of your biggest image container.

Add some images to Markdown

We'll be adding a cover_image field to our Markdown files to show a big header image above posts, and to use as a thumbnail on archives. We'll add it to the frontmatter of the Markdown file to make it easy.

Open up one of the Markdown files in the src/content/blog/ folder and add a cover_image field to the frontmatter:

---
title: "Using a Framework to Simplify Email Design"
date: "2017-08-10"
section: blog
cover_image: "./foundation-emails-guide@1x.jpg"
tags: design, development
---

Querying the images

Let's open up the first page of the site and query up some images there. Head over to src/pages/index.js and scroll to the bottom where the GraphQL query is.

We're going to use the new childImageSharp node in GraphQL to grab responsive versions of the images. You can either scale by a certain size, or by resolution ratio. We'll be scaling by size.

Replace the entire query variable with this one:

export const query = graphql`
  query IndexQuery {
    allMarkdownRemark(sort: {fields: [frontmatter___date], order: DESC}, limit: 3) {
      totalCount
      edges {
        node {
          id
          frontmatter {
            title
            date(formatString: "DD MMMM, YYYY")
            cover_image {
              publicURL
              childImageSharp {
                sizes(maxWidth: 1240 ) {
                  srcSet
                }
              }
            }
            section
          }
          fields {
            slug
          }
          excerpt
        }
      }
    }
  }
`;

Let's break the query down a bit. We call allMarkdownRemark, which accesses all Markdown files on our server. We also sort by the date and order it DESC. Then inside, we ask for fields we want to show on the page. In our case, we want to see things like the title and date, nested inside the frontmatter field.

If the syntax of GraphQL throws you for a loop, and you don't understand why you have edges and nodes, don't get stressed. I was a little confused at the start too since my background is in SQL.

I'd recommend taking a look at the GraphQLi query builder, usually at http://localhost:8000/___graphql, or just add ___graphql to the end of your development server. This pulls up a live query builder during development that helps ensure you build a properly formatted query. If you click inside, start a new line, and press any letter on your keyboard -- you'll see a tooltip popup with all the possible options for fields.

This helps immensely when making new queries from scratch, or just trying to seeing what fields are available at certain depths.

The Responsive Component

Now that we've queried the images, let's actually see them!

Here we'll be using the <Img /> component (not to be confused with <img src...>) from the gatsby-image package. You can read the plugin page for details, but it basically creates a responsive image nested inside a couple divs. If the user loads mobile, it loads a smaller image, and stretches it accordingly to fit the size. It also does stuff like the blurred placeholder loading image (ala Facebook or Medium).

To use the <Img /> component, import the gatsby-image package:

import Img from "gatsby-image";

And then add the <Img /> tag anywhere in your code:

<Img sizes={featured.frontmatter.cover_image.childImageSharp.sizes} />

We reach into the frontmatter to grab the cover_image, which now has a ImageSharp node (because we added the plugin above). Though we use childImageSharp, probably because it's not a direct image node, but a image attached to a field. The ImageSharp node provides us with a sizes array containing various images at different viewport sizes. This all gets fed into the <Img /> component, which does the heavy lifting of swapping between the set of images depending on the user's device.

That's it!

Once you figure it out and find the right plugins, it's a fairly simple process. And being able to generate queries using the help of the GraphiQL browser, combined with dumping data into the console, makes deciphering the data structure fairly simple.

You can see this code more fleshed out with CSS and whatnot in my personal blog's repo: https://github.com/whoisryosuke/ryosuke-gatsby-blog/

Next time: Paginated Archives

In the next part of this tutorial series we'll be adding a paginated archive for our blog. Each blog post has it's own page, but we need an archive for users -- and SEO spiders, to browse and find our older posts. Keep an eye on the #GatsbyJS tag to see our next post!

If you have any questions or issues: feel free to comment down below, send us a tweet, or contact us through our site's form.

Stay regular,
Oscar

Keep Reading:

• GatsbyJS
• GatsbyJS Docs
• GraphQL Docs
• gatsby-plugin-sharp
• gatsby-transformer-sharp
• gatsby-remark-copy-linked-files
• gatsby-remark-images
• Sharp image processing library

Laravel is a PHP framework that gives you essential features like JWT user authentication and routing right out of the box (with an official plugin). And it's surprisingly easy to deploy on Heroku if you know a couple of tips and tricks for proper configuration.

A (Free) API for User Authentication

Today we'll be creating a basic Laravel application with user signup/login and JWT authentication API for apps. And it'll be deployed on the free tier of Heroku, a cloud-based hosting service.

You can then use this cloud-hosted API to integrate a user authentication system to a frontend application made in React, Vue, Angular, etc. Although you will need a secondary "gateway" API to connect to this Laravel API, or use a service that offers environment variables (like Netlify), since frontend apps leave API credentials vulnerable.

This article presumes you have Composer installed globally. You don't have to know the Laravel framework, but it'll help you understand the structure of the application. And it'd probably help to run through the Heroku guide at least once to get your footing there.

Setup Laravel

The first step is getting Laravel setup. We'll install it using Composer, create a SQLite database, and then configure the .env file.

1. Install Laravel using Composer:

composer create-project --prefer-dist laravel/laravel laravel-api-heroku

2. Open up the project folder (laravel-api-heroku) and go to the database folder and create a new file called database.sqlite. It should be an empty file -- so just create it, save, and close.

3. Go back to the root of the project and copy the .env.example file and name the new file.env.

4. Open up the new .env file. Change the DB_CONNECTION variable to equal sqlite, and delete the other DB_... variables in the section. The section should look like this:

LOG_CHANNEL=stack

DB_CONNECTION=sqlite

BROADCAST_DRIVER=log
CACHE_DRIVER=file
SESSION_DRIVER=file
SESSION_LIFETIME=120
QUEUE_DRIVER=sync

Now we can start to bootstrap Laravel with some basic features like user registration/authentication.

Setting up an Authentication API

Laravel makes it incredibly simple to create a website where users can create an account or login, but it takes the simplicity a step further with the Passport package. Not only do we get user login, registration, password reset, etc all out of the box -- we also get an OAuth2.0 package with Passport that allows you to create a kind of "social login" for your own website (think the Twitter API when you access private user data).

We'll basically be following the same instructions in the Laravel docs, so check those out if you get lost.

Install the authentication package by running:

php artisan make:auth

Now we can get the Passport package installed.

composer require laravel/passport

Then we migrate the new database tables, like the users tables, or API keys.

php artisan migrate

Now we can install Passport using Artisan:

php artisan passport:install

We add a new trait to our User model (app/User.php):

<?php

namespace App;

use Laravel\Passport\HasApiTokens;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;
}

Then Passport::routes method within the boot method of your app/Providers/AuthServiceProvider.php:

<?php

namespace App\Providers;

use Laravel\Passport\Passport;
use Illuminate\Support\Facades\Gate;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class AuthServiceProvider extends ServiceProvider
{
    /**
     * The policy mappings for the application.
     *
     * @var array
     */
    protected $policies = [
        'App\Model' => 'App\Policies\ModelPolicy',
    ];

    /**
     * Register any authentication / authorization services.
     *
     * @return void
     */
    public function boot()
    {
        $this->registerPolicies();

        Passport::routes();
    }
}

Finally, in config/auth.php, you should set the driver option of the api authentication guard to passport to authenticate incoming requests with TokenGuard:

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

Protip: If you have a previous Laravel installation and you're changing the configuration, make sure to wipe out the config cache by running php artisan config:cache in the console.

Now we have a Laravel application pre-built with user authentication and OAuth2.0. You can test out the user auth by running php artisan serve and going to the local development server.There you should see the default Laravel landing page, and login and register buttons in the top right of the screen.

Deploying to Heroku

Heroku is a great host with an excellent free hosting package if you're looking quick and easy deployment for most styles of apps (NodeJS, PHP, Ruby, etc). We'll also be leveraging the free tier of their Postres database hosting, which gives you 10k database records to play with.

Check out the guide on Heroku's website for deploying Laravel.

First we have to let the Heroku server know our app is actually in the public/ folder. Let's create a new file in the project root called Procfile and add the following:

web: vendor/bin/heroku-php-apache2 public/

Then create a new Heroku application using the CLI:

heroku create

Now add your application key for the production site:

heroku config:set APP_KEY=$(php artisan --no-ansi key:generate --show)

Commit any changes and push the master branch to the Heroku remote repo:

git push heroku master

Now we can add the database. Add a SQLite database to your Heroku app by going to the Heroku PostgresSQL page and clicking the install button. Then pick your app from the dropdown and click continue. You'll be prompted to pick a pricing plan, I went with the free Hobby plan.

Now you can connect your application to Heroku's Postgres database by updating your config/database.php file:

$DATABASE_URL = parse_url(getenv("DATABASE_URL"));
$DB_CONNECTION = parse_url(getenv("DB_CONNECTION"));

return [

    'default' => env('DB_CONNECTION', $DB_CONNECTION),
    // …

    'connections' => [

        // …

        'pgsql' => [
            'driver' => 'pgsql',
            'host' => $DATABASE_URL["host"],
            'port' => $DATABASE_URL["port"],
            'database' => ltrim($DATABASE_URL["path"], "/"),
            'username' => $DATABASE_URL["user"],
            'password' => $DATABASE_URL["pass"],
            'charset' => 'utf8',
            'prefix' => '',
            'schema' => 'public',
            'sslmode' => 'require',
        ],

        // …

    ],

    // …

];

We also need to edit the environment variables to let Laravel know to use the pgsql database driver when we use Heroku in production. Head over to your project on Heroku, go to the Settings page, and click Show Config Vars. Make a new entry with they key DB_CONNECTION and pgsql as the value.

Now remove the OAuth keys that were generated locally from the .gitignore file by deleting this line:/storage/*.key. Ideally we'd generate these in production, but I had issues with Heroku generating them, so we just import the local ones instead!

Commit your changes to make the database connection real:

git add .
git commit -m "Added Heroku database configuration"
git push heroku master

Now that your database has been connected, make sure to run your database migrations in production to structure your fresh DB. You'll be running it through the Heroku CLI:

heroku run php artisan migrate

Your Laravel website should be live! You can register new users and login with the credentials you create.

Connecting to your new API

If you'd like to make an authenticated request to the API through a certain user, you'll either need to go through the OAuth2.0 verification process, or provide a personal access token (or JWT). Laravel Passport allows you to create a new client with a simple command line script:

heroku run php artisan passport:client --personal

When prompted for an app name, name it anything, and click Enter. You'll be provided a Client ID and Secret which you'll use to access the API remotely.

If you're not familiar with the OAuth2.0 protocol, here's a quick breakdown. OAuth2.0 protects your API by creating a 3-step verification system before offering a secure token to access the Laravel API endpoints secured with middleware authentication.

1. You first redirect the user to the Laravel API's OAuth Authorize page (http://yourlaravelapp.com/oauth/authorize) and attach your Client ID and a callback URL to the request.

2. The user is either presented a login screen - or if they're already logged in - they see an authorization form to allow your frontend app to access their data (similar to Twitter's authorization when you use social login). Then the API then redirects the user back to the callback URL you provided, and it sends over a secret token.

3. You take that secret token and send it back to the API with your Client ID, secret, and callback URL. The API responds back with another secret token, this time a personal access token for the specific user that authorized by logging in. This personal access token is a JWT or JSON Web Token, which is an industry standard method for authorizing between APIs.

Any time we'd like to access any part of the API that requires authentication, like private user data, we send our request to the API with a Authorization Bearer token in the header. That token in the JWT we generated in step 3.

Here's a snippet of this kind of setup in Laravel using session() to store the access token. Remember, this is a separate "gateway" application that obfuscates your API credentials for a frontend app:

Route::get('/', function () {
    $query = http_build_query([
        'client_id' => '420',
        'redirect_uri' => 'http://127.0.0.1:8001/callback',
        'response_type' => 'code',
        'scope' => 'access-patient-status'
    ]);

    return redirect('http://127.0.0.1/oauth/authorize?'.$query);
});

Route::get('/callback', function (Request $request) {
    $response = (new GuzzleHttp\Client)->post('http://127.0.0.1/oauth/token', [
        'form_params' => [
            'grant_type' => 'authorization_code',
            'client_id' => '420',
            'client_secret' => 'EXKWFSwGHrbGdC3M4F5kkzmtCZIXyE3fbA8agtw2',
            'redirect_uri' => 'http://127.0.0.1:8001/callback',
            'code' => $request->code,
        ]
    ]);

    session()->put('token', json_decode((string) $response->getBody(), true));

    return redirect('/user');
});

Route::get('/user', function () {
    if ( ! session()->has('token')) {
        return redirect('/');
    }

    $response = (new GuzzleHttp\Client)->get('http://127.0.0.1/api/user', [
        'headers' => [
            'Authorization' => 'Bearer '.Session::get('token.access_token')
        ]
    ]);

    return json_decode((string) $response->getBody(), true);
});

You could also accomplish this in a React app using react-router to create the callback route, and a service like Netlify to securely access API key variables in your build environment. (rather than exposing them directly in your production code).

Let the hackathons begin

I hope this inspires you to tackle your projects in a new way. We're living in the transition away from the monolith towards a microservices based architecture, and this type of setup will help you migrate your projects into this new infrastructure. The JAMstack revolution is upon is, and developers are engineering more frontend applications that utilize these modular, cloud-distributed API solutions.

You can take your app's source code and host it on a CDN for the most efficient distribution. And rather than pound the same server you're using to host the frontend to run requests to the backend to login or register users, we break that service out into a separate API that lives on it's own server. If the authentication API server crashes, it never takes down the website CDN (besides the functionality the API provides). It's the future!

Consider leveraging the power of Laravel's Socialite package to integrate social login into your API, and allow users to create accounts with social media profiles from Twitter, Facebook, etc.

Looking for the source code? 💻 ⚙️ Find this completed project source code on Github here.

Stay regular,
Oscar

Keep Reading:

• Heroku - Getting Started
• Heroku - Deploying Laravel
• Heroku - PostgresSQL DB Hosting
• Laravel framework
• Laravel - Passport package
• JSON Web Tokens / JWT
• Mikateach - Setting up Laravel 5.6 on Heroku
• Pusher - Build REST API using Laravel

Today we'll be developing a static blog generated by GatsbyJS, written in Markdown, and we'll deploy on Github Pages to host the blog.

But first, what is GatsbyJS?

GatsbyJS is a generator that allows you to code React apps that get compiled into static assets (HTML + JS). Each page is a technically React component that gets converted into an HTML and JS file when it's time to build the production site. If you've ever worked with a generator like Jekyll, which converts code like Liquid and Markdown into HTML, you'll be familiar with this kind of concept.

What makes GatsbyJS special is it's implementation of GraphQL. All of your content is served through a GraphQL server on the development side. When it comes time to compile the static assets, GatsbyJS queries the GraphQL server for the data and inserts it into your HTML files.

And what the heck is a JAMstack?

Static websites are growing in popularity with the JAMstack revolution. JAM stands for Javascript, API, and Markup. What it basically means is your site is only comprised of:

• Javascript (usually a framework like React)
• API (like an RSS feed, or JSON API endpoint) optional
• Markup (HTML, CSS, any media like images)

The goal is to create a website is comprised of only client-side HTML + CSS + JS. No need to install Node, Ruby, PHP, or any other server-side language. This means we could even deploy this directly on a CDN like S3 on AWS or Netlify.

When a website is made this simple, you can deploy it nearly anywhere, since most servers support HTML, CSS, and JS.

There are plenty of benefits to making your website static, from lighting fast load times to decreased server load, and Gatsby makes it fairly easy to pump out your own. You can find a great 'Getting Started' guide on the official GatsbyJS site, as well as many of the concepts we convey in this tutorial. If you get lost, I'd poke around there and see if it helps paint a clearer picture.

Let's build and deploy a static blog!

Installing Gatsby

Using the CLI

You can either install Gatsby using their CLI, which is recommended:

npm install --global gatsby-cli

Then run this command in the folder where you want the project:

gatsby new gatsby-blog

Classic Git Way

Or you can clone the repo from Github and run an NPM install:

git clone https://github.com/gatsbyjs/gatsby.git gatsby-blog && cd gatsby-blog && npm install

Note if you opt against installing the CLI, you'll have to run NPM scripts instead of gatsby commands when building for development or production.

Spin up the server

Run the following command to start up your GatsbyJS blog locally:

gatsby develop

This command runs the build process, compiling the code into static assets, and gives you access to your GatsbyJS site at http://localhost:8000/. And to make development easier, when you update your code while this is running, it'll re-compile -- allowing you to refresh and see changes instantly.

Creating the content

Our blog will use Markdown files to contain and display our posts. We'll be using the standard Markdown format with a top header. Make a new file in src/blog/first-blog-post.md:

---
title: My first blog post
date: "2018-04-20"
---

Do you enjoy Gabe the Dog? He is the immortal lead singer of Bork, a European band that does covers of popular pop songs from the 80s, 90s, and today.

<iframe width="560" height="315" src="https://www.youtube.com/embed/c--etqIJcow?ecver=1" frameborder="0" allowfullscreen></iframe>

Now that we have some content, let's display it on the website.

Grabbing our Markdown files

GatsbyJS uses components to create pages, so we could literally just create new JS files for each blog post. But that's messy and inefficient. So what do we do instead? Gatsby offers the ability to create source plugins that pull data from certain endpoints, like RSS, Medium, or Github. We're going to make Markdown in the same folder as the Gatsby project, so we'll be using the Filesystem source plugin to grab files locally.

We'll also install a transformer plugin, which takes GraphQL data and processes it. In our particular case, we want to take our data and process the Markdown into HTML. Run the following command to install that plugin:

npm install --save gatsby-source-filesystem gatsby-transformer-remark

And add the following JSON to your config to enable both plugins. If you look close at the path property of the filesystem plugin, we load our blog articles from the blog folder:

plugins: [
    // react-helmet is included by default with gatsby
    `gatsby-plugin-react-helmet`,
    `gatsby-transformer-remark`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `src`,
        path: `${__dirname}/src/blog/`,
      },
    },
  ],

Restart your development server to commit the changes (hit CTRL + C to terminate the server and then run gatsby develop again). Now run this GraphQL query on your local GraphiQL development panel:

{
 allFile {
  edges {
    node {
      name
      extension
    }
  }
 }
}

Enter the query and hit CMD + Enter. You should see a JSON object on the right side with the blog post we just made.

Making pages dynamically

We could easily start querying this data on our pages and displaying our posts. If you paste this into src/pages/index.js you'll see all your files printed out in your console:

import React from "react"

export default ({ data }) => {
  // displays an object of the query data in console
  // simply access what you need using a map function
  // data.allFile.edges.map()
  console.log(data)
  return <div>Hello world</div>
}

export const query = graphql`
  query MyFilesQuery {
    allFile {
      edges {
        node {
          relativePath
          prettySize
          extension
          birthTime(fromNow: true)
        }
      }
    }
  }
`

Which makes for a great frontpage with a list of all of our posts, but we end up at the same dilemma as before. If we want separate pages for each blog post, we have to make new components to query each page individually. That's where the GatsbyJS API comes into play.

GatsbyJS is capable of taking a GraphQL query and creating pages for every object based off a template. For every Markdown file we create, when we build our GatsbyJS website, it'll get run through a template to create a page. We end up with HTML files for each page with the Markdown parsed into readable text.

Paste this into your gatsby-node.js file.

const path = require(`path`);
const { createFilePath } = require(`gatsby-source-filesystem`);

exports.onCreateNode = ({ node, getNode, boundActionCreators }) => {
    const { createNodeField } = boundActionCreators
    if (node.internal.type === `MarkdownRemark`) {
        const slug = createFilePath({ node, getNode, basePath: `pages` })
        createNodeField({
            node,
            name: `slug`,
            value: slug,
        })
    }
};

exports.createPages = ({ graphql, boundActionCreators }) => {
    const { createPage } = boundActionCreators
    return new Promise((resolve, reject) => {
        graphql(`
      {
        allMarkdownRemark {
          edges {
            node {
              fields {
                slug
              }
            }
          }
        }
      }
    `).then(result => {
                result.data.allMarkdownRemark.edges.forEach(({ node }) => {
                    createPage({
                        path: node.fields.slug,
                        component: path.resolve(`./src/templates/blog-post.js`),
                        context: {
                            // Data passed to context is available in page queries as GraphQL variables.
                            slug: node.fields.slug,
                        },
                    })
                })
                resolve()
            })
    })
};

First, we'll create slugs based off our Markdown file names, and add them to the GraphQL query results. Then we'll use the createPages API to make new pages based off a GraphQL query for the Markdown posts. Then we'll use the createPage function to actually generate the page based off the new file path and component that'll act as the template.

When Gatsby runs the build process, it'll run this script as well, which will trigger the creation of pages.

There's not much to explain here since this is just very API specific code. It's simple enough to be self-explanatory, and anything that's unclear is probably opinionated decisions from the API.

The Blog Template

Now that our blog posts are ready to get converted into static pages, let's actually create the template we referenced above ./src/templates/blog-post.js. Make a new file there and paste this into it:

import React from "react";

export default ({ data }) => {
    const post = data.markdownRemark;
    return (
        <div>
            <h1>{post.frontmatter.title}</h1>
            <div dangerouslySetInnerHTML={{ __html: post.html }} />
        </div>
    );
};

export const query = graphql`
  query BlogPostQuery($slug: String!) {
    markdownRemark(fields: { slug: { eq: $slug } }) {
      html
      frontmatter {
        title
      }
    }
  }
`;

Show me the posts!

We've got our blog posts as Markdown ready to get converted, we have the React template, the only thing left is linking to the posts.

Head over to your index.js file and paste the following:

import React from "react";
import Link from "gatsby-link";

export default ({ data }) => {
  console.log(data);
  return (
    <div>
      <h1 style={{ display: 'inline-block', borderBottom: '1px solid' }}>
        Amazing Pandas Eating Things
      </h1>
      <h4>{data.allMarkdownRemark.totalCount} Posts</h4>
      {data.allMarkdownRemark.edges.map(({ node }) => (
        <div key={node.id}>
          <Link
            to={node.fields.slug}
            css={{ textDecoration: `none`, color: `inherit` }}
          >
            <h3 style={{ marginBottom: '4px' }}>
              {node.frontmatter.title}{" "}
              <span style={{ color: "#BBB" }}>— {node.frontmatter.date}</span>
            </h3>
          </Link>
            <p>{node.excerpt}</p>
        </div>
          ))}
    </div>
      );
      };

      export const query = graphql`
  query IndexQuery {
        allMarkdownRemark(sort: {fields: [frontmatter___date], order: DESC}) {
        totalCount
      edges {
        node {
      id
          frontmatter {
        title
            date(formatString: "DD MMMM, YYYY")
    }
          fields {
        slug
      }
      excerpt
    }
  }
}
}
`;

We query using the MarkdownRemark endpoint and grab the titles, slugs, and excerpts of our latest blog posts. Then we loop through the data to show the data, while using the <Link> component to link directly to the blog post (using the slug).

Dont forget, you can always test out the query in the GraphiQL dev panel to make sure you have the right properties.

If you restart your dev server at this point, you should see a list of the Markdown files you created. And if you click them, they'll take you to another page with the complete blog post.

Congratulations! You've built your first static blog. You can stop here and just run gatsby build to make a production-ready version of your blog available in the public folder. Upload that directly to your FTP or web host and you're good to go.

But why stop there? One of the principles of the JAMstack is using Git for version control. This allows you, or any dev on your team, to easily clone the website's repository and create an exact replica of the entire website. It also allows you to quickly push new changes to the server, rather than uploading files individually through an FTP.

Let's git started

If you haven't already installed Git on your computer, head over to the official website and download it. Then open up Terminal, cd to your project's root, and run the following command:

git init

This creates a new Git repository in your folder. Now let's commit all the changes we've made to the new repository:

git add -A && git commit -m "Your Message"

This takes all the files in the folder and adds them to the Git repo. When you make changes, you'll be able to track the differences between previous versions before each commit (git diff). The message you leave usually hints at what kind of changes were made to the code. In this case, something like "Initial commit" or "1.0" is appropriate.

Connect with Github

Connecting with Github allows you to promote the highest accessibility for developers looking to access the website's source code, and to take advantage of Github's free hosting](https://pages.github.com/). You'll sign up for a Github account if you don't already have one, create a public repo, and push (or upload) the project files to Github through Git commands.

Sign up on Github

1. Create a new account on Github
2. Login to your account.
3. Click the plus sign in the top menu and click "New repository" from the dropdown.
4. Name your repo anything you'd like, then click the big green "Create repository" button.

Sync up your repo with Github

To make syncing up to Github a single click we'll install gh-pages. This is a Github Pages package that pushes changes to Github and updates the page. Run the following command to install the package:

npm install gh-pages --save-dev

You'll also need to modify the package.json with a new script. This script runs the gatsby build process, then runs the gh-pages command to deploy to Github. Add the following line into the scripts section:

  {
        scripts: {
            // ...you'll see build, develop, format, etc above this....
            "deploy": "gatsby build --prefix-paths && gh-pages -d public",
        }
    }

And since Github Pages hosts the blog in a subdirectory (e.g. yourname.github.io/this-subdirectory/), we have to add a path prefix to the configuration gatsby-config.js to let GatsbyJS know it's not in the root:

{
  siteMetadata: {
    title: `Your site Name`,
  },
  pathPrefix: "/your-repo-name",
}

Deploy!

Go to your new repo on Github, click the Clone button, and copy the URL (ending in .git). Then run the following command to add a "remote" repo to your local git repo:

git remote add origin http://github.com/username/repo-name.git

Now we can build the site and push it to Github. Type in the following command, enter in your Github password when prompted, and profit!:

npm run deploy

The public folder of your blog will be uploaded to the gh-pages branch of your repo. If you click the dropdown labeled Branch: master you should see the gh-pages branch.

Browse your blog

Head back over to your repository on Github and see if you successfully pushed (or uploaded) your files. If it worked, head over to the project settings page. Here, you'll want to make sure Github Pages is enabled and that it's set to the gh-pages branch.

You should be able to access the blog by going to http://yourusername.github.io/repo-name/.

Maybe not the Wordpress 5-minute install

It might not be the most lightning fast blog creation out there, between the time it takes to install npm packages and the time you waste fussing with git. Though you have to admit that in a fairly short time span we were able to create a static blog ecosystem that deploys instantly. It's incredible to see the potential of GatsbyJS, and the different kind of experiences you can create compared to standard CMS platforms like Wordpress or Drupal.

If you've ever been thinking about taking the leap into a progressive web application (PWA), you want to try static, or you've just been interested in migrating off Wordpress -- I hope this guide helped you discover an alternative to the mainstream blogging experience.

The potential is endless

This is the first part in a series of articles we'll be writing featuring GatsbyJS. We've just dipped our toe in the water here, there's a wealth of plugins and potential we've yet to explore with this framework. We'll be looking into creating projects that explore or push the limitations of the JAMstack, from a portfolio site using the Behance API, to a static e-commerce store using Stripe, to building a true JAM app on a CDN with automatic and atomic builds.

Keep an eye on the #GatsbyJS tag to see our next post!

Find the example site here, and the final example repo here.

Stay regular,
Oscar

Keep Reading:

• Git guide - Start a new git repository
• JAMstack.org
• GatsbyJS
• GatsbyJS Tutorials
• GatsbyJS Plugins
• How GatsbyJS Works with Github Pages
• gatsby-source-filesystem
• gatsby-transformer-remark

It's something that services like Squarespace and Wix embrace. Even Wordpress is trying to implement a version of it with their Gutenberg editor, and we've had it for years with the WPBakery Page Builder (formerly Visual Composer) plugin.

Websites are a collection of components, there's no reason we can't abstract control away from the code and in the reach of a click.

Shopify offers a version of this with their 'snippets'. A snippet is a reusable component that can be included in any template file. And on the frontpage of the website, you can use customizable snippets to compose a layout for the main landing page.

How does it work?

On the frontpage it's a very similar process to something like Squarespace or Wix. You have 'content blocks', each block is a snippet, and you arrange them in whatever order you'd like. If you click on a block, it reveals more options, like inserting text or images.

The widget

A block inside the widget

On any other page however, it still requires you to manually insert the include snippets into your Liquid page templates ({% section 'your-snippet-here' %}), and it doesn't offer the same level of customization. You can insert variables, but it's a different API than the block settings, so you'd have to account for that as well.

Making the snippets

Creating a snippet is a snap. Open up your Shopify theme folder, navigate to the snippets folder, and create a new Liquid file with any HTML you'd like. This is great for components that repeat across the website, like newsletter blocks or sidebar widgets.

Here's an example of a block that contains a text header and a flex grid of boxes with images as background:

<div class="page-width">
  <div class="section-block">
      <div class="section-block__header section-block__header--padded text-center">
        <h4 class="h1--mini section-block__title">Text columns with images</h4>
      </div>

    <div class="flex column-flex">
        <div class="flex__item column-overlay text-center">
            <noscript>
              <div class="column-flex__image" style="background-image: url(http://images.google.com/imageurl.jpg); background-position: center center;"></div>
            </noscript>
            <div class="column-flex__image lazyload"
              style="background-position: center center; background-image: url('http://images.google.com/imageurl.jpg);">
            </div>
          <div class="column-flex__content">
            <p class="h5">Image Title</p>
          </div>
        </div>
    </div>
  </div>
</div>

West Code Customs

Customizing a snippet is where things get interesting. To make a snippet customizable, you have to add a schema to the bottom of the snippet. Copy and paste the following into the bottom of your current snippet:

{% schema %}
  {
    "name": "Text columns with images",
    "class": "index-section",
    "max_blocks": 24,
    "settings": [
      {
        "type": "checkbox",
        "id": "title_enable",
        "label": "Show header",
        "default": true
      },
      {
        "type": "text",
        "id": "title",
        "label": "Heading",
        "default": "Text columns with images"
      }
    ],
    "blocks": [
      {
        "type": "text_block",
        "name": "Text",
        "settings": [
          {
            "type": "text",
            "id": "title",
            "label": "Heading",
            "default": "Add a title or tagline"
          },
          {
            "type": "image_picker",
            "id": "image",
            "label": "Image"
          },
          {
            "type": "radio",
            "id": "image_align",
            "label": "Image alignment",
            "options": [
              { "value": "top center", "label": "Top center" },
              { "value": "center center", "label": "Center" },
              { "value": "bottom center", "label": "Bottom center" }
            ],
            "default": "top center"
          }
        ]
      }
    ],
    "presets": [
      {
        "name": "Overlay Columns",
        "category": "Text",
        "blocks": [
          {
            "type": "text_block"
          },
          {
            "type": "text_block"
          },
          {
            "type": "text_block"
          }
        ]
      }
    ]
  }
{% endschema %}

Once you add this to your snippet, if you go to your frontpage and click "Add Section", you should see the snippet title you defined in the list.

What does the Schema mean?

The first chunk of JSON is pretty self explanatory. The name is the title you'll see in Shopify's backend. The max_blocks limits the number of sub-components you can create (e.g.: a recent article snippet limited to 9 posts).

The settings array is where you put your top level configurations for the snippet. In this example, we give the user the type in their own header, and enable or disable the visibility of it.

The blocks array defines the extra "sub-blocks" you can create within your content blocks, or snippet. In this example, we create a block where the user can define header text, upload an image, and pick the image alignment. Depending on the max_blocks defined earlier, you can make that many "sub-blocks".

The presets array creates a "default" setup for your snippet. If the widget is 3 column and works best with 3 blocks, you can create 3 sample blocks. When the user creates a new snippet, the 3 sample blocks will be automatically created for them (filled with the defaultvalues you define).

Adding the variables to your snippet

You can access top-level snippet configurations using {{ section.settings.title | escape }}, swapping title for the ID name of the desired setting. To get to block settings, you loop through the blocks and then access the for loop, like so:

{% for block in section.blocks %}
      {{ block.settings.title | escape }}
{% endfor %}

If block contains variable, do something

When you combine the parameters you get from customization with Shopify's liquid templating system, you can achieve some fairly dynamic components with a minor tinkering. What happens if the user doesn't define any blocks? Or forgets to upload an image? We can handle all these conditional cases with Liquid's {% if %}.

How do we handle the on/off toggles, like the header?

Make a simple if statement checking for the variable. If it's switched to "on", the variable will be true, so any code inside will be executed:

{% if section.settings.title_enable %}
      {{ section.settings.title | escape }}
{% endif %}

What if an image isn't defined?

You can check for the variable and see if is equal (or in this case, not equal) to blank, a Shopify value that checks if the value is empty.

{% if block.settings.image != blank %}
      {{ block.settings.image | img_url: '600x600' }}
{% else %}
      <img src="Placeholder.svg" />
{% endif %}

What if the user doesn't create blocks?

The blocks variable contains a size attribute that lets you see how many blocks there are. You can check if it's equal to 0 in this case:

{% if section.blocks.size == 0 %}
      {% include 'no-blocks' %}
      {% comment %}
            We include a placeholder snippet that contains something like a statement saying "Sorry, no posts found".
      {% endcomment %}
{% endif %}

This also comes in handy if you need to check for grid consistency (e.g.: if blocks == 3, then do 3-column class attributes).

The final code

When we string together a couple of simple if statements, and swap the hard-coded data with our Shopify snippet configuration variables, we have a fully customizable block:

<div class="page-width">
  <div class="section-block">
    {% if section.settings.title_enable %}
      <div class="section-block__header section-block__header--padded text-center">
        <h4 class="h1--mini section-block__title">{{ section.settings.title | escape }}</h4>
      </div>
    {% endif %}

    <div class="flex column-flex">
      {% for block in section.blocks %}
        {% if block.settings.image != blank %}
          {% assign img_url = block.settings.image | img_url: '600x600' %}
        {% endif %}
        <div class="flex__item column-overlay text-center" {{ block.shopify_attributes }}>
          {% if block.settings.image != blank %}
            <noscript>
              <div class="column-flex__image" style="background-image: url({{ block.settings.image | img_url: '600x600' }}); background-position: {{ block.settings.image_align }};"></div>
            </noscript>
            <div class="column-flex__image lazyload"
              style="background-position: {{ block.settings.image_align }}; background-image: url('{{ block.settings.image | img_url: '300x300' }});"
              data-bgset="{% include 'bgset', image: block.settings.image %}"
              data-sizes="auto"
              data-parent-fit="cover">
            </div>
          {% else %}
            <div class="column-flex__image">
              <div class="placeholder-background">
                {{ 'placeholder.svg' | asset_url }}
              </div>
            </div>
          {% endif %}
          <div class="column-flex__content">
            <p class="h5">{{ block.settings.title | escape }}</p>
          </div>
        </div>
      {% endfor %}
    </div>

    {% if section.blocks.size == 0 %}
      {% include 'no-blocks' %}
    {% endif %}
  </div>
</div>

{% schema %}
  {
    "name": "Text columns with images",
    "class": "index-section",
    "max_blocks": 24,
    "settings": [
      {
        "type": "checkbox",
        "id": "title_enable",
        "label": "Show header",
        "default": true
      },
      {
        "type": "text",
        "id": "title",
        "label": "Heading",
        "default": "Text columns with images"
      }
    ],
    "blocks": [
      {
        "type": "text_block",
        "name": "Text",
        "settings": [
          {
            "type": "text",
            "id": "title",
            "label": "Heading",
            "default": "Add a title or tagline"
          },
          {
            "type": "image_picker",
            "id": "image",
            "label": "Image"
          },
          {
            "type": "radio",
            "id": "image_align",
            "label": "Image alignment",
            "options": [
              { "value": "top center", "label": "Top center" },
              { "value": "center center", "label": "Center" },
              { "value": "bottom center", "label": "Bottom center" }
            ],
            "default": "top center"
          }
        ]
      }
    ],
    "presets": [
      {
        "name": "Overlay Columns",
        "category": "Text",
        "blocks": [
          {
            "type": "text_block"
          },
          {
            "type": "text_block"
          },
          {
            "type": "text_block"
          }
        ]
      }
    ]
  }
{% endschema %}

You should have something that looks like this:

Easy as Schema

I hope this helps you create some flexible components for your Shopify template. These customizable blocks empowers less tech-savvy editors with the ability to contribute on a new level effortlessly.

Is something not working correctly for you? Hit us up on Twitter and ask for help. Or contact us today if you need professional consultation and development for Shopify.

Stay regular,
Oscar

Keep Reading:

• Shopify Docs on Snippets

It's a simple as importing a single CSS if you're interested in using the default library. But if you want to easily change colors, typography, or any other settings across all the components -- it's much easier to use the SASS version. It was pretty easy, but it wasn't as well documented as I preferred, so I wrote this to help others through the process.

Install Bulma-Start

The kind folks at Bulma have put together a package to help developers compile SASS without any additional configuration to their existing project. Rather than installing node-sass yourself and setting up the package.json, you install the bulma-start package.

Run the following command in your project root:

npm install bulma-start

How to use Bulma-Start

The Github repo's readme wasn't very detailed on how to actually use the package. Luckily, someone had this issue already, so the question's been roughly answered there.

In order to compile the SASS, you have to navigate terminal to the node_modules/bulma-start folder and run npm commands from there.

1. cd node_modules/bulma-start/
2. npm run css-build

But what do I do with the files?

You could include the CSS directly from the node_modules folder once it's compiled. But I personally put that folder under .gitignore, so it won't be committed to the repo.

I swapped this line in the bulma-start/package.json:

"css-build": "node-sass _sass/main.scss ../../assets/css/bulma.css",

This compiles the SASS file into a CSS file in your projects assets directory. And when you set NPM to watch, it'll keep updating the CSS file there as well. Much easier.

At the end of the day

I wasn't a huge fan of Bulma. It's not organized well enough for my tastes. I had to convert it to a dark theme, which required me finding unique SASS variables for each components color (from background to link colors). It allows for greater customization between components, but makes mass-editing styles a nightmare.

They could really take a cue from Semantic UI and how they've designed their framework to be OOCSS. When I want a navbar to be blue, I don't have to dig through the Bulma SASS variables to find $navbar-background-color, I just include the CSS classes: inverted blue.

Stay regular,
Oscar

Keep Reading:

• Bulma
• Bulma start (SASS Starter Kit)
• Bulma Docs