Note: As of July 2022, GraphCMS is now Hygraph.

• What are we going to build?
• Step 1: Creating a new app with Gatsby Starter Leaflet
• Step 2: Creating and managing a list of travel locations with GraphCMS
• Step 3: Querying our GraphCMS location data with Gatsby and GraphQL
• Step 4: Creating a bucket list of destinations and adding them to the map
• What else other features can we add to our app?
• Want to learn more about maps?

What are we going to build?

We’re going to build a mapping app with Gatsby managed by a CMS that will both display markers on a map and show our locations in a simple text-based list for our bucket list locations.

Demo of a Travel Bucket List mapping app

We’ll spin up the app with a Gatsby Starter for Leaflet and then we’ll use GraphCMS to create and manage the list of locations for our map!

Woah, a mapping app?

Yup. If you haven't played with maps before, don't be discouraged! It's not as bad as you probably think. If you'd rather start with mapping basics, you can read more about how mapping works first.

Step 1: Creating a new app with Gatsby Starter Leaflet

We’ll start off with Gatsby Starter Leaflet. This is going to give us a basic React application with our mapping tools already built in.

Creating a new Gatsby app with Gatsby Starter Leaflet

To get started, navigate to where you want to create your new app and run:

gatsby new my-travel-bucket-list https://github.com/colbyfayock/gatsby-starter-leaflet

Note: you can replace my-travel-bucket-list with whatever you want. This will be used to create the new folder for the app.

Once you run that, Gatsby will pull down the Starter and install the dependencies. After it’s complete, navigate to that directory and run the development command:

cd my-travel-bucket-list
yarn develop
# or
npm run develop

Once it’s finished location, your app should be ready to go!

Cleaning our some demo code

Because we’re using a Starter, it has a little bit of demo code. Let’s clean that out to avoid any confusion.

Open up the src/pages/index.js file.

First, remove everything inside of mapEffect except the first line and set up an alias for leafletElement to map:

async function mapEffect({ leafletElement: map } = {}) {
  if ( !map ) return;
}

With that gone, we can remove the markerRef definition at the top of the IndexPage component, remove the ref={markerRef} prop from our <Marker> component, and the useRef import next to React.

Now, we can remove all of the variables that start with popup and time, including:

• timeToZoom
• timeToOpenPopupAfterZoom
• timeToUpdatePopupAfterZoom
• popupContentHello
• popupContentGatsby

Lastly, you can remove all of the following lines:

import L from 'leaflet';
...
import { promiseToFlyTo, getCurrentLocation } from 'lib/map';
...
import gatsby_astronaut from 'assets/images/gatsby-astronaut.jpg';
...
const ZOOM = 10;

Once done, we should be ready to go with a basic app with a map!

New app with Gatsby Starter Leaflet

Follow along with the commit!

Step 2: Creating and managing a list of travel locations with GraphCMS

Creating a GraphCMS account

To get started with GraphCMS, you’ll need an account. I’m not going to walk you through this part, but the good news is they have a generous free tier that makes it easy to sign up for us to use for our demo!

Sign up for GraphCMS

Alternatively, if you already have an account, you can make sure you’re logged in.

Creating a new GraphCMS project

Once logged in, we’ll want to create a new project. We’re going to create one manually, so once at the GraphCMS Dashboard, select Create new project:

Creating a new project in GraphCMS

Here, you can enter whatever you’d like for the Name and Description such as:

• Name: My Travel Bucket List
• Description: The locations that I want to travel to some day!

Below that you’ll see a map where you’ll select a Region. This is where your database data will live, so while it probably doesn’t matter too much for our purposes, you can choose the one that’s closest to you.

Configuring a new project in GraphCMS

After you select your options, go ahead and click Create Project.

Selecting the Personal plan in GraphCMS

Next, you’ll be presented with billing options. Since we’re just creating a demo, under Personal select Continue at which point we’ll be dropped into our new GraphCMS project dashboard.

Creating a new Content Model Schema with GraphCMS

In GraphCMS, a Content Model refers to a specific type of data that has specific properties associated with it. In our case, our Model will be a Destination, which will be defined by a Name and a Location.

First, navigate to the Schema section of GraphCMS in the left sidebar and select Create Model.

Creating a new Schema Model in GraphCMS

Once selected, you’ll see a popup that asks for a bit more information. Here, you can type in “Destination” as the Display Name, which will also fill in most of the other fields. We’ll leave those as is.

Configuring a new Model in GraphCMS

Feel free to add a description if you’d like, but it’s not required. Then select Create model.

Now that we have our Model, we need our properties.

First, select Single line text in the right list of fields and add a Display Name of “Name”. This will also fill out App Id which you can leave as is. Then click Create.

Adding and configuring a new text field in GraphCMS

Next, scroll down in the field options on the right and under Location select Map. Add “Location” as the Display Name, which will set the App Id as “location” which you can leave as is. Then same as before, click Create.

Adding and configuring a new map field in GraphCMS

Now we have a Content Model which we’ll use to create our locations!

Destination content Model in GraphCMS

Creating our locations

Finally, let’s create our locations. Navigate over to Content in the GraphCMS dashboard, make sure you’ve selected Destination under System (should be the only one), and select Create New.

Create new Destination Content in GraphCMS

Now we can start adding all of our locations! First, add the name of your location in the Name field, then you can use the Search box under Location to find that location on the map.

Adding a new Destination Content item in GraphCMS

Once you’re good, hit Save and publish. This will create your first location!

Follow those same steps and create as many locations as you want.

List of Destination Content items in GraphCMS

We’ll use these for our map and bucket list.

Step 3: Querying our GraphCMS location data with Gatsby and GraphQL

Now that we have our locations, let’s use them!

Adding a plugin to Gatsby to query our GraphQL data

First, we need to add a new plugin to our Gatsby project to query our GraphQL data. In your terminal make sure your development server isn’t running and run:

yarn add gatsby-source-graphql
# or
npm install gatsby-source-graphql

Next, open up your gatsby-config.js file in the root of your project and add the following to your plugins:

{
  resolve: 'gatsby-source-graphql',
  options: {
    typeName: 'GCMS',
    fieldName: 'gcms',
    url: '[API ENDPOINT]',
  }
}

This will be what sources our data from GraphCMS, but we need an endpoint.

Finding our API endpoint for GraphCMS

Open back up your browser and head over to your GraphCMS project. After selecting Settings in the left navigation, select API Access.

API Access in GraphCMS

Before we copy our API Endpoint, first we need to update our permissions so we can query our API. Under Public API Permissions, check the box next to Content from stage Published and click Save.

Configuring API permissions in GraphCMS

Next, copy the URL under Endpoints:

Copying API Endpoint in GraphCMS

And paste that in to your gatsby-config.js file that we modified above:

{
  resolve: 'gatsby-source-graphql',
  options: {
    typeName: 'GCMS',
    fieldName: 'gcms',
    url: 'https://[region-id].graphcms.com/v2/[project-id]/master',
  },
},

Note: your URL will have actual values inside of [region-id] and [project-id].

Save your gatsby-config.js file and start your development server backup (yarn develop) and we’re ready to go!

Querying our locations via GraphQL

Finally, let’s actually query our data so that we’ll be able to use it in our app.

We’re going to create a new React Hook that we’ll be able to use to grab our locations anywhere within our app.

Under src/hooks/index.js, add the following line to the existing list:

export { default as useDestinations } from './useDestinations';

This will allow us to more conveniently import our hook which we’ll create next.

Under src/hooks, create a new file useDestinations.js and paste in this code:

import { graphql, useStaticQuery } from 'gatsby';

export default function useDestinations() {
  const { gcms = {} } = useStaticQuery( graphql`
    query {
      gcms {
        destinations {
          id
          name
          location {
            latitude
            longitude
          }
        }
      }
    }
  ` );

  let { destinations } = gcms;

  return {
    destinations,
  };
}

Here, we’re:

• Importing the graphql and useStaticQuery utilities from Gatsby
• We’re creating a new function (or hook) that is exported by default
• In that function, we’re using useStaticQuery to create a new GraphQL query which asks GraphCMS to return the data structure we defined.
• That query returns a value which we destructure immediately to grab the gmcs object
• We destructure destinations from gmcs and return it as part of a new object from our hook

With this, we can now use our hook anywhere in our app!

Head over to your src/pages/index.js file, first import our new hook:

import { useDestinations } from 'hooks';

And at the top of the IndexPage component, query our data:

const { destinations } = useDestinations();

This puts all of our locations into the destinations variable. We can test that this works by console logging it out:

console.log('destinations', destinations);

And once we open up our browser and look in our web developer tools console, we can see our location data!

Logging destinations data to the web console

Step 4: Creating a bucket list of destinations and adding them to the map

We’re going to start with creating a simple text list of our destinations. This will let us see all of our destinations in an easy to read format.

Creating a text list of our destinations

Inside of our IndexPage and above “Still Getting Started?”, let’s add the following code:

<h2>My Destinations</h2>
<ul>
  { destinations.map(destination => {
    const { id, name } = destination;
    return <li key={id}>{ name }</li>
  })}
</ul>

This code:

• Adds a new header for our list
• Creates a new unordered list
• Loops through our destinations and creates a new list item for each destination that include’s the location’s name

Once we hit save and reload, we should see our list under our map!

New basic list of destinations in the app

The list looks a little odd though right? We probably want to format it a little better to fit into the page.

Open up src/assets/stylesheets/pages/_home.scss and inside of the .home-start class, add:

.home-start {

  ...

  ul {
    list-style: none;
    padding: 0;
    margin: 1.2em 0;
  }

Let’s also modify the h2 to space things out a little better:

.home-start {

  ...

  h2 {

    margin-top: 2em;

    &:first-child {
      margin-top: 0;
    }

  }

Once you hit save and reload, it should look a little better.

Destinations in the app with cleaned up styles

Feel free to make additional changes, but we’ll leave it there for now.

Adding our destinations to the map

Now we can finally add our destinations to the map!

Inside of our <Map> component, we already have a <Marker>. This allows us to easily add a marker to the map given a position. We’ll take this concept and combine it with our text list to add our locations to the map.

Let’s update our <Map> code to match the following:

<Map {...mapSettings}>
  { destinations.map(destination => {
    const { id, name, location } = destination;
    const position = [location.latitude, location.longitude];
    return <Marker key={id} position={position} />
  })}
</Map>

Here we:

• Loop through our destinations to dynamically create a new list of components inside our <Map>
• Inside each loop instance, we destructure our date from destination
• We create a new position array with the latitude and longitude
• Create a new Marker where we use our position to add it to the map

This gives us our markers on the map!

Markers for each destination in the mapping app

But we want to know what each of those locations are, so let’s also add a popup to each marker that will show the name.

First, we need to import Popup from react-leaflet:

import { Marker, Popup } from 'react-leaflet';

Then, let’s update our <Marker> component to return:

return (
  <Marker key={id} position={position}>
    <Popup>{ name }</Popup>
  </Marker>
);

And once we save and open back up our map, you can now click on each marker and see our destinations name!

Popup for each destination marker in the mapping app

Before we’re done, center the map

Previously, our demo map centered on Washington, DC. Let’s update that to the center of the world since our map doesn’t focus on the United States.

Update the LOCATION variable to:

const LOCATION = {
  lat: 0,
  lng: 0,
};

And with that, we have our map!

Final mapping app with markers and popups for each destination

Follow along with the commit!

What else other features can we add to our app?

Add a way to check off each location

Inside GraphCMS, you can add a new field to your Destination content model that allows you to select whether you visited each location or not.

With this value, we can add it to our query and update our map with some kind of indicator like a checkmark to show that we’ve checked it off our bucket list!

Customize your map background styles

We’re using a public version of OpenStreetMap which is open source, but Mapbox offers some cool maps we can use to make it look a little more impressive.

If you want to get started changing your map styles, you can check out this other walkthrough of mine to learn how to use Mapbox.

Check out the blog post or watch the video!

Style the map markers with a custom image

You can check out my video walk through on how to change the markers to a custom image.

Take that a step further and use the feature above to dynamically show a different marker image when you’ve checked off a location.

Check out the video on Egghead.io!

Want to learn more about maps?

Check out some of my other tutorials and videos:

• Mapping with React Leaflet (egghead.io)
• Mapping Apps with React, Gatsby, & Leaflet (youtube.com)
• How to create a Coronavirus (COVID-19) Dashboard & Map App with Gatsby and Leaflet (colbyfayock.com)
• How to Create a Summer Road Trip Mapping App with Gatsby and Leaflet (colbyfayock.com)
• How to build a mapping app in React the easy way with Leaflet (colbyfayock.com)
• Anyone Can Map! Inspiration and an introduction to the world of mapping (colbyfayock.com)

What’s on your travel bucket list?

Let me know on Twitter!

How can we configure this so we don't have to directly edit our code to change our environment?

• What are environment variables?
• How can environment variables be useful?
• How can I keep these files secure?
• Gatsby and environment variables
• Netlify and environment variables
• Step 1: Creating a "Hello, world" website
• Step 2: Creating a local environment variable with Gatsby
• Step 3: Deploying the website to Netlify
• Where can you add or update more variables in Netlify?

What are environment variables?

Environment variables are predetermined values that are typically used to provide the ability to configure a value in your code from outside of your application.

_MY_SECRETKEY environment variable used for authorization

When developing locally, or sometimes even in a deployment pipeline, you'll oftentimes find these variables stored in a file named with some kind of variation of .env.

How can environment variables be useful?

Probably the most common use case for environment variables is being able to set up different configuration options for different environments. Often when developing against third party services, you want to have a development version or sandbox available to make test requests against, that way it doesn't impact real production data.

Environment variables are helpful because they allow you to change which of your environments use which third party service environment by changing an API key, endpoint, or whatever the service uses to distinguish between environments.

The code you deploy should be predictable, so by not having to change any code, just the configuration outside of the code, you can maintain that predictability.

How can I keep these files secure?

This is probably one of the more important points here – you need to ensure you're handling these files with care and not checking them into a git repository. By exposing these keys by inadvertently uploading them to a public location, the internet could easily find these keys and abuse them for their own gains.

For instance, AWS keys are a valuable source. People run bots with the sole purpose of trying to scan Github for keys. If someone finds an AWS key, they could use this key to access resources such as running a bitcoin operation at your expense. This isn't to scare you, its to make you aware so you avoid your keys getting compromised.

So how can we keep these secure? The easiest way is to add the environment file where you keep these keys to your .gitignore file.

To do this, simply open your existing .gitignore file or create a new one at the root of your repository and add the filename as a new line:

# Inside .gitignore
.env

If you want to get more advanced and make sure this never happens to a repository, you can check out some tools like git-secrets from AWS Labs or GitLeaks that even has a Github Action to make it easy to integrate with Github.

Gatsby and environment variables

Gatsby by default makes two files available as part of its environment variable workflow that makes these values available in the client: .env.development and .env.production. These correlate to the gatsby develop and gatsby build scripts to either develop or build your site.

_MY_SECRETKEY environment variable for development and production

To make use of these files within the Gatsby development and build process, Gatsby requires you to prefix these variables with GATSBY_. This also works if you'd like to have them available from an OS process level.

Though you could integrate dotenv if you have more advanced needs or don't want to use the GATSBY_ prefix, your path of least resistance is probably to just follow the Gatsby way when working in Gatsby.

Netlify and environment variables

Netlify provides the ability to add environment variables as part of its Build & deploy settings which gets picked up as part of the build processes.

Adding an environment variable in Netlify

Luckily, Netlify makes it easy to add whatever environment variable you'd like to the build process! To add one, you can simply navigate to the Environment section of your project's Build & deploy settings page and add a variable under Environment variables.

We'll walk you through this process a little later.

Step 1: Creating a "Hello, world" website

For our walkthrough, we're going to set up a really basic example of a Gatsby website just for the purposes of testing this out.

New website with Gatsby Sass Starter

Though this isn't really a common use case of environment variables, where normally you would use them for things like API keys and service configurations, this will give you a great idea of how it fundamentally works.

We're going to use this Gatsby Sass Starter I created which will give us a starting point and add "Hello, [Environment]" depending on where it's running.

To get started, let's create our local project by using the Gatsby CLI. Navigate to where you'd like to store this project and run:

gatsby new my-env-project https://github.com/colbyfayock/gatsby-starter-sass

You can change my-env-project to whatever directory you'd like this project created in, but once you run this command, you'll now have a project in that new directory.

New Gatsby project in the terminal

To get started, once inside that directory, run yarn develop to make changes locally or yarn build to compile your new site.

Once you're ready to go, you'll want to add this project to Github. If you're not familiar with how to do this, you can learn how to add an existing project to Github here.

Step 2: Creating a local environment variable with Gatsby

Our next step is to create a local environment and add a change that will let us see that it works.

To get started, let's first create a new file at the root of our project called .env.development. It might ask you if you really want to use the . prefix, make sure you say yes!

Inside that file, let's add:

# Inside .env.development
GATSBY_MY_ENVIRONMENT="Development"

Creating an .env.development file

Next, to make sure we don't forget to do this, let's also add this .env.development file to our .gitignore so we don't accidentally commit this to our git history. If you don't already have a .gitignore file, make sure you create it at the root of your project.

Adding .env.development to your .gitignore

Finally, to check that this works, let's open pages/index.js and let's replace our <h1> tag's content with a "Hello, world!" variation:

<h1>Hello, {process.env.GATSBY_MY_ENVIRONMENT}</h1>

And if we save that change and open it in our browser, we should see "Hello, Development"!

Using an environment variable for your Gatsby site

Follow along with the commit!

Step 3: Deploying the website to Netlify

So we have our website created using a simple environment variable. Next we'll want to actually deploy that site to Netlify. If you haven't already, we'll need to add our website to Github or another Git provider. Make sure to have that set up before continuing on.

After creating an account and logging in to Netlify, let's click the New site from Git button the main dashboard, follow the instructions for connecting your Github or other Git provider to Netlify, and then find your new repository.

Adding a new Github repository to Netlify

Once you select your repository, you'll be asked to configure your build process. Luckily, Netlify can detect that we're using a Gatsby site and has it pre-filled for us. Unless you've added something special, keep the basic configuration to use gatsby build to build your project and public/ for the output.

Configuring Netlify build settings

Now before we hit Deploy, there's one thing we want to add, and that's our environment variable!

Right above the Deploy site button there's an Advanced button. Click that and you'll see a new dropdown with an additional New variable button.

Configuring an environment variable in the Netlify setup

Click that New variable button, add our GATSBY_MY_ENVIRONMENT as a new variable and add Production as the value. And finally, hit Deploy site!

From here, you should be able to watch your website deploy and once finished, you'll see your new site with "Hello, Production"!

Deployed Gatsby site using Netlify environment variable

Where can you add or update more variables in Netlify?

With our example, we only added one variable during the setup. But Netlify lets you add or update any other variables you'd like.

If you'd ever like to change that variable or add more, you can navigate to the Environment section of the Build & deploy settings, where you can edit and add any other variables in the Environment variables section.

Environment variables settings in Netlify

Looking to learn more?

Here are a few other things to help you get started with development fundamentals!

• What is Gatsby and why it's time to get on the hype train?
• What is the JAMstack and how do I get started?
• How to Become a Full Stack Web Developer in 2020
• Put Down the Javascript - Learn HTML & CSS
• Set Future You Up for Success with Good Coding Habits

Author's note: Similar to before, this dashboard is meant to be a demo and proof of concept for using real world data to build a dashboard. While this data should be accurate per the NovelCOVID API, I would recommend using tools like the Johns Hopkins University dashboard for complete and accurate analysis. Stay home and be safe! ❤️

• What are we going to build?
• What do we need before we get started?
• Step 1: Update how we fetch our data and fetch the statistics
• Step 2: Adding statistics to our dashboard
• Step 3: Make the data human friendly
• Step 4: Add the Last Updated date
• What can I do next?

What are we going to build?

We're going to be extending our original map demo with some basic statistics that we can retrieve from the NovelCOVID API. To get an idea, here's my demo I'm basing this off of.

Coronavirus (COVID-19) map demo with dashboard statistics

While you're not required to have completed Part 1 to apply these concepts, it definitely helps, and it lets you set up a map for your dashboard. If you'd like to start there, which I recommend, check out How to create a Coronavirus (COVID-19) Dashboard & Map App with Gatsby and Leaflet first.

Woah, a mapping app?

Yup. If you haven't played with maps before, don't be discouraged! It's not as bad as you probably think. If you'd rather start with mapping basics, you can read more about how mapping works first.

What do we need before we get started?

For this walkthrough, you pretty much need a React app in some form. I'll be working with the dashboard we previously built in my last walkthrough that includes a map of the cases of the Coronavirus (COVID-19) per country.

Coronavirus (COVID-19) map dashboard

I recommend starting with the previous tutorial, but if you want to skip the map and start fresh, the easiest way would probably be to use Create React App, Gatsby, or Next.js.

Step 1: Update how we fetch our data and fetch the statistics

To get started with our statistics dashboard, we're going to do a little prep work by changing how we're fetching the data. The goal here, is we're going to wrap our request logic in a reusable way so that we can use it for both our countries data and our new statistics data.

Creating a new React hook to fetch data

Diving in, the first we'll do is create a new React hook that will serve as how we fetch the data. To get started, create a new file in your hooks directory called useTracker.js and add a line inside of hooks/index.js to export it:

// New file src/hooks/useTracker.js
// This will be empty for now

// Inside hooks/index.js
export { default as useTracker } from './useTracker';

Inside of our useTracker.js file, we're going to set up our request logic. This is a long file, so make sure you copy and paste the entire thing before we walk through what it does:

import { useEffect, useState } from 'react';
import axios from 'axios';

const API_HOST = 'https://corona.lmao.ninja/v2';

const ENDPOINTS = [
  {
    id: 'all',
    path: '/all',
    isDefault: true
  },
  {
    id: 'countries',
    path: '/countries'
  }
]

const defaultState = {
  data: null,
  state: 'ready'
}

const useTracker = ({ api = 'all' }) => {

  const [tracker = {}, updateTracker] = useState(defaultState)

  async function fetchTracker() {
    let route = ENDPOINTS.find(({ id } = {}) => id === api);

    if ( !route ) {
      route = ENDPOINTS.find(({ isDefault } = {}) => !!isDefault);
    }

    let response;

    try {
      updateTracker((prev) => {
        return {
          ...prev,
          state: 'loading'
        }
      });
      response = await axios.get(`${API_HOST}${route.path}`);
    } catch(e) {
      updateTracker((prev) => {
        return {
          ...prev,
          state: 'error',
          error: e
        }
      });
      return;
    }

    const { data } = response;

    updateTracker((prev) => {
      return {
        ...prev,
        state: 'ready',
        data
      }
    });

  }

  useEffect(() => {
    fetchTracker()
  }, [api])

  return {
    fetchTracker,
    ...tracker
  }
};

export default useTracker;

Starting from the top:

• We import our dependencies: we're going to use Reacts useEffect and useState hooks to manage our requests
• We define default constants: we have a base API endpoint for our data, a list of the available endpoints we'll use, and a state object that will store our data
• We define our useTracker hook: our hook includes one argument api that will allow us to specify which endpoint we'll use to make our request
• We set up a state instance: we'll want to keep track of our fetched data, so we create a tracker state instance that we'll be able to update
• We created an asynchronous fetchTracker function: we'll use this to make our actual request
• Inside our function: we first find the API route and create our URL, update our state instance to a "loading" state, try to make our request, catch any errors if there are any, and finally if the request is successful, we update our state with that data
• We trigger our function: using a useEffect hook, we trigger our fetchTracker function to make the request. We only have one dependency of api. This means the function will only fire the first time and any time the api value we pass in changes. We won't be changing that value, but it may be helpful in other instances if you're dynamically changing the API used
• We return our tracker: the returned object includes both our tracker data as well as our fetchTracker function that we could use to refetch the data if we'd like

And with all of that, we have a brand new hook that will fetch data from the NovelCOVID API.

Using our new tracker hook

To make use of this hook, let's jump over to src/pages/index.js, remove our axios import if it's there, and instead import our hook:

import { useTracker } from 'hooks';

With our hook, let's replace our original country data request. First, add the following to the top of the IndexPage component:

const { data: countries = [] } = useTracker({
  api: 'countries'
});

const hasCountries = Array.isArray(countries) && countries.length > 0;

This will let us fetch our country data and let us know if we have any results. Next, let's replace our original request.

Inside of our mapEffect function, let's remove the axios request in addition to the response, the destructured data object, and the hasData constant.

Code diff showing update to map effect

Then, replace hasData with hasCountries:

if ( !hasCountries ) return;

And replace data with countries in the geoJson object where we map our features:

features: countries.map((country = {}) => {

At this point, if you hit save and refresh, you shouldn't notice any difference to what you previously had.

Add a request for our stats

Now that we are using our useTracker hook to fetch our country data, let's also use that to fetch our stats.

Right next to where we set up our useTracker hook before, let's add another request:

const { data: stats = {} } = useTracker({
  api: 'all'
});

And if we add a console.log statement under to see what's inside stats:

console.log('stats', stats);

We should see our stats data object logged out!

Using console.log to show Coronavirus (COVID-19) statistics

Follow along with the commit!

Step 2: Adding statistics to our dashboard

Now that we have our data available to use, let's use it!

To get started adding our statistics to the dashboard, let's create a data structure that will allow us to easily configure the data we want to use.

To do this, let's first create a new array called dashboardStats below hasCountries at the top of the page component:

const dashboardStats = [];

Inside this array, let's add some new objects that specify our data that we're pulling from the stats object we requested. To start, let's try to add:

const dashboardStats = [
  {
    primary: {
      label: 'Total Cases',
      value: stats?.cases
    },
    secondary: {
      label: 'Per 1 Million',
      value: stats?.casesPerOneMillion
    }
  },
  {
    primary: {
      label: 'Total Deaths',
      value: stats?.deaths
    },
    secondary: {
      label: 'Per 1 Million',
      value: stats?.deathsPerOneMillion
    }
  },
  {
    primary: {
      label: 'Total Tests',
      value: stats?.tests
    },
    secondary: {
      label: 'Per 1 Million',
      value: stats?.testsPerOneMillion
    }
  }
]

The reason we're splitting this up into primary and secondary keys, is we're going to use that to differentiate between logically similar stats that we want to style a little bit differently.

_Note: if you're not familiar with the ?. syntax, it's called Optional Chaining. This allows us to chain our properties without worrying about if the objects exist. If stats is undefined, it will simply return undefined instead of throwing an error._

With our stats data, let's add the tracker to our map. Let's remove our current <Map> component and include it nested inside our tracker div in the following:

<div className="tracker">
  <Map {...mapSettings} />
  <div className="tracker-stats">
    <ul>
      { dashboardStats.map(({ primary = {}, secondary = {} }, i) => {
        return (
          <li key={`Stat-${i}`} className="tracker-stat">
            { primary.value && (
              <p className="tracker-stat-primary">
                { primary.value }
                <strong>{ primary.label }</strong>
              </p>
            )}
            { secondary.value && (
              <p className="tracker-stat-secondary">
                { secondary.value }
                <strong>{ secondary.label }</strong>
              </p>
            )}
          </li>
        );
      })}
    </ul>
  </div>
</div>

This code should be immediately following the <Helmet> component if you're following along.

To explain what we're doing:

• We're creating a "tracker" div that will organize our stats
• We move our <Map component inside of this tracker
• We create a separate section called "tracker-stats"
• Inside of this, we create an unordered list (ul)
• Inside of our list, we loop through all of our stats inside dashboardStats
• For each stat, we create a new list element (li) and include 2 optional paragraphs that includes our primary stat data and our secondary stat data

Once we reload our page, we should now see a few stats:

Adding the first statistics to the page

Now that we have our stats on our page, let's make them look like they're in a dashboard.

Let's create a new file called _tracker.scss inside of our src/assets/stylesheets/components directory. Once that file is created, additionally add it to the src/assets/stylesheets/components/__components.scss file:

@import "tracker";

With our new component style file ready to go, let's add some styles into _tracker.scss:

.tracker-stats {

  color: white;
  background-color: $blue-grey-900;
  border-top: solid 1px darken($blue-grey-900, 5);

  ul {
    display: grid;
    grid-template-columns: 1fr 1fr 1fr;
    list-style: none;
    padding: 0;
    margin: 0;
  }

}

.tracker-stat {

  font-size: 2em;
  text-align: center;
  padding: .5em;
  border-right: solid 1px darken($blue-grey-900, 5);
  border-bottom: solid 1px darken($blue-grey-900, 5);

  strong {
    font-weight: normal;
    color: $blue-grey-300;
  }

}

.tracker-stat-primary {

  margin: 0;

  strong {
    display: block;
    font-size: .5em;
  }

}

.tracker-stat-secondary {

  font-size: .5em;
  margin: .8em 0 0;

  strong {
    font-size: .8em;
    margin-left: .4em;
  }

}

Above – we're adding colors and organizational effects, such as using CSS Grid, to allow our data to be organized in an easy to read way and to look good! We're also making use of some pre-existing colors variables that are used within the project to keep the color use consistent.

Once you save those styles and reload the page, it should look much better:

Adding case statistics to the dashboard

From here, feel free to add more stats or adjust them to your liking. In the demo I created, I added the stats for active cases, critical cases, and recovered cases. If you'd like to do the same, you can check out the commit.

Follow along with the commit!

Step 3: Make the data human friendly

Now the rest of this walkthrough could be considered optional, but ultimately we want people to be able to read these statistics, right? So let's make the numbers a little more easy to read.

First, let's open our src/lib/util.js file and add this function:

/**
 * commafy
 * @description Applies appropriate commas to large numbers
 */

export function commafy(value) {
  let numberString = `${value}`;

  numberString = numberString.split('');

  numberString.reverse();

  numberString = numberString.reduce((prev, current, index) => {
    const shouldComma = (index + 1) % 3 === 0 && index + 1 < numberString.length;
    let updatedValue = `${prev}${current}`;
    if ( shouldComma ) {
      updatedValue = `${updatedValue},`;
    }
    return updatedValue;
  }, '');

  numberString = numberString.split('');
  numberString.reverse()
  numberString = numberString.join('');

  return numberString;
}

This function will take a number and turn it into a string with commas. To walk through what it does:

• Takes in a value as an argument. For our use, this value will most likely be a number.
• It converts the value into a string. We'll use this to work with adding commas to our number.
• We split that string into an array and reverse it. We want to reverse it because it makes it easier to add our commas depending on the index.
• We use the javascript reduce function to recreate our number-string. After every 3 numbers, we want to add a comma.
• Once we have our new value with the commas, we want to re-reverse it. So we split it again, reverse the array of characters, and re-join it, which is what we return

And now that we have our commafy function, let's use it. Back inside src/pages/index.js, let's import our function at the top of the page:

import { commafy } from 'lib/util';

Then, in our dashboardStats array, let's replace every number value with a ternary expression and function that will convert our number if it's available:

value: stats ? commafy(stats?.cases) : '-'

This line checks to see if stats exists. If it does, we commafy the cases value. If it doesn't exist, we return a - to show it's unavailable.

Once we repeat that process for all of our numbers, we can save, reload the page, and see our human friendly numbers!

Formatting the statistics to be human readable

Follow along with the commit!

Step 4: Add the Last Updated date

Finally, we want to make sure people are staying informed and understand the last time this data was updated. Luckily, our API provides a Last Updated date for us, so let's use it!

At the bottom of our "tracker" div under tracker-stats, let's add the following:

<div className="tracker-last-updated">
  <p>
    Last Updated: { stats?.updated }
  </p>
</div>

This creates a new section where we simply include the updated property from our stats. And if we save and reload the page, we can see the last updated date!

Adding last updated to the dashboard

But how could we even understand what that number is, unless you're the computer crawling this blog post? So let's change it to a human readable format like we did with our numbers.

Inside of our src/lib/util.js file, let's add another function:

/**
 * friendlyDate
 * @description Takes in a date value and returns a friendly version
 */

export function friendlyDate(value) {
  const date = new Date(value);
  return new Intl.DateTimeFormat('en', {
    year: 'numeric',
    month: 'short',
    day: '2-digit',
    hour: 'numeric',
    minute: 'numeric'
  }).format(date);
}

This function creates a new Date object, then uses the javascript International DateTimeFormat API to convert it into a friendly readable format!

Once that's saved, let's import it next to our commafy function at the top of src/pages/index.js:

import { commafy, friendlyDate } from 'lib/util';

Then we can update our code similar to how we updated our numbers:

Last Updated: { stats ? friendlyDate(stats?.updated) : '-' }

And if we save and reload, we see it in a human readable way!

Formatting the last updated date

Finally for our "last updated" should look like it fits in with the rest of the dashboard, so let's add a few more styles. Inside of our _tracker.scss file we were working with earlier:

.tracker-last-updated {

  color: white;
  background-color: $blue-grey-900;
  padding: .8em 0;

  p {
    color: $blue-grey-300;
    font-size: .8em;
    text-align: center;
    margin: 0;
  }

}

And once we hit save and refresh the browser, we have our dashboard statistics with the last updated time! ?

Final dashboard with formatted lasted updated date

Follow along with the commit!

What can I do next?

Make the marker tooltip data human friendly

Now that we have our handy commafy and friendlyDate functions, we can reuse those functions to clean up the data in our country marker popups!

Use the fetchTracker function to poll for updates

Inside of the useTracker hook we created, we exported a function called fetchTracker. This allows us to force a request to the API to fetch new data. To make sure our map stays current even when somebody doesn't refresh the page, we can create a timer in javascript to regularly invoke that function to update our dashboard data.

Clear the map layers before re-adding the new ones

One thing we're currently not doing is cleaning up old layers before adding a new one. The way the map is set up, it just keeps layering them on top. What we can do is before we add all of our new layers, we can clear out the old ones. Check out this commit to get started!

Want to learn more about maps?

You can check out a few of my other resources to get started:

• How to create a Coronavirus (COVID-19) Dashboard & Map App in React with Gatsby and Leaflet (Part 1 of this post)
• How to set up a custom Mapbox basemap style with React Leaflet and Leaflet Gatsby Starter
• Anyone Can Map! Inspiration and an introduction to the world of mapping
• How to Create a Summer Road Trip Mapping App with Gatsby and Leaflet
• How to Create your own Santa Tracker with Gatsby and React Leaflet
• How to build a mapping app in React the easy way with Leaflet

• What are we going to build?
• What is Mapbox?
• Part 1: Creating a custom Mapbox style
• Part 2: Adding a custom TileLayer to React Leaflet
• Part 3: Adding a custom basemap to Gatsby Starter Leaflet
• Securing your Mapbox key
• Want to learn more about maps?

What are we going to build?

We’re going to walk through creating a new basic Mapbox style in our Mapbox account. Once created, we’re going to use their Map API to add a custom basemap to our React Leaflet app.

Gatsby Starter Leaflet with Mapbox basemap

For our map, we’re going to use this Leaflet Gatsby Starter I created that will allow you to easily spin up a new mapping app. Before we spin that up though, I’ll walk you through how to add it using only React Leaflet components.

A mapping app?

Yup! Maps are used all around the world to study datasets for geographic locations. They're important tools for scientists and others that are trying to help the world.

Coronavirus (COVID-19) custom map

If you want to learn more about building a map and adding data to it, you can check out some of my other articles first such as creating a Coronavirus (COVID-19) map or a Summer Road Trip map as well as a little bit of inspiration about why Anyone Can Map.

What is Mapbox?

Mapbox is a mapping platform that allows its customers to create custom mapping solutions. They also leverage a variety of APIs that provide powerful capabilities for building map features.

mapbox.com

For our purposes, we’re going to utilize their Map API, specifically their Static Tiles API, to serve a custom map style that we create.

Part 1: Creating a custom Mapbox style

To get the look and feel that we want for our map, it’s important to have a basemap that helps make our data present itself without distractions. Plus, sometimes it’s fun to have a custom map.

Mapbox account

The first thing we’ll need to set up our custom Mapbox style is to have an account. I'm not going to walk you through that process, but you can head over to Mapbox’s website where you can sign up for free: mapbox.com

Creating a new custom style

Creating a new style in Mapbox isn’t as hard as it sounds. While it can get really complex if you want something unique, we can copy one of Mapbox’s default styles to get started.

First, head over to Mapbox’s Studio dashboard by clicking your account link in the top right corner when logged in.

Mapbox Studio

Once we’re on our Studio dashboard, we want to select the New Style button.

Create a new style in Mapbox Studio

After clicking the button, a modal will pop up allowing you to choose a template. You can choose whatever you want here, but I’m going to choose Monochrome with a variation of Dark. And after you’ve selected your template, click the Customize button.

Select and customize a template for a new style in Mapbox Studio

And now we’re dropped into our customization UI.

Mapbox customize style UI

From here, you can really do what you’d like. There are a ton of options to customize your map. It’s a little complex to try to dig in here, but Mapbox provides some resources to try to help you get productive.

Generating a Mapbox token

Once you’re happy with your new style and everything’s published, we want to generate a token that we’ll use for providing access to our Map.

Head on over to the Account section of the Mapbox dashboard.

Creating a new token in Mapbox

Mapbox provides you with a “default” token that you can use in your applications. You're free to use this, but I recommend creating a new token that you can provide a unique name, that way if you ever blow past the free tier of Mapbox, you’ll be able to track your usage.

Additionally, it’s best to keep a separate token for each application, that way you can easily rotate an individual key, without having to update every application using it.

Once you click Create a token, you can set up the key how you’d like, with the scopes and permissions you choose, but for our purposes, you can leave all of the Public scopes checked for our map, which they do by default.

Create a new access token in Mapbox

Configuring our custom endpoint

For this tutorial, we’re going to use Mapbox’s Static Tiles service.

Mapbox Static Tiles Maps API

Our endpoint will look like the following:

https://api.mapbox.com/styles/v1/{username}/{style_id}/tiles/256/{z}/{x}/{y}@2x?access_token={access_token}

There are a few parameters here we need to understand:

• username: this will be your Mapbox account’s username
• style_id: this will be the ID of the style you created before
• z, x, y: these are parameters that Leaflet programmatically swaps out, so we want to leave them as is
• access_token: this is the Mapbox key you created above

To find your username and style ID, we can use the Style URL for our new Mapbox style to get those values.

Finding the Style URL in Mapbox Studio

In my example, my Style URL looks like:

mapbox://styles/colbyfayock/ck8lryjfq0jdo1ip9ctmuhc6p

colbyfayock is my username and ck8lryjfq0jdo1ip9ctmuhc6p is my style ID.

And once I update my endpoint parameters, the final tilepoint URL will look like:

https://api.mapbox.com/styles/v1/colbyfayock/ck8lryjfq0jdo1ip9ctmuhc6p/tiles/256/{z}/{x}/{y}@2x?access_token=MYACCESSTOKEN

Part 2: Adding a custom TileLayer to React Leaflet

When building a map with React Leaflet, your main component will be a <Map> that wraps the entirety of the app. This is what sets up your Map instance for Leaflet.

For our purposes here, we’re going to use the example on the React Leaflet homepage as our starting point.

React Leaflet TileLayer Component

Inside of your <Map> component you include a <TileLayer> component, which defines the imagery of the world that you base your map upon.

The example on the React Leaflet homepage uses a public version of OpenStreetMap as their TileLayer, which is an open source map project created and updated by people all around the world.

<Map center={position} zoom={13}>
  <TileLayer
    url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
    attribution="&copy; <a href=&quot;http://osm.org/copyright&quot;>OpenStreetMap</a> contributors"
  />
</Map>

This gives you a basic map, but we want to swap in Mapbox so we can set up a custom look and feel for our map.

Custom Mapbox TileLayer

To add our custom style, we’ll want to update the url and attribution props of the TileLayer component.

For URL, it will simply be the custom style endpoint we created earlier, so in my example, it looks like:

https://api.mapbox.com/styles/v1/colbyfayock/ck8lryjfq0jdo1ip9ctmuhc6p/tiles/256/{z}/{x}/{y}@2x?access_token=MYACCESSTOKEN

For attribution, we want to credit Mapbox as the service, so we want to set our attribution as:

Map data &copy; <a href=&quot;https://www.openstreetmap.org/&quot;>OpenStreetMap</a> contributors, <a href=&quot;https://creativecommons.org/licenses/by-sa/2.0/&quot;>CC-BY-SA</a>, Imagery &copy; <a href=&quot;https://www.mapbox.com/&quot;>Mapbox</a>

When plugged in to our TileLayer, our code should now look like this:

<Map center={position} zoom={13}>
  <TileLayer
    url="https://api.mapbox.com/styles/v1/colbyfayock/ck8lryjfq0jdo1ip9ctmuhc6p/tiles/256/{z}/{x}/{y}@2x?access_token=MYACCESSTOKEN"
    attribution="Map data &copy; <a href=&quot;https://www.openstreetmap.org/&quot;>OpenStreetMap</a> contributors, <a href=&quot;https://creativecommons.org/licenses/by-sa/2.0/&quot;>CC-BY-SA</a>, Imagery &copy; <a href=&quot;https://www.mapbox.com/&quot;>Mapbox</a>"
  />
</Map>

And once we open up our map, we should see our new basemap!

React Leaflet with a Mapbox basemap

See the code!

If you want to see how I did it, check out the diff commit by commit.

The only caveat there is I created an .env.development.local file in the root of my project in which I stored a new environment variable called REACT_APP_MAPBOX_KEY to store my Mapbox key.

Part 3: Adding a custom basemap to Gatsby Starter Leaflet

I’ve written a few other articles on how to get started with my Leaflet Gatsby Starter, but for this part, we’ll want to have a basic app spun up that we can use to change our TileLayer endpoint.

Setting up our React Leaflet Gatsby app

To get started, check out the instructions on the Starter github:

https://github.com/colbyfayock/gatsby-starter-leaflet

Once you’re ready, you should have a basic mapping app ready to go!

New Leaflet Gatsby app in the browser

Configuring our Mapbox service

The first thing we’ll want to do is add Mapbox as a service in our src/data/map-services.js file.

Taking our custom endpoint URL that we created in Part 1, let’s set up a new object with a name of Mapbox, and with a url and attribution similar to what we did in Part 2.

export const mapServices = [
  {
    name: ‘OpenStreetMap’,
    attribution: '&copy; <a href="http://osm.org/copyright”>OpenStreetMap</a> contributors’,
    url: ‘https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png’
  },
  {
    name: ‘Mapbox’,
    attribution: ‘Map data &copy; <a href=&quot;https://www.openstreetmap.org/&quot;>OpenStreetMap</a> contributors, <a href=&quot;https://creativecommons.org/licenses/by-sa/2.0/&quot;>CC-BY-SA</a>, Imagery &copy; <a href=&quot;https://www.mapbox.com/&quot;>Mapbox</a>’,
    url: `https://api.mapbox.com/styles/v1/colbyfayock/ck8c2foj72lqk1jnug0g2haw0/tiles/256/{z}/{x}/{y}@2x?access_token=MY_ACCESS_TOKEN`
  }
];

Using our Mapbox map service

Once you have your Mapbox service set up, all that’s left is to open up the src/pages/index.js file, find the mapSettings object definition, and update the defaultBaseMap property to Mapbox.

const mapSettings = {
  center: CENTER,
  defaultBaseMap: ‘Mapbox’,
  zoom: DEFAULT_ZOOM,
  mapEffect
};

Save that change, refresh the map in your browser, and you should now see your custom basemap style!

Gatsby Starter Leaflet with custom Mapbox basemap in browser

See the code!

If you want to see how I did it, check out the diff with the commit.

The only caveat there is I created an .env.development file in the root of my project in which I stored a new environment variable called GATSBY_MAPBOX_KEY to store my Mapbox key.

Securing your Mapbox key

Environment variables

Part of most development processes that use individual keys will generally set the keys up as environment variables. Environment variables are configured settings that don’t live in the code itself.

This is important because it prevents your key from being checked in to your code, which is bad from a security perspective, but it also allows you to provide a different key for different environments.

When generating your keys, try to keep this in mind, as it can save you in the long run.

Locking down your Mapbox key

In your settings when creating a token or when editing a token, Mapbox allows you to specify only the URLs you want your key to be accessible from.

Though Mapbox has a generous free tier, you probably want to keep it locked down only to the URLs that you’re using it on. You can create multiple keys, where one could be for public use on your website and one would be for your local development.

This is helpful for instance, where you have a key that will never be used publicly for development purposes, but then you have a key that you deploy with, which can be locked down only to that URL.

If someone grabs your key, they could plug it into their own website and use up all of your free tier, potentially running up your bill!

Want to learn more about maps?

You can check out a few of my other resources to get started:

• How to create a Coronavirus (COVID-19) Dashboard & Map App in React with Gatsby and Leaflet
• Anyone Can Map! Inspiration and an introduction to the world of mapping
• How to Create a Summer Road Trip Mapping App with Gatsby and Leaflet
• How to Create your own Santa Tracker with Gatsby and React Leaflet
• How to build a mapping app in React the easy way with Leaflet

Update: The original NovelCOVID API v1 endpoint has been deprecated. Please update and use the following instead: https://corona.lmao.ninja/v2/countries

Author’s Note: This is meant to be a demo and proof of concept for putting together an impactful mapping application using real life data. For complete and accurate analysis, please make sure to use tools like Johns Hopkins University dashboard. Stay home and be safe! ❤️

• What are we going to build?
• What do we need before we get started?
• Step 1: Cleaning up some unneeded code
• Step 2: Fetching the Coronavirus data
• Step 3: Transform the Coronavirus data into a geographic data format
• Step 4: Adding the Coronavirus data to the map
• What else can we do?
• Be safe and stay informed
• Want to learn more about maps?

What are we going to build?

We’ll be putting together a mapping application that uses an API containing recent Coronavirus statistics and maps out the locations and impact each country is facing.

Coronavirus map dashboard demo

On the map, we’ll show a marker for each country with the number of confirmed cases. On top of that, we’ll include a little popup tooltip that shows more in depth information.

The map we’ll build will mostly look like the above, but will look a little simpler. We’ll utilize the OpenStreetMap public tileserver instead of using a custom Mapbox

To get started, we’re going to use this Leaflet Gatsby Starter I created to make the initial setup a little smoother. With our app bootstrapped, we’ll fetch our data and add markers to the map with our data.

Woah, a mapping app?

Yup. If you haven’t played with maps before, don’t be discouraged! It's not as bad as you probably think. If you’d rather start with mapping basics, you can read more about how mapping works first.

What do we need before we get started?

If you followed along with my previous tutorials for building a Santa Tracker or creating a Summer Road Trip map, you can follow the same steps to get started. If not, we’ll want to make sure we have the following set up:

• node or yarn - I'll be using yarn, but you can substitute with npm where appropriate
• Gatsby’s CLI - yarn global add gatsby-cli

If you’re not sure about one of the above, you can try checking out the beginning my previous tutorial.

We’ll also want to set up a foundation for our map. We can do this by utilizing the Leaflet Gatsby Starter I put together that provides us a basic setup with Leaflet and React Leaflet.

gatsby new my-coronavirus-map https://github.com/colbyfayock/gatsby-starter-leaflet

Creating a new Leaflet Gatsby app in the terminal

After that’s finished running, you can navigate to the newly created project directory and start your local development server:

cd my-coronavirus-map
yarn develop

Starting your Gatsby app in the terminal

If all goes as planned, your server should start and you should now be able to see your basic mapping app in your browser!

New Leaflet Gatsby app in the browser

Follow along with the commit!

Step 1: Cleaning up some unneeded code

The Gatsby Starter we're using to spin up this app comes with some demo code that we don’t need here. We’ll want to make all of the changes below in the file src/pages/index.js, which is the homepage of our app.

First, let’s remove everything from the mapEffect function. This function is used to run code that fires when the map renders.

// In src/pages/index.js
async function mapEffect({ leafletElement } = {}) {
  // Get rid of everything in here
}

We’ll also change the variable name of our leafletElement simply for being able to more easily understand the code as we write it.

async function mapEffect({ leafletElement: map } = {}) {
}

Next, we don’t want a marker this time, so let’s remove the <Marker component from our <Map component:

<Map {...mapSettings} />

Now that we have those pieces cleared out, we can remove all of the following imports and variables from the top of our file:

• useRef
• Marker
• promiseToFlyTo
• getCurrentLocation
• gatsby_astronaut
• timeToZoom
• timeToOpenPopupAfterZoom
• timeToUpdatePopupAfterZoom
• ZOOM
• popupContentHello
• popupContentGatsby
• markerRef

After, our map should still work, but not do anything.

New mapping app with nothing going on

Follow along with the commit!

Step 2: Fetching the Coronavirus data

For our app, we’re going to use the NovelCOVID API. Particularly, we’re going to use the countries endpoint to fetch the list of our countries and the stats associated with them.

For making requests, I personally like to use axios as it has a nice to use API. If you want to use fetch or your own favorite request library, substitute that in for this step.

We’ll start by installing axios:

yarn add axios

Once that installs, remember to restart your server.

Import the axios package ta the top of our pages/index.js file:

import axios from 'axios';

Next we’ll actually make our request. Inside our mapEffect function, let’s try to make a request to the API endpoint:

async function mapEffect({ leafletElement: map } = {}) {
    let response;

    try {
      response = await axios.get('https://corona.lmao.ninja/v2/countries');
    } catch(e) {
      console.log(`Failed to fetch countries: ${e.message}`, e);
      return;
    }

    const { data = [] } = response;
}

In this snippet, we’re doing the following:

• Setting up a response variable that will allow us to store the response
• Adding a try/catch block that will catch any API errors if the request fails
• If the request is successful, we store the response in the response variable
• If the request fails, we console log out the error and return out of the function so we don’t continue to run the code with a failed request
• Once we have our response, we can destructure data from the response and set the default value to an empty array, as that will be the type of data we need

After that’s set up, we can console log out the data object and we’ll see our data successfully fetched!

Logging the Coronavirus location data to the browser console

Follow along with the commit!

Update: The previous commit includes a link to the original NovelCOVID v1 API endpoint which has now been deprecated. Please use this instead: https://corona.lmao.ninja/v2/countries.

See updated commit.

Step 3: Transform the Coronavirus data into a geographic data format

Now that we have our data, we can transform it into a geographic data format, particularly GeoJSON, that will allow us to interface with Leaflet.

Let’s start by adding this block of code:

const { data = [] } = response;
const hasData = Array.isArray(data) && data.length > 0;

if ( !hasData ) return;

const geoJson = {
  type: 'FeatureCollection',
  features: data.map((country = {}) => {
    const { countryInfo = {} } = country;
    const { lat, long: lng } = countryInfo;
    return {
      type: 'Feature',
      properties: {
       ...country,
      },
      geometry: {
        type: 'Point',
        coordinates: [ lng, lat ]
      }
    }
  })
}

So what are we doing here?

• We create a new constant called hasData that checks if our data variable is an array and has data
• If we don’t have data, we want to return out of the function, as we don’t want to try to add data we don’t have
• We create a geoJson object that will be our GeoJSON document
• Our document is of type FeatureCollection and as our features we loop through our dataset
• For each country in our data, we obtain the lat and lng to create a point for our map
• We additionally add our country data as properties so we can access it within our mapping APIs

If you console.log this object our into your browser and copy the contents, you can paste this into geojson.io and see the location data show up correctly.

Previewing Coronavirus location data on geojson.io

With this GeoJSON document, we'll now be able to add it to our map.

Follow along with the commit!

Step 4: Adding the Coronavirus data to the map

We have our GeoJSON document with our location data, so let’s add it to the map.

Let’s start with this code block. It's a long one, but we’ll break it down piece by piece:

const geoJsonLayers = new L.GeoJSON(geoJson, {
  pointToLayer: (feature = {}, latlng) => {
    const { properties = {} } = feature;
    let updatedFormatted;
    let casesString;

    const {
      country,
      updated,
      cases,
      deaths,
      recovered
    } = properties

    casesString = `${cases}`;

    if ( cases > 1000 ) {
      casesString = `${casesString.slice(0, -3)}k+`
    }

    if ( updated ) {
      updatedFormatted = new Date(updated).toLocaleString();
    }

    const html = `
      <span class="icon-marker">
        <span class="icon-marker-tooltip">
          <h2>${country}</h2>
          <ul>
            <li><strong>Confirmed:</strong> ${cases}</li>
            <li><strong>Deaths:</strong> ${deaths}</li>
            <li><strong>Recovered:</strong> ${recovered}</li>
            <li><strong>Last Update:</strong> ${updatedFormatted}</li>
          </ul>
        </span>
        ${ casesString }
      </span>
    `;

    return L.marker( latlng, {
      icon: L.divIcon({
        className: 'icon',
        html
      }),
      riseOnHover: true
    });
  }
});

So what are we doing here?

• We create a new instance of L.GeoJSON which will transform our GeoJSON document into something Leaflet will understand
• Inside that instance, we define a custom pointToLayer function. This allows us to customize the map layer Leaflet creates for our map
• In our function, we assign and create our datapoints that we want. Most of it is destructuring, but we format the cases count to show 1k+ instead of 1000 and a formatted date instead of the timestamp
• We create an HTML string block which is used to define our map marker that will be added to the map. This also includes the HTML for the tooltip that will pop up when hovering over a marker
• We return L.marker with our custom configuration that includes a class of icon for the container and our custom HTML.
• Additionally, we add the riseOnHover property so when hoving over a marker, it surfaces itself above over the other markers on the map

We also want to add a bit of CSS here so that we can make sure our markers show up in the map and are usable. Let’s add this snippet to our assets/stylesheets/components/_map.scss file:

.icon-marker {

  display: flex;
  position: relative;
  justify-content: center;
  align-items: center;
  color: white;
  width: 3.6em;
  height: 3.6em;
  font-size: .7em;
  font-weight: bold;
  background-color: $red-800;
  border-radius: 100%;
  box-shadow: 0 2px 5px rgba(black, .9);

  &:hover {

    .icon-marker-tooltip {
      display: block;
    }

  }

}

.icon-marker-tooltip {

  display: none;
  position: absolute;
  bottom: 100%;
  width: 16em;
  font-size: 1.4em;
  padding: 1em;
  background-color: $blue-grey-900;
  border-radius: .4em;
  margin-bottom: 1em;
  box-shadow: 0 3px 5px rgba(black, .9);

  &:before {
    display: block;
    position: absolute;
    bottom: -.6em;
    left: 50%;
    content: '';
    width: 1.4em;
    height: 1.4em;
    background-color: $blue-grey-900;
    transform: rotate(45deg);
    margin-left: -.7em;
  }

  h2 {
    font-size: 1.5em;
    line-height: 1.2;
    margin-bottom: .1em;
    margin-top: 0;
  }

  h3 {
    font-size: 1.2em;
    margin: .1em 0;
    font-weight: normal;
    color: $blue-grey-100;
  }

  ul,
  p {
    font-weight: normal;
  }

  ul {
    list-style: none;
    padding: 0;
    margin: .6em 0 0;
  }

}

What we’re doing:

• We create our round markers using the .icon-marker class and set up our .icon-marker-tooltip class to show up when hovered over
• Our .icon-marker-tooltip class is hidden by default, as it’s our tooltip, but we position it absolutely to appear over top of our marker and formatted the way we want it

And finally, once we have our geoJsonLayers created with our styling added, we can add it to the map!

geoJsonLayers.addTo(map)

Map with Coronavirus location data

Now you might be wondering why it doesn't appear to be centering properly. Go ahead and change the LOCATION variable at the top of the index.js file to:

const LOCATION = {
  lat: 0,
  lng: 0
};

Once that’s set, when the page reloads, the map should be centered in the middle of the world!

Map with Coronavirus location data centered with a tooltip

Follow along with the commit!

Yay, we did it! ?

If you followed along, you now have created your own Coronavirus map dashboard that gives some quick stats about the cases around the world.

Take what you learned and run with it. You can apply this to any other type of data that you can imagine.

What else can we do?

Add more styles and a custom basemap

In my original demo, I set up a custom basemap using Mapbox that allows me to have a dark background making the markers easier to see.

Creating a new basemap in Mapbox Studio

Mapbox is great and has a nice free tier if you’re interested in getting started.

Once you have a Mapbox account, you can even copy the style I used and make it your own.

Basic Dark Mapbox Theme

To learn how to integrate it, you can try to check out the source code of my original demo:

https://github.com/colbyfayock/coronavirus-map-dashboard

Add overview dashboard stats

Dashboards with maps like the Johns Hopkins University app allows us to see more than a look on the map, but a glimpse at quick stats about the cases around the world.

Johns Hopkins University Coronavirus Map Dashboard - March 29, 2020

The NovelCOVID API has more endpoints like /all that provide a few global stats.

Be safe and stay informed

I want to reiterate that you should make sure you're staying up to date using official sources for information, such as the Johns Hopkins University dashboard. Though the data should be reliable, it should also be considered a proof of concept for building a map and referencing, but shouldn't be considered for any kind of statistical analysis.

Please take care of yourself during these times. We're all in this together! ❤️

Want to learn more about maps?

You can check out a few of my other resources to get started:

• Anyone Can Map! Inspiration and an introduction to the world of mapping
• How to set up a custom Mapbox basemap style with React Leaflet and Leaflet Gatsby Starter
• How to Create a Summer Road Trip Mapping App with Gatsby and Leaflet
• How to Create your own Santa Tracker with Gatsby and React Leaflet
• How to build a mapping app in React the easy way with Leaflet

• What are we going to build?
• What do we need before we get started?
• Step 1: Cleaning up some unneeded code
• Step 2: Create our road trip locations
• Step 3: Prepare our app with some functions
• Step 4: Building our trip path
• Step 5: Styling our map components
• Want to learn more about maps?

Author’s Note: Even though we’re going through some challenging times, we can still be optimistic that we’ll get through this together and be able to enjoy our summer. Stay safe and wash your hands. ❤️

What are we going to build?

We’ll be walking through building a new mapping app that shows a route representing the trip. Each location will have a little card where we can add a picture and some things we did.

Colbana's Summer Road Trip

To get started, we’re going to use this Leaflet Gatsby Starter I created to make the initial setup a little smoother. With our app bootstrapped, we’ll create our list of locations and use Leaflet’s API to draw our route on the map.

Woah, a mapping app?

Yup. If you haven’t played with maps before, don’t be discouraged! It's not as bad as you probably think. If you’d rather start with mapping basics, you can read more about how mapping works first.

What do we need before we get started?

If you followed along with my last tutorial for building a Santa Tracker, you can follow the same steps to get started. If not, we’ll want to make sure we have the following set up:

• node or yarn - I'll be using yarn, but you can substitute with npm where appropriate
• Gatsby’s CLI - yarn global add gatsby-cli

If you’re not sure about one of the above items, you can try checking out the beginning of my previous tutorial.

We’ll also want to set up a foundation for our map. We can do this by utilizing the Leaflet Gatsby Starter I put together that provides us a basic setup with Leaflet and React Leaflet.

gatsby new my-road-trip https://github.com/colbyfayock/gatsby-starter-leaflet

Creating a new Leaflet Gatsby app in the terminal

After that’s finished running, you can navigate to the newly created project directory and start your local development server:

cd my-road-trip
yarn develop

Starting your Gatsby app in the terminal

If all goes as planned, your server should start and you should now be able to see your basic mapping app in your browser!

New Leaflet Gatsby app in the browser

Step 1: Cleaning up some unneeded code

The Gatsby Starter we're using to spin up this app comes with some demo code that we don’t need here. We’ll want to make all of the changes below in the file src/pages/index.js, which is the homepage of our app.

First, let’s remove everything from the mapEffect function. This function is used to run code that fires when the map renders.

// In src/pages/index.js

async function mapEffect({ leafletElement } = {}) {
  // Get rid of everything in here
}

Next, we don’t want a marker this time, so let’s remove the <Marker component from our <Map component:

<Map {…mapSettings} />

Now that we have those pieces cleared out, we can remove all of the following imports and variables from the top of our file:

• useRef
• Marker
• promiseToFlyTo
• getCurrentLocation
• gatsby_astronaut
• timeToZoom
• timeToOpenPopupAfterZoom
• timeToUpdatePopupAfterZoom
• ZOOM
• popupContentHello
• popupContentGatsby
• markerRef

After, our map should still work, but not do anything.

New mapping app with nothing going on

Follow along with the commit

Step 2: Create our road trip locations

This step will involve preparing our location data that will populate our road trip app. Our locations will include properties like a name, date, things we did, and a picture if we want.

First, create a new file in the src/data directory called locations.js. Inside of that file, we want to create and export a new array.

export const locations = [
  {
    placename: ‘Herndon, VA’,
    date: ‘August 1, 2015’,
    location: {
      lat: 38.958988,
      lng: -77.417320
    },
    todo: [
      ‘Where we start! ?’
    ]
  },
  {
    placename: ‘Middlesboro, KY',
    date: ‘August 1, 2015’,
    location: {
      lat: 36.627517,
      lng: -83.621635
    },
    todo: [
      ‘Cumberland Gap ?’
    ]
  }
];

You can use the above to get started, but you’ll eventually want to change the details to something of your choosing.

If you want to add an image to your location, you can do so by including an image property to the object. You can use either a URL string or you can import a local file if you have one available, like I’m doing in this example:

import imgHerndonStart from 'assets/images/herndon-start.jpg’;

export const locations = [
  {
    placename: ‘Herndon, VA’,
    date: ‘August 1, 2015’,
    image: imgHerndonStart,
    location: {
      lat: 38.958988,
      lng: -77.417320
    },
    todo: [
      ‘Where we start! ?’
    ]
  }
]

Once we have that file created, we can now import our locations into our src/pages/index.js file so we can use it in our next step:

import { locations } from 'data/locations’;

If you add a console.log(locations) inside of your page, you should now see all of your location data in an array!

Follow along with the commit

Step 3: Prepare our app with some functions

To try to keep things simple and focused, I grouped together 3 important components of creating our map into functions. Though it’s available to copy and paste, we’ll walk through what’s happening in each function.

You can place each of these functions at the bottom of the src/pages/index.js file so they’re ready to use in our next step.

createTripPointsGeoJson

Our first function is going to take the array of our locations and return a GeoJSON document, with our locations mapped into an individual Feature. We’ll use this function to create the individual points on our map.

What is a GeoJSON document? It's essentially a JavaScript object or JSON document with a specific structure that creates consistency with geographical data.

function createTripPointsGeoJson({ locations } = {}) {
  return {
    “type”: “FeatureCollection”,
    “features”: locations.map(({ placename, location = {}, image, date, todo = [] } = {}) => {
      const { lat, lng } = location;
      return {
        “type”: “Feature”,
        “properties”: {
          placename,
          todo,
          date,
          image
        },
        “geometry”: {
          “type”: “Point”,
          “coordinates”: [ lng, lat ]
        }
      }
    })
  }
}

So what’s happening in the above?

• We take an argument of locations, which will be our array of destinations
• We return an object with some dynamic properties associated with it
• Within the object, we map our locations to individual Feature objects
• Each object includes a Point shape using our coordinates
• It additionally includes our properties that store our metadata

When this function is invoked, we will have a newly created JavaScript object that includes an array of Points representing the locations we are stopping at on our road trip.

createTripLinesGeoJson

We’re going to create another function that’s similar to the previous one. This time however, instead of points, we want to create lines that represent going from one point to the next.

function createTripLinesGeoJson({ locations } = {}) {
  return {
    “type”: “FeatureCollection”,
    “features”: locations.map((stop = {}, index) => {
      const prevStop = locations[index - 1];

      if ( !prevStop ) return [];

      const { placename, location = {}, date, todo = [] } = stop;
      const { lat, lng } = location;
      const properties = {
        placename,
        todo,
        date
      };

      const { location: prevLocation = {} } = prevStop;
      const { lat: prevLat, lng: prevLng } = prevLocation;

      return {
        type: ‘Feature’,
        properties,
        geometry: {
          type: ‘LineString’,
          coordinates: [
            [ prevLng, prevLat ],
            [ lng, lat ]
          ]
        }
      }
    })
  }
}

So you’ll immediately notice that this is very similar to our last function. We’re returning an object and setting our metadata properties on a list of Features.

The big difference, however, is that we're creating a Line. To do this, we're looking up and referring to prevStop which will be the previous stop. We’ll use both the previous stop and our current stop in order to have 2 points which we can use to draw the line.

If we don’t have a previous stop, we return an empty array, which basically means we’re at the beginning of our journey with no line before it.

With the previous stop and current stop, we create a LineString type of Feature with our 2 points.

tripStopPointToLayer

Our last function is going to allow us to create custom content for each of the points that we will be adding to our map. We’ll actually be utilizing this function within a Leaflet property, so we’ll be conforming our arguments to that specification.

function tripStopPointToLayer( feature = {}, latlng ) {
  const { properties = {} } = feature;
  const { placename, todo = [], image, date } = properties;

  const list = todo.map(what => `<li>${ what }</li>`);
  let listString = ‘’;
  let imageString = ‘’;

  if ( Array.isArray(list) && list.length > 0 ) {
    listString = list.join(‘’);
    listString = `
      <p>Things we will or have done…</p>
      <ul>${listString}</ul>
    `
  }

  if ( image ) {
    imageString = `
      <span class=“trip-stop-image” style=“background-image: url(${image})”>${placename}</span>
    `;
  }

  const text = `
    <div class=“trip-stop”>
      ${ imageString }
      <div class=“trip-stop-content”>
        <h2>${placename}</h2>
        <p class=“trip-stop-date”>${date}</p>
        ${ listString }
      </div>
    </div>
  `;

  const popup = L.popup({
    maxWidth: 400
  }).setContent(text);

  const layer = L.marker( latlng, {
    icon: L.divIcon({
      className: ‘icon’,
      html: `<span class=“icon-trip-stop”></span>`,
      iconSize: 20
    }),
    riseOnHover: true
  }).bindPopup(popup);

  return layer;
}

One thing you’ll notice as we work through this function is that we create strings of HTML text. Given that the Leaflet API we’re utilizing for this doesn’t interface directly with React, we have to build out HTML manually to pass it in to our functions.

Starting from the top:

• We take in 2 arguments, feature and latlng. Leaflet passes these 2 values in for us to use in our function.
• We destructure our feature, allowing us to assign our metadata into variables
• 2 string variables are initialized that we’ll use for our HTML
• If we include a todo property as an array, we add a new list with each item inside.
• If we include an image, we create an image tag.
• With our newly created HTML strings, we construct the entirety of what will be our popup card for each strop
• With our popup HTML, we create a Leaflet popup instance
• With the latlng argument and our popup, we create a new Leaflet marker instance. This will represent the point on the map.
• Inside of the Marker creation, we create a basic HTML tag that well use to style the marker
• We then bind our popup to this new Marker instance. This will allow the popup to be associated with that individual Marker
• Finally, we return our newly created layer

Remember to make sure you put all of the functions above at the bottom of your src/pages/index.js page.

Once all of those functions are added, our map should still be the same thing, basically nothing happening.

Follow along with the commit

Step 4: Building our trip path

This is where things get interesting. We’ll now utilize the functions we created to build our road trip path. All of our work here will be within the mapEffect function inside of the src/pages/index.js file.

For context, our mapEffect function includes an argument called leafletElement. This value refers to the Map instance that Leaflet recognizes. This Map instance includes our map state as well as many utility functions to work with our map.

First, at the top of the function, we want to make sure we have a map. If not, we can return to bail out of the function.

if ( !leafletElement ) return;

Next, we want to use the eachLayer utility function and remove each layer from our map element. We do this to make sure we always have the correct map layer state.

leafletElement.eachLayer((layer) => leafletElement.removeLayer(layer));

With our cleaned up map, we can utilize 2 of the functions we created to create new GeoJSON objects.

const tripPoints = createTripPointsGeoJson({ locations });
const tripLines = createTripLinesGeoJson({ locations });

With our GeoJSON objects, we need to convert those to Leaflet GeoJSON instances, which we’ll use to add to the map.

const tripPointsGeoJsonLayers = new L.geoJson(tripPoints, {
  pointToLayer: tripStopPointToLayer
});

const tripLinesGeoJsonLayers = new L.geoJson(tripLines);

If you notice in the above, we're using our tripStopPointToLayer function. As I alluded to before, the geoJson instance we’re creating includes a property that allows us to pass in a function, giving us the ability to manipulate the layer creation. This is how we create our point and popup content.

We can proceed to adding both of those new layers to our map using the addTo .

tripPointsGeoJsonLayers.addTo(leafletElement);
tripLinesGeoJsonLayers.addTo(leafletElement);

Next, to make sure we zoom and center on the right location, we want to grab the bounds of the map using the getBounds function on our GeoJSON layer instance.

const bounds = tripPointsGeoJsonLayers.getBounds();

Finally, we fit our map's view to those bounds using the fitBounds function on our Map instance.

leafletElement.fitBounds(bounds);

Once you save and reload the page, you should now see a blue path representing the jump from each of our locations on the map!

Mapping app with road trip path

One issue though. If you notice, we only see the path. This is because we need to add some CSS which we’ll get to in the next step.

Follow along with the commit

Step 5: Styling our map components

Our last step will be adding some styles that will allow our markers to show and our popups to look just right.

In this step, we’ll be working inside of the _home.scss file, which you can find in src/assets/stylesheets/pages.

We can get started by copy and pasting this block of styles into the bottom of that file. With that done, we can walk through what’s happening.

.trip-stop {

  width: 400px;
  overflow: hidden;

  h2 {
    font-size: 1.4em;
    margin-top: 0;
    margin-bottom: .2em;
  }

  p,
  ul,
  h3 {
    font-size: 1.2em;
    font-weight: normal;
  }

  p {
    margin: .2em 0;
  }

  .trip-stop-date {
    color: $grey-600;
    font-size: 1em;
  }

  ul {
    padding: 0 0 0 1.4em;
    margin: 0;
  }

}

.trip-stop-image {
  display: block;
  float: left;
  overflow: hidden;
  width: 150px;
  height: 150px;
  text-indent: 100%;
  color: transparent;
  background-position: center;
  background-size: cover;
}

.trip-stop-content {
  float: left;
  width: 250px;
  padding-left: 1em;
}

.icon-trip-stop {

  display: block;
  width: 1.5em;
  height: 1.5em;
  background-color: $orange-500;
  border-radius: 100%;
  box-shadow: 0 2px 5px rgba(0,0,0,.5);

  &:hover {
    background-color: $deep-orange-400;
  }

}

There’s three components to our styles above:

• .trip-stop-images: Inside of the marker popup, we optionally can include an image. These styles set the size, make the text transparent, (it’s there for accessibility), and float it to the left so that our popup content can align correctly side by side.
• .trip-stop-content: This refers to the other half of our popup content. All we need to do here is make sure our size is appropriate and that it floats next to our image.
• .icon-trip-stop: The HTML tag that we’re using as our icon designation gets styled here. We size it up, set a color using a predetermined Scss variable, and we’re good to go.

Once those styles are saved, you should now see the points on the map representing each location. Additionally, you should be able to click each of these points to open up a popup containing information about the stop.

Road trip mapping app with popups

Follow along with the commit

Optional Last Step: Style Tweaks

The last thing that's completely optional is to make a few style tweaks to give your site a little personality. I’m not going to go over this in details, but if you’d like to follow along and dress things up a little bit, you can follow along with this commit which shows each code change I made.

Final version of the road trip mapping app

Follow along with the commit

Yay, we did it!

If you followed along with me, or skipped right to the starter, you should now have a mapping app that you can use for your next road trip.

The good news is this project can apply to anything! Want to map out your favorite restaurants in Washington, DC? Add your locations and remove the lines. Want to create line drawings over the map? That's certainly an option.

Whatever it is, if you enjoyed getting this map spun up, get creative and apply it to your next project!

Want to learn more about maps?

You can check out a few of my other resources to get started:

• How to create a Coronavirus (COVID-19) Dashboard & Map App in React with Gatsby and Leaflet
• How to set up a custom Mapbox basemap style with React Leaflet and Leaflet Gatsby Starter
• Anyone Can Map! Inspiration and an introduction to the world of mapping
• How to Create your own Santa Tracker with Gatsby and React Leaflet
• How to build a mapping app in React the easy way with Leaflet

Buddy the Elf waving

To get in the spirit, we’re going to spin up a web app that includes a map that tracks Santa on it!

Edit 12/23: Updated the app to request directly to Santa's route, just in case the original API doesn't work as originally expected.

What are we going to build?

We’re going to work through building a mapping app that tracks Santa’s route and his current location.

To achieve this, we’re going to spin up a premade Gatsby starter that will give us a basic foundation for a map, utilize Google’s unofficial API to grab Santa’s route, and overlay his position and route on top of the map with Leaflet.

Woah, a mapping app?

Ay Caramba

Yup. If you haven’t played with maps before, don’t be discouraged! It's not as bad as you probably think. If you’d rather start with mapping basics, you can read more about how mapping works first.

What do we need before we get started?

For this exercise, I’m going to assume you have node or yarn installed. For each example, I'll use yarn, but use the tool of your choice.

You’ll also want to install Gatsby’s CLI globally which will allow us to use their Starter tools.

To set up Gatsby’s CLI, run the following command:

yarn global add gatsby-cli

After, you should be able to run gatsby -h to see the available commands, which means it’s successfully installed.

Running gatsby -h to verify install

For more info about the Gatsby CLI, you can check out their documentation.

Getting started with our map foundation

Once our command line tools are set up, the first thing we’ll want to do is create a new Gatsby project using a Leaflet starter I put together. It provides us with a basic setup with Leaflet and React Leaflet.

Starting in your project directory, let’s install the project:

gatsby new [directory] https://github.com/colbyfayock/gatsby-starter-leaflet

Make sure to replace [directory] with the location you want to set up your project.

Once you run that command, Gatsby will clone that project without any of the git references and install the packages required to start.

Installing Gatsby Starter Leaflet

To make sure it works, you can now navigate to that directory, spin up your server, and test it in the browser:

cd [directory]
yarn develop

Where you see [directory] above, make sure to use the same path as you did before when setting up the new Gatsby project.

Running Gatsby Starter Leaflet

If all goes as planned, your server should start and you should now be able to see your basic mapping app in your browser!

Gatsby Starter Leaflet in the browser

Cleaning things up

This starter comes with a quick example of how we can interact with the map. We're not going to need this at all for our purposes so we can go ahead and clean things up.

To start, we’re going to open up our index.js file, the homepage file, and get rid of everything inside of the mapEffect function, which leaves us with:

// In src/pages/index.js

async function mapEffect({ leafletElement } = {}) {
  // Get rid of everything in here
}

Now, let’s remove the Marker component nested inside of our Map, so we end up with:

<Map {…mapSettings} />

Now that we’re no longer using that functionality, we can get rid of the variables and references at the top of the file, so you can go ahead and remove:

• useRef
• promiseToFlyTo
• getCurrentLocation
• Marker
• gatsby_astronaut
• ZOOM
• timeToZoom
• timeToOpenPopupAfterZoom
• timeToUpdatePopupAfterZoom
• popupContentHello
• popupContentGatsby
• markerRef

Follow along with the commit.

Finding Santa

Now that we’re in a good place, let’s get our hands dirty and find Santa. To do this, we’re going to use Google’s unofficial, undocumented API. This means that it’s possible this API won’t be available the day after this get’s published, but let’s be optimistic.

Additionally, at the time of writing, it’s still showing last year’s destinations, so what we’re really going to be visualizing here is Santa’s previous year’s route, though the hope is this would reset on the 24th and we’ll all be merry!

Before we get Santa, let’s first add a line back to our mapEffect function:

async function mapEffect({ leafletElement } = {}) {
  if ( !leafletElement ) return;
}

What this will do is prevent the rest of our code from running in the event our map isn't ready yet. The mapEffect function itself, as you can see in the Map component, runs inside of an instance of useEffect passing an argument of a ref to the map, allowing us to run some code after our component renders.

So once we have that line, let’s now fetch Santa’s route inside of our mapEffect function:

async function mapEffect({ leafletElement } = {}) {
  if ( !leafletElement ) return;
  let route, routeJson;
  try {
    route = await fetch('https://firebasestorage.googleapis.com/v0/b/santa-tracker-firebase.appspot.com/o/route%2Fsanta_en.json?alt=media&2018b');
    routeJson = await route.json();
  } catch(e) {
    console.log(`Failed to find Santa!: ${e}`);
  }
  console.log(‘routeJson’, routeJson);
}

Let’s break this down:

• We grab Santa’s route via the API endpoint
• Once we have his route, we grab the response in a JSON format to make it easier to work with
• This is all wrapped in a try/catch so we can safely handle any response errors
• Finally, we just log out our response for now

Santa's route object in the web console

Now we have Santa and his route, which means we can see all the destinations in his route. If you dig in the response a little bit, you can see some fun things like how many presents were delivered to each location and the weather at the time!

Follow along with the commit.

Put a pin in his location

We found Santa! ? Now let’s put him on the map.

For our purposes, we’ll need to find the latitude and longitude of Santa. The problem is, we don’t get this exact value defined anywhere, we just get his destinations.

Since we don’t have his location specified anywhere, we can utilize his last known location where presents were delivered. Add the following after our last snippet inside the mapEffect function:

const { destinations = [] } = routeJson || {};
    const destinationsVisited = destinations.filter(({arrival}) => arrival < Date.now());
    const destinationsWithPresents = destinationsVisited.filter(({presentsDelivered}) => presentsDelivered > 0);
const lastKnownDestination = destinationsWithPresents[destinationsWithPresents.length - 1]

Below our request code, we:

• Destructure routeJson to grab destinations into a constant, adding a fallback to an empty object
• Filter the results to only find the destinations that he's visited, using the arrival time from the route object
• Filter the results to find only the locations with presents
• And finally grab the last item from the array, which shows his last known location

At this point in time, 12/23, we don't actually have any destinations, as Santa is still at the North Pole. At any time, we can test this out to simulate a future date by replaceing Date.now() in destinationsVisited with a future date, such as 1577188980000 which would be around 7pm Eastern on 12/24. With that change, we can see what Santa's route actually looks like!

Handle a missing Santa

Now that it's close to Christmas, Santa will still be at the North Pole, so let's handle the case where we don't have a location.

Above the line where we set lastKnownDestination, let's add:

if ( destinationsWithPresents.length === 0 ) {
  // Create a Leaflet Market instance using Santa's LatLng location
  const center = new L.LatLng( 0, 0 );
  const noSanta = L.marker( center, {
    icon: L.divIcon({
      className: 'icon',
      html: `<div class="icon-santa">?</div>`,
      iconSize: 50
    })
  });
  noSanta.addTo( leafletElement );
  noSanta.bindPopup( `Santa's still at the North Pole!` );
  noSanta.openPopup();
  return;
}

Okay so what are we doing here?

• First, we’re checking if we have any destinations with presents, which here we don't
• We first create a LatLng of the center of the map
• We create a Leaflet marker, using that center, with a custom Icon of Santa
• Next we add that Santa marker to the leafletElement, which is our map
• To show a message, we first bind a popup with a custom message and open it
• Finally we return so the rest of the code doesn’t run, as we don’t have Santa at this point

This was a section added after published to handle the API resetting, but you can still follow along with the code I added in context of the rest of the rest of the code.

Follow along in the code.

Pinning Santa

Edit 12/23: This section was originally written with the previous year's API, but this is still a good example of what you'll expect on the response, so you can follow right along.

And as we can see, since we’re looking at last year’s data, Santa is back home at the North Pole.

Santa's last known location in the web console

With his location, we can pull that apart, set up a Leaflet marker instance, and add our old friend to the map. Add the following after our last snippet inside the mapEffect function:

const santaLocation = new L.LatLng( lastKnownDestination.location.lat, lastKnownDestination.location.lng );

const santaMarker = L.marker( santaLocation, {
  icon: L.divIcon({
    className: ‘icon’,
    html: `<div class=“icon-santa”>?</div>`,
    iconSize: 50
  })
});

santaMarker.addTo(leafletElement);

Here we:

• Create a Leaflet LatLng instance with his location
• Create a Marker instance with our newly created LatLng instance
• Add our new Marker to the map

If we refresh our page, you’ll have to zoom out and pan up a little bit, but we'll see Santa on the map!

Santa on the map

Before we move on, let’s give Santa a little holiday cheer to make him easier to find. Find your application.scss file and toss these styles in:

// In src/assets/stylesheets/application.scss

.icon {

  & > div {

    display: flex;
    justify-content: center;
    align-items: center;
    overflow: hidden;
    border-radius: 100%;
    box-shadow: 0 3px 4px rgba(0,0,0,.4);
    border: none;
    transition: all .2s;

    &:hover {
      box-shadow: 0 4px 8px rgba(0,0,0,.6);
    }

  }

}

.icon-santa {
  width: 50px;
  height: 50px;
  font-size: 3em;
  background: white;
}

This just adds a white circle around him, a little drop shadow, and increases the size a bit to make him a little easier to find on the map.

Santa styled on the map

Follow along with the commit.

Drawing his route

The last thing we’re going to do here is draw a path on the map showing his route so we can follow along.

To get started, let’s update our code and add this last bit after our last snippet in the mapEffect function:

// Create a set of LatLng coordinates that make up Santa's route

const santasRouteLatLngs = destinationsWithPresents.map(destination => {
  const { location } = destination;
  const { lat, lng } = location;
  return new L.LatLng( lat, lng );
});

// Utilize Leaflet's Polyline to add the route to the map

const santasRoute = new L.Polyline( santasRouteLatLngs, {
  weight: 2,
  color: 'green',
  opacity: 1,
  fillColor: 'green',
  fillOpacity: 0.5
});

// Add Santa to the map!

santasRoute.addTo(leafletElement);

What we’re doing:

• Creating an array of Leaflet LatLng instances that make up Santa’s route
• Creating a Leaflet Polyline (a multi-point line) using that routes array
• Make that Polyline green
• Add our Polyline to the map

What we get… is a bunch of squiggly lines!

Santa's route on the map

This is expected. This gets technical really fast, but Leaflet by default can only understand 1 “portion” of the map as it wraps around in our browser. What this realistically means, is instead of drawing a line around a globe, the coordinates think it goes from one side of the world to the other as it hits the International Dateline. This is a bit out of scope for this tutorial, but you can check out Leaflet.Antimeridian to learn more and see if you can implement the solution to it.

Follow along with the commit.

A few quick style tweaks

One last thing! And this is completely optional. Let’s make the map a little bit bigger, set the background color to match our oceans, and zoom out a little bit. So let’s make a few changes:

// In src/pages/index.js

const DEFAULT_ZOOM = 1;

We’re setting our default zoom to 1 instead of 2 to allow the map to be zoomed out a bit.

// In src/assets/stylesheets/pages/_home.scss

.page-home {

  .map,
  .map-base {
    height: 80vh;
  }

}

We’re setting our map to a height of 80vh instead of 50vh to make it take up a little more of our screen.

// In src/assets/stylesheets/components/_map.scss
.map {

  &,
  .map-base {
    background: #acd3de;
  }

}

We’re setting the background color of our map to #acd3de instead of $blue-grey-50 which allows us to match the color of the oceans on our map.

What this achieves is being able to see Santa’s full route and Santa on the first view. Additionally, since the map only covers part of the screen, setting the background color of the map allows us to not have a little bit of a weird cutoff.

Santa's route zoomed out

Follow along with the commit.

Want a challenge?

To take this 1 step further, follow along with both how we added the routes and Santa to the map and try to see if you can add a marker to each destination location to show where all of the stops are. Bonus, add a popup to each one that says how many presents were delivered to that location!

To see the answer with some code organization and how I added the gift markers, check out the final version of the Santa Tracker demo.

Final Santa Tracker demo

While you’re there, you can also see how I utilized Leaflet.Antimeridian to fix our map's route.

What did we learn?

Building basic apps with a map isn’t nearly as bad as we thought! We learned how to fetch some data from an API, grab the data we need, and draw representations of that data on a map.

Next time you want to add a map widget to your landing page, try Leaflet. Share what you create on Twitter! Would love to see what you come up with.

I hope you and your family have a fantastic holiday season!

Happy Holidays from Dunder Mifflin

Want to learn more about maps?

You can check out a few of my other resources to get started:

• Anyone Can Map! Inspiration and an introduction to the world of mapping
• How to create a Coronavirus (COVID-19) Dashboard & Map App in React with Gatsby and Leaflet
• How to set up a custom Mapbox basemap style with React Leaflet and Leaflet Gatsby Starter
• How to Create a Summer Road Trip Mapping App with Gatsby and Leaflet
• How to build a mapping app in React the easy way with Leaflet

Want to read some of my other articles? Check out my blog: https://www.colbyfayock.com/2019/12/create-your-own-santa-tracker-with-gatsby-and-react-leaflet/

I have been a Gatsby user since around version 0 back in May 2017.

Back then, I was using a template called Lumen. It was just what I needed at the time. Since then I have gone from using a template to creating my blog.

Over the years I have built my own Progressive Disclosure of Complexity with Gatsby to where I am now.

What does that mean?

It means that although there are an awesome amount of Gatsby starters and themes out there to get you up and running in minutes, this post is going to focus on what you need to do to build your own blog. Starting with the most basic “Hello World!” to deploying your code to production.

What you’re going to build

You’re going to build a developer blog with MDX support (for some React components in Markdown goodness), so you will be able to add your own React components into your Markdown posts.

There’ll be:

• Adding a Layout
• Basic styling with styled-components
• Code blocks with syntax highlighting
• Copy code snippet to clipboard
• Cover images for the posts
• Configuring an SEO component
• Deploying it to Netlify

Who is this how-to for?

People that may have used Gatsby before as a template and now want to get more involved in how to make changes.

If you want to have code syntax highlighting.

If you want to use styled-components in an app.

I really want to avoid this!

Requirements

You’re going to need a basic web development setup: node, terminal (bash, zsh or fish) and a text editor.

I do like to use codesandbox.io for these sort of guides to reduce the barrier to entry but in this case I have found there are some limitations with starting out from scratch on codesandbox.io which doesn’t make this possible.

I have made a guide on getting set up for web development with Windows Web-Dev Bootstrap and covered the same process in Ubuntu as well.

Ok? Time to get started!

Hello World

To kick this off with the Gatsby ‘hello world’, you’ll need to initialise the project with:

npm init -y
git init

I suggest that you commit this code to a git repository, so you should start with a .gitignore file.

touch .gitignore

echo "# Project dependencies
.cache
node_modules

# Build directory
public

# Other
.DS_Store
yarn-error.log" > .gitignore

Ok now is a good time to do a git init and if you’re using VSCode you’ll see the changes reflected in the sidebar.

basic hello world

Ok a Gatsby hello world, get started with the bare minimum! Install the following:

yarn add gatsby react react-dom

You’re going to need to create a pages directory and add an index file. You can do that in the terminal by typing the following:

# -p is to create parent directories too if needed
mkdir -p src/pages
touch src/pages/index.js

Now you can commence the hello word incantation! In the newly created index.js enter the following:

import React from 'react';

export default () => {
  return <h1>Hello World!</h1>;
};

Now you need to add the Gatsby develop script to the package.json file, -p specifies what port you want to run the project on and -o opens a new tab on your default browser, so in this case localhost:9988:

"dev": "gatsby develop -p 9988 -o"

And now it’s time to run the code! From the terminal type the npm script command you just created:

yarn dev

Note I’m using Yarn for installing all my dependencies and running scripts. If you prefer you can use npm, just bear in mind that the content on here uses yarn, so swap out commands where needed.

And with that the “Hello World” incantation is complete ?!

Add content

Now you have the base for your blog you’re going to want to add some content. First up we’re going to get the convention out of the way. For this how-to, the date format will be logical – the most logical way for a date format is YYYYMMDD, fight me!

So you’re going to structure your posts content in years. In each one of those you’re going to have another folder relating to the post with the (correct) date format for the beginning of the file followed by the title of the post.

You could drill into this further if you like by separating out months and days. Depending on the volume of posts you've got going this may be a good approach. In this case and in the examples provided the convention detailed will be used.

# create multiple directories using curly braces
mkdir -p posts/2019/{2019-06-01-hello-world,2019-06-10-second-post,2019-06-20-third-post}
touch posts/2019/2019-06-01-hello-world/index.mdx
touch posts/2019/2019-06-10-second-post/index.mdx
touch posts/2019/2019-06-20-third-post/index.mdx

Ok that’s how to set up your posts. Now you need to add some content to them, so each file you have in here should have frontmatter. Frontmatter is a way to assign properties to the contents, in this case a title, published date and a published flag (true or false).

---
title: Hello World - from mdx!
date: 2019-06-01
published: true
---

# h1 Heading

My first post!!

## h2 Heading

### h3 Heading

---
title: Second Post!
date: 2019-06-10
published: true
---

This is my second post!

#### h4 Heading

##### h5 Heading

###### h6 Heading

---
title: Third Post!
date: 2019-06-20
published: true
---

This is my third post!

> with a block quote!

Gatsby config API

Next, you’re going to configure Gatsby so that it can read your super awesome content you just created. First up you need to create a the gatsby-config.js file. In the terminal create the file:

touch gatsby-config.js

Plugins

And now you can add the plugins Gatsby needs to use for sourcing and displaying the the files you just created.

Gatsby source filesystem

The gatsby-source-filesystem collects the files on the local filesystem for use in Gatsby once configured.

Gatsby plugin MDX

The gatsby-plugin-mdx is what will be allowing us to write JSX in our Markdown documents and the heart of how the content is displayed in the blog.

Now is a good time to also add in dependent packages for the Gatsby plugin MDX which are @mdx-js/mdx and @mdx-js/react.

In the terminal install the dependencies:

yarn add gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react gatsby-source-filesystem

Now it's time to configure gatsby-config.js:

module.exports = {
  siteMetadata: {
    title: `The Localhost Blog`,
    description: `This is my coding blog where I write about my coding journey.`,
  },
  plugins: [
    {
      resolve: `gatsby-plugin-mdx`,
      options: {
        extensions: [`.mdx`, `.md`],
      },
    },
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `${__dirname}/posts`,
        name: `posts`,
      },
    },
  ],
};

Query data from GraphQL

Now you can see what the gatsby-source-filesystem and gatsby-plugin-mdx have done for us. You can now go to the Gatsby GraphQL GraphiQL explorer and check out the data:

{
  allMdx {
    nodes {
      frontmatter {
        title
        date
      }
    }
  }
}

Site Metadata

When you want to reuse common pieces of data across the site (for example, your site title), you can store that data in siteMetadata. You touched on this when defining the gatsby-config.js, and now you’re going to separate this out from the module.exports. Why? It will be nicer to reason about once the config is filled with plugins.

At the top of gatsby-config.js add a new object variable for the site metadata:

const siteMetadata = {
  title: `The Localhost Blog`,
  description: `This is my coding blog where I write about my coding journey.`,
};

Now query the Site Metadata with GraphQL.

{
  site {
    siteMetadata {
      title
      description
    }
  }
}

Site metadata hook

Ok, so, that’s cool n’ all but how am I meant to use it? We'll do some of the code stuff and make a React hook so you can get your site data in any component you need it.

Create a folder to keep all your hooks in and create a file for our hook. In the terminal do:

mkdir src/hooks
touch src/hooks/useSiteMetadata.js

Ok, and in your newly created file were going to use the Gatsby useStaticQuery hook to make your own hook:

import { graphql, useStaticQuery } from 'gatsby';

export const useSiteMetadata = () => {
  const { site } = useStaticQuery(
    graphql`
      query SITE_METADATA_QUERY {
        site {
          siteMetadata {
            title
            description
          }
        }
      }
    `
  );
  return site.siteMetadata;
};

Now you can use this hook anywhere in your site, so do that now in src/pages/index.js:

import React from 'react';
import { useSiteMetadata } from '../hooks/useSiteMetadata';

export default () => {
  const { title, description } = useSiteMetadata();
  return (
    <>
      <h1>{title}</h1>
      <p>{description}</p>
    </>
  );
};

Styling

You’re going to use styled-components for styling. Styled-components (for me) help with scoping styles in your components. Time to go over the basics now.

install styled-components

yarn add gatsby-plugin-styled-components styled-components babel-plugin-styled-components

So, what was all that I just installed?

The babel plugin is for automatic naming of components to help with debugging.

The Gatsby plugin is for built-in server-side rendering support.

Configure

Ok, with that detailed explanation out of the way, configure them in gatsby-config.js:

const siteMetadata = {
  title: `The Localhost Blog`,
  description: `This is my coding blog where I write about my coding journey.`,
};

module.exports = {
  siteMetadata: siteMetadata,
  plugins: [
    `gatsby-plugin-styled-components`,
    {
      resolve: `gatsby-plugin-mdx`,
      options: {
        extensions: [`.mdx`, `.md`],
      },
    },
    {
      resolve: `gatsby-source-filesystem`,
      options: { path: `${__dirname}/posts`, name: `posts` },
    },
  ],
};

Time to go over a styled component. In index.js you’re going to import styled from 'styled-components' and create a StyledH1 variable.

So, you’re using the variable to wrap your {title} that you’re destructuring from the useSiteMetadata hook you made previously.

For this example make it the now iconic Gatsby rebeccapurple.

import React from 'react';
import styled from 'styled-components';
import { useSiteMetadata } from '../hooks/useSiteMetadata';

const StyledH1 = styled.h1`
  color: rebeccapurple;
`;

export default () => {
  const { title, description } = useSiteMetadata();
  return (
    <>
      <StyledH1>{title}</StyledH1>
      <p>{description}</p>
    </>
  );
};

That is styled-components on a very basic level. Basically create the styling you want for your page elements you’re creating in the JSX.

Layout

Gatsby doesn’t apply any layouts by default but instead uses the way you can compose React components for the layout. This means it’s up to you how you want to layout what you're building with Gatsby.

In this guide we're going to initially create a basic layout component that you’ll add to as you go along. For more detail on layout components take a look at the Gatsby layout components page.

Now you’re going to refactor the home page (src/pages/index.js) a little and make some components for your blog layout and header. In the terminal create a components directory and a Header and Layout component:

mkdir src/components
touch src/components/Header.js src/components/Layout.js

Now to move the title and description from src/pages/index.js to the newly created src/components/Header.js component, destructuring props for the siteTitle and siteDescription, you’ll pass these from the Layout component to here. You’re going to add Gatsby Link to this so users can click on the header to go back to the home page.

import { Link } from 'gatsby';
import React from 'react';

export const Header = ({ siteTitle, siteDescription }) => (
  <Link to="/">
    <h1>{siteTitle}</h1>
    <p>{siteDescription}</p>
  </Link>
);

Now to the Layout component: this is going to be a basic wrapper component for now. You’re going to use your site metadata hook for the title and description and pass them to the header component and return the children of the wrapper (Layout).

import React from 'react';
import { useSiteMetadata } from '../hooks/useSiteMetadata';
import { Header } from './Header';

export const Layout = ({ children }) => {
  const { title, description } = useSiteMetadata();
  return (
    <>
      <Header siteTitle={title} siteDescription={description} />
      {children}
    </>
  );
};

Now to add the slightest of styles for some alignment for src/components/Layout.js, create an AppStyles styled component and make it the main wrapper of your Layout.

import React from 'react';
import styled from 'styled-components';
import { useSiteMetadata } from '../hooks/useSiteMetadata';
import { Header } from './Header';

const AppStyles = styled.main`
  width: 800px;
  margin: 0 auto;
`;

export const Layout = ({ children }) => {
  const { title, description } = useSiteMetadata();
  return (
    <AppStyles>
      <Header siteTitle={title} siteDescription={description} />
      {children}
    </AppStyles>
  );
};

Ok, now refactor your homepage (src/pages/index.js) with Layout.

import React from 'react';
import { Layout } from '../components/Layout';

export default () => {
  return (
    <>
      <Layout />
    </>
  );
};

Index page posts query

Now you can take a look at getting some of the posts you’ve created added to the index page of your blog. You’re going to do that by creating a GraphQL query to list out the posts by title, order by date, and add an excerpt of the post.

The query will look something like this:

{
  allMdx {
    nodes {
      id
      excerpt(pruneLength: 250)
      frontmatter {
        title
        date
      }
    }
  }
}

If you put that into the GraphiQL GUI, though, you’ll notice that the posts aren’t in any given order. So now add a sort to this - and you’ll also add in a filter for posts that are marked as published or not.

{
  allMdx(
    sort: { fields: [frontmatter___date], order: DESC }
    filter: { frontmatter: { published: { eq: true } } }
  ) {
    nodes {
      id
      excerpt(pruneLength: 250)
      frontmatter {
        title
        date
      }
    }
  }
}

On the homepage (src/pages/index.js) you’re going to use the query we just put together to get a list of published posts in date order; add the following to the index.js file:

import { graphql } from 'gatsby';
import React from 'react';
import { Layout } from '../components/Layout';

export default ({ data }) => {
  return (
    <>
      <Layout>
        {data.allMdx.nodes.map(({ excerpt, frontmatter }) => (
          <>
            <h1>{frontmatter.title}</h1>
            <p>{frontmatter.date}</p>
            <p>{excerpt}</p>
          </>
        ))}
      </Layout>
    </>
  );
};

export const query = graphql`
  query SITE_INDEX_QUERY {
    allMdx(
      sort: { fields: [frontmatter___date], order: DESC }
      filter: { frontmatter: { published: { eq: true } } }
    ) {
      nodes {
        id
        excerpt(pruneLength: 250)
        frontmatter {
          title
          date
        }
      }
    }
  }
`;

Woah! WTF was all that yo!?

Ok, you’re looping through the data passed into the component via the GraphQL query. Gatsby graphql runs the query (SITE_INDEX_QUERY) at runtime and gives us the results as props to your component via the data prop.

Slugs and Paths

Gatsby source filesystem will help with the creation of slugs (URL paths for the posts you’re creating). In Gatsby node you’re going to create the slugs for your posts.

First up you’re going to need to create a gatsby-node.js file:

touch gatsby-node.js

This will create the file path (URL) for each of the blog posts.

You’re going to be using the Gatsby Node API onCreateNode and destructuring out node, actions and getNode for use in creating the file locations and associated value.

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

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

Now to help visualise some of the data being passed into the components you’re going to use Dump.js for debugging the data. Thanks to Wes Bos for the super handy Dump.js component.

To get the component set up, create a Dump.js file in your src\components folder and copypasta the code from the linked GitHub page.

touch /src/components/Dump.js

import React from 'react';

const Dump = props => (
  <div
    style={{
      fontSize: 20,
      border: '1px solid #efefef',
      padding: 10,
      background: 'white',
    }}>
    {Object.entries(props).map(([key, val]) => (
      <pre key={key}>
        <strong style={{ color: 'white', background: 'red' }}>
          {key} ?
        </strong>
        {JSON.stringify(val, '', ' ')}
      </pre>
    ))}
  </div>
);

export default Dump;

Now you can use the Dump component anywhere in your project. To demonstrate, use it with the index page data to see the output.

So in the src/pages/index.js you’re going to import the Dump component and pass in the data prop and see what the output looks like.

import { graphql } from 'gatsby';
import React from 'react';
import Dump from '../components/Dump';
import { Layout } from '../components/Layout';

export default ({ data }) => {
  return (
    <>
      <Layout>
        <Dump data={data} />
        {data.allMdx.nodes.map(({ excerpt, frontmatter }) => (
          <>
            <h1>{frontmatter.title}</h1>
            <p>{frontmatter.date}</p>
            <p>{excerpt}</p>
          </>
        ))}
      </Layout>
    </>
  );
};

export const query = graphql`
  query SITE_INDEX_QUERY {
    allMdx(
      sort: { fields: [frontmatter___date], order: DESC }
      filter: { frontmatter: { published: { eq: true } } }
    ) {
      nodes {
        id
        excerpt(pruneLength: 250)
        frontmatter {
          title
          date
        }
      }
    }
  }
`;

Link Paths

Now you’ve created the paths you can link to them with Gatsby Link. First you’ll need to add the slug to your SITE_INDEX_QUERY Then you can add gatsby Link to src/pages/index.js.

You’re also going to create some styled-components for wrapping the list of posts and each individual post as well.

import { graphql, Link } from 'gatsby';
import React from 'react';
import styled from 'styled-components';
import { Layout } from '../components/Layout';

const IndexWrapper = styled.main``;

const PostWrapper = styled.div``;

export default ({ data }) => {
  return (
    <Layout>
      <IndexWrapper>
        {data.allMdx.nodes.map(
          ({ id, excerpt, frontmatter, fields }) => (
            <PostWrapper key={id}>
              <Link to={fields.slug}>
                <h1>{frontmatter.title}</h1>
                <p>{frontmatter.date}</p>
                <p>{excerpt}</p>
              </Link>
            </PostWrapper>
          )
        )}
      </IndexWrapper>
    </Layout>
  );
};

export const query = graphql`
  query SITE_INDEX_QUERY {
    allMdx(
      sort: { fields: [frontmatter___date], order: DESC }
      filter: { frontmatter: { published: { eq: true } } }
    ) {
      nodes {
        id
        excerpt(pruneLength: 250)
        frontmatter {
          title
          date
        }
        fields {
          slug
        }
      }
    }
  }
`;

Adding a Blog Post Template

Now you have the links pointing to the blog posts you currently have no file associated with the path. This means that clicking a link will give you a 404 and the built-in gatsby 404 will list all the pages available in the project, currently only the / index/homepage.

So, for each one of your blog posts you’re going to use a template that will contain the information you need to make up your blog post. To start, create a templates directory and template file for that with:

mkdir -p src/templates
touch src/templates/blogPostTemplate.js

For now you’re going to scaffold out a basic template (you’ll be adding data to this shortly):

import React from 'react';

export default () => {
  return (
    <>
      <p>post here</p>
    </>
  );
};

To populate the template you’ll need to use Gatsby node to create your pages.

Gatsby Node has many internal APIs available to us. For this example you’re going to be using the createPages API.

More info on Gatsby createPages API can be found on the Gatsby docs, details here: https://www.gatsbyjs.org/docs/node-apis/#createPages

In your gatsby-node.js file you’re going to add in the following in addition to the onCreateNode export you did earlier.

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

exports.createPages = ({ actions, graphql }) => {
  const { createPage } = actions;
  const blogPostTemplate = path.resolve(
    'src/templates/blogPostTemplate.js'
  );

  return graphql(`
    {
      allMdx {
        nodes {
          fields {
            slug
          }
          frontmatter {
            title
          }
        }
      }
    }
  `).then(result => {
    if (result.errors) {
      throw result.errors;
    }

    const posts = result.data.allMdx.nodes;

    // create page for each mdx file
    posts.forEach(post => {
      createPage({
        path: post.fields.slug,
        component: blogPostTemplate,
        context: {
          slug: post.fields.slug,
        },
      });
    });
  });
};

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

The part that you need to pay particular attention to right now is the .forEach loop where you’re using the createPage function we destructured from the actions object.

This is where you pass the data needed by blogPostTemplate you defined earlier. You’re going to be adding more to the context for post navigation soon.

// create page for each mdx node
posts.forEach(post => {
  createPage({
    path: post.fields.slug,
    component: blogPostTemplate,
    context: {
      slug: post.fields.slug,
    },
  });
});

Build out Blog Post Template

Now you’re going to take the context information passed to the blogPostTemplate.js to make the blog post page.

This is similar to the index.js homepage, whereas there’s GraphQL data used to create the page. But in this instance the template uses a variable (also known as a parameter or an identifier) so you can query data specific to that given variable.

Now quickly dig into that with a demo. In the GraphiQL GUI, create a named query and define the variable you’re going to pass in:

query PostBySlug($slug: String!) {
  mdx(fields: { slug: { eq: $slug } }) {
    frontmatter {
      title
      date(formatString: "YYYY MMMM Do")
    }
  }
}

Here you’re defining the variable as slug with the $ denoting that it’s a variable. You also need to define the variable type as (in this case) String!. The exclamation after the type means that it has to be a string being passed into the query.

Using mdx you’re going to filter on fields where the slug matches the variable being passed into the query.

Running the query now will show an error as there’s no variable being fed into the query. If you look to the bottom of the query pane you should notice QUERY VARIABLES. Click on that to bring up the variables pane.

This is where you can add in one of the post paths you created earlier. If you have your dev server up and running, go to one of the posts and take the path and paste it into the quotes "" and try running the query again.

{
  "slug": "/2019/2019-06-20-third-post/"
}

Time to use that data to make the post. You’re going to add body to the query and have that at the bottom of your page file.

Right now you’re going to create a simple react component that will display the data you have queried.

Destructuring the frontmatter and body from the GraphQL query, you’ll get the Title and the Data from the frontmatter object and wrap the body in the MDXRenderer.

import { graphql } from 'gatsby';
import { MDXRenderer } from 'gatsby-plugin-mdx';
import React from 'react';
import { Layout } from '../components/Layout';

export default ({ data }) => {
  const { frontmatter, body } = data.mdx;
  return (
    <Layout>
      <h1>{frontmatter.title}</h1>
      <p>{frontmatter.date}</p>
      <MDXRenderer>{body}</MDXRenderer>
    </Layout>
  );
};

export const query = graphql`
  query PostsBySlug($slug: String!) {
    mdx(fields: { slug: { eq: $slug } }) {
      body
      frontmatter {
        title
        date(formatString: "YYYY MMMM Do")
      }
    }
  }
`;

If you haven’t done so already now would be a good time to restart your dev server.

Now you can click on one of the post links and see your blog post template in all it’s basic glory!

Previous and Next navigation

Coolio! Now you have your basic blog where you can list available posts and click a link to see the full post in a predefined template. Once you’re in a post you have to navigate back to the home page to pick out a new post to read. In this section you’re going to work on adding in some previous and next navigation.

Remember the .forEach snippet you looked at earlier? That’s where you’re going to pass some additional context to the page by selecting out the previous and next posts.

// create page for each mdx node
posts.forEach((post, index) => {
  const previous =
    index === posts.length - 1 ? null : posts[index + 1];
  const next = index === 0 ? null : posts[index - 1];

  createPage({
    path: post.fields.slug,
    component: blogPostTemplate,
    context: {
      slug: post.fields.slug,
      previous,
      next,
    },
  });
});

So this should now match up with the query you have on the homepage (src/pages/index.js) except you currently have no filter or sort applied here. So do that now in gatsby-node.js and apply the same filters as on the homepage query:

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

exports.createPages = ({ actions, graphql }) => {
  const { createPage } = actions;
  const blogPostTemplate = path.resolve(
    'src/templates/blogPostTemplate.js'
  );

  return graphql(`
    {
      allMdx(
        sort: { fields: [frontmatter___date], order: DESC }
        filter: { frontmatter: { published: { eq: true } } }
      ) {
        nodes {
          fields {
            slug
          }
          frontmatter {
            title
          }
        }
      }
    }
  `).then(result => {
    if (result.errors) {
      throw result.errors;
    }

    const posts = result.data.allMdx.nodes;

    // create page for each mdx node
    posts.forEach((post, index) => {
      const previous =
        index === posts.length - 1 ? null : posts[index + 1];
      const next = index === 0 ? null : posts[index - 1];

      createPage({
        path: post.fields.slug,
        component: blogPostTemplate,
        context: {
          slug: post.fields.slug,
          previous,
          next,
        },
      });
    });
  });
};

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

Now you will be able to expose the previous and next objects passed in as context from Gatsby node.

You can destructure previous and next from pageContext and for now pop them into your super handy Dump component to take a look at their contents.

import { graphql } from 'gatsby';
import { MDXRenderer } from 'gatsby-plugin-mdx';
import React from 'react';
import Dump from '../components/Dump';
import { Layout } from '../components/Layout';

export default ({ data, pageContext }) => {
  const { frontmatter, body } = data.mdx;
  const { previous, next } = pageContext;
  return (
    <Layout>
      <Dump previous={previous} />
      <Dump next={next} />
      <h1>{frontmatter.title}</h1>
      <p>{frontmatter.date}</p>
      <MDXRenderer>{body}</MDXRenderer>
    </Layout>
  );
};

export const query = graphql`
  query PostsBySlug($slug: String!) {
    mdx(fields: { slug: { eq: $slug } }) {
      body
      frontmatter {
        title
        date(formatString: "YYYY MMMM Do")
      }
    }
  }
`;

Add in previous and next navigation, this is a couple of ternary operations. If the variable is empty then return null else render a Gatsby Link component with the page slug and the frontmatter title:

import { graphql, Link } from 'gatsby';
import { MDXRenderer } from 'gatsby-plugin-mdx';
import React from 'react';
import Dump from '../components/Dump';
import { Layout } from '../components/Layout';

export default ({ data, pageContext }) => {
  const { frontmatter, body } = data.mdx;
  const { previous, next } = pageContext;
  return (
    <Layout>
      <Dump previous={previous} />
      <Dump next={next} />
      <h1>{frontmatter.title}</h1>
      <p>{frontmatter.date}</p>
      <MDXRenderer>{body}</MDXRenderer>
      {previous === false ? null : (
        <>
          {previous && (
            <Link to={previous.fields.slug}>
              <p>{previous.frontmatter.title}</p>
            </Link>
          )}
        </>
      )}
      {next === false ? null : (
        <>
          {next && (
            <Link to={next.fields.slug}>
              <p>{next.frontmatter.title}</p>
            </Link>
          )}
        </>
      )}
    </Layout>
  );
};

export const query = graphql`
  query PostsBySlug($slug: String!) {
    mdx(fields: { slug: { eq: $slug } }) {
      body
      frontmatter {
        title
        date(formatString: "YYYY MMMM Do")
      }
    }
  }
`;

Code Blocks

Now to add some syntax highlighting for adding code blocks to your blog pages. To do that you’re going to add dependencies for prism-react-renderer and react-live. You’ll also create the files you’re going to need to use:

yarn add prism-react-renderer react-live
touch root-wrapper.js gatsby-ssr.js gatsby-browser.js

You’ll come onto react-live soon. For now, you’re going to get prism-react-render up and running for syntax highlighting for any code you’re going to add to the blog. But before that you’re going to go over the root wrapper concept.

So, to change the rendering of a page element, such as a heading or a code block, you’re going to need to use the MDXProvider. The MDXProvider is a component you can use anywhere higher in the React component tree than the MDX content you want to render.

Gatsby browser and a Gatsby SSR both have wrapRootElement available to them and that is as high up the tree as you can get. So you’re going to create the root-wrapper.js file and add elements you want to override there and import it into both gatsby-browser.js and gatsby-ssr.js so you’re not duplicating code.

Before you go any further I want to add that there is a top quality egghead.io playlist resource for using MDX with Gatsby by Chris Chris Biscardi. There’s a ton of useful information in there on MDX in Gatsby.

Ok, first up you’re going to import the root-wrapper.js file into both gatsby-browser.js and gatsby-ssr.js. Into both code modules paste the following:

import { wrapRootElement as wrap } from './root-wrapper';

export const wrapRootElement = wrap;

Ok, now you can work on the code that will be used in both modules. MDX allows you to control the rendering of page elements in your markdown. MDXProvider is used to give React components to override the markdown page elements.

Quick demonstration, in root-wrapper.js add the following:

import { MDXProvider } from '@mdx-js/react';
import React from 'react';

const components = {
  h2: ({ children }) => (
    <h2 style={{ color: 'rebeccapurple' }}>{children}</h2>
  ),
  'p.inlineCode': props => (
    <code style={{ backgroundColor: 'lightgray' }} {...props} />
  ),
};

export const wrapRootElement = ({ element }) => (
  <MDXProvider components={components}>{element}</MDXProvider>
);

You’re now overriding any h2 in your rendered markdown along with any code blocks (that’s words wrapped in backticks).

Ok, now for the syntax highlighting, create a post with a block of code in it:

mkdir posts/2019-07-01-code-blocks
touch posts/2019-07-01-code-blocks/index.mdx

Paste in some content:

---
title: Code Blocks
date: 2019-07-01
published: true
---

## Yes! Some code!

Here is the `Dump` component!

```jsx
import React from 'react';

const Dump = props => (
  <div
    style={{
      fontSize: 20,
      border: '1px solid #efefef',
      padding: 10,
      background: 'white',
    }}>
    {Object.entries(props).map(([key, val]) => (
      <pre key={key}>
        <strong style={{ color: 'white', background: 'red' }}>
          {key} ?
        </strong>
        {JSON.stringify(val, '', ' ')}
      </pre>
    ))}
  </div>
);

export default Dump;

Go to the [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) GitHub page and copy the example code into `root-wrapper.js` for the `pre` element.

You’re going to copy the provided code for highlighting to validate that it works.

```js
import { MDXProvider } from '@mdx-js/react';
import Highlight, { defaultProps } from 'prism-react-renderer';
import React from 'react';

const components = {
  h2: ({ children }) => (
    <h2 style={{ color: 'rebeccapurple' }}>{children}</h2>
  ),
  'p.inlineCode': props => (
    <code style={{ backgroundColor: 'lightgray' }} {...props} />
  ),
  pre: props => (
    <Highlight
      {...defaultProps}
      code={`
        (function someDemo() {
          var test = "Hello World!";
          console.log(test);
        })();

        return () => <App />;
      `}
      language="jsx">
      {({
        className,
        style,
        tokens,
        getLineProps,
        getTokenProps,
      }) => (
        <pre className={className} style={style}>
          {tokens.map((line, i) => (
            <div {...getLineProps({ line, key: i })}>
              {line.map((token, key) => (
                <span {...getTokenProps({ token, key })} />
              ))}
            </div>
          ))}
        </pre>
      )}
    </Highlight>
  ),
};

export const wrapRootElement = ({ element }) => (
  <MDXProvider components={components}>{element}</MDXProvider>
);

Cool, cool! Now you want to replace the pasted in code example with the props of the child component of the pre component. You can do that with props.children.props.children.trim() ?.

import { MDXProvider } from '@mdx-js/react';
import Highlight, { defaultProps } from 'prism-react-renderer';
import React from 'react';

const components = {
  pre: props => (
    <Highlight
      {...defaultProps}
      code={props.children.props.children.trim()}
      language="jsx">
      {({
        className,
        style,
        tokens,
        getLineProps,
        getTokenProps,
      }) => (
        <pre className={className} style={style}>
          {tokens.map((line, i) => (
            <div {...getLineProps({ line, key: i })}>
              {line.map((token, key) => (
                <span {...getTokenProps({ token, key })} />
              ))}
            </div>
          ))}
        </pre>
      )}
    </Highlight>
  ),
};

export const wrapRootElement = ({ element }) => (
  <MDXProvider components={components}>{element}</MDXProvider>
);

Then to match the language, for now you’re going to add in a matches function to match the language class assigned to the code block.

import { MDXProvider } from '@mdx-js/react';
import Highlight, { defaultProps } from 'prism-react-renderer';
import React from 'react';

const components = {
  h2: ({ children }) => (
    <h2 style={{ color: 'rebeccapurple' }}>{children}</h2>
  ),
  'p.inlineCode': props => (
    <code style={{ backgroundColor: 'lightgray' }} {...props} />
  ),
  pre: props => {
    const className = props.children.props.className || '';
    const matches = className.match(/language-(?<lang>.*)/);
    return (
      <Highlight
        {...defaultProps}
        code={props.children.props.children.trim()}
        language={
          matches && matches.groups && matches.groups.lang
            ? matches.groups.lang
            : ''
        }>
        {({
          className,
          style,
          tokens,
          getLineProps,
          getTokenProps,
        }) => (
          <pre className={className} style={style}>
            {tokens.map((line, i) => (
              <div {...getLineProps({ line, key: i })}>
                {line.map((token, key) => (
                  <span {...getTokenProps({ token, key })} />
                ))}
              </div>
            ))}
          </pre>
        )}
      </Highlight>
    );
  },
};

export const wrapRootElement = ({ element }) => (
  <MDXProvider components={components}>{element}</MDXProvider>
);

prism-react-renderer comes with additional themes over the default theme which is duotoneDark. You’re going to use nightOwl in this example, but feel free to take a look at the other examples if you like.

Import the theme then use it in the props of the Highlight component.

import { MDXProvider } from '@mdx-js/react';
import Highlight, { defaultProps } from 'prism-react-renderer';
import theme from 'prism-react-renderer/themes/nightOwl';
import React from 'react';

const components = {
  pre: props => {
    const className = props.children.props.className || '';
    const matches = className.match(/language-(?<lang>.*)/);

    return (
      <Highlight
        {...defaultProps}
        code={props.children.props.children.trim()}
        language={
          matches && matches.groups && matches.groups.lang
            ? matches.groups.lang
            : ''
        }
        theme={theme}>
        {({
          className,
          style,
          tokens,
          getLineProps,
          getTokenProps,
        }) => (
          <pre className={className} style={style}>
            {tokens.map((line, i) => (
              <div {...getLineProps({ line, key: i })}>
                {line.map((token, key) => (
                  <span {...getTokenProps({ token, key })} />
                ))}
              </div>
            ))}
          </pre>
        )}
      </Highlight>
    );
  },
};

export const wrapRootElement = ({ element }) => (
  <MDXProvider components={components}>{element}</MDXProvider>
);

Ok, now time to abstract this out into its own component so your root-wrapper.js isn’t so crowded.

Make a Code.js component, and move the code from root-wrapper.js into there:

touch src/components/Code.js

Remember this?

Cool, cool! Now you want to replace the pasted in code example with the props of the child component of the pre component. You can do that with props.children.props.children.trim() ?.

If that ☝ makes no real amount of sense for you (I’ve had to read it many, many times myself), don’t worry: now you’re going to dig into that a bit more for the creation of the code block component.

So, for now in the components you’re adding into the MDXProvider, take a look at the props coming into the pre element.

Comment out the code you added earlier and add in a console.log:

pre: props => {
  console.log('=====================');
  console.log(props);
  console.log('=====================');
  return <pre />;
};

Now if you pop open the developer tools of your browser you can see the output.

{children: {…}}
  children:
    $$typeof: Symbol(react.element)
    key: null
    props: {parentName: "pre", className: "language-jsx", originalType: "code", mdxType: "code", children: "import React from 'react'↵↵const Dump = props => (…  </pre>↵    ))}↵  </div>↵)↵↵export default Dump↵"}
    ref: null
    type: ƒ (re....

If you drill into the props of that output you can see the children of those props. If you take a look at the contents of that you will see that it is the code string for your code block. This is what you’re going to be passing into the Code component you’re about to create. Other properties to note here are the className and mdxType.

So, take the code you used earlier for Highlight, everything inside and including the return statement, and paste it into the Code.js module you created earlier.

Highlight requires several props:

<Highlight
  {...defaultProps}
  code={codeString}
  language={language}
  theme={theme}
>

The Code module should look something like this now:

import Highlight, { defaultProps } from 'prism-react-renderer';
import theme from 'prism-react-renderer/themes/nightOwl';
import React from 'react';

const Code = ({ codeString, language }) => {
  return (
    <Highlight
      {...defaultProps}
      code={codeString}
      language={language}
      theme={theme}>
      {({
        className,
        style,
        tokens,
        getLineProps,
        getTokenProps,
      }) => (
        <pre className={className} style={style}>
          {tokens.map((line, i) => (
            <div {...getLineProps({ line, key: i })}>
              {line.map((token, key) => (
                <span {...getTokenProps({ token, key })} />
              ))}
            </div>
          ))}
        </pre>
      )}
    </Highlight>
  );
};

export default Code;

Back to the root-wrapper where you’re going to pass the props needed to the Code component.

The first check you’re going to do is if the mdxType is code then you can get the additional props you need to pass to your Code component.

You’re going to get defaultProps and the theme from prism-react-renderer so all that’s needed is the code and language.

The codeString you can get from the props, and the children by destructuring from the props being passed into the pre element. The language can either be the tag assigned to the meta property of the backticks, like js, jsx or equally empty. So you check for that with some JavaScript and also remove the language- prefix, then pass in the elements {...props}:

pre: ({ children: { props } }) => {
  if (props.mdxType === 'code') {
    return (
      <Code
        codeString={props.children.trim()}
        language={
          props.className && props.className.replace('language-', '')
        }
        {...props}
      />
    );
  }
};

Ok, now you’re back to where you were before abstracting out the Highlight component to it’s own module. Add some additional styles with styled-components and replace the pre with a styled Pre. You can also add in some line numbers with a styled span and style that as well.

import Highlight, { defaultProps } from 'prism-react-renderer';
import theme from 'prism-react-renderer/themes/nightOwl';
import React from 'react';
import styled from 'styled-components';

export const Pre = styled.pre`
  text-align: left;
  margin: 1em 0;
  padding: 0.5em;
  overflow-x: auto;
  border-radius: 3px;

  & .token-line {
    line-height: 1.3em;
    height: 1.3em;
  }
  font-family: 'Courier New', Courier, monospace;
`;

export const LineNo = styled.span`
  display: inline-block;
  width: 2em;
  user-select: none;
  opacity: 0.3;
`;

const Code = ({ codeString, language, ...props }) => {
  return (
    <Highlight
      {...defaultProps}
      code={codeString}
      language={language}
      theme={theme}>
      {({
        className,
        style,
        tokens,
        getLineProps,
        getTokenProps,
      }) => (
        <Pre className={className} style={style}>
          {tokens.map((line, i) => (
            <div {...getLineProps({ line, key: i })}>
              <LineNo>{i + 1}</LineNo>
              {line.map((token, key) => (
                <span {...getTokenProps({ token, key })} />
              ))}
            </div>
          ))}
        </Pre>
      )}
    </Highlight>
  );
};

export default Code;

Copy code to clipboard

What if you had some way of getting that props code string into the clipboard?

I had a look around and found the majority of the components available for this sort of thing expected an input until this in the Gatsby source code. Which is creating the input for you ?

So, create a utils directory and the copy-to-clipboard.js file and add in the code from the Gatsby source code.

mkdir src/utils
touch src/utils/copy-to-clipboard.js

// https://github.com/gatsbyjs/gatsby/blob/master/www/src/utils/copy-to-clipboard.js

export const copyToClipboard = str => {
  const clipboard = window.navigator.clipboard;
  /*
   * fallback to older browsers (including Safari)
   * if clipboard API not supported
   */
  if (!clipboard || typeof clipboard.writeText !== `function`) {
    const textarea = document.createElement(`textarea`);
    textarea.value = str;
    textarea.setAttribute(`readonly`, true);
    textarea.setAttribute(`contenteditable`, true);
    textarea.style.position = `absolute`;
    textarea.style.left = `-9999px`;
    document.body.appendChild(textarea);
    textarea.select();
    const range = document.createRange();
    const sel = window.getSelection();
    sel.removeAllRanges();
    sel.addRange(range);
    textarea.setSelectionRange(0, textarea.value.length);
    document.execCommand(`copy`);
    document.body.removeChild(textarea);

    return Promise.resolve(true);
  }

  return clipboard.writeText(str);
};

Now you’re going to want a way to trigger copying the code to the clipboard.

Let's create a styled button. But first add a position: relative; to the Pre component which will let us position the styled button:

const CopyCode = styled.button`
  position: absolute;
  right: 0.25rem;
  border: 0;
  border-radius: 3px;
  margin: 0.25em;
  opacity: 0.3;
  &:hover {
    opacity: 1;
  }
`;

And now you need to use the copyToClipboard function in the onClick of the button:

import Highlight, { defaultProps } from 'prism-react-renderer';
import theme from 'prism-react-renderer/themes/nightOwl';
import React from 'react';
import styled from 'styled-components';
import { copyToClipboard } from '../utils/copy-to-clipboard';

export const Pre = styled.pre`
  text-align: left;
  margin: 1rem 0;
  padding: 0.5rem;
  overflow-x: auto;
  border-radius: 3px;

  & .token-line {
    line-height: 1.3rem;
    height: 1.3rem;
  }
  font-family: 'Courier New', Courier, monospace;
  position: relative;
`;

export const LineNo = styled.span`
  display: inline-block;
  width: 2rem;
  user-select: none;
  opacity: 0.3;
`;

const CopyCode = styled.button`
  position: absolute;
  right: 0.25rem;
  border: 0;
  border-radius: 3px;
  margin: 0.25em;
  opacity: 0.3;
  &:hover {
    opacity: 1;
  }
`;

const Code = ({ codeString, language }) => {
  const handleClick = () => {
    copyToClipboard(codeString);
  };

  return (
    <Highlight
      {...defaultProps}
      code={codeString}
      language={language}
      theme={theme}>
      {({
        className,
        style,
        tokens,
        getLineProps,
        getTokenProps,
      }) => (
        <Pre className={className} style={style}>
          <CopyCode onClick={handleClick}>Copy</CopyCode>
          {tokens.map((line, i) => (
            <div {...getLineProps({ line, key: i })}>
              <LineNo>{i + 1}</LineNo>
              {line.map((token, key) => (
                <span {...getTokenProps({ token, key })} />
              ))}
            </div>
          ))}
        </Pre>
      )}
    </Highlight>
  );
};

export default Code;

React live

So with React Live you need to add two snippets to your Code.js component.

You’re going to import the components:

import {
  LiveEditor,
  LiveError,
  LivePreview,
  LiveProvider,
} from 'react-live';

Then you’re going to check if react-live has been added to the language tag on your mdx file via the props:

if (props['react-live']) {
  return (
    <LiveProvider code={codeString} noInline={true} theme={theme}>
      <LiveEditor />
      <LiveError />
      <LivePreview />
    </LiveProvider>
  );
}

Here’s the full component:

import Highlight, { defaultProps } from 'prism-react-renderer';
import theme from 'prism-react-renderer/themes/nightOwl';
import React from 'react';
import {
  LiveEditor,
  LiveError,
  LivePreview,
  LiveProvider,
} from 'react-live';
import styled from 'styled-components';
import { copyToClipboard } from '../../utils/copy-to-clipboard';

const Pre = styled.pre`
  position: relative;
  text-align: left;
  margin: 1em 0;
  padding: 0.5em;
  overflow-x: auto;
  border-radius: 3px;

  & .token-lline {
    line-height: 1.3em;
    height: 1.3em;
  }
  font-family: 'Courier New', Courier, monospace;
`;

const LineNo = styled.span`
  display: inline-block;
  width: 2em;
  user-select: none;
  opacity: 0.3;
`;

const CopyCode = styled.button`
  position: absolute;
  right: 0.25rem;
  border: 0;
  border-radius: 3px;
  margin: 0.25em;
  opacity: 0.3;
  &:hover {
    opacity: 1;
  }
`;

export const Code = ({ codeString, language, ...props }) => {
  if (props['react-live']) {
    return (
      <LiveProvider code={codeString} noInline={true} theme={theme}>
        <LiveEditor />
        <LiveError />
        <LivePreview />
      </LiveProvider>
    );
  }

  const handleClick = () => {
    copyToClipboard(codeString);
  };

  return (
    <Highlight
      {...defaultProps}
      code={codeString}
      language={language}
      theme={theme}>
      {({
        className,
        style,
        tokens,
        getLineProps,
        getTokenProps,
      }) => (
        <Pre className={className} style={style}>
          <CopyCode onClick={handleClick}>Copy</CopyCode>
          {tokens.map((line, i) => (
            <div {...getLineProps({ line, key: i })}>
              <LineNo>{i + 1}</LineNo>
              {line.map((token, key) => (
                <span {...getTokenProps({ token, key })} />
              ))}
            </div>
          ))}
        </Pre>
      )}
    </Highlight>
  );
};

To test this, add react-live next to the language on your Dump component, so you have added to the blog post you made:

```jsx react-live

Now you can edit the code directly. Try changing a few things like this:

const Dump = props => (
  <div
    style={{
      fontSize: 20,
      border: '1px solid #efefef',
      padding: 10,
      background: 'white',
    }}>
    {Object.entries(props).map(([key, val]) => (
      <pre key={key}>
        <strong style={{ color: 'white', background: 'red' }}>
          {key} ?
        </strong>
        {JSON.stringify(val, '', ' ')}
      </pre>
    ))}
  </div>
);

render(<Dump props={['One', 'Two', 'Three', 'Four']} />);

Cover Image

Now to add a cover image to go with each post, you’ll need to install a couple of packages to manage images in Gatsby.

install:

yarn add gatsby-transformer-sharp gatsby-plugin-sharp gatsby-remark-images gatsby-image

Now you should config gatsby-config.js to include the newly added packages. Remember to add gatsby-remark-images to gatsby-plugin-mdx as both a gatsbyRemarkPlugins option and as a plugins option.

config:

module.exports = {
  siteMetadata: siteMetadata,
  plugins: [
    `gatsby-plugin-styled-components`,
    `gatsby-transformer-sharp`,
    `gatsby-plugin-sharp`,
    {
      resolve: `gatsby-plugin-mdx`,
      options: {
        extensions: [`.mdx`, `.md`],
        gatsbyRemarkPlugins: [
          {
            resolve: `gatsby-remark-images`,
            options: {
              maxWidth: 590,
            },
          },
        ],
        plugins: [
          {
            resolve: `gatsby-remark-images`,
            options: {
              maxWidth: 590,
            },
          },
        ],
      },
    },
    {
      resolve: `gatsby-source-filesystem`,
      options: { path: `${__dirname}/posts`, name: `posts` },
    },
  ],
};

Add image to index query in src/pages.index.js:

cover {
  publicURL
  childImageSharp {
    sizes(
      maxWidth: 2000
      traceSVG: { color: "#639" }
    ) {
      ...GatsbyImageSharpSizes_tracedSVG
    }
  }
}

Fix up the date in the query too:

date(formatString: "YYYY MMMM Do")

This will show the date as full year, full month and the day as a ‘st’, ‘nd’, ‘rd’ and ‘th’. So if today’s date were 1970/01/01 it would read 1970 January 1st.

Add gatsby-image use that in a styled component:

const Image = styled(Img)`
  border-radius: 5px;
`;

Add some JavaScript to determine if there’s anything to render:

{
  !!frontmatter.cover ? (
    <Image sizes={frontmatter.cover.childImageSharp.sizes} />
  ) : null;
}

Here’s what the full module should look like now:

import { Link } from 'gatsby';
import Img from 'gatsby-image';
import React from 'react';
import styled from 'styled-components';
import { Layout } from '../components/Layout';

const IndexWrapper = styled.main``;

const PostWrapper = styled.div``;

const Image = styled(Img)`
  border-radius: 5px;
`;

export default ({ data }) => {
  return (
    <Layout>
      <IndexWrapper>
        {/* <Dump data={data}></Dump> */}
        {data.allMdx.nodes.map(
          ({ id, excerpt, frontmatter, fields }) => (
            <PostWrapper key={id}>
              <Link to={fields.slug}>
                {!!frontmatter.cover ? (
                  <Image
                    sizes={frontmatter.cover.childImageSharp.sizes}
                  />
                ) : null}
                <h1>{frontmatter.title}</h1>
                <p>{frontmatter.date}</p>
                <p>{excerpt}</p>
              </Link>
            </PostWrapper>
          )
        )}
      </IndexWrapper>
    </Layout>
  );
};

export const query = graphql`
  query SITE_INDEX_QUERY {
    allMdx(
      sort: { fields: [frontmatter___date], order: DESC }
      filter: { frontmatter: { published: { eq: true } } }
    ) {
      nodes {
        id
        excerpt(pruneLength: 250)
        frontmatter {
          title
          date(formatString: "YYYY MMMM Do")
          cover {
            publicURL
            childImageSharp {
              sizes(maxWidth: 2000, traceSVG: { color: "#639" }) {
                ...GatsbyImageSharpSizes_tracedSVG
              }
            }
          }
        }
        fields {
          slug
        }
      }
    }
  }
`;

Additional resources:

• this helped me for my own blog: https://juliangaramendy.dev/custom-open-graph-images-in-gatsby-blog/
• and the Gatsby docs: https://www.gatsbyjs.org/docs/working-with-images/

Creating an SEO component with React Helmet

There’s a Gatsby github PR on seo with some great notes from Andrew Welch on SEO and a link to a presentation he did back in 2017.

Crafting Modern SEO with Andrew Welch:

Crafting Modern SEO with Andrew Welch:

In the following comments of that PR, Gatsby’s LekoArts details his own implementation which I have implemented as a React component. You’re going to be configuring that now in this how-to.

First up, install and configure gatsby-plugin-react-helmet. This is used for server rendering data added with React Helmet.

yarn add gatsby-plugin-react-helmet

You’ll need to add the plugin to your gatsby-config.js. If you haven’t done so already now is a good time to also configure the gatsby-plugin-styled-components as well.

Configure SEO Component for Homepage

To visualise the data you’re going to need to get into the SEO component use the Dump component to begin with to validate the data.

The majority of the information needed for src/pages/index.js can be first added to the gatsby-config.js, siteMetadata object then queried with the useSiteMetadata hook. Some of the data added here can then be used in src/templates/blogPostTemplate.js – more on that in the next section.

For now add the following:

const siteMetadata = {
  title: `The Localhost Blog`,
  description: `This is my coding blog where I write about my coding journey.`,
  image: `/default-site-image.jpg`,
  siteUrl: `https://thelocalhost.blog`,
  siteLanguage: `en-GB`,
  siteLocale: `en_gb`,
  twitterUsername: `@spences10`,
  authorName: `Scott Spence`,
}

module.exports = {
  siteMetadata: siteMetadata,
  plugins: [
    ...

You don’t have to abstract out the siteMetadata into its own component here. It’s only a suggestion on how to manage it.

The image is going to be the default image for your site. You should create a static folder at the root of the project and add in an image you want to be shown when the homepage of your site is shared on social media.

For siteUrl at this stage it doesn’t necessarily have to be valid. You can add a dummy url for now and change it later.

The siteLanguage is your language of choice for the site. Take a look at w3 language tags for more info.

Facebook OpenGraph is the only place the siteLocale is used and it is different from language tags.

Add your twitterUsername and your authorName.

Update the useSiteMetadata hook now to reflect the newly added properties:

import { graphql, useStaticQuery } from 'gatsby';

export const useSiteMetadata = () => {
  const { site } = useStaticQuery(
    graphql`
      query SITE_METADATA_QUERY {
        site {
          siteMetadata {
            description
            title
            image
            siteUrl
            siteLanguage
            siteLocale
            twitterUsername
            authorName
          }
        }
      }
    `
  );
  return site.siteMetadata;
};

Begin with importing the Dump component in src/pages/index.js then plug in the props as they are detailed in the docs of the react-seo-component.

import Dump from '../components/Dump'
import { useSiteMetadata } from '../hooks/useSiteMetadata'

export default ({ data }) => {
  const {
    description,
    title,
    image,
    siteUrl,
    siteLanguage,
    siteLocale,
    twitterUsername,
  } = useSiteMetadata()
  return (
    <Layout>
      <Dump
        title={title}
        description={description}
        image={`${siteUrl}${image}`}
        pathname={siteUrl}
        siteLanguage={siteLanguage}
        siteLocale={siteLocale}
        twitterUsername={twitterUsername}
      />
      <IndexWrapper>
        {data.allMdx.nodes.map(
          ...

Check that all the props are displaying valid values. Then you can swap out the Dump component with the SEO component.

The complete src/pages/index.js should look like this now:

import { graphql, Link } from 'gatsby';
import Img from 'gatsby-image';
import React from 'react';
import SEO from 'react-seo-component';
import styled from 'styled-components';
import { Layout } from '../components/Layout';
import { useSiteMetadata } from '../hooks/useSiteMetadata';

const IndexWrapper = styled.main``;

const PostWrapper = styled.div``;

const Image = styled(Img)`
  border-radius: 5px;
`;

export default ({ data }) => {
  const {
    description,
    title,
    image,
    siteUrl,
    siteLanguage,
    siteLocale,
    twitterUsername,
  } = useSiteMetadata();
  return (
    <Layout>
      <SEO
        title={title}
        description={description || `nothin’`}
        image={`${siteUrl}${image}`}
        pathname={siteUrl}
        siteLanguage={siteLanguage}
        siteLocale={siteLocale}
        twitterUsername={twitterUsername}
      />
      <IndexWrapper>
        {/* <Dump data={data}></Dump> */}
        {data.allMdx.nodes.map(
          ({ id, excerpt, frontmatter, fields }) => (
            <PostWrapper key={id}>
              <Link to={fields.slug}>
                {!!frontmatter.cover ? (
                  <Image
                    sizes={frontmatter.cover.childImageSharp.sizes}
                  />
                ) : null}
                <h1>{frontmatter.title}</h1>
                <p>{frontmatter.date}</p>
                <p>{excerpt}</p>
              </Link>
            </PostWrapper>
          )
        )}
      </IndexWrapper>
    </Layout>
  );
};

export const query = graphql`
  query SITE_INDEX_QUERY {
    allMdx(
      sort: { fields: [frontmatter___date], order: DESC }
      filter: { frontmatter: { published: { eq: true } } }
    ) {
      nodes {
        id
        excerpt(pruneLength: 250)
        frontmatter {
          title
          date(formatString: "YYYY MMMM Do")
          cover {
            publicURL
            childImageSharp {
              sizes(maxWidth: 2000, traceSVG: { color: "#639" }) {
                ...GatsbyImageSharpSizes_tracedSVG
              }
            }
          }
        }
        fields {
          slug
        }
      }
    }
  }
`;

Configure SEO Component for Blog Posts

This will be the same approach as with the homepage. Import the Dump component and validate the props before swapping out the Dump component with the SEO component.

import Dump from '../components/Dump'
import { useSiteMetadata } from '../hooks/useSiteMetadata'

export default ({ data, pageContext }) => {
  const {
    image,
    siteUrl,
    siteLanguage,
    siteLocale,
    twitterUsername,
    authorName,
  } = useSiteMetadata()
  const { frontmatter, body, fields, excerpt } = data.mdx
  const { title, date, cover } = frontmatter
  const { previous, next } = pageContext
  return (
    <Layout>
      <Dump
        title={title}
        description={excerpt}
        image={
          cover === null
            ? `${siteUrl}${image}`
            : `${siteUrl}${cover.publicURL}`
        }
        pathname={`${siteUrl}${fields.slug}`}
        siteLanguage={siteLanguage}
        siteLocale={siteLocale}
        twitterUsername={twitterUsername}
        author={authorName}
        article={true}
        publishedDate={date}
        modifiedDate={new Date(Date.now()).toISOString()}
      />
      <h1>{frontmatter.title}</h1>
      ...

Add fields.slug, excerpt and cover.publicURL to the PostsBySlug query and destructure them from data.mdx and frontmatter, respectively.

For the image you’ll need to do some logic as to whether the cover exists and default to the default site image if it doesn’t.

The complete src/templates/blogPostTemplate.js should look like this now:

import { graphql, Link } from 'gatsby';
import { MDXRenderer } from 'gatsby-plugin-mdx';
import React from 'react';
import SEO from 'react-seo-component';
import { Layout } from '../components/Layout';
import { useSiteMetadata } from '../hooks/useSiteMetadata';

export default ({ data, pageContext }) => {
  const {
    image,
    siteUrl,
    siteLanguage,
    siteLocale,
    twitterUsername,
    authorName,
  } = useSiteMetadata();
  const { frontmatter, body, fields, excerpt } = data.mdx;
  const { title, date, cover } = frontmatter;
  const { previous, next } = pageContext;
  return (
    <Layout>
      <SEO
        title={title}
        description={excerpt}
        image={
          cover === null
            ? `${siteUrl}${image}`
            : `${siteUrl}${cover.publicURL}`
        }
        pathname={`${siteUrl}${fields.slug}`}
        siteLanguage={siteLanguage}
        siteLocale={siteLocale}
        twitterUsername={twitterUsername}
        author={authorName}
        article={true}
        publishedDate={date}
        modifiedDate={new Date(Date.now()).toISOString()}
      />
      <h1>{frontmatter.title}</h1>
      <p>{frontmatter.date}</p>
      <MDXRenderer>{body}</MDXRenderer>
      {previous === false ? null : (
        <>
          {previous && (
            <Link to={previous.fields.slug}>
              <p>{previous.frontmatter.title}</p>
            </Link>
          )}
        </>
      )}
      {next === false ? null : (
        <>
          {next && (
            <Link to={next.fields.slug}>
              <p>{next.frontmatter.title}</p>
            </Link>
          )}
        </>
      )}
    </Layout>
  );
};

export const query = graphql`
  query PostBySlug($slug: String!) {
    mdx(fields: { slug: { eq: $slug } }) {
      frontmatter {
        title
        date(formatString: "YYYY MMMM Do")
        cover {
          publicURL
        }
      }
      body
      excerpt
      fields {
        slug
      }
    }
  }
`;

Build Site and Validate Meta Tags

Add in the build script to package.json and also a script for serving the built site locally.

"scripts": {
  "dev": "gatsby develop -p 9988 -o",
  "build": "gatsby build",
  "serve": "gatsby serve -p 9500 -o"
},

Now it’s time to run:

yarn build && yarn serve

This will build the site and open a browser tab so you can see the site as it will appear when it is on the internet. Validate meta tags have been added to the build by selecting “View page source” (Crtl+u in Windows and Linux) on the page. You can do a Ctrl+f to find them.

Adding the Project to GitHub

Add your code to GitHub by either selecting the plus (+) icon next to your avatar on GitHub or by going directly to https://github.com/new

Name your repository and click create repository. Then you will be given the instructions to link your local code to the repository you created via the command line.

How you authenticate with GitHub will depend on what the command looks like.

Some good resources for authenticating with GitHub via SSH are Kent Dodds Egghead.io video and also a how-to on CheatSheets.xyz.

Deploy to Netlify

To deploy your site to Netlify, if you haven’t done so already, you’ll need to add the GitHub integration to your GitHub profile. If you got to app.netlify.com the wizard will walk you through the process.

From here you can add your built site’s public folder drag ‘n drop style directly to the Netlify global CDNs.

You, however, are going to load your site via the Netlify CLI! In your terminal, if you haven’t already got the CLI installed, run:

yarn global add netlify-cli

Then once the CLI is installed:

# authenticate via the CLI
netlify login
# initialise the site
netlify init

Enter the details for your team: the site name is optional, the build command will be yarn build, and directory to deploy is public.

You will be prompted to commit the changes and push them to GitHub (with git push). Once you have done that your site will be published and ready for all to see!

Validate Metadata with Heymeta

Last up is validating the metadata for the OpenGraph fields. To do that you’ll need to make sure that the siteUrl reflects what you have in your Netlify dashboard.

If you needed to change the url you’ll need to commit and push the changes to GitHub again.

Once your site is built with a valid url you can then test the homepage and a blog page for the correct meta tags with heymeta.com.

OpenGraph checking tools:

• https://www.heymeta.com/
• https://opengraphcheck.com/
• https://cards-dev.twitter.com/validator
• https://developers.facebook.com/tools/debug/sharing
• https://www.linkedin.com/post-inspector/

Additional resources:

• The Essential Meta Tags for Social Media

Example Code for this Blog can be found here:

Or here.

Thanks for reading ?

That’s all folks! If there is anything I have missed, or if there is a better way to do something, then please let me know.

Follow me on Twitter or Ask Me Anything on GitHub.

You can read other articles like this on my digital garden.

Not that AAA map under your car seat

Maps have been around for thousands of years, but they’ve become more complex and powerful within the last couple decades simply due to the fact that computers exist. This has enabled the creation of products we use every day - like Google Maps that help us get home from work and avoid traffic, or weather maps that allow us to check real time radar images. Taking that a step further, scientists use maps every day using data from satellite imagery to try to get a better understanding of our humble planet.

This sounds hard…

Building maps

Plot twist, it’s not hard!

Final Space — What a twist!

At least it’s not hard to get started. Thankfully, the parts that are the hardest are already built into libraries that can easily be tapped into with JavaScript.

Enter Leaflet…

Mapping Libraries

There are a few libraries in the mapping space right now (like OpenLayers), but we like Leaflet.

To get started with Leaflet, first include the library’s assets on your page. Next, mount the application onto a root element within the DOM with some basic settings. You can kind of think of it like how React mounts to a DOM node, but Leaflet itself doesn’t use React. Once initialized, Leaflet allows you to start utilizing it’s API to project a basemap, add layers, tiles on those layers, and even start to draw on it.

Basemap? Layers? Tiles?

To get the basic gist, think of a cake. Traditionally, cakes have different layers, some on the bottom, some on the top, some might just cover one side with icing. Your map layers function similarly. The bottom layer, which is your foundation, will be your “basemap”. Below, we’re seeing a snapshot of the 2018 California Camp Fire wildfires on top of NASA’s MODIS Aqua satellite imagery.

MODIS Aqua – California “Campfire” Wildfires

Now, to get a basemap, we need the imagery to produce it, which is where tiles come in. A tile is a single image block that makes up your group of tiles that represent your layer.

_MODIS Aqua single tile and URI scheme – Tile Link_

Your tiles are really just a simple image, but alongside the rest, coordinated by geographic positions and zoom levels, make up what you see when you’re looking at a web map like the basemap shown above. The goal of including these smaller individual pieces rather than 1 huge image is that between dealing with the entire globe, the different zoom levels available, and the resolutions available beyond that, we’re talking about gigabytes upon gigabytes of image assets that just wouldn’t be reliable or realistic to serve as a whole.

Once you’ve established your basemap, you can then overlay additional layers using more imagery, vector tiles, or datapoints that get transformed to layers. In the screenshot below, we’re zoomed in beyond the highest resolution of our basemap. Notice though the imagery on the left, is an individual overlay tile from Digital Globe that provides us with a higher resolution of part of the area surrounding the fire zone.

MODIS Aqua with tile overlay from Digital Globe

Another example on top of that is adding points representing fires collected from NASA’s VIIRS imagery.

MODIS Aqua with VIIRS fire datapoint layer

This allows us to have the context of the basemap as well as being able to cast any type of data we’d like to better understand its effects.

In addition to the VIIRS data, there are many sources of imagery, vector tiles, and datasets published by governments and municipalities that you can use to help build interesting maps and data visualizations. NASA is one good source of these types of assets, but many commercial providers release open access to disaster datasets that help others build solutions around relief efforts.

What’s this about drawing stuff?

Usually when people use maps, they want to look at points of interest. Drawing gives us the ability to frame those areas of interest with different drawing tools such as creating a rectangle using a bounding box tool or drawing a circle. These are simple shapes, but those shapes represent a geographic space that can then be used to gather data about that area.

Rectangular bounding box around Alexandria, VA

React ❤️ Leaflet

Leaflet in itself gives you a lot to work with, but there’s still a lot of manual effort that goes along with it. If you’re used to building a React app, you’re probably not as used to building an entire UI using nothing but APIs based on the browser’s window, and this is where React Leaflet shines.

React Leaflet is a React library that takes the map building and bundles it into intuitive components that represents those parts of the map. Consider the above, where we talked about your basemap and layers to along with it, you might see it looking something along the lines of:

Pseudo map component code

While you would probably expect that it’s not as flexible as utilizing the Leaflet APIs directly, this completely opens up one’s world to being able to easily spin up simple map solutions in an intuitive way without all the effort. After all, at that point, you’re spinning up a React app which you’re probably already familiar with.

Taking it a bit further with Gatsby

You want it easier, you say? You want me to build the map for you, you say? Well, you’re in luck! First, let’s give a brief introduction to another tool.

For the unfamiliar, Gatsby is a javascript framework that allows developers to easily spin up full, completely working React applications in a matter of minutes. They have all the nuts and bolts in place and moved out of the way to let you do what you do best: focus on the important parts of your application.

The beautiful part about Gatsby is that it supports extensions of their default installation which they call Starters. What better way to make it easier for people to spin up maps than to create a Gatsby Starter?

Gatsby Starter Leaflet

Combining the ease of a Gatsby Starter and the flexibility of Leaflet, we have Gatsby Starter Leaflet. This simple tool allows you to scaffold a new React application running Leaflet along side React Leaflet in the matter of seconds (or minutes depending on your computer).

Starting page for Gatsby Starter Leaflet

With a few basic commands, including installing your dependencies, you have an app that’s ready for you to start building on top of to create maps that will save the world. Even better, it includes some out of the box integrations like OpenStreetMap and an easy to setup map service configuration to the foundational React Leaflet component APIs that allow you to easily get product and have more flexibility to create smarter Mapping apps.

There’s gotta be some downsides…

No library or framework isn’t without its downsides. The more complicated your mapping application gets, the more pain points you run into. Here are a few from our experience that might help you settle in.

Bob Kelso — Scrubs

Leaflet — from the Window to React

Trying to manage state and the lifecycle between your Leaflet map and your React components can prove to be tricky. Trying to constantly maintain and update your component using props will immediately start to create issues between stale map state or memory leaks due to maps not properly unmounting when the component does.

Advice: mount your map with React, interact with it using the native Leaflet API. Once your map is rendered and settled down, you can use Leaflet to fly your user around the world and draw on your map without running into the state issues of multiple component renders.

Limited Use of Public Tiles

While there are a few tiling services available that allow you to easily plug in and create a basemap, not all of these are actually intended to be heavily used. Take for instance OpenStreetMap, while you may be able to play around and develop basic solutions on their public endpoint, heavy use will be throttled and potentially blocked without explicit permission from those who maintain their servers.

Advice: when you’re just starting out playing around, you shouldn’t have to worry too much. Worst case the maps will be a little slow to download. As your application starts to get more traffic, you’ll want to look into spinning up your own tiling service or paying for an out of the box solution such as Mapbox.

Get mapping!

It has never been easier to build a map-based web application. There is enough tooling, documentation, and public data available to help you get off the ground and start building maps to explore our world in the time it takes you to set up a blog or static website. So what are you waiting for?

Go explore with Dora!

Originally published at https://www.element84.com/blog/mapping-with-leaflet-and-react

So what is linting?

lint, or a linter, is a tool that analyzes source code to flag programming errors, bugs, stylistic errors, and suspicious constructs. https://en.wikipedia.org/wiki/Lint(software)

Simply put, a linter is a tool that programmatically scans your code with the goal of finding issues that can lead to bugs or inconsistencies with code health and style. Some can even help fix them for you!

Michael Scott - Tell me more

Take for instance, the following example:

const test = 'I am a test';
console.log(`Test: ${test}`);
const test = 'Another one.';

We’re declaring the constant test twice, which our javascript engine won’t be happy about. With the proper linter settings and watch configuration, instead of getting caught later as an error when the code runs, you’ll immediately get an error through your linter running in the background:

  10:9  error  Parsing error: Identifier 'test' has already been declared

   8 |   const test = 'I am a test';
   9 |   console.log(`Test: ${2}`);
> 10 |   const test = 'Another one.';
     |         ^

It might be pretty obvious that you have 2 of the same const declarations given this is only 3 lines, but in a more complex application, this can save tons of time having to hunt down a pesky bug that’s not always obvious.

What all can linting help with?

Lots of things, including but not limited to:

• Flagging bugs in your code from syntax errors
• Giving you warnings when code may not be intuitive
• Providing suggestions for common best practices
• Keeping track of TODO’s and FIXME’s
• Keeping a consistent code style

Most things you can think of probably already exist in one form or another, and if not, you can even create custom rules that fit your needs!

How is this actually helping or why should I care?

Probably the biggest overlying theme of the list above is the fact that these issues will be called out immediately. No longer will these issues creep up on you in the middle of running your app or give someone anxiety during a code review. No longer will you and your reviewer endlessly fight passive aggressively through the comments about whether or not to include a semicolon at the end of JS statements (you should ?).

Grandma looking for a semicolon

All of those moments that stop you from being productive because of a silly syntax error or the micro-interactions you and your teammates have during a review take time. They add up and end up taking away the time you can spend fixing another bug or developing the next great feature of your product.

So how do I actually get started?

Even though there are linters for most, if not all, other mainstream languages, for the purpose of this post, I’m going to focus on Javascript. The same principles apply, but the tooling may be a bit different.

I’m going to run through how you can get set up for basic linting in a React app. You can easily follow along by spinning up your own React app or using my Gatsby starter: https://github.com/colbyfayock/gatsby-starter-sass#starting-from-scratch

Your Linter

To get started, we first need a linter. Probably the most popular in the Javascript world is ESLint. Your linter will actually be the engine for defining rules and parsing your files to test against. ESLint is available as an npm package by itself and once installed, out of the box it allows you to set up a basic configuration file and hit the ground running with some command line tools.

Let’s first add our ESLint dependency:

yarn add eslint -D

We’re installing this as a devDependency (hence the -D flag), because this isn’t something our application needs to run. After it’s successfully installed, let’s add it to our package.json as a script:

...
"scripts": {
  ...
  "lint": "eslint .  --ext .js"
  ...
},
...

In the above, we’re running our linter on the entire project directory on any file that has an extension of .js. If you're working with a large project with many file types, maybe even some you don't want linted, you can change that flag or be more specific with other options.

To support ESLint, we’ll need to do one more thing. Let’s add a file at the root of our project (probably where your package.json is) called .eslintrc.js and make the contents of the file simply:

module.exports = {};

Once you’re ready, you can run yarn lint and… get an error.

Lint results - Import errors

This is okay, and expected in our project, so let’s move on.

Your Parser

A common tool in the chain for Javascript developers is Babel, which allows you to write code with features that may not be supported in all browsers, such as using arrow functions, that are available in ES6, and other conventions like importing files via import.

The code you write may already run through Babel to work in a browser, but that doesn’t apply to ESLint by default, so ESLint allows you to specify a parser that allows the linting processing to look at the same code as your browser sees. In this case we’ll want to use Babel’s ESLint parser that’s made available to us.

To set that up, we’ll want to first install our dependency:

yarn add babel-eslint -D

Typically if you're using babel-eslint you'll want to make sure babel is installed next to it, but in our case, Gatsby already uses babel, so we don’t necessarily need to add it. After that’s set up, we’ll want to update our .eslintrc.js config file with some new options:

module.exports = {
    "env": {
        "browser": true,
        "node": true,
        "es6": true
    },
    "parser": "babel-eslint"
};

Here, we’re letting ESLint know that our environment will be run in node (Gatsby’s precompiling), inside the browser (the app), and it will use ES6. This helps ESLint know how to run your code. Additionally, we want to set up our parser to be babel-eslint.

Once we’re ready to go, run yarn lint again and… well nothing really happened.

Lint results - Nothing happened

This is still expected, as we don’t have any rules set up!

Plugins for your code

Writing a React app? The Babel parser may help you transform your code, but you might have a hard time being productive, as ESLint needs to understand how it should work to lint your React files.

Part of the beauty of ESLint is that it allows you to configure plugins that have the opportunity to create and set rules for you. Luckily, along with our Babel parser above that does some of the heavy lifting, we have a React plugin available that does just that and takes care of linting the JSX for us.

Let’s first install our dependency:

yarn add eslint-plugin-react -D

Further, let’s update our .eslintrc.js file again:

module.exports = {
    "settings": {
        "react": {
            "version": "detect"
        }
    },
    "env": {
        "browser": true,
        "node": true,
        "es6": true
    },
    "plugins": [
        "react"
    ],
    "parser": "babel-eslint"
};

What we’re adding here is a setting that automatically detects what React version you’re using, which is helpful to let your linting get parsed properly, and then set up our react plugin that we installed above.

For one last final time, we will run our lint script and get nothing:

Lint results - Nothing happened

Rules defined by others’s opinions

If you’re not really sure where to get started or just want to quickly get up and running, it’s recommend that you enable ESLint’s own recommended rules. Let’s add this to our .eslintrc.js config file:

module.exports = {
    "settings": {
        "react": {
            "version": "detect"
        }
    },
    "env": {
        "browser": true,
        "node": true,
        "es6": true
    },
    "plugins": [
        "react"
    ],
    "extends": [
        "eslint:recommended"
    ],
    "parser": "babel-eslint"
};

And let’s run our yarn lint.

Woah! This will immediately give you a lot errors, it seems like something’s wrong.

Lint results - React errors

Since we’re running a React app, we also want to make sure our linter understands the rules it should follow, so let’s also add our React plugin to the .eslintrc.js config setup:

    "extends": [
        "eslint:recommended",
        "plugin:react/recommended"
    ],

Now if you run yarn lint, you get something a little more logical.

Lint results - Normal errors

If you’re following along, it looks like our starter app had a misplaced semicolon and a missing prop in our propTypes validation for Layout.js. Writing this helped me fix my own repo! ?

Going further, if those don’t seem to fit your needs, lots of developers and teams have published their own configurations that ESLint allows you to easily tap into.

Some popular ones include:

• Airbnb’s config
• Semistandard
• Google’s JS Style Guide

Not happy with the options available? You can even create and publish your own to either layer on top of others as a starting point or give it a go from scratch.

Let it do the work (most of it)

You don’t think I’m going to make you fix all of those thing yourself do you? Well, you may have to fix some, but let’s try to get ESLint to fix some of it for us.

If you noticed after we ran the command above, ESLint gave us an extra message:

Lint results - Option to fix

So let’s give it a try! Let’s run:

yarn lint --fix

And what do you know, it now only gives us 1 linting error.

Lint results - 1 error

Turns out ESLint was able to fix our semicolon issue automatically, but we’ll still have to add pageName to our Layout’s propTypes manually, not too much of a lift.

Running one more time and finally nothing again! But this time because everything's looking good.

Lint results - No errors

Go forth and write messy code!

Bruce Almighty - Typing

Kidding ? The good news here, is now you can easily take a look at the general health of your codebase as well as hopefully fix most of it automatically. This is going to save a lot of headaches as you work with others on your team, and generally, it’s nice to have all of your code neat and tidy.

This post is just getting started. ESLint is a wide open book with tons of plugins and rules, and it’s not the only linting tool in the game. Play around and find what fits best for you and your team. The little time spent configuring it to your app will save you lots more time in the long run.

Other linting tools to check out

• JSHint: an alternative to ESLint
• Stylelint: a linting tool for CSS and CSS-like syntaxes like Sass
• Awesome ESLint: a simple list of awesome configs, parsers, plugins, and other tools to boost your ESLint game
• Webhint: linting tool for accessibility, speed, and more website best practices
• A11y JSX Plugin: ESLint plugin for checking accessibility rules on JSX elements

Originally published at https://www.colbyfayock.com/2019/10/what-is-linting-and-how-can-it-save-you-time

Wait up, what is Gatsby?

Gatsby is a free and open source framework based on React that helps developers build blazing fast websites and apps

Their emphasis (I’ll explain later). I like to describe it as Create React App on steroids, where it’s an easy way to bootstrap a React application and focus on getting productive with the truly different parts of your application. At it’s core, it’s a glorified Webpack app, where everything gets built upon that same Webpack pipeline that you’ve struggled to write and fully understand til this day (or maybe that’s just me).

The beauty though is that what it outputs is a static website (simple HTML file) with your application prerendered for optimal delivery. This means it can essentially run anywhere like simply dumping it in S3 and serving it as a static webpage or even easier, have Netlify build and serve it for you.

It’s all in the scripts

Chubbs with Happy Gilmore

Gatsby is one of the many tools available that supports the JAMstack architecture. For the unfamiliar, JAM stands for Javascript APIs and Markup, or pretty much a static HTML website that utilizes javascript to make the magic happen.

JAMstack apps have a lot of benefits right out of the box including:

• Easy to host
• Cheap to host
• It loads super quick (most of the time)

This means generally more often than not, you’re going to have a fast site that doesn’t cost you a lot of money to both host and maintain.

Sound a bit familiar?

It’s easy to compare this to Rails, as I hear often from others on my team, and rightfully so. There’s a lot of magic behind the scenes in Gatsby!

But unless you’re purely leaning on plugins and themes (which is fine), at the end of the day you’re still building a React application as you would anywhere else. Your app can pretty much be ported to any other framework (aside from the data sourcing and page generation part). Components are components, styles are styles.

const Nav = () => {
  return (
    <nav>A normal nav component in a normal Gatsby app.</nav>
  )
}

Gatsby is opinionated on many aspects, but those opinions mostly fall outside of the idea that you’re still building a webpack app and those conventions are of webpack and the config behind it, not necessarily Gatsby.

So, what actually makes it so great?

Literally bootstrap in under a minute

Parks and Recreation "Literally"

Seriously. Spinning up a new Gatsby site is the literal definition of all those click bait articles saying you can do something in 5 minutes. Install the CLI and you’re 3 commands away from your app spun up locally or statically built.

For example, if you wanted to spin up a new barebones project with Sass:

$ gatsby new my-cool-gatsby-project https://github.com/colbyfayock/gatsby-starter-sass
$ cd my-cool-gatsby-project
$ yarn develop

Bootstrapping a Gatsby app

A community of Starters provides an easy entry point to your new app (or the whole thing you want).

Note: the whole “under a minute” depends on what kind of connection you’re on, as you’ll need to wait for the dependencies to download and install.

Bringing it all together in the content mesh

One of the concepts behind Gatsby is the idea of the “content mesh” and Gatsby being the solution to pull it all together. Many apps, and growing, are being built with the JAMstack architecture, which helps with the idea that we can source as much of our content from as many places as we want and bring it into one application in a performant way.

https://www.gatsbyjs.org/blog/2018-10-04-journey-to-the-content-mesh/

When all is said and finished, you can pull in data from many sources into one statically compiled application. That is indeed blazing fast. ?

Free performance boost!

Out of the box you get your supercharged webpack config including code splitting, prefetching, inline styles, minification of assets, and a ton of other greatness. Upgrade that easily with a wealth of plugins that are easy to configure like setting up your app as a PWA (progressive web app) and providing the ability for offline mode

Lots of buzzwords in there, but at the end of the day, that means your website should be snappy based on mostly best practices that are optimizing all of your site’s assets for speed and delivery, all while making it as accessible as possible by transpiling for older browsers and making sure slow connections aren’t wasting valuable resources. It’s difficult to confirm as a hard stat, but Kyle Mathews (Gatsby Founder) claims Gatsby sites are 2-3x faster than similar types of sites.

Increased productivity!

No longer do you have to concern yourself with the complexities of making sure your application is performant by rewriting and tweaking your webpack config to the new best practices for each new app you bootstrap. Gatsby does this all for you. It lets you focus on the import bits that makes your app special, not the scaffolding.

This is taken a step further with Gatsby’s plugins and the addition of Themes. Themes are not what you would expect in the traditional sense, or what you would expect from Wordpress, but they provide a way to abstract any part of your Gatsby application so you can reuse it app to app.

Have a core component library you use every time? Make it a theme. Have a particular configuration for data sourcing that you don’t want to rewrite every time? Make it a plugin. Being able to abstract these key pieces to your app saves you time and stress on each new project you spin up, not to mention the ability to maintain those pieces in one place, fixing bugs and improvements with a simple package update.

Large community

Gatsby itself has a decently large community already, but on top of that you have Webpack and React, which have been around for a while. React is the most popular UI framework at the moment, which makes debugging via a simple Google search much easier. It’s hard to find a problem that you’re the first and only to stumble upon.

If you have a Gatsby question in particular, their Github Issues is swarming with people willing to help you debug or tackle the next bug. All they ask is that you politely provide them a way to reproduce, which just makes it easier for them to help you in the first place!

Friend of Hackerman

Like to roll up your sleeve and tweak the pipeline yourself? Gatsby provides easy ways to patch into the processing whether it’s hooking into the lifecycle of the build or tweaking the webpack config. This allows the core of your app to be as easy or advanced as you want, though if you’re that advanced, maybe help write a plugin or two!

Hackerman

The maybe not so great…

Building fast yields more bugs

You should expect that you’ll hit some snags here and there staying on the latest and greatest, after all it is open source software developing for more than just your individual site.

The Gatsby team has been building very rapidly, which is awesome, but moving fast is prone to overlooking things as they build. Luckily, they’re starting to push automated testing all over to help harden the code and they’re intentionally trying to avoid rushing work to address this type of concern.

Just make sure to be thorough on testing your package upgrades and don’t be afraid to downgrade and lock your package version if you’re running into issues.

Static sites are first class, not web apps

Gatsby pens itself as an all inclusive solution for static and non-static apps alike, but is it? Support for client only routes requires a plugin or page creation tweak which is fine, but their tone on issues tends to suggest they’re not always equally focused on the two.

Really the only argument here is why would you use Gatsby over Create React App for that use case? Although it may not be first class, it’s still quite functional with a bonus of the standard underlying Gatsby benefits, but clearly bugs and features aren’t going to be prioritized towards that goal.

Just give it a shot already!

My opinion or any other’s doesn’t matter until you try it. Worst case you literally wasted 5 minutes between installing the dependencies and deleting the folder with the project in it, which on a positive note is a learning experience. Best case you just discovered an awesome tool that’s going to help you do great things.

Lego - we could build a spaceship!

Go build, go experiment, and share what great things you make!

Edit: Changed “slowing down” to “avoid rushing” to clarify statement intent, as they’re not slowing down the amount of actual work getting put in, but trying to be more careful with it.

Originally published at https://www.colbyfayock.com/2019/09/what-is-gatsby-and-why-its-time-to-get-on-the-hype-train

On Twitter, in Slack, on Discord, in IRC, or wherever you hang out with other developers on the internet, you may have heard some formulation of the following statements:

• React doesn't support accessibility
• React makes websites inaccessible
• People should write accessible HTML instead of React
• React is ruining the internet

There's a somewhat common misperception that JavaScript frameworks and web accessibility don't mix. React, being one of the largest JavaScript libraries, is often the target.

In my career, however, I have had the interesting experience of being introduced to accessibility and ReactJS at around the same time. I found tooling in React that helped me learn a lot about accessibility that I never would have encountered otherwise.

And while I don't disagree that there are plenty of libraries, websites, apps, etc. written in React that are inaccessible, I do disagree there is something inherent in ReactJS that makes developers build inaccessible sites. In fact, I love the accessibility tooling available in the React ecosystem, so this post is really about how React can help you make more accessible websites than you've ever made before.

I'll outline how you can combine React linting tools, DOM auditing, and Storybook (a component library tool) to provide a really supportive accessibility environment for developers -- whether they are accessibility pros or just getting started. By the end of this post, you'll have the following configured for your Gatsby project (or other React project):

• in-editor reporting of accessibility errors
• a pre-commit hook for preventing accessibility errors from getting into the repository
• browser console reporting of accessibility errors during development, with links to info on how to resolve the errors
• a component library with built-in accessibility testing so all project stakeholders can hold the team accountable for accessibility issues

Want to get started right away? I created a Gatsby starter with all these accessibility tools built in. Checkout the gatsby-starter-accessibility repo that has all these features available out of the box.

Tools and Setup

eslint-plugin-jsx-a11y

If you've written JavaScript over the past few years, you've probably used or at least heard of ESLint. If not, now is a great time to get started with it!

ESLint is a linting utility for JavaScript that helps you catch formatting and syntax errors while you are writing code. Most editors have some sort of linting configuration built in, which lets you see errors in your editor while you code.

This is really helpful for keeping code consistent, especially when there's a lot of people working on a project.

ESLint also has a really healthy plugin ecosystem. You can include rules specific to the JavaScript framework you are working with (i.e., React, Angular, Vue, etc), among others. For React, I typically use the eslint-plugin-react and the really helpful eslint-plugin-jsx-a11y. This plugin lints your code for known accessibility violations, using these rules.

Having these automated tests run while you are writing code can prevent so many errors. Even though automated accessibility testing catches only about 20-30% of all accessibility errors, catching these errors before they make it into a codebase can save time, budget, and energy for doing more manual testing once the code is in the browser.

Usage

Here's how you can get started with accessibility linting in your React project.

First, we'll need to install the necessary eslint packages:

npm install eslint eslint-plugin-react eslint-plugin-jsx-a11y --save-dev

In your package.json, add the following configuration:

"eslintConfig": {
    "parserOptions": {
      "sourceType": "module"
    },
    "env": {
      "node": true,
      "browser": true,
      "es6": true
    },
    "plugins": [
      "react",
      "jsx-a11y"
    ],
    "extends": [
      "eslint:recommended",
      "plugin:react/recommended",
      "plugin:jsx-a11y/recommended"
    ]
}

With this added to your package.json, ESLint will use the rules recommended by ESLint, React, and the jsx-a11y plugin while you are working.

You'll want to make sure your editor is set up to display linting errors in the editor for this to be really useful.

Add a pre-commit hook for preventing inaccessible code in the codebase using lint:staged

Now we've got some accessibility linting set up, and hopefully everyone working on the project has linting turned on in their editor so they can see any errors while they work.

But you can't be 100% sure that everyone will be paying attention to the linter. And even if they are, it's easy to make a quick change, switch files, and any errors will be out of sight, out of mind.

What we can do as an extra check to prevent inaccessible code from entering the codebase is to add a pre-commit hook that runs the linting we set up above every time a developer tries to commit code. If an accessibility error is found, an error message will display with the relevant linting error and location of the error, and the commit will be prevented until the developer resolves the issue.

lint-staged will run a pre-commit hook that will catch any accessibility errors raised by eslint-plugin-jsx-a11y

Usage

The easiest way to set up pre-commit linting hooks is using the [lint-staged](https://www.npmjs.com/package/lint-staged) package. After you've got all your eslint configuration set up (from our first step), run the following command in your project directory:

npx mrm lint-staged

This command will install the [husky](https://www.npmjs.com/package/husky) package for managing the pre-commit hooks and look in your package.json to automatically setup a pre-commit hook based on your linting configuration.

A simple configuration that lints all JS files based on the existing eslint configuration in the repo will look like this (from package.json):

"husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
},
"lint-staged": {
    "*.js": [
      "eslint"
    ]
}

You can adjust this as you see fit. For example, sometimes you want to limit linting to certain directories. To run the pre-commit hook only on JS files in the src directory, you would update the lint-staged configuration like this:

"lint-staged": {
    "src/*.js": [
      "eslint"
    ]
}

The great thing about lint-staged is that it only lints the files that are part of the current commit. If for some reason there is some pre-existing errors in another part of the codebase, the commit won't be prevented--it only prevents new errors from being introduced.

react-axe

The great thing about the linting setup we have now is that it will prevent a lot of errors from being introduced into the codebase. It won't prevent all errors, however. Some errors only exist when several components are used together, or from certain content, and can only be caught in the browser.

Luckily, we have a solution for this, too. Axe is an open source engine for automated accessibility testing, supported by Deque. I first became familiar with axe by using their really useful browser extension for testing individual pages in the browser.

The problem with browser-extension accessibility testing is that they are typically only run after development is complete. Using the react-axe library, you can have automated accessibility testing run on every page during development, so developers can get real-time feedback on accessibility issues. This helps make sure that accessibility issues never make it to production, and it also educates developers who may not be accessibility experts on potential pitfalls.

The react-axe library is an easy to use implementation of the axe engine, specifically for React.

Usage

Here's how to get started using react-axe with Gatsby (someone made a Gatsby plugin for it!):

npm install --save gatsby-plugin-react-axe

Add gatsby-plugin-react-axe to your plugins array in gatsby-config.js

module.exports = {
 siteMetadata: {
        title: 'Gatsby Default Starter',
    description:
      'Kick off your next, great Gatsby project with this default starter. This barebones starter ships with the main Gatsby configuration files you might need.',
    author: '@gatsbyjs',
  },
  plugins: [
    'gatsby-plugin-react-axe',
    // other plugins go here
  ],
};

Now, when the page renders, the plugin will print any accessibility errors to the browser console. Here's an example, where I've put an <h5> directly underneath an <h1>:

React aXe will show accessibility errors in the console while you are developing.

​

React aXe will show accessibility errors in the console while you are developing.

You can see that in the axe message in the console that it has identified my heading issue: "Heading issues should only increase by one" as a moderate issue. It also includes a link to learn more about why this is an issue and how to resolve it: https://dequeuniversity.com/rules/axe/3.2/heading-order. And lastly, it displays the specific element that is causing the issue for easy identification.

This kind of instant feedback is so important, whether you are an accessibility beginner or even a seasoned pro. Catching the automated issues instantaneously can give you more bandwidth to focus on other more involved tasks.

Storybook and Accessibility

The last piece of our accessibility workflow has to do with our component-driven workflow. For React projects, I have really enjoyed using Storybook to build and document our front end components.

Storybook is an open source tool for developing UI components in isolation for React, Vue, and Angular. It makes building stunning UIs organized and efficient.

• storybook.js.org

Besides having a nice workflow and UI, Storybook has an awesome accessibility add-on that adds a panel to each component in your component library highlighting accessibility issues.

Our storybook configuration has built-in axe tests for each component and a color blindness simulator, provided by the storybook accessibility add-on.

Behind the scenes, the add-on actually also uses aXe for testing. This is really nice, because it means that the testing we are using in development is the same as what we are using in the component library. Having the errors highlighted in the component library also helps everyone on our project teams catch accessibility issues as they are browsing the library, either for QA purposes or design inspiration.

Setup

The setup for Storybook is a bit more involved, so if you haven't used Storybook before, you can checkout the Storybook for React documentation for a generic React setup.

If you want to get Storybook running with Gatsby, see Visual Testing with Storybook in the Gatsby docs.

Once you have Storybook setup, adding the accessibility add-on is pretty straightforward.

First, install the add-on:

npm install @storybook/addon-a11y --save-dev

Then add this line to your addons.js file in your storybook config directory:

import '@storybook/addon-a11y/register';

And lastly, add this line in your Storybook config.js file to automatically add the accessibility panel to all components:

addDecorator(withA11y);

When you run Storybook now, you should now see the accessibility panel (see a live version here):

Our storybook configuration has built-in axe tests for each component and a color blindness simulator, provided by the storybook accessibility add-on.

As a side note - you can control the order of the tabs in your add-ons panel based on the order that you import add-ons into your addons.js file, if you want to have the accessibility panel display by default, make sure it is the first line in your addons.js.

Wrap up

If you didn't follow along with the setup or just want to get a new project setup quickly with this workflow, checkout the gatsby-starter-accessibility Gatsby starter!

You can create a new Gatsby site with all the configuration I described above out-of-the box with this single line in your terminal:

npx gatsby new my-accessible-project https://github.com/benjamingrobertson/gatsby-starter-accessibility

Or you can checkout the specific configuration in the repo.

Whether you ran through all the steps above or use with the starter, you'll have the following features set up in your Gatsby / React project:

• in-editor reporting of accessibility errors
• a pre-commit hook for preventing accessibility errors from getting into the repository
• browser console reporting of accessibility errors during development, with links to info on how to resolve the errors
• a component library with built-in accessibility testing so all project stakeholders can hold the team accountable for accessibility issues

On a complex project with many team members and moving parts, automating accessibility testing will help save time to make sure you can pay more attention to the accessibility tasks that can't be caught by automated tests.

Beyond that, tools like this can really help developers level up their accessibility knowledge.

I know it's helped me--I hope it helps your team too!

Want to dive deeper into building accessible websites? Join my free email course: ? Common accessibility mistakes and how to avoid them. 30 days, 10 lessons, 100% fun! ? Sign up here!

With the recent exodus from Medium many developers are now creating their own GatsbyJS Blogs and then cross-posting to Medium or publications like freecodecamp.org and dev.to.

Cross-posting is time consuming, but necessary to drive traffic to your personal site. Let's look at how we can automate this by adding an RSS feed to your personal GatsbyJS blog.

Add Canonical URL's to Your Blog

What is a canonical url?

A canonical url tells search engines which page is the primary or authorative page when duplicate content is found (ie. cross-posting).

Let's install gatsby-plugin-canonical-urls

Quick tip: npm i is an alias for npm install --save

npm i gatsby-plugin-canonical-urls

Note: If you are using gatsby-plugin-react-helmet install this plugin instead: gatsby-plugin-react-helmet-canonical-urls*

npm i gatsby-plugin-react-helmet-canonical-urls

Add plugin configuration to /gatsby-config.js

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-canonical-urls`,
    // or
    // resolve: `gatsby-plugin-react-helmet-canonical-urls`
    options: {
      // Change `siteUrl` to your domain 
      siteUrl: `https://tueri.io`

      // Query string parameters are inclued by default.
      // Set `stripQueryString: true` if you don't want `/blog` 
      // and `/blog?tag=foobar` to be indexed separately
      stripQueryString: true
    }
  }
]

With this configuration, the plugin will add a <link rel="canonical" ... /> to the head of every page e.g.

<link rel="canonical" href="https://tueri.io/2019-04-04-how-to-securely-deploy-to-kubernetes-from-bitbucket-pipelines/" />

Install an RSS Feed Generator

We'll use gatsby-plugin-feed to generate an rss feed from our blog posts.

npm i gatsby-plugin-feed

Add plugin configuration to /gatsby-config.js

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-feed`,
    options: {
      query: `
        {
          site {
            siteMetadata {
              title
              description
              siteUrl
              site_url: siteUrl
            }
          }
        }
      `,
      feeds: [
        {
          serialize: ({ query: { site, allMarkdownRemark } }) => {
            return allMarkdownRemark.edges.map(edge => {
              return Object.assign({}, edge.node.frontmatter, {
                description: edge.node.excerpt,
                date: edge.node.frontmatter.date,
                url: site.siteMetadata.siteUrl + edge.node.fields.slug,
                guid: site.siteMetadata.siteUrl + edge.node.fields.slug,
                custom_elements: [{ "content:encoded": edge.node.html }],
              })
            })
          },
          query: `
            {
              allMarkdownRemark(
                sort: { order: DESC, fields: [frontmatter___date] },
              ) {
                edges {
                  node {
                    excerpt
                    html
                    fields { slug }
                    frontmatter {
                      title
                      date
                    }
                  }
                }
              }
            }
          `,
          output: "/rss.xml",
          title: "Your Site's RSS Feed",
          // optional configuration to insert feed reference in pages:
          // if `string` is used, it will be used to create RegExp and then test if pathname
          // of current page satisfied this regular expression;
          // if not provided or `undefined`, all pages will have feed reference inserted
          match: "^/blog/",
        },
      ],
    }
  }
]

NOTE: This plugin will only generates the xml file(s) when run in production mode! To test your feed, run: gatsby build && gatsby serve

Here's what our feed looks like: Tueri.io's RSS Feed

For more information on configuring your feed check out the plugin docs.

Connect dev.to to Your RSS Feed

1. Log in to your dev.to account
2. Go to: Settings > Publishing from RSS or https://dev.to/settings/publishing-from-rss
3. Add your "RSS Feed URL" e.g. https://tueri.io/rss.xml
4. Check "Mark the RSS source as canonical URL by default
5. Click "Update"

Connect Medium to Your RSS Feed

The connection for Medium is not quite as straight-forward, but simple enough using Zapier.

Head on over to Zapier and create a free account.

"Make a Zap"

1. Choose "RSS" as your "Trigger App"
2. Select "New Item in Feed"
3. Paste in your "Feed URL"
4. Select a sample from your feed.
5. Choose "Medium" as your "Action App"
6. Select "Create Story"
7. Authorize your Medium account
8. Select your fields: make sure you select your Canonical URL
9. Send a test to Medium
10. Finish and turn on your Zap

Conclusion

Make sure Google gives you credit for your content by using Canonical URL's.

I hope you found this helpful and that it saves you lots of time cross-posting your content!

_Originally published at Tueri.io_

For all your developer note-taking needs

Taking notes is key to remembering most things in our lives. How many times have you worked on a project, then three months later needed to get back in the code, and it took you hours to come back up to speed? If you had taken a few minutes to jot down some documentation, you could have cut to the chase.

Personally, I keep my notes all over the place — in notebooks, mostly, but also right here on this blog. Many times when I finish a large, difficult feature, I like to blog key elements of it so I can come back later and figure out how I did what I did. Plus, it might help someone else along the way. However, there are tons of things I learn every day that just slip away. I keep learning and re-learning them and that’s inefficient.

I recently wanted a way to quickly jot down things I learn throughout the day, or lessons I want to keep in mind. But that’s not enough — I also need to be able to search these logs so I can find exactly what I’m looking for right away. That’s exactly what I’m going to show you how to build today. This project, front-to-back, took me maybe an hour and a half.

Gatsby

This project is built using Gatsby, the wildly popular front-end framework for creating static websites. I’m going to skip all the sales pitch stuff and just jump into the code, but if you want to back up a step, I wrote a long blog post about why I love Gatsby so much. In short: it’s awesome if you know React, and probably worth learning anyway if you need a static site.

Step 1: Create a new Gatsby site using the beautiful “Julia” template

Assuming you’ve got the Gatsby CLI working, run this to pull the pared-down but beautifully laid-out Julia template:

gatsby new <site-name> https://github.com/niklasmtj/gatsby-starter-julia

Pop open the gatsby-config.js and swap out your details for “Julia Doe” under siteMeta. You’re halfway there.

Step 2: Add logging

Now we want to add some functionality to the site. In the content directory, add a markdown file or twenty. Nest them however you like. You’ll follow this format:

---
title: "Whatever title you want"
date: "2019-05-010"
draft: false
path: "/logs/some-slug-for-the-file"
tags: testing, documentation
---

# Monday, May 6, 2019
* Added documentation ....

Note that path needs to be unique for each file. I named mine by date (with each week getting one file) but obviously you can do anything you like.

Step 2A: follow the Gatsby documentation for creating pages from Markdown

I could reiterate, but the Gatsby documentation itself is incredibly straightforward and easy to follow. You’ll install the required plugins, configure them in gatsby-config.js, create a template for how your posts should look, and set up gatsby-node.js to build pages from your markdown files.

To steal a tip from somewhere else on the internet: if you head to a localhost page you know doesn’t take you anywhere (I prefer localhost:8000/garbage), you can see all the available links for your page. It’s a quick way to check Gatsby has created all your markdown pages appropriately.

Keep it clean

I learned working on this project that you can assign multiple folders to get scanned by Gatsby’s file system plugin:

{
  resolve: `gatsby-source-filesystem`,
  options: {
    name: `images`,
    path: `${__dirname}/src/images`,
  },
},
{
  resolve: `gatsby-source-filesystem`,
  options: {
    name: `markdown-pages`,
    path: `${__dirname}/src/content`,
  },
},

So no problem if you are already using gatsby-source-filesystem to read, for instance, your image files. I also tested nesting, and Gatsby will grab anything in your content folder recursively — so you can go ahead and organize any way you like.

Good times! If you took that diversion to the Gatsby docs, you should now have a fully-functioning log system.

Step 3: Add search

Now the fun part. We’ll add the ability to search our logs using the Gatsby lunr elastic search plugin.

Configure

First, yarn add @gatsby-contrib/gatsby-plugin-elasticlunr-search, then we’ll add to gatsby-config.js:

{
  resolve: `@gatsby-contrib/gatsby-plugin-elasticlunr-search`,
  options: {
    // Fields to index
    fields: [`title`, `tags`, `html`],
    resolvers: {
      MarkdownRemark: {
        title: node => node.frontmatter.title,
        tags: node => node.frontmatter.tags,
        path: node => node.frontmatter.path,
        html: node => node.internal.content,
      },
    },
  },
},

Note that I’ve added a field not included on the lunr docs: html. We’ll need this for full text search of the logs, rather than just searching by tags.

Add a search bar

Obviously yours can go anywhere. I put mine right on the index under my name.

The search bar component:

import React from "react"
import { graphql, StaticQuery } from "gatsby"
import Search from "./search"

export default () => {
  return (
    <StaticQuery
      query={graphql`
          query SearchIndexQuery {
            siteSearchIndex {
              index
            }
          }
        `}
      render={data => (
        <Search searchIndex={data.siteSearchIndex.index}/>
      )}
    />
  )
}

Nothing much going on here — we’re just grabbing the search index from the elastic search data.

The search component, essentially copied directly from the lunr docs:

import React, { Component } from "react"
import { Index } from "elasticlunr"
import { Link } from "gatsby"
import styled from "@emotion/styled"
export default class Search extends Component {
  state = {
    query: ``,
    results: []
 }

  render() {
    return (
      <div>
        <input type="text" value={this.state.query} onChange={this.search} />
        <ul>
          {this.state.results.map(page => (
            <li key={page.id}>
              <Link to={"/" + page.path}>{page.title}</Link>
              {': ' + page.tags}
            </li>
          ))}
        </ul>
      </div>
    )
  }

  getOrCreateIndex = () => {
    return this.index
      ? this.index
      : // Create an elastic lunr index and hydrate with graphql query results
      Index.load(this.props.searchIndex)
  }

  search = evt => {
    const query = evt.target.value
    this.index = this.getOrCreateIndex()
    this.setState({
      query,
      // Query the index with search string to get an [] of IDs
      results: this.index
        .search(query, { expand: true })
        // Map over each ID and return the full document
        .map(({ ref }) => {
          return this.index.documentStore.getDoc(ref)
        }),
    })
  }
}

You build a search index, fetch results based on a partial string, hydrate those results based on what the index returns, then map over them to display.

And that is seriously it. Your markdown pages will be built when Gatsby build runs and your search will index the first time you try to search.

Step 4: Add security

I’m not putting any state secrets or env variables in these logs, but I would rather not have a potential employer stumble upon them, mostly because I want to be free to talk about my struggles or be very clear about what I don’t know. If I have to censor myself, it will affect the quality of my logs.

At the same time, I can’t be bothered with a login or anything too fancy. So I opted for the silliest, loosest, easiest security I could come up with: a basic localStorage token. If you have it, you see the logs, and if not, too bad. Here’s how that works.

In landing-bio.js and anywhere else I want to protect:

const isBrowser = () => typeof window !== "undefined"
const isAuthenticated = isBrowser() && window.localStorage.getItem('authenticated');
[...]
{isAuthenticated ? <SearchBar /> : <div>You aren't Amber, so you don't get to read her logs.</div>}

I would never use this for actually-sensitive information, but it’s great for a tiny bit of peace of mind that my coworkers won’t be sneaking around my personal logs.

Note that the browser check (first line) is needed for this to pass tests on Netlify — it works fine without it otherwise.

Bonus: Deploy with Netlify

I talked about how much I love Netlify on my previous Gatsby blog post, and I still love them. It’s so dang easy to get your stuff right online.

All you’ll do is head over to Netlify, authorize them to access the Github where your logs are stored, and they will monitor Github and make new releases for you whenever you push to master. They will also create deploy previews when you make PRs! It’s really wonderful and I super-recommend them.

If you are going to create logs in markdown, I highly recommend a deploy system as easy as this one, and I don’t know of another that is as seamless.

In this course from Andrew Mead, you will learn everything you need to build and launch your first site with Gatsby. You’ll build a website from scratch and learn how to get it deployed to production with tools like GraphQL. Some things you'll learn:

1. How to create a Gatsby Site
2. Working with Gatsby Pages
3. Linking Between Pages with Gatsby
4. Creating Shared Page Components
5. Creating Gatsby Page Layouts
6. Styling Gatsby Projects
7. Styling Gatsby with CSS Modules
8. Gatsby Data with GraphQL
9. GraphQL Playground
10. Sourcing Content from the File System
11. Working with Markdown Posts
12. Generating Slugs for Posts
13. Dynamically Generating Pages
14. Rendering Post Data in Blog Template
15. Adding Images to Posts
16. Getting Started with Contentful
17. Rendering Contentful Posts
18. Dynamic Pages from Contentful
19. 404 Pages and React Helmet
20. Deploying Your Gatsby Site

You can watch the full video course on the freeCodeCamp.org YouTube channel (5 hour watch).