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

I'll walk you through the process of installing dependencies, the structure of our app, and how to build it from scratch - step by step.

This guide assumes you have basic knowledge of mySQL (and ideally a database - either on your local server, LAMP, remote URL, anywhere), and that you've at least installed Node on your computer. and used NPM before.

Installing the dependencies

In order to create the API, we need to use a few different libraries to make it happen. This is where things get opinionated.

We're going to use Express as our primary framework. If you're not jiving with this, you might want to try Koa or hapi (and another tutorial, cause we're jumping on the Express train).

Production

npm install express express-rate-limit cors helmet mysql --save

We'll be installing the following packages:

• express - MVC for creating Node sites
• express-rate-limit - Allows for rate limiting of API
• cors - Cors will allow you to serve the API remotely
• helmet - Secures your Express app with HTTP headers
• mysql - Connects and interacts with MySQL through Node.

Development

npm install --save-dev nodemon

Nodemon is used for hot reloading the server in development. Whenever we make a change in the code and save, if nodemon is running, it'll restart the Node server with the new code.

App Structure

Our app is structured as MVC, or Model View Controller. The model is the connection to the MySQL db. The view are the routes we connect to and display JSON data (like yoursite.com/api/users/). The controller are the functions that get data from the model and feed it to the view.

Development Server

Our 'development server' is Node. Isn't that convenient?

Let's setup your package.json. Under the scripts section, we'll set the start script to run our server.js file and set the port to 4200 (PORT=4200 node server.js). We'll also set the dev script to run nodemon, which will allow hot reloading in development. It should look like this:

Now you can run the server using npm start in Terminal/Command Line. That'll spin up the Node server and run Express. Or you can enable hot reloading for development using Nodemon by running npm run dev.

Hello World

Lets set up the server to a working state. We'll create a file called server.js in your project root, include Express and it's router, and print out a 'Hello World' style statement to website. You can find a version of this tutorial on the Express site. My version is modified to use routes, instead of a direct printout:

Model

Now let's connect to our MySQL database and start pulling information to feed into Express. Create file in your models folder called dbconnection.js:

We define our variables that we want to query for, and execute the SQL statement using the query function. This returns a callback function, which has a object with results and another for any error reporting.

This MySQL package follows the same kind of principles you see from PDO in PHP, you use prepared SQL statements. That's when you never directly insert your variables into a SQL statement, you use placeholders like ?? and ? to represent spots you want escaped variables like `table_name or'value'`. You can find more query examples here.

Now that we have a way to grab data, let's setup our routes to request it.

Routes

Routes tell the server what to show when you access certain parts of the site. For example, if you wanted to have an 'About' page located at http://yoursite.com/about/, you'd have to setup a route for /about/. The route would tell the server, when someone requests /about/, we give them a response (like HTML).

We'll be creating a route file that shows the user welcome text when they come to the site (like the Hello World example). And we'll create another route for accessing strain data.

Let's do it!

The Route

Create a new file in your routes folder called index.js and add the following code:

We create a function that accepts the Express app variable. Inside the function, we import our controllers, which will actually display the data. Then we use app to assign the routes.

For the site index, we go with app.use(), which pumps out HTML. For the strains, we use app.route to send data to any GET POST request.

Now the server is programmed to use getAllItems() from the strain controller when we visit http://yoursite.com:4200/strains/. If we visit there now, we'll get an error. So let's give it something to show.

Controllers + GET Data

We need a controller that pulls data from the model (MySQL DB), converts it to JSON, and returns it to the route. You could just create a single function that queries the DB. But we'll create a Class, that way we can have multiple functions (for different routes in the future). Type or copy paste the following:

The gist breaks down each step. We basically do a SQL query and we print results or error. We use res.json() to send the JSON to Express.

POST/UPDATE/DELETE?

We've handled the GET part of the POST request, but what about sending data or deleting? It's simple with the Express framework:

We assign different functions to the get, put, and delete routes. In the put and delete functions, we use req.params.rowId to pull up the :rowID, and do a SQL statement to delete them. And ideally -- authenticate the request somehow (password, OAuth, something).

Production

You can run this server in production, but you'll notice one major flaw: once it crashes, it's down, and the API won't work until you manually restart the server command line-style. We solve this problem by using a process manager.

We can either use a server to deploy our app like Heroku (which is a cloud-based host with built-in process manager), or we install our own process manager on the production server. We'll cover Heroku another time.

I use PM2, but there are other options. I'll be covering PM2 here. There's a quick start guide on the PM2 site, you'll find more details and useful commands there.

This requires SSH access to your production server. If you don't know what that is, I'd contact your host and see if it's available.

Upload your project

Upload the node project to your server. You can copy the node_modules folder, but it's recommended your run npm install in your project folder. The local node_modules folder will contain dev dependencies the production server might not need.

Installing PM2

You have to install PM2 globally, as we'll be using across the entire server.

npm install pm2 -g

Quick Start

We can quickly spin up our app right away using the following command in the project folder:

pm2 start app.js

But let's create a configuration file to pass variables to the app, like PORT=4200 so our app knows it should run on that port. It's basically like the package.json script earlier, but PM2 uses a different structure.

Create your ecosystem file

Create a file called ecosystem.json in your project root (where server.js is):

Run the server!

You're good to go! Run this script in your project folder:

pm2 start ecosystem.json --env production

Check sever status!

How do we know it's running? Did it crash? Where's my console.log?! -- No worries! PM2 stores it's data in logs, which we can access with the following shell scripts:

• pm2 show kushy-api - Show server info and stats.
• pm2 logs kushy-api --lines 50 - Show last 50 lines of server logs

Change kushy-api to the app name you specified in your ecosystem file.

Conclusion

You can make any kind of API with this. As much as I have space in my heart for PHP, once you understand Node and Express, it's insanely easy to make an API. It feels more natural than using libraries like Slim in PHP.

If you have any questions, feel free to hit us up Twitter.

Hope that helps,
Oscar

Keep Reading

• Express
• How to access RowDataPacket mysql-node.js

The Problem

Email design is hard. It's a bunch of nested tables and inline styles that create a deafening cacophony of inefficient code.

If you've ever designed an email from scratch, or even altering a template, you've experienced the pain of parsing through the spaghetti.

We were using a template that had enough components to make it flexible, but required us removing each component and it's inlined CSS every time. It was cumbersome to say the least, and we struggled to design emails that were short enough not to get clipped by standard ESPs like GMail.

The Solution - Foundation for Emails

Foundation for Emails by ZURB is an email design framework that simplifies the development, testing, and building of emails. It comes pre-packaged with a SASS compiler, browser sync for fast development, production builds zipped by Gulp, and even sends test emails via AWS and Litmus.

Inky

One of the most attractive features was Inky, a templating language that simplifies the process of creating layouts with tables. With just a few lines of a code, you create a tabular layout that respects the complex email compatibility requirements.

Inky:

<container>
  <row>
    <columns>This is a column.</columns>
  </row>
</container>

And the final compiled HTML:

<table class="container">
  <tbody>
    <tr>
      <td>
        <table class="row">
          <tbody>
            <tr>
              <th class="small-12 large-12 columns first last">
                <table>
                  <tr>
                    <th>This is a column.</th>
                    <th class="expander"></th>
                  </tr>
                </table>
              </th>
            </tr>
          </tbody>
        </table>
      </td>
    </tr>
  </tbody>
</table>

This allowed us to cut out a significant amount of code from our emails, which made the template more elegant and legible. Things like spacing elements with nested tables and blank GIFs were made effortless using the <spacer> tag.

<container>

  <row class="header leaf">
    <columns small="12" style="background:url(./assets/img/bg-leaf.jpg)">
        <spacer size="25"></spacer>
        <center>
            <a href="http://stayregular.net/?utm_source=newsletter&utm_campaign=redesign2018">
                <img src="./assets/img/logo.png" alt="Stay Regular logo" />
            </a>
        </center>
        <spacer size="100"></spacer>
        <img src="./assets/img/text-header-1.png" alt="We redesigned our portfolio site" />
        <spacer size="45"></spacer>
        <a href="http://stayregular.net/?utm_source=newsletter&utm_campaign=redesign2018">
            <img src="./assets/img/btn-check-us-out.jpg" alt="Check us out" />
        </a>
        <spacer size="145"></spacer>
    </columns>
  </row>

</container>

The Flaws

Even though the framework made designing emails incredibly simpler in a lot of ways, it still had a few kinks.

I had random conversion errors with MailChimp and sending the emails to GMail accounts. Foundation for Emails comes pre-built with a grid system, and it has media queries that make the email responsive at smaller widths (so it's not hard-set to a certain pixel width). The email code looked fine in MailChimp, but GMail compiled it differently, inlining the smallest media queries CSS. It broke the layout completely making the email fluid -- rather than a set width.

I also had issues testing emails with anything other than AWS. I wanted to use Mailtrap, since it's my go-to dev server for emails. Though I can't find any documentation on how to use Foundation with it.

At the end of the day you're still designing emails, so you're limited to what is compatible with common ESPs. No fancy CSS or JS effects, even with the SASS support. But don't hate the player, hate the game.

All in one solution?

This framework is the easiest and best solution I've found for developing emails. No one comes close to this complete package. Despite a few kinks, the automated sync and build process are stellar additions to this framework.

All my changes, from SASS to compressing images, gets compiled in seconds into production build that I can live edit or zip up for MailChimp.

It even makes collaboration a bit easier by keeping all emails and styles under one repository. You git clone it off our Gitlab and you're good to go designing emails using our styled components.

Quick Start Guide

If I've piqued your interest with how successful our transition was, it's very easy to get started with Foundation for Emails. Just paste the following commands into terminal in your project's parent folder:

git clone https://github.com/zurb/foundation-emails-template your_project_folder
cd your_project_folder
npm install

Thanks again to ZURB and all the contributors for putting together such an awesome seamless and simplified email development solution (that's open source!).

Stay regular,
Oscar

Keep Reading:

• Foundation for Emails on Github
• Foundation for Emails Docs

We're here to help you demystify the process so you can gain access to METRC.

What is METRC?

METRC is a 3rd party company that has been contracted by many states to handle their seed to sale tracking. METRC offers an online interface and API for growers, distributors, and retailers to update with their cannabis plant's progress (from planting seeds to sales receipt). Under the METRC system, each plant and 'package' is assigned a unique RFID tag distributed solely by METRC. This unique RFID tracks the plant through the system.

Certification Process

To gain access to METRC, you must first get certified to use the METRC system. This involves studying their terminology and workflow, and then taking 40 question multiple choice test.

Once you're certified, you can apply for access to certain API endpoints that your company requires access to. If you're developing a seed to sale application for example, you'll apply for access to the Plants, Plant Batches, Strains, Rooms, and Harvests endpoints. To apply for the access, you have to complete a competency examination for each endpoint (a GET, POST, UPDATE, and DELETE request usually).

The Steps

It's a fairly straightforward process to get certification. If you visit the METRC website for your state, you'll find their checklist there. This is technically the bare minimum required to achieve certification and access to the API:

• Contact Metrc
• Attend webinar
• Get sandbox API keys
• Take the sandbox test(s)
• Get production API access

The Initial Steps

The first few steps are easy, albeit time consuming. Contacting METRC is a snap and they respond back within a day with more details. Make sure to reserve your spot for the webinar when you make your initial contact, to cut back on the back and forth.

They only host the webinars every couple of weeks, and they do 2 sessions (a morning and afternoon). So if you don't catch it, you've got to wait a couple weeks until you can progress.

The webinar sucks the life out of you. My experience with the webinar was absolutely terrible.

They used GoToMeeting, requiring me to download that program. The webinar was full when I first clicked the invitation link and I didn't get in until 15 minutes later after about 20 attempts. After finally getting into the webinar, the audio was working fine, but the screen presenter's slides didn't work for the first half of the presentation. Luckily after complaining in the chat, they sent out a link to a PDF copy. The speaker was terrible, mumbling most of the time and incoherently stumbling through the subject matter.

By the end of the presentation, I was handed a 200+ page METRC manual and essentially sent off to go do some homework.

The Certification Test

The test was one of the more difficult parts, primarily due to the spotty reference material I was sourcing. You're required to know how the METRC online interface works as well. The 200+ page manual has plenty of screenshots of the website to work off of, but it can get confusing.

Here's an example of one of the questions:

Some are fairly simple. Other can be pretty innocuous. While some questions aren't even in any documentation provided. One question asked: "Which of the following attributes are required for the input of sales?". The manual cites: "Please see your State Supplemental for entering sales into METRC". I had to track this supplemental down on Google. And questions repeat. It's a 40 question test, with about 3-4 questions that were exactly the same.

Sandbox Tests

Once you take the first test and get certified, you can request API access. METRC sends over the sandbox API information, as well as a Word document that contains your API examination.

The sandbox tests to acquire API access were by far one of the worst punishments I've received lately. Between the essentially incomplete API documentation and the useless manual, you're left to poke and prod about to properly use most of the API.

Here are some of the key issues I had with the sandbox test:

Guesswork

METRC simple doesn't provide you with enough data to complete the test, between their incomplete documentation to the cryptic paperwork you're occasionally forwarded. I had to poke around their API and experiment with what works.

The first question on the test asks you to perform a POST request to an endpoint, but doesn't give you the necessary parameters (license number) to complete it. So I had to go to their Facilities endpoint (GET /facilities/v1/), go through each one, and find a license number that works with the POST request. If it involved lab tests, I had to find a license associated with a testing lab.

After seeing the Facilities endpoint, I realized that Metrc had emailed me JSON files with the license numbers inside the filenames. It was never mentioned in the email or any docs, I apparently had to intuitively attain the information. And even after checking the JSON files, they still would require you to GET request multiple endpoints to figure out which facility was which.

Half Ass Docs

The plant batches API endpoint to POST plant growth changes requires 2 extra parameters that the documentation fails to outline -- but an error message will inform you of. Strain Name and Actual Date are necessary as well as the other 6 fields mentioned in the docs.

Finding your POST results

Once you figure out how to make a POST request with a valid license number, you'll get a 200 response code signifying success -- and nothing else. POST requests to Metrc don't provide any response, not even the IDs of the posts you just made.

To find your posts, use the same license number and request the GET endpoint for active posts. And depending on the endpoint, you have to specify the time range. If you POST a couple strains, you'll find them at GET /strains/v1/active.

Often you'll need the ID of an item you just created, so you'll have to do a GET on the appropriate section's endpoint to find it. A bit cumbersome, particularly when you do a batch of requests.

Don't Timeout

Responses can and will take a long time. Make sure you don't set a timeout on the HTTP request. I set a 2 second timeout and couldn't POST to some endpoints because of how intensive error generation was (9993ms!). I only hope the production API is half as fast, since an average dispensary services about 1000 customers per hour (16 per minute, 0.2 per second), plus any other API requests (inventory changes, patient verification, etc).

Downtime

Speaking of slow servers, the API sandbox crashed during my testing period, and I couldn't test my application for 3 days before they were able to get it back online. If you're allotting yourself time for this in your schedule, keep this in mind.

Track and Trace Flow

Know the flow for METRC, because the docs won't give you any hints. If you're lucky you'll get an error message pointing you in the right direction.

Every plant has to have a tag associated to it, plants belong to batches that associate a strain and plant type. Here's the order of operations for creating new items, from first to last:

Strains > Room > Individual Plants > Harvest > Package

Strains are required to make plant. But things like plant batches can be created without first creating plants (think of it like a category that contains a certain type of plant). It's a bit confusing at first (and there are holes), but it's a little more manageable once you've gone through the flow a couple times.

Plants Missing Tags?

I had a major issue where I had to find plants to change their growth phase, however the facility I was using didn't have any plants with plant tags. The field was null, making it impossible to access through certain endpoints that require plant tags as a reference point. This was clearly a fault on METRC's side, either inputting incomplete sample data into the sandbox, or allowing for users to send incomplete POST requests that break the system's flow.

I contacted the METRC staff about the problem and never received any support. The only solution was to change the facility, find another plant with actual tags, and use that instead.

You also can't create new plants using the API. Either the sandbox doesn't allow it, or METRC is expected to input every new plant when you purchase RFID tags from them. I wouldn't know, because after contacting METRC about it, I received no response.

New Plant Tags

If a POST request requires a new plant tag, you have to look inside the JSON file that's labeled with your facilities license number. If you can't find your license number in the files, you have to change to one of the provided options.

Sometimes plant tags may already be taken by other users in the sandbox environment. Just grab another from the sample data.

That's it!

Once you complete the examination, it's sent off to a 3rd party to check it, and you're give production level API keys.

It's a bit of a cumbersome process due to the METRC's incomplete and disorganized direction. What should be a straightforward process easily becomes a multi-week endeavor to navigate through their rat's nest of a system.

I wrote this article because I couldn't find anyone documenting any form of the process, despite METRC being used in 9 different states. If you have any information you'd like to share or clarify, please send us a copy and we'll update this post with your insights.

Stay regular!~
Oscar

Keep Reading:

• Official METRC website
• METRC API Documentation for California
• California Cannabis Track and Trace System

In Sublime (and Atom I believe), you can grab multiple lines of code and find and replace the entire code snippet with something else (like an entire other code snippet). It's totally possible in VSCode, don't get me wrong. But it requires you to manually RegEx the snippet each time.

It's a feature that's been requested since Nov 18, 2016. And there are plugins available, but they're not as elegant as just using the Find and Replace dialog.

The "Solution"

Switch your Find and Replace over to RegEx mode. Add \n or \t wherever you want a line break. It's a little tricky figuring out where it is sometimes, especially when applying it to snippets with tabbed indents.

You can also use *. continue the search across the line so it grabs everything.

Example

'something
like this'

'something\n like this'
-with regex enabled

You get the idea

It's really a shame that VSCode hasn't implemented this kind of feature. I don't mind flexing the RegEx muscles every now and then, but when it inhibits my workflow -- and I know a competitor easily accomplishes it -- it's unacceptable.

I hope this helps you with this simple problem I had switching over.

Stay regular,
Oscar

Keep Reading:

• StackOverflow - Find and replace VSCode
• Multiline Find and Replace plugin for VSCode

High Risk

Payment processing for cannabis falls under the category of 'high risk'. It literally means just that for the banks and processors, they're dealing with a client that's a higher risk than others. Whether it's a higher risk of chargebacks or fraud -- or in the case of cannabis, selling a product that's borderline illegal.

Other companies that fall under the category of 'high risk' include:

• Adult orientated sites (anything porn)
• Auctions
• Drug Paraphrenalia
• Gambling
• Get Rich Quick / Life Coaching

What does High Risk mean for business?

You'll have to find a payment processor that specializes in high risk accounts, and they'll connect you to banks and credit institutions willing to work with you.

It also means you'll have to pay more. You'll pay more per transaction, as the fees tend to be around 6-12% -- instead of the 3.5% you see on a site like Paypal or Stripe. You also may have to pay a small fee per chargeback.

The Rules

Most online processors have a baseline of rules for dealing with cannabis companies.

• CBD or services. No actual cannabis with THC (unless you get a really good deal, and honestly, it's probably not a permanent solution)
• 21+ popup (most processors require it)
• Terms of Service that reflect the age limitation
• No sale or promotion of illegal drugs (As tempting as it may be, you can't associate your brand with magic mushrooms, cocaine, or any other illicit substance)

In some cases, processors may ask for this (but if they do, I'd personally keep looking):

• Clean site of any cannabis references, apply, then re-apply canna-branding after confirmation.
• Remove all social media posts referencing cannabis

The Slim List

• Shopify
• Any other 3rd party Authorize.net reseller
• SkyHighMoly
• European Banks (EMerchantPay, Skrill, etc)

Here's where things get interesting. In my research of over 200 companies, I found that most (read: 99%) of American based companies would not offer any website associated with cannabis processing. And I'm talking any website, even if you're in lifestyle selling apparel -- if it's got a leaf it's a scarlet letter.

If you're working in the online space and you're looking for a quick option to sign up and get going -- there are few and far between. And the handful that are listed only work with non-cannabis selling entities, you'd basically have to be slinging only CBD.

What should you pick?

Your easiest bet is to go with Shopify. I tried going directly to Authorize.net, Shopify's payment processor, and they denied any form of cannabis business. But they informed me that their resellers can offer payment services to cannabis companies at their own risk. Which Shopify does --
albeit not openly, you can find plenty of paraphrenalia and CBD shops on their platform.

Your safest bet is to go overseas to Europe and poach on financial institutes in countries like the UK and Amsterdam -- where they already have a proliferation of quazi-legal cannabis-based businesses between coffeeshops and headshops. Find a bank/processor that allows for overseas banking and you should be set.

SkyHighMoly is a semi-safe option. They've been around for at least couple years now, and they were able to offer me personally some of the best rates around. And I've shopped everywhere else.

My Advice?

• Never settle for check processing. It's a scam. In this day and age, there's no reason you can't be processing with credit or even debit. If the salesman offers you check processing and can't offer credit, walk away, they're a waste of time. Don't give any percent of your profits to people who can't even provide you a standardized experience.

• Go hard. Never hide anything. Show all your cards from the start and see what's allowed. The hidden cards will be played out on the table eventually. Most processors will work with you and advise you on what particular aspects failed their criteria. It's easier to go back and forth a few rounds in the preliminary process, than lose profits when your site is booming due to a random spot check.

• Have a backup plan. Make sure to have a minimum top 2, or top 3-5 options. With the flaky relationship of finance and cannabis due to federal limitations, a processor that seemed reliable for years may disappear in a day. It happened to dispensaries in Florida recently when their banking solution closed all cannabis accounts. The bank wanted to clean their slate due to a buyout from a federally regulated institution.

Oh and don't fall for any of those phony "potcoin" fads. Cryptocurrency has proven to be an excellent way for businesses to facilitate sales. However, it comes at the cost of pouring money in a volatile micro-economy often controlled by a small subset that have been known to steal funds. But if you're seriously interested in cryptocurrency, I'd recommend going with a mainstream coin like Bitcoin. And services like Bitpay can get your sales going.

Still need help?

If you've gotten this far and you've already expended all the options I've laid out -- welcome to the club!

Regardless of what choice you make, there is always an immense amount of risk involved in sustaining payment processing. And most businesses can and will lose their current processor in the next 1-2 years (or tomorrow!). That's why you might want to look into a payment processing consultant who specializes in developing relationships with processors and even banks to offer you solutions. These experts find private banks on your behalf and create the relationship to facilitate sales. If you're selling cannabis, like a dispensary or distributor, this is your best option.

It's not impossible!

You can sell cannabis, and cannabis-related products, with a credit card. It is totally possible, and it's happening every single day with countless businesses. The most important thing is to not feel defeated, because the battle for payment processing will be an uphill struggle. That's why most people lean on simple solutions like Shopify, or run to consultants who solve everything for small percentages of everything.

Whichever you decide, I wish you the best of luck on your entrepreneurial journey!

Stay regular,
Oscar