DEV Community: John Grisham

How I Automated My Weekly Newsletter using BlitzJs and CRON

John Grisham — Tue, 24 Aug 2021 17:00:32 +0000

I recently discovered Blitz.js and love how quickly the framework lets you build an application but my favorite part is the command-line tool. Blitz.js has a console that can be used to run predefined queries and mutations via a node REPL environment which is great for manually running tasks from the command line, but less good when ran inside of CRON job since it will take over whatever process it’s running on.

I have a newsletter that collects news stories and I wanted to automate sending this newsletter every other week. I needed a CRON solution initiated via a bash script that wasn’t using expect commands so I started looking into the child_process module.

To support me sign up for Medium and read this tutorial there: Medium signup link

Clearing old data

Blitz.js is built upon Next.js so hosting is flexible but for me, the winner is Render.com. I’m not affiliated with them but of the hosting platforms I’ve tried, they have been the cheapest and easiest to set up. This post won’t go in-depth with how to use Render for hosting, just be aware that is the host where I set up my CRON job.

Render offers a simple CRON service. I want mine to do two things once a week.

Delete records from my database that are more than 6 days old
Run my newsletter auto-mail mutation if the week is odd (every other week)

My bash script will be the entry point and will initiate these processes.

echo 'Running weekly script...'
echo 'Clearing old data...'
chmod +x ./automation/clearMail.ts
ts-node ./automation/clearMail.ts
echo 'Old data cleared from db'
echo 'Checking if auto mailer should send...'
WEEK=`date +"%V"`
if [ $(($WEEK%2)) -eq 0 ];
then
    echo "Sending auto mailer..."
    chmod +x ./automation/sendAutoMail.ts
    ts-node ./automation/sendAutoMail.ts
else
    echo "No auto mail to send"
fi
echo 'Done'

I use ts-node to make calls to other Typescript files here which will execute the core logic that I want to accomplish. Lets take a look at the first one.

// clearMail.ts
import { onExit, streamEnd } from '@rauschma/stringio'
import { spawn } from 'child_process'
import { writeToWritable } from '../app/core/utils'

async function clearMail() {
    const blitzProcess = spawn('blitz console', [], { shell: true, stdio: ['pipe', process.stdout, process.stderr] })
    blitzProcess.on('error', (err) => {
        console.error(err.message)
    })

    await writeToWritable({
        commands: ['await clearOld()', '.exit'],
        writable: blitzProcess.stdin
    })

    return await onExit(blitzProcess)
}

clearMail()

This file will spawn a new process using the blitz console with a custom stdio configuration. This configuration is important and is the only one that worked for my solution. The problem I kept running into was that once the blitz console started it would gum up my main process and prevent me from running further commands inside the console. We are making a way for the parent process to communicate with the child process input. The parent can tell the child what to do and vice versa. As for the output and error channel, we make those default to the main process stout and sterr respectively.

I also tell the blitz process to log any errors via the process on error event handler. I’m using some utility methods to then run my clearOld mutation that will delete old records from my mail database. I’m also using the stringio package from Axel Rauschmayer for managing the console execution stream.

// writeToWritable.ts
import { streamEnd, streamWrite } from '@rauschma/stringio'
import { Writable } from 'stream'

export default async function writeToWritable({ commands, writable }: { writable: Writable; commands: string[] }) {
    for (const cmd of commands) {
        await streamWrite(writable, `${cmd}\n`)
    }

    return await streamEnd(writable)
}

This file will write multiple commands to the new child process and then end the stream. Once we’re done we’ll exit the blitz console child process. In case you’re interested my clearOld mutation looks like this.

// clearOld.ts
import db from 'db'
import { sub } from 'date-fns'

export default async function clearOld() {
    try {
        return await db.mail.deleteMany({
            where: {
                createdAt: {
                    lt: sub(new Date(), { days: 6 })
                }
            }
        })
    } catch (err) {
        throw new Error(err.message)
    }
}

Sending the newsletter

The next part of the bash script runs the automatic mailer file every other week. This file will get my signups from Firebase and send them a collection of news stories via the Sendgrid API. The child process setup is the same here the only difference is that I have some arguments that I’d like to be able to pass when I run the file for this I use the pirate-themed command-line arguments package Yargs.

Yargs on Github

I also have some utility methods for making a temp file with some HTML that I will then load when I send the newsletter. This HTML will serve as my template for the newsletter that I have saved in a different table. Anyway, all of that falls outside of the scope of this tutorial so here’s the base code for the auto mailer file.

// sendAutoMail.ts
import { makeTemp, writeToWritable } from '../app/core/utils'
import { autoMailer } from '../designs/designs.json'
import { hideBin } from 'yargs/helpers'
import { onExit } from '@rauschma/stringio'
import { spawn } from 'child_process'
import yargs from 'yargs/yargs'

async function sendAutoMail() {
    try {
        const argv = yargs(hideBin(process.argv)).argv
        const isTest = (argv.test as boolean) ?? false
        const testUsers = isTest ? JSON.stringify([{ email: 'test@test.com' }]) : undefined
        const subject = isTest ? 'test' : 'Your weekly echo stories'
        const html = autoMailer
        const htmlName = await makeTemp({ data: html, name: 'auto_mailer' })
        const blitzProcess = spawn('blitz console', [], { shell: true, stdio: ['pipe', process.stdout, process.stderr] })

        blitzProcess.on('error', (err) => {
            throw new Error(err.message)
        })

        blitzProcess.stdin.on('error', (err) => {
            throw new Error(err.message)
        })

        if (testUsers !== undefined) {
            await writeToWritable({
                commands: [
                    `await sendMail({ html: '${htmlName}', raw: false, mail: true, subject: '${subject}', testUsers: ${testUsers}  })`,
                    '.exit'
                ],
                writable: blitzProcess.stdin
            })
        } else {
            await writeToWritable({
                commands: [`await sendMail({ html: '${htmlName}', raw: false, mail: true, subject: '${subject}'  })`, '.exit'],
                writable: blitzProcess.stdin
            })
        }

        return await onExit(blitzProcess)
    } catch (err) {
        throw new Error(err.message)
    }
}

sendAutoMail()

Conclusion

I hope this has been helpful. Blitz.js is great and it’s a lot of fun to develop with but the CLI can also be used outside of generating files and folders which opens up some interesting CRON job solutions. I found the console to be simple to use and fun but lacking when trying to run commands automatically via bash. My solution is very specific to my use case and if I didn’t have such a particular goal in mind for my newsletter I would have used an existing email newsletter solution.

This guide isn’t intended to be a step-by-step solution for your CRON endeavors with the blitz console but it should give you inspiration into what you can automate out of your workflow using these technologies. If you’re like me and you need solutions outside of what other Saas providers give, you can create your automated workflows using CRON and some elbow grease. What do you think of my solution? Is there room for improvement or have I overengineered it? If you’re curious you can also check out the newsletter that I built this CRON job for here.

Echo Breaking News

How to use typescript & sails js for your REST API (Safer seas)

John Grisham — Wed, 05 May 2021 17:51:46 +0000

Shoutin', typing' an' screamin' — that be how we sail.

Have you ever seen pirates of the Caribbean? It's a Disney film series based on the exploits of various fictional pirate characters and pirate lore. The films make being a pirate sound cool as a sea cucumber but in reality the average life expectancy of a pirate was around 26 years, a dangerous life indeed.

So why am I talking about pirates? My point is that freedom in life just like freedom in code is not always a good thing. That's why I love Typescript. Coding can be freeing but with that freedom comes a lot of danger. With Typescript troubled waters become much safer.

I'm going to take you through my journey with Sails JS and Typescript so far and show you some tricks I've learned along the way. So let's get started!

Typescript with Sails JS

Sails doesn't use typescript by default but does support it. I won't dive very deep into getting started with Sails or integrating Typescript but you can configure a sails project with Typescript very easily by following the docs:

Using TypeScript

note The docs will have you install ts-node, typescript and the necessary types as dependencies but make sure you install these as Dev dependencies only.

Creating Types

If you have a Sails project with Typescript ready you can follow along. In case you're interested here's my tsconfig:

{
    "compilerOptions": {
        "target": "es6",
        "allowJs": true,
        "skipLibCheck": true,
        "strict": false,
        "forceConsistentCasingInFileNames": true,
        "noEmit": true,
        "esModuleInterop": true,
        "module": "commonjs",
        "moduleResolution": "node",
        "resolveJsonModule": true,
        "isolatedModules": false,
        "jsx": "preserve",
    "lib": ["es2018", "DOM", "ESNext"],
        "sourceMap": true,
        "baseUrl": "./",
        "outDir": "./build",
        "rootDir": "./"
    },
    "exclude": ["node_modules"],
    "include": ["./**/*.ts", "./**/*.tsx"]
}

We're going to make a basic turtle type that we'll use in a minute. So go ahead and create an interfaces folder in api and inside it make a turtle.ts file:

// api/interfaces/turtle.ts
export interface Turtle {
  shellColor: string
  age: number
}

These are just some basic props to illustrate how Typescript works. We'll use this type for the inputs in a standalone action. Similarly we will want to define our exits type as well:

// api/interfaces/exits.ts
export interface Exits {
  error: (response: Record<string, unknown>) => void
  success: (response: Record<string, unknown>) => void
}

If you aren't familiar with Typescript the Record type is sort-of like an object so what we're defining is two functions that will receive generic objects and return void. (But in reality both these functions will return a response from the action.)

I also like to use an index file to manage my imports I recommend you do the same:

// api/interfaces/index.ts
export * from './exits'
export * from './turtle'

Our first API endpoint

noteGoing forward you may have to stop and restart your sails app to see these changes.

It is now recommend by the developers at Sails to use the new Actions 2 format for actions. I like this format and I also like standalone actions because we don't have to explicitly define the routes to our endpoints, enabling automatic routes for standalone actions is easy. Just add this line in your config/blueprints.js file:

actions: true,

This will allow our actions to be available at a logical location in our API by default. Go ahead and create a new standalone action by using the sails cli or by just copying the code:

 sails generate action turtles/sea

This will generate an action in api/controllers/turtles/sea, by default this is a .js file so rename it to a .ts file and replace the contents with this:

import { Exits, Turtle } from '../../interfaces'
import sails from 'sails'

module.exports = {

  friendlyName: 'Sea Turtles!',

  description: 'Turtles all the way down.',

  inputs: {},

  exits: {
    error: {
      message: 'Error!'
    },
    success: {
      data: null,
      message: 'success!'
    }
  },

  fn: async function (inputs: Turtle, exits: Exits) {
    exits.success({ message: 'success', data: inputs });
  }
}

Navigating to localhost/turtles/sea should return this:

{
  "message": "success",
  "data": {}
}

Congrats you created a standalone action in Sails JS now it's time for some deep sea diving.

Generating Sails Schema's from Types

So we have a couple types and an action but you may have noticed something missing. While we have defined what the exits should look like in the action schema we haven't done so with the inputs. One problem I have with Actions 2 is that even though we gave types to our inputs and exits we still have to include them in the schema for Sails to understand what they are. If you were to try sending parameters to this endpoint they would get wiped and nothing would be returned.

I decided to create a helper that generates a Sails JS schema from a Typescript type. That way we can keep our types in sync with our schema and we don't have to repeat ourselves. To do this we'll need help from this library.

Typescript JSON schema

You can add it via yarn like so:

yarn add typescript-json-schema

The above library will take a Type and spit out a plain JSON object that we can use for our inputs. Inside api/helpers create a new file called generate-schema.ts and paste the following code into it:

// api/helpers/generate-schema.ts
import { resolve } from "path";
import * as TJS from "typescript-json-schema";
import sails from 'sails'

interface GeneratorInputs {
  filePath: string
  name: string
}

interface GeneratorExits {
  success: (definition: TJS.Definition) => TJS.Definition
}

const settings: TJS.PartialArgs = {
  required: true
};

const compilerOptions: TJS.CompilerOptions = {
  strictNullChecks: true,
};

module.exports = {
  friendlyName: 'Generate Schema',

  description: 'Generate schema from types!',

  sync: true,

  inputs: {

    filePath: {
      type: 'string',
      example: 'my-type.ts',
      description: 'The path to your type file.',
      required: true
    },

    name: {
      type: 'string',
      example: 'myType',
      description: 'The type name',
      required: true
    }

  },

  fn: function (inputs: GeneratorInputs, exits: GeneratorExits) {
    try {
      const typePath = resolve(`./api/interfaces/${inputs.filePath}`)
      sails.log.info(`generating inputs for type: ${inputs.name} at path: ${typePath}...`)

      const program = TJS.getProgramFromFiles(
        [typePath],
        compilerOptions
      )

      const schema = TJS.generateSchema(program, inputs.name, settings)

      return exits.success(schema)
    } catch (err) {
      throw new Error(`Could not generate types: ${err.message}`)
    }
  }
}

The helper we just made will take a file path which is basically just the file name in this instance and a type name to create a program which will get passed to the generateSchema function. It's OK if you don't understand what's going on in the background with this library. When we're done we will either return the newly created schema or throw an error. The output will look something like this when we call it with the turtle type.

{
    "type": "object",
    "properties": {
      "shellColor": {
        "type": "string"
      },
      "age": {
        "type": "number"
      }
    },
    "required": [
      "age",
      "shellColor"
    ],
    "$schema": "http://json-schema.org/draft-07/schema#"
  }

Awesome! Right away we have a JSON object that has all our properties defined along with their type and whether or not they are required. However there are a few issues here.

Properties is not necessary for the schema
The required field needs to be on the property itself
Type of "object" is not supported in Sails

In order to solve these issues we'll need to parse and manipulate the generated schema. But to add a layer of complexity we will need to do so recursively since types can be nested.

Finally, a recursive problem in programming that isn't inverting a binary tree!

Turtles all the way down

Let's make our Turtle type even more complex:

export interface Turtle {
  shellColor: string
  size: { length: number, weight?: number },
  age?: number
}

We'll make age optional by adding the ? before the type and add a size prop with length and an optional weight prop, because it's rude to ask a turtle it's age or weight! Now that we have a more complex type to test let's create a format function and put it between the compiler options and the module exports.

const formatSchema = (obj: TJS.Definition) => {
    const format = (layer: TJS.Definition) => {
      const keys = Object.keys(layer)

      keys.forEach(key => {
        if (key === "properties" || layer[key]?.hasOwnProperty("properties")) {
          let newProperties = {}
          let nextRequired = []

          if(key === "properties") {
            newProperties = Object.assign(layer, layer[key]);
            nextRequired = layer["required"]
            delete layer["type"]
            delete layer["required"]
            delete layer[key];
          } else {
            newProperties = Object.assign(layer[key], layer[key]["properties"]);
            nextRequired = layer[key]["required"] || []
            newProperties["required"] = layer["required"].includes(key)
            delete layer[key]["properties"];
          }

          if(newProperties["type"] === "object") {
             newProperties["type"] = "ref"
          }

          format({ ...newProperties, required: nextRequired  })
        } else if (key !== 'type' && key !== 'required') {
          layer[key]["required"] = layer["required"]?.includes(key) || false
        }
      })

      return layer
  }

    delete obj.$schema
    return format(obj);
}

This will go through each "layer" of the type iterate the keys and unwrap it's properties from the parent object. It will also determine if each property is required and what the type is. And since "ref" is the approximation of object in the Sails schema we'll replace references to object with "ref". As a last touch we'll delete the $schema prop since it's not needed. Now replace the call to create the schema with this:

const schema = formatSchema(TJS.generateSchema(program, inputs.name, settings))

Now in sea.ts call the helper as an exit with the turtle type:

exits.success({ data: sails.helpers.generateSchema('turtle', 'Turtle') })

When you visit localhost:8080/turtles/sea you should see this:

{
  "data": {
    "shellColor": {
      "type": "string",
      "required": true
    },
    "size": {
      "type": "ref",
      "required": true,
      "length": {
        "type": "number",
        "required": true
      },
      "weight": {
        "type": "number",
        "required": false
      }
    },
    "age": {
      "type": "number",
      "required": false
    }
  }
}

But of course we don't want to return the generated schema we want to use it as our inputs so replace the inputs with the helper instead:

inputs: sails.helpers.generateSchema('turtle', 'Turtle'),

And just return the inputs:

exits.success({ data: inputs })

When you stop your Sails app and re-lift you'll see the generation log get called at our endpoint and just like that we have generated inputs and type safety!

You can test it out by passing parameters for a turtle like so: Test Endpoint with Parameters

Conclusion

This concludes my introduction to Sails JS and Typescript.

What we covered:

Creating interfaces
Actions 2 and standalone actions
Automatic routes for actions
Generated Sails Schema

l like how easy it is to start using Typescript with Sails JS but I do wish Sails had type definitions. I would love to start adding them if there is enough interest. Let me know what you think about it here.

Type definitions for Sails

And for more tutorials about Sails, Pirates and programming follow me on Twitter @SquashBugler.

The quote at the beginning was generated at:The pirate quotes generator

And my favorite quote generated there.

I think that be his ol' poop deck. Blimey!

I'm a child, I know. Thanks for joining me and feel free to share your favorite pirate quotes in the comments.

How to Create Blog Posts From Markdown With Gatsby in 2021

John Grisham — Fri, 26 Feb 2021 18:41:08 +0000

If you want to support me please check out the original post on Medium:
How to create blog posts from Markdown with Gatsby in 2021

Let’s face it building a website is easier than ever; with plenty of platforms to choose from.

But Regardless of where your website is hosted or the platform one thing is usually the same; blog posts.

Then introduce Gatsby which is perfect for building static websites. And
moving from another platform to Gatsby is easier when your blog posts are in Markdown which luckily they usually are!

I’m going to show you how to take markdown files in Gatsby and turn them into generated HTML blog posts, so let’s get started.

Setting up the project

For this tutorial, I’m going to be using the free Peanut Butter & Jelly
Gatsby template I created. The complete version is also available if you
like the template and want to support me by purchasing it.

You can check out the template demo here:

PB&J Demo

And you can download it here:
PB&J Gumroad

Clone the repo:

https://github.com/JohnGrisham/PB-JPlain.git

This will give you the same project to work from as the one I used to
set up my landing page. To get this template up and running, in a
terminal go into the directory you put the project in and run:

yarn

This will download all the dependencies required to get going and once
that’s done run:

yarn develop

This will start development and you should be able to navigate to
localhost:8000 to see the landing page.

If you haven’t done so already go ahead and open up the project in a
text editor of your choice, I use Vscode.

Take a few minutes to note the file structure, everything that’s
included is documented in the readme.

We’ll need a few more packages to get started so run this command in a
separate terminal.

yarn add gatsby-transformer-remark rehype-react

Generating types and configuration

This template uses a development tool to generate Typescript types from
Graphql schemas. If this is all Greek to you that’s fine, I handle most
of the setup for you. All you need to know is that we’ll need the types
for the new transformer we added. But first, we need to do some
configuration. In the codegen.yml file at the root of the project add
this line under documents.

// codegen.yml  - node_modules/gatsby-transformer-remark/!(node_modules)/**/*.js

This will add the new types for Remark to our generated types file. This
works fine for most uses but we need to extend the ‘frontmatter’ field
to add some extra props such as slug. So open the typedefs.js file in
src/graphql/typedefs.js to include these new types.

// src/grapql/typedefs.jstype

MarkdownRemarkFrontmatter {  
    author: AttributedUser
    title: String!
    slug: String!
    date: String
    featuredImage: String
}

type MarkdownRemark implements Node {  
    frontmatter: MarkdownRemarkFrontmatter
}

The last thing we need to do before generating types is update the
gatsby-config with the plugin we added. So somewhere in the plugins
array add this:

// gatsby-config.js

plugins: [`gatsby-transformer-remark`]

Then stop and restart your development process and run:

yarn generate-types

Gatsby templates with styled components

Now we will need to tell Gatsby to generate the HTML files for our
markdown. We’ll want control over how each of these pages looks but we
also want them to all function the same. That’s where Gatsby templates
come in.

You can see an example of this in Gatsby’s docs:

Creating Pages from Data Programmatically

We’re going to create our own template and use it for layout and styling
on our posts. In the src folder add a templates folder. And inside it
add a styles folder with article-template.styled.tsx and index.ts files.
Inside of the article-template.styled.tsx file add these styles.

// templates/styles/article-template.styled.tsx

import styled from 'styled-components'

export const Article = styled.article`
  background-color: white;
  color: ${({ theme }) => theme.colors.mediumGray};
  display: flex;
  flex-direction: column;
  padding: 2em 10vw 2em 10vw;`

export const Author = styled.div`
  display: flex;
  justify-content: center;`

export const AfterTitle = styled.div`
  margin: auto auto;
  width: 100%;

  @media all and (min-width: 700px) {
       width: 70%;
    }`

export const Content = styled.div`
   display: flex;
   flex: 1;
   margin-top: 2em;
   max-width: 100vw;
   overflow: hidden;
   word-wrap: break-word;

   div {
       max-width: 100%;
     }`

export const Heading = styled.h1`
  font-size: 2em;`

export const List = styled.ul`
  list-style-type: disc;`

export const Paragraph = styled.p`
  font-size: 1.2em;
  line-height: 1.5;`

export const SubHeading = styled.h2`
  font-size: 1.5em;`

export const Title = styled.h1`
  font-size: 3em;
  text-align: center;`

And export all the styles from the index.ts file like so:

// templates/styles/index.ts

export * from './article-template.styled'

Finally, create an article-template.tsx file at the root of templates:

// src/templates/article-template.tsx
import * as React from 'react'
import * as Styled from './styles'
import { Avatar, Image, Layout } from '../components'
import { ImageType } from '../enums'
import { Query } from '../interfaces'
import RehypeReact from 'rehype-react'
import { format } from 'date-fns'
import { graphql } from 'gatsby'

export const query = graphql`
    query($slug: String!) {
        allMarkdownRemark(filter: { frontmatter: { slug: { eq: $slug } } }) {
            edges {
                node {
                    frontmatter {
                        author {
                            avatar
                            name
                        }
                        date
                        featuredImage
                        title
                    }
                    excerpt
                    htmlAst
                }
            }
        }
    }
`

const articleTemplate: React.FC<{ data: { allMarkdownRemark: Query['allMarkdownRemark'] } }> = ({ data }) => {
    if (!data) {
        return null
    }

    const {
        allMarkdownRemark: {
            edges: [
                {
                    node: { frontmatter, htmlAst }
                }
            ]
        }
    } = { ...data }

    const renderAst = new (RehypeReact as any)({
        components: { h1: Styled.Heading, h2: Styled.SubHeading, p: Styled.Paragraph, ul: Styled.List },
        createElement: React.createElement
    }).Compiler

    return (
        <Layout>
            {' '}
            <Styled.Article>
                {' '}
                {frontmatter && (
                    <>
                        {' '}
                        <Styled.Title>{frontmatter.title}</Styled.Title>{' '}
                        {frontmatter.author && (
                            <Styled.Author>
                                {frontmatter.author.avatar && <Avatar avatar={frontmatter.author.avatar} />}{' '}
                                <Styled.SubHeading> {frontmatter.author.name} </Styled.SubHeading>{' '}
                            </Styled.Author>
                        )}{' '}
                        {(frontmatter.featuredImage || frontmatter.date) && (
                            <Styled.AfterTitle>
                                {' '}
                                {frontmatter.featuredImage && (
                                    <Image
                                        src={frontmatter.featuredImage}
                                        type={ImageType.FLUID}
                                        style={frontmatter.date ? { marginBottom: '10px' } : undefined}
                                    />
                                )}{' '}
                                {frontmatter.date && (
                                    <Styled.SubHeading style={{ textAlign: 'center' }}>
                                        {' '}
                                        {format(new Date(frontmatter.date), 'MMM do yyyy')}{' '}
                                    </Styled.SubHeading>
                                )}{' '}
                            </Styled.AfterTitle>
                        )}
                    </>
                )}{' '}
                <Styled.Content>{renderAst(htmlAst)}</Styled.Content>{' '}
            </Styled.Article>{' '}
        </Layout>
    )
}

export default articleTemplate

This may look complicated but all we’re doing is querying all the
markdown and filtering it by the slug. The slug is used to determine the
URL of the post and the front matter are fields like featured image and
author. After we have the correct post we will render all the
frontmatter I mentioned. Then use Rehype React to turn the raw HTML
string into a component. Each of the defined basic HTML elements we
specified get converted to styled-components. By doing so we have more
control over the style of our posts.

Creating Pages as Blog Posts

Here’s where the magic happens.

We will be using the create pages hook provided by Gatsby to query our
markdown into pages using the template we made. In the gatsby-config.js
file add the hook.

// gatsby-config.js

exports.createPages = async ({ actions: { createPage }, graphql }) => {
    const {
        data: { allMarkdownRemark, errors }
    } = await graphql(
        `
            {
                allMarkdownRemark {
                    edges {
                        node {
                            frontmatter {
                                slug
                            }
                        }
                    }
                }
            }
        `
    )

    if (!allMarkdownRemark || errors) {
        console.log('Error retrieving data', errors || 'No data could be found for this query!')
        return
    }

    const articleTemplate = require.resolve('./src/templates/article-template.tsx')

    allMarkdownRemark.edges.forEach((edge) => {
        createPage({
            component: articleTemplate,
            context: { slug: edge.node.frontmatter.slug },
            path: `/blog/${edge.node.frontmatter.slug}/`
        })
    })
}

Navigating Posts

We could just navigate manually to the URL in each of our posts but the
user will need to be able to find and navigate to our posts. So first
off create a blog folder in components and inside that folder create a
post folder. From there create a styles folder and populate it with
post.styled.tsx and index.ts files.

// blog/post/styles/post.styled.tsx

import { Card } from '@material-ui/core'
import { Image } from '../../../image'
import { Link } from 'gatsby'
import styled from 'styled-components'

export const AuthorInfo = styled.div`
  align-items: center;
  display: flex;
  flex-direction: column;
  justify-content: center;

    h4 {
        margin: 0px;
   }`

export const FeaturedImage = styled(Image).attrs(() => ({ 
  aspectRatio: 21 / 11,
  type: 'fluid'
}))`flex: 1;`

export const Info = styled.div`
  align-items: center;
  display: flex;
  flex-direction: column;
  margin-top: 1em;`

export const PostItem = styled(Card).attrs({ raised: true })`
  align-items: center;
  display: flex;
  flex-direction: column;
  text-align: center;`

export const PostContent = styled.span`padding: 1em;`

export const PostContentUpper = styled.div`
  margin-bottom: 10px; 

    h3 { 
        margin: 0px;
    }`

export const PostLink = styled(Link)`
  color: ${({ theme }) => theme.colors.black};
  display: flex;
  flex: 1;
  flex-direction: column;
  text-decoration: none;
  width: 100%;`

Once again export the styles:

// blog/post/styles/index.ts

export * from './post.styled'

Now let’s make the actual post component. We’ll need to pass along the
‘frontmatter’ of each post in order to give the reader a taste of what
the post is about.

// blog/post/post.tsx

import * as React from 'react'
import * as Styled from './styles'
import { MarkdownRemark, MarkdownRemarkFrontmatter } from '../../../interfaces'
import { Avatar } from '../../avatar'
import { CardProps } from '@material-ui/core'
import { GatsbyLinkProps } from 'gatsby'
import { format } from 'date-fns'

interface Post extends MarkdownRemarkFrontmatter, Omit<CardProps, 'title' | 'onClick'> {
    excerpt: MarkdownRemark['excerpt']
    onClick?: GatsbyLinkProps<Record<string, unknown>>['onClick']
}

const Post: React.FC<Post> = ({ author, className, date, excerpt, featuredImage, onClick, slug, title }) => {
    return (
        <Styled.PostItem className={className}>
            <Styled.PostLink to={`/blog/${slug}`} onClick={onClick}>
                {' '}
                {featuredImage && <Styled.FeaturedImage src={featuredImage} />}{' '}
                <Styled.PostContent>
                    {' '}
                    <Styled.PostContentUpper>
                        {' '}
                        <h3>{title}</h3>
                        <Styled.Info>
                            {author && (
                                <Styled.AuthorInfo>
                                    {' '}
                                    {author.avatar && <Avatar avatar={author.avatar} />} <h4>{author.name}</h4>{' '}
                                </Styled.AuthorInfo>
                            )}{' '}
                            {date && <h5>{format(new Date(date), 'MMM do yyyy')}</h5>}{' '}
                        </Styled.Info>{' '}
                    </Styled.PostContentUpper>
                    <p>{excerpt}</p>
                </Styled.PostContent>{' '}
            </Styled.PostLink>
        </Styled.PostItem>
    )
}

export default Post

We might want to use this component in other places on our site so go
ahead and export it from the root of the post folder with another
index.ts file.

// blog/post/index.ts

export { default as Post } from './post'

We’ll need a component to display our yummy posts in, so go ahead and
make a styles folder at the root of components/blog. Just like the post
example, you’ll create a blog.styled.tsx file and an index.ts file
inside the styles folder.

// blog/styles/blog.styled.tsx

import styled from 'styled-components'

export const Blog = styled.div`
  align-items: center;
  background-color: ${({ theme }) => theme.colors.white};
  display: flex;   justify-content: center;
  min-height: 100vh;
  padding: 1em 0 1em 0;`

And don’t forget to export:

// blog/styles/index.ts

export * from './blog.styled'

If our posts are peanut butter inside the sandwich of the blog page then
the blog component is the jelly. It uses a grid component I provided to
hold posts together in a simple but effective manner on the page.

// blog/blog.tsx

import * as React from 'react'
import * as Styled from './styles'
import { MarkdownRemark, MarkdownRemarkFrontmatter } from '../../interfaces'
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { Grid } from '../grid'
import { Post } from './post'
import { faBlog } from '@fortawesome/free-solid-svg-icons'

interface BlogProps {
    posts: MarkdownRemark[]
}

const Blog: React.FC<BlogProps> = ({ posts }) => {
    const blogItems = React.useMemo(() => {
        const postsWithFrontMatter = posts.filter(({ frontmatter }) => frontmatter)

        if (postsWithFrontMatter.length <= 0) {
            return null
        }

        return postsWithFrontMatter.map(({ frontmatter, excerpt, id }) => (
            <Post key={id} {...(frontmatter as MarkdownRemarkFrontmatter)} excerpt={excerpt} />
        ))
    }, [posts])

    return (
        <Styled.Blog>
            {' '}
            {blogItems ? (
                <Grid items={blogItems} style={{ width: '90%' }} />
            ) : (
                <h2>
                    No blog posts yet but check back soon!&nbsp; <FontAwesomeIcon icon={faBlog} />
                </h2>
            )}{' '}
        </Styled.Blog>
    )
}

export default Blog

And this is the final time I’ll have you export something from another
file I promise. In the index.ts file at the root of the components
folder add this line at the top.

// components/index.ts

export * from './blog'

If you took a look at the demo I gave earlier for this template you’ll
have noticed that the latest post section included a familiar article.
In this tutorial, I won’t go into creating this latest post section on
but I will have you export the Blog and Post components so they can be
used elsewhere.

Putting it all together

Now we’re done with the hard part. We have the pieces needed for
displaying our brilliant posts all that’s left is to create the page to
display them and at least one sample post to try it out. Find the pages
folder at src/pages and add a blog.tsx file. This will be the page that
displays our blog component and posts.

// src/pages/blog.tsx

import * as React from 'react'
import { Blog, Layout, SEO } from '../components'
import { Query } from '../interfaces'
import { graphql } from 'gatsby'

export const query = graphql`
    query {
        allMarkdownRemark {
            totalCount
            edges {
                node {
                    id
                    frontmatter {
                        author {
                            avatar
                            name
                        }
                        slug
                        title
                        date
                        featuredImage
                    }
                    excerpt
                }
            }
        }
    }
`

const BlogPage: React.FC<{ data: { allMarkdownRemark: Query['allMarkdownRemark'] } }> = ({
    data: {
        allMarkdownRemark: { edges }
    }
}) => {
    return (
        <Layout>
            {' '}
            <SEO title="Blog" /> <Blog posts={edges.map(({ node }) => node)} />
        </Layout>
    )
}

export default BlogPage

This page will look for all of our markdown files and pass them along to
the blog component as posts. If you go to
localhost:8001/blog you should see an
empty blog page with a no posts message.

Now is the moment of truth, we need to make a sample post to make sure
this is all working. Go ahead and create a folder in src/content called
posts and inside it create a what-time-is-it.md file. We’ll be using the
lyrics to ‘Peanut Butter Jelly Time’ as a fitting test.

---

author: { avatar: 'bannans.png', name: 'Buckwheat Boyz' }
title: 'What time is it?'
slug: 'what-time-is-it'
date: '2/1/2021'
---

It's peanut butter jelly time!
Peanut butter jelly time!
Peanut butter jelly time!

<!-- endexcerpt -->

Now Where he at?
Where he at?
Where he at?
Where he at?

NowThere he go
There he go
There he go
There he go

## Peanut butter jelly [x4]

Do the Peanut butter jelly
Peanut butter jelly
Peanut butter jelly with a baseball bat

Do the Peanut butter jelly
Peanut butter jelly
Peanut butter jelly with a baseball bat

## Chorus

Now break it down and freeze
Take it down to your knees
Now lean back and squeeze
Now get back up and scream

## Chorus

Now sissy walk
Sissy walk
Sissy walk
Sissy walk

Now sissy walk
Sissy walk
Sissy walk
Sissy walk

## Chorus

Now walk walk walk walk
Stomp stomp stomp stomp
Slide slide slide slide
Back it up one more time

Now walk walk walk walk
Stomp stomp stomp stomp

Peanut butter jelly break it down
Throw the ball up swing that bat

Turn your head back and see where it at
Throw the ball up swing that bat
Turn you head back and see where it at

Palm beachpeanut butter
Dade countyjelly
Orlandopeanut butter
Tallahasse jelly

Hold on hold on hold on hold on
"Hey chip man what time is it?"

"I don't know what time it is ray low"

"It's peanut butter jelly time"

You should see our what-time-is-it blog post appear on the blog page and
clicking it will, in fact, tell you what time it is.

Conclusion

You should now understand the concepts behind querying markdown files
and changing them into HMTL pages. To recap, we added and generated
types for the Remark transformer in Gatsby. Then we made a template to
use for our markdown that converts each file into valid HTML with
styles. We then set up a create pages hook that uses a template to
render our posts. And finally, we made a page with blog and post
components to display those posts for site visitors to enjoy.

I hope you enjoyed this tutorial and learned a few things along the way.
This is my first attempt at creating a Gatsby website template and would
love feedback.

If you got lost or didn’t have the time to follow along you can get the
$5 version of the template at the link I listed at the beginning of
this tutorial. It includes all the code I went over here as
well as a few more features such as the latest post section.

But most importantly, what’s the best kind of peanut butter; crunchy or
smooth? Let the debate ensue in the comments section, thanks!

By John Grisham on February 2,
2021.

Using CRUD operations with React SWR for mutating REST API cache

John Grisham — Wed, 02 Dec 2020 23:17:15 +0000

To support me please read this tutorial at its original posting location on Medium:
Using CRUD operations with React SWR for mutating REST API cache

SWR for making fetch requests

Vercel has made some great libraries and frameworks in the past so it's no surprise that the SWR library would be any different. I'm going to show you how to fetch and manipulate data from a REST API with Vercel's SWR library. This post has a quick overview of the Vercel library, but if you want to learn more about the library and how it works, you can read the full documentation here.

SWR: React Hooks for Data Fetching

What is SWR?

The idea behind SWR which stands for stale while revalidating is defined in the docs as such. SWR is a strategy to first return the data from cache (stale), then send the fetch request (revalidate), and finally, come with the up-to-date data. So what does this have to do with CRUD? In case you didn't know CRUD is a set of operations that are performed on data and it is shorthand for create, read, update and delete. By default, SWR will perform the read part of this for you by returning the result of a fetch request. But if you want to expand this you will have to mutate the cache from that request. That's why I created a useCrud hook that will help us do just that. I also incorporate Typescript to ensure that the proper keys are used when updating the cache so you will need to have that set up as well.

Setting things up

So first thing is to install SWR, to do this run:

npm install swr
or
yarn add swr

This will add the SWR library to your project. Next, we will add a configuration provider for our app. This will provide the global configuration for SWR when we make requests. I have a contexts folder where I store contexts like this.

import * as React from 'react'
import { SWRConfig } from 'swr'

const swrConfig = {
 revalidateOnFocus: false,
 shouldRetryOnError: false
}

export const SWRConfigurationProvider: React.FC = ({ children }) => <SWRConfig value={swrConfig}>{children}</SWRConfig>

This will need to wrap around your app root, for me that is in the pages/_app.tsx file because I'm using NextJS but it can work in another framework like Gatsby as long as it wraps your app globally. Feel free to change the settings as needed for your project.

R you ready to read some data?

Now we will need to start implementing the fetch that will form the basis of the hook. Here is an example of how fetching works in SWR.

const fetcher = useCallback(
 async (url: string) => {
 const response = await fetch(url)
 return response as T[]
 },
 []
 )

const { data, error, isValidating, mutate } = useSWR(url, fetcher, {
 fetchOptions
 })

The useSWR hook is pretty straight forward it takes a URL and a 'fetcher' which is the function that will perform the request. The URL is passed to the fetcher to make the request and you can also provide some nifty options. SWR will return some things back for you the first is the data that was returned, an error status if there is one, a mutate function, and an isValidating boolean that will tell you if the data is fresh or not. You can think of the isValidating flag as a loading indicator; it isn't quite the same thing but for my purposes it is.

Go ahead and create a use-crud.tsx file wherever you put your custom hooks and add this to start.

import useSWR, { ConfigInterface } from 'swr'
import { useCallback } from 'react'

// T is the response type
// K is the request type which defaults to T
export function useCrud<T, K = T>(url: string, key: keyof T, fetchOptions?: ConfigInterface) {
 const fetch = useCallback(
 async (url: string) => {
 const response = await fetch(url)
 return response as T[]
 },
 []
 )

const { data, error, isValidating, mutate } = useSWR(url, fetch, {
 fetchOptions
 })

return {
 fetch: {
 data,
 error,
 loading: isValidating,
 mutate
 }
 }
}

Making it user friendly

I'll go over the parameters and types later but for now all you need to know is that we will be able to pass a URL to this hook and it will give us the data and the methods to perform CRUD operations on that data. There's just one problem that I ran into. Sometimes the response is too quick for my app since we have the cached data to fall back on so I added a loading state and timeout to make the request take at least half a second. This will improve the user experience.

import { useCallback, useEffect, useState } from 'react'
import useSWR, { ConfigInterface } from 'swr'

// T is the response type
// K is the request type which defaults to T
export function useCrud<T, K = T>(url: string, key: keyof T, fetchOptions?: ConfigInterface) {
const [loading, setIsLoading] = useState(true)

const loadingTimeout = () => {
 setIsLoading(false)
 }

const fetch = useCallback(
 async (url: string) => {
 const response = await fetch(url)
 return response as T[]
 },
 []
 )

const { data, error, isValidating, mutate } = useSWR(url, fetch, {
 fetchOptions
 })

useEffect(() => {
 if (isValidating) {
 setIsLoading(true)
 return
 }

setTimeout(loadingTimeout, 500)
 }, [isValidating])

return {
 fetch: {
 data,
 error,
 loading,
 mutate
 }
 }
}

There's one little quirk with SWR that I need to mention. When there is no data from a request an empty object is returned; that's not really what I want so I added an extra step to check if the data is empty. For that I will use lodash, go ahead and install it if you haven't already. If the object is empty I will return an empty array instead, update your imports to add this.

import { isArray, isEmpty } from 'lodash'
import { useCallback, useEffect, useMemo, useState } from 'react'

We'll need the isArray method later for the CRUD operations and we'll be memoizing the result of the data check. Add this above the return statement.

const memoizedData = useMemo(() => (!isEmpty(data) ? data : []), [data])

And then return memoizedData instead of data.

return {
 fetch: {
 data: memoizedData,
 error,
 loading,
 mutate
 }
 }

C what I did there

Now the moment you've been waiting for, we're going to start modifying the data but before we do that let me explain the Typescript parameters of this function. The T generic type is the type of data we'll be expecting to get back and the K generic type is the type of data we will be using to perform the create operation. In most cases, this will be the same but in case we need to perform some operations on that data before sending it we will use a different type. As you can see it defaults to T anyway if we don't pass anything. The key in the parameters is a key of the type T which means any props on the type can be used but we need to tell typescript what the index key is so we can mutate the cached data from the fetch. The create operation will look like this.

const create = useCallback(
 async (newObject: K, shouldRevalidate = false) => {
 const response = await fetch(url, {
 body: newObject,
 method: 'POST'
 })

const result = response as T

if (data && mutate) {
 let newData = data
 if (isArray(data)) {
 newData = data.concat(result)
 }

await mutate([new Set(newData)], shouldRevalidate)
 }

return result
 },
 [url, data, mutate]
 )

Two is better than one

This will create a new object in our URL post method. If we have data it will mutate its cache if we don't we'll just return the result of the post. There is an additional check to see if the data is an array, if it is we will add the new object to the data array if it isn't we will add a new set of data and skip revalidation. I went ahead and added a parameter for revalidation that can be overridden if we want the new data and not just the cache. This will call the mutate function we got earlier and allow us to mutate the cache with the new data and return an optimistic response of what the new array should look like; all without fetching the data again. But this method will only work for creating a single instance so we will need one for creating multiple objects as well.

const createMultiple = useCallback(
 async (newObjects: K[], shouldRevalidate = false) => {
 const response = await fetch(url, {
 body: newObjects,
 method: 'POST'
 })

const result = response as T[]

if (data && mutate) {
 await mutate([data, result], shouldRevalidate)
 }

return result
 },
 [url, data, mutate]
 )

Gimme the D

This separate method will handle creating more than one object. One improvement would be to combine these but this will work for the purpose of the tutorial. Next, we'll handle the removal operation of CRUD. The function should look like this.

const remove = useCallback(
 async (body: number, shouldRevalidate = false) => {
 const response = await fetch(url, {
 body,
 method: 'DELETE'
 })
 const result = response as T

if (data && mutate) {
 if (isArray(result)) {
 const updatedObjects = [data].filter((current) => {
 const isDeleted = result.find((result) => result[key] === current[key])
 return !isDeleted
 })

 await mutate(result.length === 0 ? [] : updatedObjects, shouldRevalidate)
 } else {
 const deletedIndex = data.findIndex((object) => object[key] === result[key])

if (deletedIndex >= 0) {
 const updatedObjects = [data]
 updatedObjects.splice(deletedIndex, 1)

        await mutate(updatedObjects, shouldRevalidate)
       }
    }
 }

return result
 },
 [url, data, key, mutate]
 )

This will take a number for the key you are modifying so you can get that from the data you got from the original fetch and parse it according to whichever item you are removing. If the result of this operation is an array then we will find each item in the data that matches the key and remove it from the list. Otherwise, we will have to find the index of the object that was deleted and if it is in the list remove that index. One important note is that each of these requests should return the value of whatever object was manipulated so that we can update the cache. Removing multiple objects is very similar.

const removeMultiple = useCallback(
 async (ids: number[], shouldRevalidate = false) => {
 const response = await fetch(url, {
 body: ids,
 method: 'DELETE'
 })
 const results = response as T[]

if (data && mutate) {
 const updatedObjects = [data].filter((current) => {
 const isDeleted = results.find((result) => result[key] === current[key])
 return !isDeleted
 })

        await mutate(updatedObjects, shouldRevalidate)

        return results
       }
   },
 [url, data, key, mutate]
 )

U know what comes next

The update part of CRUD is a little different since the SQL server can throw an error if the rows being updated aren't different. For this, you should probably have some validation on the front end to make sure that doesn't happen but just in case I will make a check for it here using a method I stole. Create a helper method called get-object-difference.ts somewhere you can easily access it.

import { isEqual } from 'lodash'

/*
 * Compare two objects by reducing an array of keys in obj1, having the
 * keys in obj2 as the initial value of the result. Key points:
 *
 * ' All keys of obj2 are initially in the result.
 *
 * ' If the loop finds a key (from obj1, remember) not in obj2, it adds
 * it to the result.
 *
 * ' If the loop finds a key that is both in obj1 and obj2, it compares
 * the value. If it's the same value, the key is removed from the result.
 */
export function getObjectDifference(obj1: any, obj2: any) {
 const diff = Object.keys(obj1).reduce((result, key) => {
 if (!obj2.hasOwnProperty(key)) {
 result.push(key)
 }
 return result
 }, Object.keys(obj2))

return Object.fromEntries(
 diff.map((key) => {
 return [key, obj2[key]]
 })
 )
}

This method will return an object of the difference between two objects otherwise it will return an empty object if there is none. Go ahead and import it into the useCrud file and add the update method.

const update = useCallback(
 async (updatedObject: T, shouldRevalidate = false): Promise<T> => {
 const currentObjectIndex = data.findIndex((object) => object[key] === updatedObject[key])
 const currentObject = data[currentObjectIndex]
 const diff = currentObject ? getObjectDifference(currentObject, updatedObject) : null

if (!diff) {
 throw new Error('Update Failed')
 }

if (isEmpty(diff)) {
 return currentObject
 }

const response = await fetch(url, {
 body: { diff, id: updatedObject[key] },
 method: 'PATCH'
 })

if (data && mutate) {
 const updatedObjects = [data]
 updatedObjects.splice(currentObjectIndex, 1, response)
 await mutate(updatedObjects, shouldRevalidate)
 }

return response as T
 },
 [url, data, mutate, key]
 )

This will check the cache for the current object you are modifying and get the difference between the old object and the new one. If the current object doesn't exist in the cache it will throw an error. Otherwise, if there is no difference it will just return the current object and not execute the fetch request to patch. If there is a difference it will pass the difference and the updated object's id as whatever key you specified earlier on the updated object. It will then go ahead and perform the mutate on the cached data, updating multiple objects is slightly different.

const updateMultiple = useCallback(
 async (updatedObjects: T[], shouldRevalidate = false): Promise<T[]> => {
 const currentObjects = data.filter((object) => updatedObjects.find((updated) => object[key] === updated[key]))

if (!currentObjects || currentObjects <= 0) {
 throw new Error('Update Failed')
 }

const diffs = currentObjects.map((currentObject) => {
 const updatedObject = updatedObjects.find((updated) => updated[key] === currentObject[key])
 return { getObjectDifference(currentObject, updatedObject), id: updatedObject[key] }
 })

if (diffs.length <= 0) {
 return currentObjects
 }

const response = await fetch(url, {
 body: { diffs },
 method: 'PATCH'
 })

if (data && mutate) {
 const updatedObjects = [data].map((current) => {
 if (current[key] === response[key]) {
 return response
 }

   return current
 })

   await mutate(updatedObjects, shouldRevalidate)
 }

return response as T[]
 },
 [url, data, mutate, key]
 )

This will run the difference check on all the objects and instead pass an array of object differences in the body. All of these implementations are of course specific to my API routes but they could easily be modified to work with your use case.

Wrapping up this spelling lesson

Phew! If you made it this far I owe you a drink but since I can't buy you one right now instead I'll give you the full code.

import { isArray, isEmpty } from 'lodash'

import { useCallback, useEffect, useMemo, useState } from 'react'

import useSWR, { ConfigInterface } from 'swr'

import { getObjectDifference } from '../where-ever-you-put-this-earlier'

// T is the response type

// K is the request type which defaults to T

export function useCrud<T, K = T>(url: string, key: keyof T, fetchOptions?: ConfigInterface) {

const [loading, setIsLoading] = useState(true)

const loadingTimeout = () => {

setIsLoading(false)

}

const fetch = useCallback(

async (url: string) => {

const response = await fetch(url)

return response as T[]

},[])

const { data, error, isValidating, mutate } = useSWR(url, fetch, {fetchOptions})

useEffect(() => {

if (isValidating) {

setIsLoading(true)

return

}setTimeout(loadingTimeout, 500)},

[isValidating])

const create = useCallback(

async (newObject: K, shouldRevalidate = false) => {

const response = await fetch(url, {

body: newObject,

method: 'POST'

})

const result = response as T

if (data && mutate) {

let newData = data

if (isArray(data)) {

newData = data.concat(result)

}

await mutate([new Set(newData)], shouldRevalidate)

  }

return result

},[url, data, mutate])

const createMultiple = useCallback(async (newObjects: K[], shouldRevalidate = false) => {

const response = await fetch(url, {

body: newObjects,

method: 'POST'

})

const result = response as T[]

if (data && mutate) {

await mutate([data, result], shouldRevalidate)}

return result

},[url, data, mutate])

const remove = useCallback(async (body: number | unknown, shouldRevalidate = false) => {

const response = await fetch(url, {

body,

method: 'DELETE'

})

const result = response as T

if (data && mutate) {

if (isArray(result)) {

const updatedObjects = [data].filter((current) => {

const isDeleted = result.find((result) => result[key] === current[key])

return !isDeleted

})

await mutate(result.length === 0 ? [] : updatedObjects, shouldRevalidate)

} else {

const deletedIndex = data.findIndex((object) => object[key] === result[key])

if (deletedIndex >= 0) {

const updatedObjects = [data]

updatedObjects.splice(deletedIndex, 1)

    await mutate(updatedObjects, shouldRevalidate)
  }



}

}

return result

},[url, data, key, mutate])

const removeMultiple = useCallback(async (ids: number[], shouldRevalidate = false) => {

const response = await fetch(url, {

body: ids,

method: 'DELETE'

})

const results = response as T[]

if (data && mutate) {

const updatedObjects = [data].filter((current) => {

const isDeleted = results.find((result) => result[key] === current[key])

return !isDeleted

})

 await mutate(updatedObjects, shouldRevalidate)

 return results



}

},

[url, data, key, mutate])

const update = useCallback(async (updatedObject: T, shouldRevalidate = false): Promise<T> => {

const currentObjectIndex = data.findIndex((object) => object[key] === updatedObject[key])

const currentObject = data[currentObjectIndex]

const diff = currentObject ? getObjectDifference(currentObject, updatedObject) : null

if (!diff) {

   throw new Error('Update Failed')

}

if (isEmpty(diff)) {

   return currentObject

}

const response = await fetch(url, {

body: { diff, id: updatedObject[key] },

method: 'PATCH'

})

if (data && mutate) {

const updatedObjects = [data]

updatedObjects.splice(currentObjectIndex, 1, response)

  await mutate(updatedObjects, shouldRevalidate)

}

return response as T

},[url, data, mutate, key])

const updateMultiple = useCallback(async (updatedObjects: T[], shouldRevalidate = false): Promise<T[]> => {

const currentObjects = data.filter((object) => updatedObjects.find((updated) => object[key] === updated[key]))

if (!currentObjects || currentObjects <= 0) {

  throw new Error('Update Failed')

}

const diffs = currentObjects.map((currentObject) => {

  const updatedObject = updatedObjects.find((updated) => updated[key] === currentObject[key])

return { getObjectDifference(currentObject, updatedObject), id:   updatedObject[key] }

})

if (diffs.length <= 0) {

  return currentObjects

}

const response = await fetch(url, {

body: { diffs },

method: 'PATCH'

})

if (data && mutate) {

  const updatedObjects = [data].map((current) => {

   if (current[key] === response[key]) {

  return response

}

  return current

})

await mutate(updatedObjects, shouldRevalidate)

}

  return response as T[]

},[url, data, mutate, key])

const memoizedData = useMemo(() => (!isEmpty(data) ? filterDeleted<T>(data) : []), [data])

return {

    create,

    createMultiple,

    fetch: { data: memoizedData, error, loading, mutate },

    remove,

    removeMultiple,

    update,

    updateMultiple

  }

}

Conclusion

Congratulations you've made it through this tutorial, this hook should give you all the functionality you need to perform CRUD operations with a custom restful API. This implementation is specific to my API so you may have to modify it for your use purposes but it is generic enough to be used in most cases. Thanks for joining me, I hope you enjoyed this load of CRUD.

Please follow me on Twitter: @SquashBugler

You're doing Javascript exports wrong, here's why.

John Grisham — Fri, 13 Nov 2020 16:09:16 +0000

To support me please read this tutorial at its original posting location on Medium:
You're doing Javascript exports wrong, here's why.

A lot of starting developers wonder what is the best way to export something. Maybe for you it's just about your personal preference and what you're used to but surely there must be some sort of best practice right? Should you use default exports or named? Should you export from the file itself or an index? The answer to these questions is yes.

I'm going to make a bold statement here. The code you write isn't for you. (Unless you're the type that enjoys being a hermit and never working with others). Before I get into why this matters here's an explanation of each flavor of export.

Default exports

Exporting: export default thing
Importing: import thingy from 'place'

This is pretty basic you have one thing that you want to export and it doesn't matter what it's called only that it's the main thing being exported. Note that above although I exported the package as 'thing' I am importing it as 'thingy'. That's because default imports don't care about names only that they are the default package. These are great for namespaces or roots of libraries where aliasing is ok.

Named exports

Exporting: export const thing / export { thing }
Importing: import { thing } from 'place'

The main difference here is the brackets. We denote a named import with these and as the name implies it has to be called the same Importing it as we exported it. I personally prefer named exports because we are forced into using consistent names this way and avoids confusion.

File exports

Importing: import Bob from './street/bobs-house'

There is no export example here because it doesn't matter how we export it but where we export it from. In this example we would export from the file where our code exists. Think of a house where someone lives. If I want to find Bob I go to Bob's house directly.

Indexed exports

Exporting: export { Bob } from './bobs-house'
Importing: import { Bob } from './street'

What if I don't know where Bob lives but I do know the street. Well this is where an index would come in handy. Think of an index as a phone book (wow did I just show my age) or Google maps. It's basically a way to direct us from the street in this example to the house.

So in your street folder you would have two files, bobs-house and the index file. When you import from a folder without specifying a file JavaScript will import the index file by default. This can be great when you have a bunch of individual files that you want to import from on the same line.

So why should you care about other developers when you export? Well think of it like this Imagine that your code is a dinner party. And your teammates or party guests are attending. In this situation you would want to be a good host correct? And since different developers prefer importing in different ways we should try to be as accommodating as possible.

That means putting in the extra work to export our files as many ways as possible. So they can have a main course of default import and a side of named too. Thanks for joining me, I hope I was a good host!

Follow me on Twitter to get this article and others: @SquashBugler

Adding Firebase Authentication in Gatsby With a Little Typescript Magic

John Grisham — Tue, 27 Oct 2020 13:26:07 +0000

To support me please read this tutorial at its original posting location on Medium:
Setup Gatsby Firebase Authentication with Typescript in 10 minutes

Gatsby is a great framework for building and designing a website but what about authentication? Well That's where firebase comes in, I've read a few articles and posts about how to integrate firebase with GatsbyJS but most of them didn't involve typescript support. They also failed to explain keeping a user logged in, or setting up private routes. It's important that authentication be tracked in the browser and app state. That's why my approach will provide further customization and help you follow security best practices, let's get started!

Setting up the Gatsby project

First, you'll want to add the Gatsby client globally, use either depending on preference but I prefer yarn:

# using YARN
yarn global add gatsby-cli
# using NPM
npm install gatsby-cli -g

And then create the new project with gatsby-cli:

gatsby new project-name https://github.com/resir014/gatsby-starter-typescript-plus

There are a few different forks of the original gatsby-default starter but I chose this one because it had a decent number of stars and forks.

Then change directories to be in the new project:

cd project-name/

Then install the project dependencies:

# using NPM
npm install
# using YARN
yarn

This may take a while to install all the dependencies but be patient... Once it's done open the project in your preferred text editor, personally I use VS code and if you're on the fence about what you should use I highly recommend it. You should then be able to start your project by running this from the project root.

# using NPM
npm start
# using YARN
yarn start

Open up a browser window and go to http://localhost:8000 and you should see a basic landing page, fancy!

Getting Firebase set up

Now we need to make a firebase account and add that to our project. Create a firebase account and follow this guide then come back here when you're done.

https://firebase.google.com/docs/web/setup

You now have a firebase project in the firebase console, now to add firebase to the Gatsby project:

# using YARN
yarn add firebase
# using NPM
npm install firebase

Now in the firebase console go into your project settings and find your app config once you have that create an env file in the Gatsby app project root and call it .env.development this will be your development environment file where you'll store secret or universal app information.

// .env.development

GATSBY_FIREBASE_APIKEY={YOUR_API_KEY}
GATSBY_FIREBASE_AUTHDOMAIN={YOUR_AUTHDOMAIN}
GATSBY_FIREBASE_DATABASEURL={YOUR_DATABASE_URL}
GATSBY_FIREBASE_PROJECTID={YOUR_PROJECTID}
GATSBY_FIREBASE_STORAGEBUCKET={YOUR_STORAGE_BUCKET}
GATSBY_FIREBASE_MESSAGINGSENDERID={YOUR_MESSAGING_SENDER_ID}
GATSBY_FIREBASE_APPID={YOUR_APPID}
GATSBY_FIREBASE_MEASUREMENTID={YOUR_MEASUREMENTID}

You should be able to find all these values from the config you found earlier in the firebase project console. Now in the src folder add a services folder and create a firebase provider file called FirebaseProvider.tsx this will be our firebase provider that will store and pass the firebase context we'll create for use throughout the app.


    // FirebaseProvider.tsx

    import React from 'react'
    import firebase from 'firebase'

    // Your config that you stored in the env file.
    const firebaseConfig = {
     apiKey: process.env.GATSBY_FIREBASE_APIKEY,
     appId: process.env.GATSBY_FIREBASE_APPID,
     authDomain: process.env.GATSBY_FIREBASE_AUTHDOMAIN,
     databaseURL: process.env.GATSBY_FIREBASE_DATABASEURL,
     measurementId: process.env.GATSBY_FIREBASE_MEASUREMENTID,
     messagingSenderId: process.env.GATSBY_FIREBASE_MESSAGINGSENDERID,
     projectId: process.env.GATSBY_FIREBASE_PROJECTID,
     storageBucket: process.env.GATSBY_FIREBASE_STORAGEBUCKET
    }
    // The type definition for the firebase context data.

    export interface FirebaseContextData {
     isInitialized: boolean
     firebase: typeof firebase
     authToken: string | null
     setAuthToken: (authToken: string) => void
    }
    // The firebase context that will store the firebase instance and other useful variables.

    export const FirebaseContext = React.createContext<FirebaseContextData>({
     authToken: null,
     firebase,
     isInitialized: false,
     setAuthToken: () => {}
    })

    // The provider that will store the logic for manipulating the firebase instance and variables.

    export const FirebaseProvider: React.FC = ({ children }) => {
     const [isInitialized, setIsInitialized] = React.useState(false)

    // If we have a window and the authToken already exists in localstorage then initialize the authToken value otherwise null.

    const [authToken, setAuthToken] = React.useState<FirebaseContextData['authToken']>(
     typeof window === 'object' ? window.localStorage.getItem('authToken') : null
     )

     // If firebase has not been initialized then initialize it.
     if (!firebase.apps.length) {
     firebase.initializeApp(firebaseConfig)
     setIsInitialized(true)
     }

     // A method for setting the authToken in state and local storage.
     const onSetAuthToken = (token: string) => {
     setAuthToken(token)
     localStorage.setItem('authToken', token)
     }

     // If we have the window object and there is no authToken then try to get the authToken from local storage.
     React.useEffect(() => {
     if (typeof window === 'object' && !authToken) {
     const token = window.localStorage.getItem('authToken')

       if (token) {
         onSetAuthToken(token)
         }
       }
    }, [authToken])

    return (
     <FirebaseContext.Provider
     value={{
     authToken,
     firebase,
     isInitialized,
     setAuthToken: onSetAuthToken
     }}>
     {children}
     </FirebaseContext.Provider>
     )
    }

This might seem complicated but it really only does a few things.

It initializes the firebase app
It sets up the context that will provide a reference to the firebase instance
It creates state and set state methods for tracking authentication
It provides the context with the firebase instance to the rest of the app

For more on contexts and how they work: https://reactjs.org/docs/context.html

Using the firebase context

Inside the services folder create an index.ts file that will export all of our services.

// index.ts

export { FirebaseContext, FirebaseProvider } from './FirebaseProvider'

This exports the context and provider. Then inside the components folder find the LayoutRoot.tsx file and wrap the provider around it.

// LayoutRoot.tsx

import * as React from 'react'
import { Global, css } from '@emotion/core'
import { FirebaseProvider } from '../services'
import styled from '@emotion/styled'
import normalize from '../styles/normalize'

const StyledLayoutRoot = styled.div`
 display: flex;
 flex-direction: column;
 min-height: 100vh;
`
interface LayoutRootProps {
 className?: string
}

const LayoutRoot: React.FC<LayoutRootProps> = ({ children, className }) => (
 <FirebaseProvider>
 <Global styles={() => css(normalize)} />
 <StyledLayoutRoot className={className}>{children}</StyledLayoutRoot>
 </FirebaseProvider>
)

export default LayoutRoot

This will provide our context to the rest of the app. Also in the services folder create a types folder and inside that create a file called AuthError.tsx that will export the error type we'll need in a minute.

// AuthError.tsx

import { FirebaseError as FBError } from 'firebase'
export type AuthError = FBError & Error

And then export that from the root of services like so.

In the index.ts file of the services folder:

// index.ts

export { FirebaseContext, FirebaseProvider } from './FirebaseProvider'
export { AuthError } from './types/AuthError'

This is an error type that will come in handy when catching errors that we might get from firebase authentication. Now find the Page component in src/components/Page.tsx and make some changes.

// Page.tsx

import * as React from 'react'
import { FirebaseContext } from '../services'
import styled from '@emotion/styled'
import { dimensions } from '../styles/variables'

const StyledPage = styled.div`
 display: block;
 flex: 1;
 position: relative;
 padding: ${dimensions.containerPadding}rem;
 margin-bottom: 3rem;
`

interface PageProps {
 className?: string
}

const Page: React.FC<PageProps> = ({ children, className }) => { 
 const { isInitialized } = React.useContext(FirebaseContext)
 console.log(`firebase instance is ${isInitialized ? 'initialized' : 'not initialized'}`)

 return(<StyledPage className={className}>{children}</StyledPage>)
}

export default Page

You may have to refresh the page but you should get a message logged in the console that says the instance has been initialized. You can go ahead and remove these changes if it worked. Now we will add some more dependencies for creating the login page.

Making it stylish! The login page edition

# using YARN
yarn add @material-ui/core @fortawesome/react-fontawesome @fortawesome/free-brands-svg-icons
# using NPM
npm install @material-ui/core @fortawesome/react-fontawesome @fortawesome/free-brands-svg-icons

We'll need material and font awesome to quickly make the login page. In components create a Login.tsx file that will handle our login logic.


    // Login.tsx

    import { AuthError, FirebaseContext } from '../services'
    import { Button, FormControl, FormHelperText, Input, InputLabel } from '@material-ui/core'
    import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
    import React from 'react'
    import { auth } from 'firebase'
    import { faGoogle } from '@fortawesome/free-brands-svg-icons'
    import { navigate } from 'gatsby'

    const Login: React.FC = () => {
     // get the variables we need for authentication.
     const { firebase, authToken, setAuthToken } = React.useContext(FirebaseContext)
     // setup some state variables for login
     const [email, setEmail] = React.useState<string>('')
     const [password, setPassword] = React.useState<string>('')

     // The method for handling google authentication
     const handleGoogleAuth = React.useCallback(
         async (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
     try {
        event.preventDefault()
        const provider = new firebase.auth.GoogleAuthProvider()
    // get the credential from the google auth.
        const { credential } = await   firebase.auth().signInWithPopup(provider)
     // if we have a credential then get the access token and set it in state.

        if (credential) {
    // This has to be assigned to the oathcredential type so that we can get the accessToken property.

    const { accessToken } = credential as auth.OAuthCredential
     setAuthToken(accessToken as string)
       }
     } catch (e) {
     console.log(e)
       }
     },
     [firebase, setAuthToken]
     )

     // Method for signing up and logging in.
     const handleSignupAndLogin = React.useCallback(
     async (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
     let authError: AuthError | undefined
    try {
     event.preventDefault()
     // Try to create a new user with the email and password.
     const { user } = await firebase.auth().createUserWithEmailAndPassword(email, password)

    // If successful and we have a user the set the authToken.
     if (user) {
     const { refreshToken } = user
     setAuthToken(refreshToken)
       }
     // If there is an error set the authError to the new error
     } catch (error) {
     authError = error
     } finally {
     // If there is an authError and the code is that the email is already in use, try to sign 
    // the user in with the email and password instead.

     if (authError?.code === 'auth/email-already-in-use') {
     const { user } = await firebase.auth().signInWithEmailAndPassword(email, password)
     // We've been here before... set the authToken if there is a user.

           if (user) {
           const { refreshToken } = user
           setAuthToken(refreshToken)
           }
         }
       }
     },
     [email, password, firebase, setAuthToken]
     )

    // Effect that will reroute the user to the index.tsx file if there is an authToken
     React.useEffect(() => {
     if (authToken) {
     navigate('/')
     }
     }, [authToken])

    return (
     <form style={{ display: 'flex', flexDirection: 'column' }}>
       <FormControl>
         <InputLabel htmlFor="email">Email address</InputLabel>
         <Input id="email" aria-describedby="email-helper" value={email}
          onChange={(event) => setEmail(event.currentTarget.value)} />
         <FormHelperText id="email-helper">We&apos;ll never share your email.</FormHelperText>
       </FormControl>
       <FormControl>
         <InputLabel htmlFor="password">Password</InputLabel>
          <Input id="password" value={password} onChange={(event) =>   setPassword(event.currentTarget.value)} />
       </FormControl>
       <Button type="submit" variant="contained" color="primary" style={{ marginTop: '10px' }} onClick={handleSignupAndLogin}>
     Login / Sign Up
       </Button>
       <Button type="button" variant="contained" color="primary"
        style={{ marginTop: '10px' }} onClick={handleGoogleAuth}>
       <FontAwesomeIcon icon={faGoogle} style={{ marginRight: '10px' }} />
     Login With Google
     </Button>
     </form>
     )
    }

    export default Login

The login component will handle sign in and sign up as well as google authentication, neat! Before all of this will work though you'll have to enable these sign in options from the firebase project console; there's a brief explanation of how to do this in the firebase documentation.

https://firebase.google.com/docs/auth/web/password-auth
https://firebase.google.com/docs/auth/web/google-signin

Once that's done you'll have to create the page that will use the login component we just created go into the pages folder and create a login.tsx file.

// login.tsx

import * as React from 'react'
import Page from '../components/Page'
import Container from '../components/Container'
import IndexLayout from '../layouts'
import Login from '../components/login'

const LoginPage = () => (
 <IndexLayout>
 <Page>
 <Container>
 <Login />
 </Container>
 </Page>
 </IndexLayout>
)

export default LoginPage

Preventing users from seeing things they shouldn't

Now, in components create a PrivateRoute.tsx file that we will use to prevent unauthenticated users from seeing content that they shouldn't be allowed to access.

// PrivateRoute.tsx

import * as React from 'react'
import { FirebaseContext } from '../services'
import { navigate } from 'gatsby'

interface PrivateRouteProps {
 path: string
}

const PrivateRoute: React.FC<PrivateRouteProps> = ({ children, path }) => {
 const { authToken } = React.useContext(FirebaseContext)

if (!authToken && window.location.href !== path) {
 navigate(path)
 return null
 }

return <>{children}</>
}

export default PrivateRoute

This will re-route users to the login page if they try to access anything that is nested in this component. Finally, we just have to add this component to our index.tsx file in pages.

// index.tsx

import * as React from 'react'
import { Link } from 'gatsby'
import Page from '../components/Page'
import Container from '../components/Container'
import IndexLayout from '../layouts'
import { PrivateRoute } from '../components/PrivateRoute'

const IndexPage = () => (
 <IndexLayout>
   <Page>
    <PrivateRoute path="/login">
     <Container>
      <h1>Hi people</h1>
      <p>Welcome to your new Gatsby site.</p>
      <p>Now go build something great.</p>
      <Link to="/page-2/">Go to page 2</Link>
     </Container>
    </PrivateRoute>
   </Page>
 </IndexLayout>
)

export default IndexPage

This will tell the index page to re route to the login page if there isn't an authToken and therefore the user is not logged in. You'll still have to implement signing out but all that involves is making the token expire somehow. You'll probably want to separate the signin / signup flow at some point as well but this will get you a good start on authentication.

That concludes this tutorial on GatsbyJS and firebase, this solution is an improvement on some of the other tutorials I've seen that don't use typescript or store the firebase instance in state. By tracking the authToken we get more control over the state and we can easily add new fields to our context.

I hope you've learned something from this article and if you have any questions feel free to leave a comment below I will be writing more articles in the future on other topics that I feel haven't been covered well enough or that I struggled with, thanks for joining me!

Please follow me on Twitter: @SquashBugler