Monica's Digital Playground

2019 into 2020, Year in Review

Wed, 01 Jan 2020 02:43:13 GMT

The past decade included many transitions for me, from graduating high school to graduating from my dream college in New York City to successfully switching careers and becoming a software developer.

I’m hoping in the next decade that I can continue to do meaningful work to make it easier for underrepresented folks to thrive in tech roles, learning how to work smarter not harder, further develop my sense of self & identity outside of my career/professional skills, and tackle some of my vices for the long run (holding onto things too long and procrastinating esp. when that means more work or trouble for me later, etc.).

I could go on and on about the last 10 years but it's officially 2020 and I've decided to start by writing my first public year in review!

In 2019, I started to learn new technologies including TypeScript, Concourse, GraphQL, etc. and explored new-to-me areas of the codebase at my full-time job. At work, I presented my product engineering work at various internal demo days, had the opportunity to work with more legacy code and also contribute to production-level software from its inception. In 2018, I primarily contributed to a relatively new (but pre-existing) software project. Whereas, in 2019 I had the chance to create a deployment pipeline, streamline the creation of new packages via CLI prompts (which inspired my talk on generating React components at React Girls Conf in London) and lead more independent projects and investigations.

Sketchnotes by [@malweene](<Tweet tweetLink="malweene) from my talk at React Girls Conf

Below are some professional-related highlights of my year:

Redesigning My Site

I've started to consider my site my playground (similar to a digital garden worthy of a love letter.

I decided to completely re-do my website in September and am pretty happy with where it landed. Instead of managing a separate blog and portfolio site I combined the two which has given me the flexibility to experiment with different website content hierarchies. The site was written with GatsbyJS and through building my site I learned more about writing JavaScript in a server-side rendered site and how to use GraphQL in Gatsby. The previous version of my site was using outdated technology and in my opinion, was difficult to update as it wasn't modularized.

Throughout the year I had a desire to be more creative and learn in public more and so far my site has allowed me a creative outlet to explore and provided me opportunity to share some of my learnings from my explorations like How To Add Search Functionality to a Gatsby Blog and Less JavaScript Makes Font Awesome More Awesome. While building out my site with GraphQL I also started using GraphQL more at work as both an API consumer and developer. I learned more tech-wise throughout the year both at work and beyond I want to push myself to explore new creative mediums in the future as that is something I wish I had done more of.

More Public Speaking and Community Involvement

After attending Global Diversity CFP Day in March, I leaned into more public speaking and even spoke internationally. I spoke at a Women Who Code NYC, useReact NYC, React Girls Conference, React Conf, Barnard College (2x), Columbia University and The Flatiron School. I also made my podcast debut and was featured on an episode of the Egghead.io podcast where I discussed my journey to landing my first engineering role, attending and organizing meetups and contributing to open-source.

At the end of 2018, I was accepted into Dev/Color and as I'm writing this I just completed my first year. Being a part of Dev/Color and having the opportunity to connect with other Black software engineers has helped me grow in terms of developing professional development goals as an engineer. Before I transitioned into engineering full-time a lot of my professional goals were tied to just getting in the door as an engineer and after I started working as an engineer I needed to start shifting my goals in the context of "okay, I'm an engineering individual contributor now what?".

In 2017, I went to Ela Conf where I met people who changed my life (Michelle, Lauren, Laura, Kristen)! Ela Conf was an inclusive tech conference and community for cis women, trans men and trans women, and gender-queer people. I wrote about what I learned from attending Ela Conf which was centered around self-care, inclusion, diversity, learning, and growth.

To this day I continue to be involved with a ~ goal ~ group that spun out of Ela Conf and act as a facilitator. We have weekly check-ins and monthly video calls which have provided a consistent time for me to check in with myself and others about what we'd like to accomplish. When I first joined this group I was not yet working as a software engineer and it has been inspiring to see over the last 2+ years how my goals and accomplishments along with everyone else in that group have evolved.

In addition to joining other communities, I hosted 7 React Meetup events for the React Ladies community which I founded in 2018. I am looking forward to hosting more events in 2020 and finding co-organizers. Our next scheduled event is Global Diversity CFP Day in January. If you’re interested in being a co-organizer of React Ladies e-mail me at monica[at]aboutmonica.com. One of my highlights of React Ladies from 2019 was the Hacktoberfest we hosted with StackOverflow which helped make contributing to open-source feel less scary to some people.

Another highlight was seeing the community rally together to provide Sylwia Vargas, a React Ladies member a free ticket to a Kent C. Dodds workshop, thank you Donavon West and Christian Nwamba!

In the larger React community, I was featured in a zine that was distributed at React Conf alongside some amazing women involved in the React community. Thanks to Rachel Nabors for putting this project together and for including me.

Overall, I am excited about what I accomplished in 2019 and for what's to come in 2020. I want to focus on helping other underrepresented folks in tech thrive, dive deeper into API development (REST + GraphQL), build a stronger understanding of Computer Science (data structures and algorithms), learn in public more and continue public speaking. In terms of non-engineering related goals, I want to discover new hobbies(and do more things without a practical purpose), explore different creative outlets, digital and analog illustration and expand on the fitness routine I doubled-down on last year.

I hope 2020 gives us all a fresh start.

Note: If you encounter strange formatting in your RSS feed reader, I'm still tweaking my RSS feed settings to display my content (which is written in MDX) properly. For a better content-viewing experience I encourage visiting the article directly.

Automating File Creation With JavaScript

Wed, 29 Jan 2020 12:40:44 GMT

Do you ever find yourself copying and pasting the same boilerplate code for multiple files at a time? Do you stop and think every time you have to construct an ISO 8601 formatted date? 🤔 How frustrating would it be if you could no longer copy and paste your template code from one file to another?

This article will walk through how to quickly create a command-line interface (CLI) tool that generates text-based files. In particular, the examples in this article will walk through how to create templates to generate a new .jsx Page in a Gatsby blog with tests as well as how to generate markdown files with the initial structure of a blog post. These examples should serve as inspiration as the sky is the limit in regards to what type of text files can be generated based on the needs of a particular developer or project.

Why Scaffolding?

The CLI we will be creating is a type of scaffolding software as it generates starter code based on templates. Note that starter code generated by scaffolding generally is not ready for production however it still has benefits as it can improve the developer experience, make it easier to implement standardization and enable faster software delivery.

Some of the benefits of scaffolding can be:

involving less work - no more copying and pasting boilerplate code (i.e., relative imports from one file to another)
automating the implementation of design patterns and best practices
reducing time to generate new projects or components
being less error-prone than the manual process of copy & pasting & editing
encouraging consistency and implementation of design patterns

Scaffolding can answer questions like:

Where should translations for this React component live?
Where can I find our current code standards?
What directory should this type of file live in?
Should I use cameCase? snake_case? kebab-case? PascalCase? UPPERCASE_SNAKE_CASE?

Is scaffolding "worth it"?

Implementing scaffolding takes time. The potential benefits of scaffolding a particular piece of software versus time involved in developing it should be assessed to determine if it's worth the time and effort to implement scaffolding. If we are analyzing the estimated time invested vs. saved and not other intangible benefits like consistency or reducing context switching you can use the below XKCD comic to assess if it's worth implementing.

xkcd Is It Worth the Time?

In terms of other potential down-sides, code requirements often evolve over time and scaffolded templates may require future maintenance as new requirements surface. Ideally refactoring the scaffolding template should feel like a natural extension of a workflow versus like maintenance is additional overhead and slowing down the process. Some implementation details or decisions can be concealed by scaffolding which can reduce context depending on the tool the actual logic being used to generate files can be easily accessible.

Micro-generator tool: PlopJS

If you’re looking for a lightweight way to introduce scaffolding into your workflow consider using Plop, a micro-generator. Plop allows developers to generate files based on user input via a Command Line Interface (CLI) with minimal setup.

How does Plop work?

PlopJS combines the Handlebars templating language and Inquirer.js. Inquirer.js is a tool for collecting user input via CLI. You can present questions a.k.a CLI prompts in different formats with inquirer. Handlebars is a templating language that you may be familiar with. Templating languages are used in a variety of contexts from displaying React props, creating e-mail templates, or even making your workflow easier as we'll see today. Before, I was using .jsx in React I worked with the Liquid templating language in Jekyll and Handlebars in Foundation for Emails.

By combining the functionality of Inquirer.js with Handlebars, plop allows users to quickly create templates with minimal setup. If you're not familiar with software templates you can think of them as similar to mail merge in a word processor. In mail merge, there's generally a spreadsheet with data which is and then merged with a template document that has placeholder variables. When the data and template are combined with mail merge the result is a version of the document that contains data in the proper places (as determined by the placeholder variables). The data in that file is populated during the mail merge process and customized as appropriate for the recipient. In our case, the data entered in the CLI will be populated into the template and generate a new file when we run plop.

Plop Set Up

If you already have a directory with a package.json where you want to generate files then Plop can be installed with yarn with the following command:

yarn add -D plop

or npm using:

 npm install —save-dev plop

If you don't already have a package.json you can create one by typing yarn init or npm init and walking through the steps and then installing plop.

Once plop is installed as a package dependency we should update the scripts in the package.json file to enable us to run yarn plop or npm plop to run plop. You can name "plop" whatever you want the command to be for example "generate": "plop" and it will behave the same way.

"scripts": {
 "plop": "plop"
}

Unlike code snippets, plop doesn’t require additional setup to share between computers or across developers and lives in version control. Also, plop allows multiple files to be generated at once.

Now we can create our first plopfile.js in the root level of our directory which is where the plop magic will happen.

plopfile.js:

module.exports = function (plop) {
  /* welcome messag that will display in CLI */
  plop.setWelcomeMessage(
    "Welcome to plop! What type of file would you like to generate?",
  ),
    /* name and description of our template */
    plop.setGenerator("generate blog post ✏️", {
      description: "Template for generating blog posts",

      prompts: [
        /* inquirer prompts */
        /* questions we want to ask in CLI and save questions for*/
      ],

      actions: [
        /* what should be generated based off of the above prompts */
      ],
    });
};

Now that we have a baseline plopfile.js let's add some functionality. First we will add the ability to generate the frontmatter or metadata that needs to appear on every draft blog post in order for Gatsby to properly generate it.

sample frontmatter:

---
title: Automating File Creation With JavaScript
pubDate: 2020-01-14T12:40:44.608Z
template: "post"
slug: 2020-01-14-automating-file-creation-with-javascript
category:
  - tutorial
description: This article walks through how to use plop a micro-generator to generate new text-based files.
---

We should update the plop file to add built-in functionality to format today's date into an ISOString and use Inquirer (built into Plop) to create CLI prompts and collect input. We will use new Date(Date.now()) to get the current date. We will format the date both as an ISOStringDate: 2020-01-14T12:40:44.608Z and as a shortDate: 2020-01-14. The ISOStringDate will be used in the frontmatter whereas theshortDatewill be used in the file path of the newly generated file. The date utils will be returned bysetplop.setHelper()in order to expose the values in our.hbstemplates by writing{{ISOStringDate}}or{{shortDate}}.

In terms of collecting input in prompts the basic structure of a prompt is

{
  // example inquirer types:
  // input, list, raw list, expandable list, checkbox, password, editor
  // learn more here: https://github.com/SBoudrias/Inquirer.js#prompt-types
  type: "input",

  name: "description",

  message: "Description of post:",

  }

The most complex prompt in this example is this list prompt which allows users to use arrow keys to select the category for their blog post and then we transform that value to a lowercase string. The filter prompt can be used to convert a user-friendly value like "yellow" to being inserted in the template as #ffff00.

 {
          type: "list",
          name: "category",
          message: "Category:",
          choices: ["Tutorial", "Reflection"],
          filter: function(val) {
            return val.toLowerCase()
          },
        },

Once all of the prompts are squared away we need to do something with the input by adding an action:

{
          type: "add",
          path: `content/blog/${shortDate}-{{dashCase title}}.md`,
          templateFile: "src/plop-templates/blog-post.hbs",
        },

A type of action add creates a new file at the path and interpolates the responses from the prompts and values from plop helpers into the templateFile.

The complete plopfile.js at this point should look something like this:

module.exports = function (plop) {
  const today = new Date(Date.now());
  const shortDate = today.toISOString().split("T")[0];
  plop.setHelper("shortDate", () => shortDate),
    plop.setHelper("ISOStringDate", () => today.toISOString()),
    // optional welcome message

    plop.setWelcomeMessage(
      "Welcome to plop! What type of file would you like to generate?",
    ),
    plop.setGenerator("blog post ✏️", {
      description: "template for generating blog posts",
      prompts: [
        {
          type: "input",
          name: "title",
          message: "Title of post:",
        },
        {
          type: "input",
          name: "description",
          message: "Description of post:",
        },

        {
          type: "list",
          name: "category",
          message: "Category:",
          choices: ["Tutorial", "Reflection"],
          filter: function (val) {
            return val.toLowerCase();
          },
        },
      ],
      actions: [
        {
          type: "add",
          path: `content/blog/${shortDate}-{{dashCase title}}.md`,
          templateFile: "src/plop-templates/blog-post.hbs",
        },
      ],
    });
};

In order to actually use this we need to create the blog-post.hbs template in our src/plop-templates/ directory. This .hbs file is where we parametrize the code to only keep the bits that we need from file to file and to have placeholders for things that change based on the name or type of thing that is being generated. Plop has built-in case helpers like titleCase or dashCase to format input (view the built-in case modifiers at: https://plopjs.com/documentation/#case-modifiers)

blog-post.hbs

--- title:
{{titleCase title}}
# from title prompt date:
{{ISOStringDate}}
# from plopHelper template: “post” draft: true slug:
{{shortDate}}-{{dashCase title}}
# from plop helper and title prompt category: -
{{category}}
# from category prompt description:
{{description}}
# from description prompt --- ## Intro
{{description}}

Running yarn plop now should walk you through the prompts we added and generate a new file based off of the responses to the prompts and the handlebars template. The file that was generated will be at content/blog/${shortDate}-{{dashCase title}}.md (or wherever you set the path in the action).

Plop Example to Generate JSX Page

Below is an update plopfile and example handlebars template for generating a Page.jsx and Page.test.jsx:

Page.hbs:

import React from "react" // Components import { Helmet } from "react-helmet"
import { graphql } from "gatsby" import Layout from "../components/page/layout"
const
{{properCase pageName}}
= ({ data: { site: { siteMetadata: { title }, }, },}) => (<Layout>

  <div>

    <Helmet title="{title}" />

  </div>

</Layout>) export default
{{properCase pageName}}

export const pageQuery = graphql` query { site { siteMetadata { title } } }

pageTest.hbs:

import React from "react"

import { shallow } from "enzyme"

import Layout from "../components/page/layout"

import {{properCase pageName}} from "./{{properCase pageName}}"

import { Helmet } from "react-helmet"



const data = {

site: {

siteMetadata: {

title: “monica*dev”,

},

}

}



describe(“{{properCase pageName}}”, () => {

const component = shallow(

<{{properCase pageName}} data={data} />)



it(“renders page layout”, () => {

expect(component.find(Layout)).toHaveLength(1)

})



it(“renders helmet with site title from site metadata”, () => {

expect(component.find(Helmet).props().title).toBe(“monica*dev”)

})

})

plopfile.js

module.exports = function(plop) {

const today = new Date(Date.now())

const shortDate = today.toISOString().split("T")[0]

plop.setHelper("shortDate", () => shortDate),

plop.setHelper("ISOStringDate", () => today.toISOString()),

plop.setGenerator("generate blog post ✏️", {

 /*...*/

}),

plop.setGenerator("Create new page 📃", {

description: "template for creating a new page",

prompts: [

{

type: "input",

name: "pageName",

message: "Page name:",

},

],

actions: [

{

type: “add”,

path: “src/pages/{{properCase pageName}}.jsx”,

templateFile: “src/plop-templates/page.hbs”,

},

{

type: “add”,

path: “src/pages/{{camelCase pageName}}.test.jsx”,

templateFile: “src/plop-templates/pageTest.hbs”,

},

],

})

}

Formatting Output

I ran into an issue where because the initial template files were .hbs files the generated files weren't necessarily formatted like .md or .jsx. I already had prettier set up in my project so in order to solve the formatting issues I ended up updating my plop script shorthand to do format all files after running plop. However, this should be refactored to only format the relevant, just generated files.

"scripts": {
  ...
  "format": "prettier —write \"**/*.{js,jsx,json,md}\"",
  "plop": “plop && yarn format”
}

Conclusion

As a recap, we used plop to generate boilerplate code that is shared across certain types of files. Ideally implementing some type of automation for file creation should reduce time to create functional files, be less error-prone than copy + pasting + editing, encourages consistency and implementation of design patterns.

Create Your Own Template

Some ideas for things to incorporate in templates:

Create different templates based on the type of React component (examples in React-Boilerplate's generators)
Generate comments or base-level documentation
Generate self-contained directories or packages with, index file (and related tests), package.json and README.md

Additional Resources

Last year, I had the opportunity to streamline the creation of new packages via CLI prompts (which inspired my talk on generating React components at React Girls Conf in London) and led me to learn more about Plop. If you're interested in learning more about Plop in a React context or alternatives to Plop check out my previous talk.

Sketchnotes by @malweene from my talk at React Girls Conf

Here are some additional resources that may be helpful as you are getting more familiar with generating files with Plop.

https://github.com/plopjs/plop
https://github.com/react-boilerplate/react-boilerplate/tree/master/internals/generators
https://github.com/SBoudrias/Inquirer.js/
https://handlebarsjs.com/
https://prettier.io/
https://github.com/M0nica/generate-kawaii-components

Understanding Reduce in JavaScript

Sun, 29 Mar 2020 22:21:35 GMT

Reducing an array is a helpful functional programming technique to use when you need to reduce multiple values into a single value. Although that single value isn't limited to being an integer it can be an array, an object...etc. I've found reduce to be a handy method to have at your disposal during technical interviews. This article will introduce ES6's reduce() method and then walk through various ways to use reduce and discuss other built-in methods that abstract reduce() like map() and filter().

The general structure when using reduce() is:

input.reduce(callback, initialAccValue);
// Note: the `initialAccValue` is optional but effects how reduce() behaves

When an initialAccValue is supplied,the callback function is called on every item within the input array. The callback function will then mutate the accumulator until it has gone through every item and it reaches it final value. Thet final value of the accumulator is ultimately the return value of reduce().

input.reduce((accumulator, item) => {
  // What operation(s) should occur for each item?
  // What will the accumulator value look like after this operation?
  // 🚨: the accumulator value needs to be explicitly returned.
}, initialValue);

The reducer function can take up to four arguments and look like

arr.reduce(callback(accumulator, currentValue[, index[, array]] )[, initialValue])

You can read more about reduce() and the index and array parameters at https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce.

Reducing an array to a single number

A common way reduce() can be used is to return the sum of all of the values in an array.

In the below code each item in the values array is added to the accumulator in the callback function. The initial value of the accumulator is explicitly set to 0. During each iteration through the values in input the accumulator grows larger since each time the callback function is called it is passed in the resulting accumulator value from the previous iteration.

const input = [1, 100, 1000, 10000];
const sum = input.reduce((accumulator, item) => {
  return accumulator + item;
}, 0); // 11101

If we walk through each iteration of the above reduce method it will look something like this:

accumulator = 0, item = 1
- the returned accumulator = 1 + 0 = 1
accumulator = 1, item = 100
- the returned accumulator = 1 + 100 = 101
accumulator = 101, item = 1000
- the returned accumulator = 101 + 1000 = 1101
accumulator = 1101, item = 10000
- the final (and only number) returned from the reduce function is 11101. This number is reached because 1101 + 10000 = 11101 and 10000 is the last item in the input array.

Mapping Items with `map()` and `reduce()`

If you want to return a new array that is the result of performing an operation on each item in an array then you can use map() or reduce(). map() allows you to more concisely accomplish this than reduce() but either could be used. The example below shows how to return an array that contains squared versions of numbers in an original array using both map() and reduce().

Using `map()`

const numbers = [1, 10, 100];
const squared = numbers.map((item) => Math.pow(item, 2));
// [1, 100, 10000]

Using `reduce()`

const numbers = [1, 10, 100];
const squared = numbers.reduce((acc, number) => {
  acc.push(Math.pow(number, 2));
  return acc;
}, []); // [1, 100, 10000]

Filtering Items with `filter()` and `reduce()`

If you ever need to filter out values in an array to only retain values that meet certain criteria you can use either filter() or construct a new array that only is compromised of items that pass the criteria. Below are examples of using filter() and reduce() to only return the even numbers from an array of digits.

Using `filter()`

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
const evenNumbers = numbers.filter((number) => number % 2 === 0);
// [2, 4, 6, 8, 10]

Using `reduce()`

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
const evenNumbers = numbers.reduce((acc, number) => {
  if (number % 2 == 0) {
    acc.push(number);
  }
  return acc;
}, []);
// [2, 4, 6, 8, 10]

Reducing an array to a single object

Although reduce() has to return a single value but that single value doesn't have to be an integer or array it can also be an object. The following example will walk through how to reduce an array into a single object. This prompt was taken from VSchool's reduce practice exercises.

The prompt was:

Given an array of potential voters, return an object representing the results of the vote. Include how many of the potential voters were in the ages 18-25, how many from 26-35, how many from 36-55, and how many of each of those age ranges actually voted. The resulting object containing this data should have 6 properties.

The input of voters looked like:

const voters = [
  { name: "Bob", age: 30, voted: true },
  { name: "Jake", age: 32, voted: true },
  { name: "Kate", age: 25, voted: false },
  { name: "Sam", age: 20, voted: false },
  { name: "Phil", age: 21, voted: true },
  { name: "Ed", age: 55, voted: true },
  { name: "Tami", age: 54, voted: true },
  { name: "Mary", age: 31, voted: false },
  { name: "Becky", age: 43, voted: false },
  { name: "Joey", age: 41, voted: true },
  { name: "Jeff", age: 30, voted: true },
  { name: "Zack", age: 19, voted: false },
];

I ended up writing the voterResults function below which takes in an array that is shaped like the voters array above. I decided to set the initial accumulator value to:

const initialVotes = {
  youngVotes: 0,
  youth: 0,
  midVotes: 0,
  mids: 0,
  oldVotes: 0,
  olds: 0,
};

The initialVotes object was the same shape as the final value I needed the reduce() to return and encapsulated all of the potential keys that would be added and defaulted each to 0. This structure easily captures categories that ended up having a total of 0 at the end and also eliminated the need to have check that the current value of a key existed before incrementing it.

Within the callback function logic needed to be implemented to determine which peer group someone was in based on conditional logic related to their age. That peer data was also used to increment the voting data for their peer group if they voted.

function voterResults(arr) {
  const initialVotes = {
    youngVotes: 0,
    youth: 0,
    midVotes: 0,
    mids: 0,
    oldVotes: 0,
    olds: 0,
  }

  const peersToVotePeers = {
    youth: "youngVotes",
    mids: "midVotes",
    olds: "oldVotes",
  }

  return arr.reduce((acc, voter) => {
    if(voter.age < 26)
      peers = "youth"
    } else if (voter.age < 36) {
      peers = "mids"
    } else {
      peers = "olds"
    }
    if (!voter.voted) {
      // if they didn't vote let's just increment their peers
      // for example for  { name: "Zack", age: 19, voted: false }
      // The peer group would be "youth" and we'd increment acc["youth"] by one
      return { ...acc, [peers]: acc[peers] + 1 }
    } else {
      const votePeers = peersToVotePeers[peers];
      // for example for { name: "Jeff", age: 30, voted: true }
      // The peer group would is "mids"
      // acc["mids"] and acc["midVotes"] are both incremented by one
      return {
        ...acc,
        [peers]: acc[peers] + 1,
        [votePeers]: acc[votePeers] + 1,
      }
    }
  }, initialVotes)
}

The object output from voterResults(voters) is:

{ youngVotes: 1,
  youth: 4,
  midVotes: 3,
  mids: 4,
  oldVotes: 3,
  olds: 4
}

Notes

Often accumulator is abbreviated as acc.
The callback function must explicitly return a value or else reduce() will return undefined.

Refactoring useState() To useReducer()

Sat, 04 Apr 2020 17:06:08 GMT

I recently created a Stimulus Check Calculator based on figures from the CARES Act and the Washington Post to help people estimate the amount of their stimulus check under the CARES Act. This article will walk through how I refactored the calculator's state management by consolidating multiple useState() React hooks into a single useReducer(). useReducer() is an alternative that can be considered when using useState() to manage state in functional React components. This article assumes some familiarity with state management in React and React Hooks.

Managing form state with useState();

In order to use the useState() React hook for state management of the calculator I first needed to import useState from React.

import { useState } from "react";

Setting the initial state with useState()

Then within the function that is returning the Form component I setup the useState() hooks for taxYear, filingStatus,income, children and stimulusAmount.

const { SINGLE, HEADOFHOUSE, MARRIED } = filingStatuses;
const [taxYear, setTaxYear] = useState(2019);
const [filingStatus, setFilingStatus] = useState(SINGLE);
const [income, setIncome] = useState("75000");
const [children, setChildren] = useState(0);
const [stimulusAmount, setStimulusAmount] = useState(-1);

The parameter passed into useState() represents the default value for that particular state. Meaning that the below line is setting the default value of taxYear in state to 2019.

const [taxYear, setTaxYear] = useState(2019);

Updating form state with useState()

Event handlers, such as onChange or onClick can be used to update the component's state when data in the form changes. Managing form state by updating the component's internal state is considered a "controlled component" vs. having the DOM manage the state of the form.

In order to update the taxYear's value to the selected year, there's an onClick event handler that calls setTaxYear(year) with the year parameter being the current year that is selected.

{
  [2019, 2018].map((year) => (
    <button
      onClick={() => setTaxYear(year)}
      className={year == taxYear ? "selectedButton" : ""}
      key={year}
      name="tax-year"
    >
      {year == 2019 ? "Yes" : "No"}
    </button>
  ));
}

Similar logic is used to update filingStatus income and children, stimulusAmount and handleSubmit when form data is updated or submitted.

Managing form state with useReducer();

In order to use the useReducer() React hook for state management of the calculator I first needed to import useReducer from React. If you are not familiar with reducers in JavaScript check out my article on Understanding Reduce in Javascript

import { useReducer } from "react";

Setting the initial state with useReducer()

Then I set the initial state for the component like:

const initialState = {
  taxYear: 2019,
  filingStatus: SINGLE,
  income: "75000",
  children: 0,
  stimulusAmount: -1,
};

const [state, dispatch] = useReducer(reducer, initialState);

Similar to useState, useReducer returns the related state along with a method to update the state. With useReducer instead of updating the state by passing a value to setState() an action should be dispatched which will call the reducer.

In my case the reducer function looked like:

function reducer(state, action) {
  const { type, payload } = action;
  return { ...state, [type]: payload };
}

Updating form state with useReducer()

Each time dispatch is called it should be called with an action item that contains a type and in this particular case a payload as well. The state of tax year can be updated onClick by firing

 onClick={() => dispatch({ type: "taxYear", payload: year })}

instead of

  onClick={() => setTaxYear(year)}

reducer(state, action) is expecting to receive an action that is an object with type and payload. Within the reducer function the action's type and payload are used to return the current state with the [type]: payload overwritten.

const { type, payload } = action;
return { ...state, [type]: payload };

In the case of updating the state from 2017 if the current state was:

const initialState = {
  taxYear: 2019,
  filingStatus: SINGLE,
  income: "75000",
  children: 0,
  stimulusAmount: -1,
};

Then firing onClick={() => dispatch({ type: "taxYear", payload: 2018 })} would result in the reducer returning the current state but with only the value of taxYear overwritten and set to 2018. Note: this works as written because for each action in this example the type of action is the same as its corresponding key value in state.

Full Source Code of Examples

The full source code below compares the full implementations of the state management methods above. As was illustrated above, useReducer() is another React hook that can be used for state management and can be implemented in a way that allows logic from useState() hooks to be consolidated. The related source code for the current version of the calculator is available on GitHub.

source code using useState():

import { filingStatuses } from "../utils/constants";
import { getStimulusAmount } from "../utils/calculateStimulus";
import { useState } from "react";

function Form() {
  const { SINGLE, HEADOFHOUSE, MARRIED } = filingStatuses;
  const [taxYear, setTaxYear] = useState(2019);
  const [filingStatus, setFilingStatus] = useState(SINGLE);
  const [income, setIncome] = useState("75000");
  const [children, setChildren] = useState(0);
  const [stimulusAmount, setStimulusAmount] = useState(-1);

  function handleSubmit(e) {
    e.preventDefault();
    setStimulusAmount(calculateStimulus(income, filingStatus, children));
  }

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="tax-year">Have you filed your 2019 taxes yet?</label>
      {[2019, 2018].map((year) => (
        <button
          onClick={() => setTaxYear(year)}
          className={year == taxYear ? "selectedButton" : ""}
          key={year}
          name="tax-year"
        >
          {year == 2019 ? "Yes" : "No"}
        </button>
      ))}
      <label htmlFor="filing-status">
        What was your filing status in your {taxYear} taxes?{" "}
      </label>
      {[SINGLE, MARRIED, HEADOFHOUSE].map((status) => (
        <button
          onClick={() => setFilingStatus(status)}
          className={status == filingStatus ? "selectedButton" : ""}
          name="filing-status"
          key={status}
        >
          {" "}
          {status}
        </button>
      ))}
      <br />
      <label htmlFor="adjusted-income">
        What was your adjusted gross income in {taxYear}?
      </label>
      ${" "}
      <input
        type="number"
        inputMode="numeric"
        pattern="[0-9]*"
        value={income}
        onChange={(e) => setIncome(e.target.value)}
        min={0}
        name="adjusted-income"
      />
      <br />
      <label htmlFor="children">
        How many children under age 17 did you claim as dependents in {taxYear}?
      </label>
      <input
        type="number"
        inputMode="numeric"
        pattern="[0-9]*"
        value={children}
        onChange={(e) => setChildren(e.target.value)}
        min={0}
        name="label"
      />
      <br />
      <button type="submit" className="calculateButton">
        Calculate
      </button>
      <p>
        {" "}
        {stimulusAmount >= 0 &&
          (stimulusAmount > 0
            ? `Your stimulus amount is expected to be $${stimulusAmount}.`
            : `You are not expected to receive a stimulus.`)}
      </p>
      <br />
    </form>
  );
}

export default Form;

source code using useReducer():

import { useReducer } from "react";
import { filingStatuses } from "../utils/constants";
import { getStimulusAmount } from "../utils/calculateStimulus";

function reducer(state, action) {
  const { type, payload } = action;
  return { ...state, [type]: payload };
}

function Form() {
  const { SINGLE, HEADOFHOUSE, MARRIED } = filingStatuses;

  const initialState = {
    taxYear: 2019,
    filingStatus: SINGLE,
    income: "75000",
    children: 0,
    stimulusAmount: -1,
  };

  const [state, dispatch] = useReducer(reducer, initialState);

  function handleSubmit(e) {
    e.preventDefault();
    dispatch({
      type: "stimulusAmount",
      payload: getStimulusAmount(income, filingStatus, children),
    });
  }

  const { taxYear, filingStatus, income, children, stimulusAmount } = state;

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="tax-year">Have you filed your 2019 taxes yet?</label>
      {[2019, 2018].map((year) => (
        <button
          onClick={() => dispatch({ type: "taxYear", payload: year })}
          className={year == taxYear ? "selectedButton" : ""}
          key={year}
          name="tax-year"
        >
          {year == 2019 ? "Yes" : "No"}
        </button>
      ))}
      <label htmlFor="filing-status">
        What was your filing status in your {taxYear} taxes?{" "}
      </label>
      {[SINGLE, MARRIED, HEADOFHOUSE].map((status) => (
        <button
          onClick={() => dispatch({ type: "filingStatus", payload: status })}
          className={status == filingStatus ? "selectedButton" : ""}
          name="filing-status"
          key={status}
        >
          {" "}
          {status}
        </button>
      ))}
      <br />
      <label htmlFor="adjusted-income">
        What was your adjusted gross income in {taxYear}?
      </label>
      ${" "}
      <input
        type="string"
        inputMode="numeric"
        pattern="[0-9]*"
        value={income}
        onChange={(e) => dispatch({ type: "income", payload: e.target.value })}
        min={0}
      />
      <br />
      <label htmlFor="children">
        How many children under age 17 did you claim as dependents in {taxYear}?
      </label>
      <input
        type="number"
        inputMode="numeric"
        pattern="[0-9]*"
        value={children}
        onChange={(e) =>
          dispatch({ type: "children", payload: e.target.value })
        }
        min={0}
        name="label"
      />
      <br />
      <button type="submit" className="calculateButton">
        Calculate
      </button>
      <p>
        {" "}
        {stimulusAmount >= 0 &&
          (stimulusAmount > 0
            ? `Your stimulus amount is likely to be ${new Intl.NumberFormat(
                "en-US",
                { style: "currency", currency: "USD" },
              ).format(stimulusAmount)}.`
            : `You are not expected to receive a stimulus.`)}
      </p>
      <br />
    </form>
  );
}

export default Form;

Top Gatsby Plugins For Developer Blogs

Sun, 19 Apr 2020 17:44:36 GMT

I've published dozens of articles on this site, which was built using Gatsby. In the past year I decided to invest more time into maintaining my blog and want to share the top plugins I recommend to enhance your Gatsby blog. Gatsby has a vast library of plugins which are Node packages that are designed to work with Gatsby APIs to extend the functionality of Gatsby sites.

I was motivated to invest more in maintaining my site because as a creator on the web it's important to have a place that you have full control over that houses all of your content. More and more developers are migrating back to self-hosting their blogs and thus retaining greater autonomy and ownership over their content.

I encourage all developers who choose to blog and have the time/resources to not only maintain their blog but to consider cross-posting to sites like dev.to. If you're just getting started with syndicating content check out this piece by Stephanie Morillo on How Blog Post Syndication Works.

Recommended Gatsby Plugins

gatsby-plugin-google-analytics

One of the features I appreciate from Medium is that they provide content authors with access to analytics for content that they post. This information can be helpful when tracking which content resonates more with your audience and get a better gauge on how people are finding your site. If you would like access to metrics like page views, average session duration, etc. then you need to pro-actively install analytics as data usually cannot be collected retroactively. If you are interested in using Google Analytics in particular then you should check out gatsby-plugin-google-analytics.

Alternative: Adding a hit counter to your site

gatsby-plugin-react-helmet

Speaking of using gatsby-plugin-google-analytics or a hit counter to learn more about your site's traffic, an essential part of creating discoverable web content is optimizing for SEO. The gatsby-plugin-react-helmet is built on-top of react-helmet to support server-side rendered SEO. It allows you to configure a site title, description, and other metadata. Updating metadata is essential to providing visually striking previews of content when content is shared on Twitter, Facebook, Slack, text messages and more!

Also, if your experience is anything like mine then debugging metadata images is sometimes an adventure and you may need to use tools like the Twitter card validator and the Facebook sharing debugger to debug image previews.

gatsby-plugin-my-social-cards

One way to make your blog stand out more is to have custom images for each blog post vs. a generic-site wide image. Manually creating new images for each blog post can be time-consuming and depending on your strategy is not necessary. I ended up installing gatsby-plugin-my-social-cards to generate custom images for each blog post.

In my case I have a base image that looks like:

and then for each article that I post I use gatsby-plugin-my-social-cards to generate an image that combines my base image with the title of the article resulting in something that looks like:

gatsby-remark-twitter

If you want to embed relevant tweets like the ones that appear throughout this article into markdown content on your site then check out the gatsby-remark-twitter plugin.

gatsby-remark-prismjs

If the audience for your blog is developers then there's a good chance that some of your articles will feature code snippets. If so, gatsby-remark-prismsjs as an extension of PrismJS allows you to set up and style language-specific code syntax highlighting.

Example snippet with PrismJS syntax highlighting:

export function formatReadingTime(minutes) {
  let buckets = Math.round(minutes / 5);

  return `${new Array(buckets || 1).fill("🍿").join("")} ${minutes} min read`;
}

gatsby-remark-autolink-headers

gatsby-remark-autolink-headers allows you to automatically add anchor tags to all article headers. This allows these headers to be linkable similar to how Markdown files render on Github.com by default. This autolink functionality is helpful for allowing people to share links to particular sections of your article and helps make the process of creating table of contents more efficient.

These are 6 of the Gatsby plugins I've found essential to enhancing my Gatsby blog and providing it with better SEO and a richer experience for my audience. The next time I set up a blog using Gatsby I'd consider installing all of these plugins depending on the particular needs of the site.

Exploring Art Direction With Gatsby-Image

Wed, 24 Jun 2020 00:51:34 GMT

import Callout from "../../components/Callout.astro";

While updating my homepage to include my newly-commission illustration from Aishwarya Tandon, I wanted to load different versions of the image based on screen-size in a performant way. For my header image, I use gatsby-image, an official GatsbyJS plugin that optimizes images that makes it straightforward to control how images are progressively enhanced on page load. One of my favorite built-in Gatsby image effects is <a href="https://using-gatsby-image.gatsbyjs.org/traced-svg/">traced SVGs</a>, which renders an SVG tracing of an image, in a pre-determined color before the image fully loads. You can explore all of gatsby-image's built-in loading effects on the using-gatsby-image site.

The above GIF illustrates how gatsby-image transitions from traced SVG to the loaded image

While looking into how to load different images at different breakpoints without unnecessarily downloading files I discovered gatsby-image's built-in support for this feature which is known as art direction. Modern HTML can be used to dynamically load of images based on screen size using srcset attributes with <img> and <source> instead of JavaScript.

<Callout> Swapping images at different screen sizes can be done with JavaScript or CSS instead of native HTML attributes however using the HTML attributes can improve page loading performance as it prevents unnecessarily preloading two images when only one image from the srcset needs to be visible within the viewport on load. </Callout>

The above GIF shows the transition between different images loaded with art direction within gatsby-image

All images that use the gatsby-image plugin need to be constructed using a GraphQL query. Below is a slightly modified version of the useStaticQuery() I used to load image files into gatsby-image's Img. Within useStaticQuery() I wrote two named queries mobileImage and desktopImage to load both versions of the image I wanted on mobile as well as the desktop.

import React from "react";
import { useStaticQuery, graphql } from "gatsby";
import Img from "gatsby-image";

const Avatar = () => {
  const data = useStaticQuery(graphql`
    query {
      mobileImage: file(
        relativePath: { eq: "animonica-headshot-cropped.png" }
      ) {
        childImageSharp {
          fluid(maxWidth: 300, quality: 100) {
            ...GatsbyImageSharpFluid_tracedSVG
          }
        }
      }
      desktopImage: file(relativePath: { eq: "animonica-full.png" }) {
        childImageSharp {
          fluid(maxWidth: 300, quality: 100) {
            ...GatsbyImageSharpFluid_tracedSVG
          }
        }
      }
    }
  `);

  const sources = [
    data.mobileImage.childImageSharp.fluid,
    {
      ...data.desktopImage.childImageSharp.fluid,
      media: `(min-width: 625px)`,
    },
  ];

  return <Img fluid={sources} alt="Illustrated Monica" />;
};

export default Avatar;

If you inspect my site's header using Dev Tools you'll notice there's two <picture> sections, one that includes the tracedSVGs that are generated by GatsbyImageSharpFluid_tracedSVG in the image query and another with the .png files.

The HTML that ultimately renders to load the .png files from the earlier use of gatsby-image resembles the below:

<picture>
  <source media="(min-width: 625px)" srcset="animonica-full.png" />
  <source srcset="animonica-headshot-cropped.png" />
  <img src="animonica-full.png" alt="Illustrated Monica" />
</picture>

The media attribute in the <source> elements, within <picture>, determines which image srcset is displayed. The first condition that is met will be displayed, in the case where neither media condition is true or the browser doesn't support the <picture> element it will return the <img> element from within the <picture>. You can view current browser compatibility for <picture> at Can I use this?.

As a recap, within gatsby-image we can pass an array of images to generate HTML's art direction related attributes. Using this approach instead of CSS or JavaScript reduces the number of assets that need to be preloaded in the browser. My current Gatsby site, displays a complete HTML page from the server to the client on the initial load without requiring JavaScript therefore I've found it helpful to avoid delegating certain tasks to JavaScript that HTML/CSS can handle in a more performant way. I've written more about this topic in my article Less JavaScript Makes Font Awesome More Awesome.

4 Meetups That Helped Me Grow as A Woman of Color in Tech

Thu, 26 Jul 2018 17:11:11 GMT

Attending various tech Meetups over the years has been pivotal to my growth as a technologist

I took a leap and left my full-time job as an email marketer, to work to pursue software engineering! This summer I kicked off my engineering career as a Full Stack Engineering Intern at Meetup with the Meetups at WeWork team; we are responsible for allowing organizers to seamlessly book space to host their Meetup events. I strongly encourage event organizers to check it out and learn more here as this service is currently free.

Attending various Meetups in New York City over the years has been pivotal to my growth as a technologist and has led me to go to technical talks and conferences that covered topics beyond my comfort zone, pushed me to contribute my writing to multiple Medium publications, helped me to go from student to teaching assistant to teacher and even served as a valuable resource during the technical interview prep process.

<span class="figcaption_hack">A photo of me teaching a workshop on publishing a blog with Jekyll at CodeNewbie’s Codeland 2018 conference.</span>

I’d like to share some of the tech-related Meetups that I’ve benefitted the most from in recent years that have helped me transition from marketing into engineering.

1. Women Who Code NYC

Women Who Code (WWC) is “an international non-profit organization that provides services for women pursuing technology careers.”

What I love about WWC? I really enjoy one of their signature Meetups which revolves around solving whiteboarding problems. Whiteboarding algorithms commonly comes up in technical interviews, and practicing with other people in a supportive environment helps make them a little less intimidating and allows you to exercise the skills that are needed to do well when solving coding challenges during an interview.
Algorithms! Meet monthly and go through various problems on a whiteboard in a small group working in the same language.
Pro-Tip — Go to their next Algorithms Meetup even if you don’t think you’re “ready” yet! You can check out Women Who Code NYC’s GitHub (https://github.com/WomenWhoCodeNYC/Algorithms) for a sneak peak of the type of problems they generally ask and sneak in some practice.

2. Girl Develop It NYC

Girl Develop It (GDI) is hands-down one of my favorite tech non-profits (right up there with Black Girls Code). They recently celebrated having over 100,000 members across the country.

GDI hosts workshops for adults learning how to code with their open-sourced curriculum that covers everything from general web concepts to React, Pandas, Python, HTML/CSS and more. Their classes are generally more affordable than similar offerings at for-profit entities.
Pro-tip: Don’t let the cost deter you, as they offer scholarships for every class. Every event they host with a cost associated has a link to apply for the scholarship; individuals are eligible to be awarded up to 4 Girl Develop It NYC scholarships in a year.
What I love about GDI? They provide a supportive, judgement-free place for individuals new to coding and those looking to teach what they know to others. My local GDI’s leadership encouraged me to get out of my “comfort zone” and serve as a teaching assistant which was a very rewarding experience and helped me become more confident in my technical skills. Additionally, I’m a fan of Girl Develop It NYC’s weekly newsletter (exclusive to their Meetup members) which features interesting coding libraries and relevant opportunities.

3. Write/Speak/Code NYC

Write/Speak/Code (W/S/C) works “to increase the visibility and leadership of women and non-binary coders through thought leadership, conference speaking, open source contributions, career development, personal growth and self-care.”

W/S/C primarily hosts career development events that revolve around writing, public speaking, open source contributions and other professional development topics.
Pro-tip: I was going to say grab a ticket to their upcoming 4 day conference but it already sold out ;) So my tip would be to plan ahead and consider attending their next conference!
What I love about W/S/C? I strongly encourage anyone with even a hint of imposter syndrome to look into W/S/C. I went to a one day event they hosted in NYC last Fall, Own Your Expertise, and was really challenged to examine how I view leaders in the workplace. I left that event feeling empowered by knowing that with my current skillset and knowledge I already have valuable expertise to share.

4. Black Software Engineers NYC

This group is run by We Build Black, which is a non-profit organization that focuses on creating safe spaces for Black technologists and creating educational programs.
Pro-tip: They frequently host free workshops geared at those learning a new programming language or technology (React Lifecycle, Python Programming, Intro to JavaScript, etc.). You can sign up for an upcoming class at https://www.meetup.com/Black-Software-Engineers-of-NYC/.
What I love about Black Software Engineers NYC: They have created a supportive environment for individuals from various backgrounds and if you are just getting started with programming you will be in great company! Of all of the Meetups I’ve attended over the years I strongly believe this one is one of the most community-oriented ones.

Not in New York?

These organizations have a presence in multiple cities and may have an active chapter near you!

Adding Environment Variables To GitHub Actions

Sun, 23 Aug 2020 22:58:47 GMT

This article walks through how to pass environment variables to GitHub Action Workflows. I recently set up GitHub actions on this site to automatically run unit tests whenever I open a new Pull Request to ensure that changes to the site were not introduction breaking changes to unit tests under the radar.

I ran into some hiccups when setting it up so that the workflow could install the Font Awesome dependency which requires an NPM token. I went through a few of my GitHub Actions build minutes while testing how to properly pass environment variables to my .github/workflow/test.yml file. Hopefully this article saves you some time and build minutes the next time you set up environment variables for GitHub Actions.

In order to setup my GitHub Action, I modeled my new GitHub Action workflow after similar functional workflows and expected everything to run smoothly. However, I merged the pull request with my changes and saw on the Pull Request that the step of the GitHub Action workflow that installed dependencies failed with the following error:

error An unexpected error occurred: "Failed to replace env in config: $
{FONTAWESOME_NPM_AUTH_TOKEN}"

And then I remembered 💡 my site requires an environment variable to build and deploy. Locally I have .npmrc file that sets up the the npm configuration to pass in the appropriate environment variable for my site and looks like:

@fortawesome:registry=https://npm.fontawesome.com/
//npm.fontawesome.com/:_authToken=${FONTAWESOME_NPM_AUTH_TOKEN}

In particular the GitHub Action workflow did not have access to the FONTAWESOME_NPM_AUTH_TOKEN which I have set in my local bash profile and passed into the .npmrc file. So I needed to give the GitHub repository that is running this actions access to the environment variable by going to its settings page. You can access settings by clicking "Settings" in the repository's navigation. The url to update secrets for a repository (at the time of this writing) looks like: https://github.com/username/repo/settings/secrets where username and repo should be replaced with the username and repo of the desired repository and clicking "new secret".

Above is a screenshot of what the secrets page under my repository settings looked like once I added the FONTAWESOME_NPM_AUTH_TOKEN.

Now, that my repository had access to the environment variable I needed to update each job within my action to also have access to the variables. Before adding the environment variable to my repository my GitHub Action the job that installed dependencies looked like:

 - name: Install Dependencies
      run: npm install

after adding the environment variable I updated the dependency installation job to:

- name: Install Dependencies
      run: |
        npm config set //npm.fontawesome.com/:_authToken=${FONTAWESOME_NPM_AUTH_TOKEN}
        npm ci
      env:
        FONTAWESOME_NPM_AUTH_TOKEN: ${{ secrets.FONTAWESOME_NPM_AUTH_TOKEN }}

npm config set allowed me to manually set the npm configuration outside of the .npmrc file and pass in the appropriate environment variable. I also updated npm install to npm ci which installs a project with a clean slate and is better suited for a CI environment. Finally after the run values I passed in a env key that contained FONTAWESOME_NPM_AUTH_TOKEN which referenced ${{ secrets.FONTAWESOME_NPM_AUTH_TOKEN }} a.k.a the secrets from this GitHub repository.

The full GitHub action workflow I ended up using to install all dependencies (including Font Awesome which required a token ) and running unit tests looked like the below. Note: the test command also needed access to the same environment variable and needed it to be set separately in order for the GitHub Action to successfully run without running into the error we saw earlier with retrieving the environment variable.

name: CI

on:
# will run on all PRs that are opened or updated (synchronized)
pull_request:
  types: [opened, synchronize, reopened]

jobs:
test:
  name: Test
  runs-on: ubuntu-latest
  env:
    CI: true
  steps:
    - uses: actions/checkout@v2
    - name: Use Node.js 13.x
      uses: actions/setup-node@v1
      with:
        node-version: 13.x
    - name: Install Dependencies
      run: | # run multiple commands
        npm config set //npm.fontawesome.com/:_authToken=${FONTAWESOME_NPM_AUTH_TOKEN}
        npm ci
      env:
        FONTAWESOME_NPM_AUTH_TOKEN: ${{ secrets.FONTAWESOME_NPM_AUTH_TOKEN }}
    - name: Test
      run: | # run multiple commands
        npm config set //npm.fontawesome.com/:_authToken=${FONTAWESOME_NPM_AUTH_TOKEN}
        npm run test
      env:
        FONTAWESOME_NPM_AUTH_TOKEN: ${{ secrets.FONTAWESOME_NPM_AUTH_TOKEN }}
```

How to Add Instagram Timeline To a NextJS Site

Mon, 21 Dec 2020 22:10:20 GMT

import Callout from "../../components/Callout.astro";

<Callout variant="danger"> Due to changes in the Instagram API the method for displaying Instagram photos in this article currently <b>does not work</b> due to CORS issues. I recommend{" "} <a href="https://developers.facebook.com/docs/development/"> applying for access to Facebook/Instagram APIs </a>{" "} for stable access to content hosted on Instagram. </Callout>

I recently added an Instagram timeline to my site In Digital Color and wanted to share how I added the Instagram integration to my NextJS site and document some of the hiccups I encountered along the way with authentication.

Screenshot of Instagram Timeline integration on indigitalcolor.com

Install and import `instagram-web-api`

We'll use the instagram-web-api npm package to do the heavy lifting for the integration. which should be installed within a NextJS site with npm install instagram-web-api or yarn add instagram-web-api. Once the package is successfully installed it should be imported into index.js file (or whichever page you would like the Instagram feed to appear on) with:

import Instagram from "instagram-web-api";

At this point the index.js file where I imported instagram-web-api looks like this:

import Instagram from "instagram-web-api";
import Layout from "../components/layout";

export default function Index() {
  return <Layout>{/*Other Page Content*/}</Layout>;
}

Setup getStaticProps to Fetch Data at Build Time

Next, we need to set up a way to get fetched data into our component. In this case, I chose to use the async getStaticProps function to pass data into our component.getStaticProps is a function available to pages within NextJS that allows data to be fetched at build time and passed into page-level components.

import Layout from "../components/layout";
import Instagram from "instagram-web-api";

// empty array of instagram posts is being
// passed as a prop into the Index component
export default function Index({ instagramPosts }) {
  return <Layout>{/*Other Page Content*/}</Layout>;
}

export async function getStaticProps(context) {
  // set posts to an empty array as a placeholder
  let posts = [];
  return {
    props: {
      // return the posts as the prop instagramPosts
      // for the Index function to use
      instagramPosts: posts,
    },
  };
}

Setup Instagram Client Authentication

Before we can retrieve data from Instagram we should set up authentication instagram-web-api in getStaticProps() to be able to fetch data from Instagram. We can accomplish this by setting up a new Instagram client with new Instagram({username: IG_USERNAME, password: IG_PASSWORD}) and attempting to log in with await client.login()

export async function getStaticProps(context) {
  // create a new client to communicate with  Instagram
  // this service requires authentication
  //with username and password parameters
  const client = new Instagram({
    username: process.env.IG_USERNAME,
    password: process.env.IG_PASSWORD,
  });

  let images = [];
  try {
    // attempt to log in to Instagram
    await client.login();
  } catch (err) {
    // throw an error if login to Instagram fails
    console.log("Something went wrong while logging into Instagram", err);
  }

  return {
    props: {
      instagramPosts: images,
    },
  };
}

Credentials such as the password should be accessed via environment variables that are only available locally and at build time to avoid exposing this information. In NextJS, local environment variables can be accessed by creating a file entitled .env.development.local. Although the username is not a secret you can add it to the environment file if you'd like. env.development.local should be added to your .gitignore file to avoid committing it to version control. Separately, I set up my hosting to have access to the appropriate secrets at build time which supersedes the values in the .env file.

My env.development.local file looks like this:

IG_USERNAME="super_cool_username"
IG_PASSWORD="super_secret_secure_password"

In addition to the env.development.local at a minimum you should have a .env file that sets the defaults for env variables. My .env file looks like and is checked into version control:

IG_USERNAME=""
IG_PASSWORD=""

Confirm Instagram Client is Functional

If you're not already you should run the development server of your NextJS site with npm run next and check in the terminal that is running the server to see if there are any console errors. You might encounter the error log we added of "Something went wrong while logging into Instagram" during this stage of the process.

Resolving 4xx Authentication Errors

While I was setting up the Instagram client with the correct credentials I encountered various 4xx authentication relates errors (if you're not familiar with HTTP status codes check out my site https://www.httriri.com/) being returned to Instagram saying "Please wait a few minutes before trying again". I was able to temporarily circumnavigate the 4xx errors and "Please wait a few minutes before trying again" message by switching my IP address with a VPN (Virtual private network) and attempting to authenticate again. A VPN allows you to access the internet with a remote VPN server's IP address as opposed to your local IP address. This article shares other ways you can change your IP address. I already had a VPN configured on my computer so I found that to be the most straightforward solution in my case. Using a VPN to access the internet resolved the issues I was encountering as they were IP address level issues. You can check if your issues are IP level by trying to log into Instagram manually on the same IP address and on another device that is connected to a separate cellular network (and has its own IP). I am wondering if there's a more official way to get Instagram to recognize API usage as not being unusual activity. If you are running into a 4xx error for a different reason this is a good time to manually confirm that the credentials you are providing are correct.

Request Timeline Data from Instagram

Once authentication is successful we can request specific data from Instagram calling client.getPhotosByUsername({username: process.env.IG_USERNAME}) to fetch timeline data for the username that is passed in.

export async function getStaticProps(context) {
  const client = new Instagram({
    username: process.env.IG_USERNAME,
    password: process.env.IG_PASSWORD,
  });

  let posts = [];
  try {
    await client.login();
    // request photos for a specific instagram user
    const instagram = await client.getPhotosByUsername({
      username: process.env.IG_USERNAME,
    });

    if (instagram["user"]["edge_owner_to_timeline_media"]["count"] > 0) {
      // if we receive timeline data back
      //  update the posts to be equal
      // to the edges that were returned from the instagram API response
      posts = instagram["user"]["edge_owner_to_timeline_media"]["edges"];
    }
  } catch (err) {
    console.log(
      "Something went wrong while fetching content from Instagram",
      err,
    );
  }

  return {
    props: {
      instagramPosts: posts, // returns either [] or the edges returned from the Instagram API based on the response from the `getPhotosByUsername` API call
    },
  };
}

Render Instagram Data with InstagramFeed component

Once we've successfully received timeline data back from the getPhotosByUsername() call we can render this data. Below is the skeleton I used to transform the data returned from the Instagram API into a digestible and visually engaging component that displays recent photos and links to them on Instagram so that visitors can click through to the actual posts.

import Link from "next/link";

export default function InstagramFeed({ instagramPosts }) {
  return (
    <>
      <h2>
        <a href="https://www.instagram.com/yourinstagramhandle/">
          Follow Us on Instagram
        </a>
        .
      </h2>

      <ul>
        {/* let's iterate through each of the
         instagram posts that were returned
         from the Instagram API*/}
        {instagramPosts.map(({ node }, i) => {
          return (
            // let's wrap each post in an anchor tag
            // and construct the url for the post using
            // the shortcode that was returned from the API
            <li>
              <a
                href={`https://www.instagram.com/p/${node.shortcode}`}
                key={i}
                aria-label="view image on Instagram"
              >
                {/* set the image src equal to the image
                url from the Instagram API*/}
                <img
                  src={node.thumbnail_src}
                  alt={
                    // the caption with hashtags removed
                    node.edge_media_to_caption.edges[0].node.text
                      .replace(/(#\w+)+/g, "")
                      .trim()
                  }
                />
              </a>
            </li>
          );
        })}
      </ul>
    </>
  );
}

In order to actually render this component and the associated post data from Instagram we need to import InstagramFeed into index.js and render it within the Index component with the instagramPosts prop we received from getStaticProps.

import Layout from "../components/layout";
import Instagram from "instagram-web-api";
import InstagramFeed from "../components/instagramFeed";
// empty array of instagram posts is being
// passed as a prop into the Index component
export default function Index({ instagramPosts }) {
  return (
    <Layout>
      {/*Other Page Content*/}
      <InstagramFeed instagramPosts={instagramPosts} />
    </Layout>
  );
}

If everything worked properly you should now see all of your latest Instagram posts rendered on the page and be able to click any given posts to be taken to it on Instagram. If you are not seeing any posts rendering there may have been an issue with authentication (invalid credentials or rate limited by Instagram). If so, I recommend following my above troubleshooting steps of manually verifying credentials (in case of invalid credentials) or exploring using a VPN (if your IP address has been rate limited).

Advent of Code - Day 01 2022

Sun, 04 Dec 2022 11:25:50 GMT

'Tis the season of Advent of Code which is an annual challenge of holiday-themed puzzles to solve with code. I usually attempt a few of the problems each year; the puzzles tend to get progressively more challenging each day and sometimes build on top of solutions from puzzles on earlier days. Each day you can earn up to ⭐️⭐️ (two stars) by solving both Part 1 and Part 2 (which adds a twist to part 1).

To keep things interesting, Advent of Code gives different users different values in their input files to test their solution. Once you feel that you've solved a problem you can run the function against the input file that AoC provided and then see if the output matches what AoC expected. They'll generally tell you if your answer is too high/too low to help nudge you in the right direction.

Helper Functions

I find that because Advent of Code gives large input files it's helpful to have helper functions to parse the input into your solution. Three of the helper functions I've used in previous years are

// Splits the input into an array of strings
export const strInput = (data) => data.split("\n");

This converts a file of

into an array of strings like ['1',2',3',4'].

// Splits the input into an array of numbers
export const numInput = (data) => data.split("\n").map(Number);

This converts a file of

into an array of numbers like [1,2,3,4].

Day One: Part One

For Day One: Part One of Advent of Code we are tasked with determining which elf is carrying the highest number of calories (check out the official AoC prompt for a more fun description of the problem) and the calories are provided as a list of integers in a text file and each group (a.k.a set of numbers with a blank space) belongs to a different elf.

/*example input*/
1000
2000
3000

4000

5000
6000

7000
8000
9000

10000

This list represents the Calories of the food carried by five Elves: The first Elf is carrying food with 1000, 2000, and 3000 Calories, a total of 6000 Calories. The second Elf is carrying one food item with 4000 Calories. The third Elf is carrying food with 5000 and 6000 Calories, a total of 11000 Calories. The fourth Elf is carrying food with 7000, 8000, and 9000 Calories, a total of 24000 Calories. The fifth Elf is carrying one food item with 10000 Calories. (Source: https://adventofcode.com/2022/day/1 )

Reading the data

Once we're ready to solve the problem we need access to our input data in a format that is easy to manipulate with JavaScript. We'll be using Node's File System API to read our locally downloaded input text file and will convert the file from a list of numbers to an an array of numbers with the help of the numInput() helper function.

/* node boilerplate to access file system*/
import { createRequire } from "module";
const require = createRequire(import.meta.url);
const fs = require("fs");

/* import helper functions for parsing our text file into an array in order to use JavaScript array methods*/
import * as h from "../helpers.js";

function getHighestCalorieCount() {
  /* use Node File System API to store output of local txt file in a string variable  */
  const data = fs.readFileSync("../2022/inputs/day_1.txt").toString();

  /* convert our string input into an array with numerical data*/
  const caloriesForElves = h.numInput(data);
}

Finding Highest Number of Calories Carried by an Elf

We can find the Elf with the highest calories by iterating through the list of calories and keeping track of the current total for each elf. We'll know that we've finished counting the calories for an individual elf when the current calorie value is 0, as that is what the value the helper function converts the blank spaces for grouping in the original file to. If the current elf's total is higher than the highest total that we've seen then we should store that value in highestTotal where it will persist until we encounter a higher total. If the current elf's total is lower than the highest total when we're ready to move onto the next elf then we'll no longer track that total as we know that isn't the highest total number of calories.

// part 1
function getHighestCalorieCount() {
  const data = fs.readFileSync("../2022/inputs/day_1.txt").toString();

  const caloriesForElves = h.numInput(data);

  let currentTotal = 0; // tracks total for current elf
  let highestTotal = 0; // tracks highest total seen so far

  for (let entry of caloriesForElves) {
    /* when we reach a new elf's list of calories the value is == 0 and we should update the highestTotal seen so far if the current elf's total is higher than the highest total we've seen so far and then always reset the currentTotal to 0 before moving onto the next elf.*/
    if (entry == 0) {
      if (currentTotal > highestTotal) {
        highestTotal = currentTotal;
      }
      currentTotal = 0;
    }
    /* increase currentTotal for the current elf */
    currentTotal += entry;
  }

  /* return the highest value between the currentTotal and highestTotal. This is necessary in case the currentTotal in the last iteration is the highest, because the line to update the highestTotal is called before the next group that is iterated through and is last called before the second to last group. */
  return Math.max(currentTotal, highestTotal);
}

Day One: Part Two

Finding The Three Highest Number of Calories Carried by the Elves

Part two is a variation of Part One, and in my case required a different approach to storing the highest 3 totals vs. the approach I took for finding the 1 highest total. With this approach I decided to store the total for each elf in an array and then after iterating through all of the calorie values, sort the array from highest to lowest value and then return the sum of the 3 highest values. In the first solution, I opted to avoid an unnecessary sort but though sorting made the second problem easier to approach. However, I did carry over the logic of how the currentTotal is reset when encountering a new Elf (i.e., entry == 0)

// part 2
function getTopThreeHighestCalorieCounts() {
  const data = fs.readFileSync("../2022/inputs/day_1.txt").toString();

  const caloriesForElves = h.numInput(data);

  let currentTotal = 0;
  let totalsForEachElf = []; /* stores sum of calories for each elf */

  for (let entry of caloriesForElves) {
    if (entry == 0) {
      totalsForEachElf.push(currentTotal);
      currentTotal = 0;
    }
    currentTotal += entry;
  }

  // grab the first second and third value from the computed totals
  const [first, second, third] = totalsForEachElf.sort((a, b) => b - a);

  // reduce the array of first,second and third values to sum up their values; equivalent to first + second + third
  return [first, second, third].reduce((acc, count) => {
    return acc + count;
  }, 0);
}

Full Source Code in my AoC GitHub Repository: https://github.com/M0nica/advent-of-code/blob/main/2022/day_1_calorie_counting.js

Fetch Webmentions Automatically with GitHub Actions

Fri, 14 Mar 2025 18:12:21 GMT

import Callout from "../../components/Callout.astro";

As I'm re-writing this site in Astro, I'm re-implementing features such as Webmentions [^1]. Webmentions are a web standard that enables cross-site interactions including likes, replies, bookmarks, and reposts. This article walks through setting up an automated workflow that retrieves new Webmentions on a schedule, stores them as JSON files, and opens pull requests for review. This automation is largerly powered by a Node.js script and GitHub Actions. The goal of this workflow is to keep the Webmention data that is displayed relatively up-to-date while also having moderation in place before any any unreviewed content can become visible.

Displaying Webmentions

Webmentions on this site appear near the bottom of each article as avatars for likes, reposts, and bookmarks, and as comments for replies and mentions.

Avatars for likes and shares — each generated from the Webmention author's profile

The "wm-property" field in each Webmention's metadata determines how it will be displayed. For "like-of", "repost-of", and "bookmark-of", only the author avatar is shown. Whereas, when the type of "wm-property is "in-reply-to" or "mention-of", then response includes a "content" field with the actual text, so both the avatar and the text are rendered.

Threaded comments from replies and mentions

<details> <summary>Example webmention.io data for a "Like"</summary>

{
  "type": "entry",
  "author": {
    "type": "card",
    "name": "Katherine Johnson",
    "url": "https://example.com",
    "photo": "https://example.com/avatar.jpg"
  },
  "url": "https://example.com/posts/liked-post",
  "published": "2025-04-24T12:00:00-04:00",
  "wm-received": "2025-04-24T12:01:00-04:00",
  "wm-id": 123456,
  "wm-source": "https://example.com/posts/liked-post",
  "wm-target": "https://targetsite.com/original-post",
  "wm-property": "like-of",
  "wm-private": false,
  "like-of": "https://targetsite.com/original-post"
}

</details>

<details> <summary>Example webmention.io data for a "Reply"</summary>

{
  "type": "entry",
  "author": {
    "type": "card",
    "name": "Katherine Johnson",
    "url": "https://example.com",
    "photo": "https://example.com/avatar.jpg"
  },
  "url": "https://example.com/posts/reply-to-post",
  "published": "2025-04-24T12:05:00-04:00",
  "content": {
    "text": "Really enjoyed your post—this part about webmentions was especially helpful!"
  },
  "in-reply-to": "https://targetsite.com/original-post",
  "wm-received": "2025-04-24T12:06:00-04:00",
  "wm-id": 123457,
  "wm-source": "https://example.com/posts/reply-to-post",
  "wm-target": "https://targetsite.com/original-post",
  "wm-property": "in-reply-to",
  "wm-private": false
}

</details>

Setting Up the Webmention Pipeline

A few years ago, I was pair programming with Jason Lengstorf on Twitch to add Webmentions to a Next.js site. During the stream we used two Webmention related services:

Webmention.io to receive and store incoming Webmentions.
Brid.gy to retrieve Webmentions from ~~Twitter~~ BlueSky.

I still recommend both of these services, especially if you're interested in being able to capture Webmention data from social media sites. Instead of maintaining a custom Webmention receiver endpoint, these third-party services handle the infrastructure. For those interested in a self-hosted alternative, a couple of developers have written about their approaches:

Adding Webmention Support from Scratch by Dwayne Harris
Building my own webmention receiver by James

Getting started with webmention.io just requires adding two lines to the site's <head> to advertise the endpoint:

 <link rel="webmention" href="https://webmention.io/username/webmention" />
 <link rel="pingback" href="https://webmention.io/username/xmlrpc" />
 ```

## Writing the Fetch Script

Brid.gy and Webmention.io are used to remotely store and retrieve the Webmention while [GitHub Actions](https://github.com/features/actions) handles the automation layer of exporting Webmention data and  creating a persistent backup to enable displaying the Webmention data on the site without any client-side API calls.

Since this is a static site, the goal is to fetch Webmentions only at build time with no client-side data fetching. The solution is based on [Peter Goes' approach](https://www.petergoes.nl/blog/review-webmentions-before-publishing-with-github-actions/), which opens a PR for each batch of new mentions. This process makes review easy before anything goes live. Webmention.io also supports deleting mentions and blocking specific domains for additional moderation needs. The script and config below are derivatives of Peter Goes' work, with dependency updates and a few workflow tweaks.

The script lives at `automations/store-webmentions.js` and can run locally or via GitHub Actions to retrieve recent Webmentions from Webmention.io.

```js

const apiEndpoint = "https://webmention.io/api/mentions.jf2";
const apiOptions = [
`token=${process.env.WEBMENTION_API_KEY}`,
"per-page=10000&",
`since=${since.toISOString()}`,
];

fetch(`${apiEndpoint}?${apiOptions.join("&")}`)
.then(convertResponseToJson)
.then(checkDataValidity)
.then(get("children"))
.then(filter(targetIsNotHomepage))
.then(forEach(writeMentionToFile));

Each mention is then saved to mentions/ at the project root, in a subfolder matching the article's URL path, named by its "wm-id".

const targetFolder = path.join(process.cwd(), "mentions");
function writeMentionToFile(mention) {
  
  const outputFolder = path.join(targetFolder, target);

  mkdirp.sync(outputFolder);

  fs.writeFileSync(
    path.join(outputFolder, `${id}.json`),
    JSON.stringify(mention, null, 2),
    { encoding: "utf-8" },
  );
}

<details> <summary>View full script to fetch Webmentions from Webmention.io</summary>

import fs from "fs";
import path from "path";
import fetch from "node-fetch";
import filter from "lodash/fp/filter.js";
import get from "lodash/fp/get.js";
import forEach from "lodash/fp/forEach.js";
import { mkdirp } from "mkdirp";
import dotenv from "dotenv-save";

dotenv.config();

/* fetch webmentions from the past week 
   in case there was a delay in webmention.io 
   receiving webmentions or a disruption 
   in running this script */
const since = new Date();
since.setDate(since.getDate() - 7);

const domain = YOUR_DOMAIN_NAME;
const targetFolder = path.join(process.cwd(), "mentions");
const apiEndpoint = "https://webmention.io/api/mentions.jf2";
const apiOptions = [
  `token=${process.env.WEBMENTION_API_KEY}`,
  "per-page=10000&",
  `since=${since.toISOString()}`,
];

fetch(`${apiEndpoint}?${apiOptions.join("&")}`)
  .then(convertResponseToJson)
  .then(checkDataValidity)
  .then(get("children"))
  .then(filter(targetIsNotHomepage))
  .then(forEach(writeMentionToFile));

function convertResponseToJson(response) {
  return response.json();
}

function checkDataValidity(data) {
  if ("children" in data) return data;

  throw new Error("Invalid webmention.io response.");
}

function targetIsNotHomepage(mention) {
  const targetUri = mention["wm-target"].replace(domain, "");
  return targetUri !== "/" && targetUri !== "";
}

function writeMentionToFile(mention) {
  const id = mention["wm-id"];
  const target = mention["wm-target"]
    .replace(domain, "")
    .replace("https://www.", "")
    .replace("https:/", "")
    .split("#")[0]
    .split("?")[0];

  const outputFolder = path.join(targetFolder, target);

  mkdirp.sync(outputFolder);

  fs.writeFileSync(
    path.join(outputFolder, `${id}.json`),
    JSON.stringify(mention, null, 2),
    { encoding: "utf-8" },
  );
}

</details>

With data stored per article path, src/components/Webmentions.astro can query the webmentions collection by slug to load only the relevant mentions:

const { slug } = Astro.props;


const webmentions = await getCollection("webmentions", ({ id }) => {
  return Boolean(id.includes(slug));
});

Automating the Script with GitHub Actions

To keep Webmention data current without manually re-running the script, a GitHub Action runs on a schedule to fetch new mentions, writing each mention to its own JSON file, and opening a pull request with the changes.

Example PR opened by GitHub Action that contains JSON associated with 11 new Webmentions

The Action lives at .github/workflows/webmentions.yml and runs on a cron schedule every 2 hours. A future refinement could trigger only on new Webmentions. Webmention.io supports webhooks which could be configured to send a POST request each time a verified mention is received.

on:
  workflow_dispatch:
  schedule:
    - cron: "0 0/2 * * *" # every 2 hours

<Callout variant="info"> Crontab is a handy resource for writing out cron expressions. </Callout>

The first few steps of the GitHub Action is installing dependencies and creating an environment variable for the Webmentions script to access.

 steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Create .env file
        run: |
          echo "WEBMENTION_API_KEY: ${{ secrets.WEBMENTION_API_KEY }}" >> .env
      - name: Set up Node.js
        uses: actions/setup-node@master

      - name: Install dependencies
        run: npm install

With dependencies in place, the Action runs the fetch script:

 - name: Fetch webmentions
        env:
          WEBMENTION_API_KEY: ${{ secrets.WEBMENTION_API_KEY }}
        run: node ./automations/store-webmentions.js

Once the new Webmention files are saved, the Action opens a pull request with the changes for review:

- name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v7
        with:
          token: ${{ secrets.GITHUB_TOKEN}}
          commit-message: Update WebMentions
          assignees: m0nica
          title: Update Webmentions
          body: Update Webmentions
          branch: fetch-webmentions

<details> <summary>View full GitHub Actions Script to Fetch and Save Webmentions</summary>

name: Webmentions

on:
  workflow_dispatch:
  schedule:
    - cron: "0 0/2 * * *" # every 2 hours

jobs:
  webmentions:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Create .env file
        run: |
          echo "WEBMENTION_API_KEY: ${{ secrets.WEBMENTION_API_KEY }}" >> .env
      - name: Set up Node.js
        uses: actions/setup-node@master

      - name: Install dependencies
        run: npm install

      - name: Fetch webmentions
        env:
          WEBMENTION_API_KEY: ${{ secrets.WEBMENTION_API_KEY }}
        run: node ./automations/store-webmentions.js

      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v7
        with:
          token: ${{ secrets.GITHUB_TOKEN}}
          commit-message: Update WebMentions
          assignees: m0nica
          title: Update Webmentions
          body: Update Webmentions
          branch: fetch-webmentions

</details>

Future Ideas

Automating Outgoing Webmentions

The next piece is automating outgoing Webmentions when new content is published. The wm CLI tool (@remy/webmention) makes this straightforward: pass in an RSS feed and it handles discovery and delivery.

npx webmention https://yoursite.com/feed.xml --limit 1 --send

Sophie Koonin covers how to wire this into a postbuild script so it re-runs automatically on every rebuild. However, since this site is written in MDX its RSS feed only contains excerpts as opposed to the full article. Whereas, the outgoing Webmention tool needs full content to find links worth mentioning. Jason Lengstorf documented a workaround in The terrible things I did to Astro to render MDX content in my RSS feed to provide more robust MDX support in RSS.

AI-Assisted PR Review

An AI moderation step would also improve the incoming side. The fetch-and-store script is responsible for retrieving the data as-is however, The PR review requires reviewing a batch of new JSON files, filtering for potential spam, and summarizing what arrived is the type of task a language model handles well with human supervision.

If you've solved the MDX-to-RSS problem in Astro or have thoughts on the AI moderation approach, feel free to reach out.

[^1]: "Webmention is an open web standard (W3C Recommendation) for conversations and interactions across the web, a powerful building block used for a growing distributed network of peer-to-peer comments, likes, reposts, and other responses across the web" — IndieWeb Wiki.

Delete Your Code and Other Reflections from Coderetreat Day

Sun, 17 Nov 2019 02:43:13 GMT

import { Tweet } from "@astro-community/astro-embed-twitter";

Trefoil Knot Conway's Game of Life, Source: Raphaelaugusto

I participated in the 2019 Global Coderetreat Day which was held on November, 16th, 2019, and attempted to solve "Conway's Game of Life" five times throughout the day. Each time I went through the problem with different people and focused on a different software development approach such as Test-Driven Development (TDD). TDD is a software development practice where individual unit tests are written before writing any functional logic and the specific tests dictate which functionality should be implemented next. By the end of the day, I had used various code editors including Visual Studio Code, CodeSandbox, Glitch, and Atom as well as different flavors of JavaScript and JavaScript testing.

What is Global Coderetreat Day?

Global Coderetreat Day is a specific day where volunteers across the world organize and facilitate Coderetreats. A Coderetreat is a day-long event where participants solve Conway's Game of Life multiple times throughout the day alongside another developer. The practice of solving a problem with another engineer is known as pair programming. The emphasis of a Coderetreat is on practicing fundamental software development practices without worrying about finishing a problem and events can either be language-agnostic or focus on a specific programming language. Traditionally, the problem solved is Conway's Game of Life but some Coderetreats may choose to focus on a different problem.

What is Conway's Game of Life?

Game of Life is a simulation in which there's a two-dimensional grid of cells where each cell is either alive or dead. The fate of each cell is dependent upon the state of its (up to 8) neighbors. Neighbors are considered to be cells that are horizontally, vertically, or diagonally adjacent.

The Simplified Rules of Conway's Game Of Life (source: Wikipedia)

Any live cell with two or three neighbors survives.

Any dead cell with three live neighbors becomes a live cell.

All other live cells die in the next generation. Similarly, all other dead cells stay dead.

Below is an illustration from the Coderetreat facilitation guide that shows how the above Game of Life rules play out to determine what state a cell will transition to. In particular, we are looking at the center cell (which would have the index [1][1] if this grid were represented as a multi-dimensional array). In the illustration, the live cells have a smiley face whereas the dead cells have the absence of an emoji and the blue emoji with the tongue stuck out indicates that the smiley is transitioning into being dead based on its current state and the number of live neighbors that it has.

Each time you attempt to solve Conway's Game of Life during a Coderetreat it is required that you start with a clean slate and get rid of all of your previous work and come ready to approach the problem from a different angle. Starting over can feel especially frustrating right after the first iteration in my opinion as a good amount of time can go into getting oriented with Conway's Game of Life, the premise of a Coderetreat and setting up the workspace to be productive. However, the beauty of having to completely delete the code in each round means that instead of relying on previous solutions (or mistakes) each iteration forces active recall vs passively referencing previous code. "Starting over" also leaves room for more innovation and exploration than just building on the same solution directly throughout the day would.

The Format of the Coderetreat

In the version of Coderetreat that I participated in, there were 5 iterations, which were ~40 mins. chunks of time to attempt to solve the problem. For each iteration, we were provided with different constraints, deleted all of our code and switched to pair with someone new. Each of these iterations provided me with the opportunity to address the problem from a different angle as I worked through the problem with someone different than in the previous iterations and with a new mental framework in mind. The format for each iteration varied as follows

focus on getting familiar with Conway's Game of Life and attempt our first solution
solve the problem with ping-pong pair programming
solve the problem with red-green refactoring
solve the problem focusing on very clear naming conventions
solve the problem by writing out all of the tests first

After each iteration we also had a mini-retro to discuss how the previous iteration went and how we felt about a particular approach.

Getting familiar with Conway's Game of Life, Coderetreat and greenfield development

The first iteration of Coderetreat was a bit challenging for me as I needed to collaborate with people I hadn't worked with before to quickly figure out how to get an environment up and running in a language with a testing framework. There was a lot of grunt work that needed to be completed before even starting to focus on solving the problem with code. Some folks chose to spend the first iteration getting more familiar with Conway's Game of Life versus setting up their environment. However, having some challenges while setting up a testing library from scratch and configuring the project to allow ES6 syntax during the initial iteration helped make later iterations a lot more efficient. Although in each iteration I was "starting over" from a code-perspective, after the initial one I was able to spend more time focusing on writing code and tests for the problem at hand and less time setting up tools.

Ping-Pong Pair Programming Approach

In particular, I enjoyed the ping-pong pair programming iterations as it lent itself to being a very structured way to approach the task at hand in a focused way and everyone had a clear role throughout the iteration. The ping-pong part of this approach involved one person writing an initial unit test to satisfy a requirement of Conway's Game of Life and then the other person worked to write code that made the unit test pass. Then the person who wrote functioning code writes another unit test that should be solved by the other person and then going back and forth writing tests and solving them until the iteration was over.

Red, Green, Refactor and Mob Programming Approach

I also enjoyed the red, green, refactoring approach in which we went through solving Conway's Game of Life first by writing a failing test (red), then writing code that solved the failing test (green) and then refactoring to improve the initial working solution without making the initial tests fail. During the initial phase when trying to get the test to pass we were instructed to write the "dumbest" code that would allow the test to pass even if that involved hard-coding the functionality. Also, in this particular iteration where the emphasis was on red, green, refactoring I worked in a mob (a group of three developers) where we had three distinct roles. A driver, observer, and navigator. The driver was responsible for actually typing code based on the navigator's instructions while the observer had a less perscriptive role. We decided that every 20 mins. the driver would switch and every 10 mins. the observer and navigator switched off to allow everyone to serve various roles. Like the ping-pong programming iteration, I appreciated having discrete roles for everyone for a set duration.

Naming Conventions Approach

The iteration which focused on programming with more clear naming conventions allowed me and my partner to focus on communicating more to ensure we were on the same page regarding the purpose of particular variables and methods. The approach of focusing on naming conventions led to me breaking down my approach to writing Conway's Game of Life into into smaller pieces which ultimately led to us discussing when and how to consolidate these highly descriptive functions. In other iterations that did not take this approach I was more likey to write more ambiguous function that handled significantly more logic.

Writing Test Cases Upfront Approach

The last iteration of the day involved coming up with a list of various tests upfront (within a few minutes) which I think helped ensure the solution we implemented would satisfy a large amount of test coverage. This was a good starting point and I could see the approach of deciding test cases upfront being very helpful if more time is spent writing out meaningful tests.

Above were the approaches we focused on during this particular Coderetreat but countless approaches or constraints could have been introduced like attempting to solve the problem without using any loops or without using conditionals.

Takeaways

My takeaways from Coderetreat, despite working through Conway's Game of Life numerous times weren't how to program Conway's Game of Life from end to end or even the most efficient way to approach programming. The key takeaways for me were more-so centered around how there a various approaches that can be taken when developing software and how different approaches shift my thinking, leading to different solutions. I ended up using JavaScript for each iteration and was able to see various ways that the same problem could be approached within one programming language e.g., from a more class-based or functional approach. I do not doubt that I barely scratched the surface on the types of approaches that could've been taken but I enjoyed the exploration.

I learned to get more comfortable deleting my code (without committing to git) since we had to destroy all remnants of our code between each iteration. The intent of this was to force us to approach each iteration with fresher eyes,ready to try a completely different approach and reinforce learnings from one iteration to another through active recall. I may want to incorporate this into my workflow by spending more time exploring various solutions to a problem and being okay doing a git reset or git stash and then trying a different approach.

I was challenged throughout the day to embrace the TDD principle of writing the simplest thing to make a test pass even if that meant the solution was hard-coded. Eventually you will hit a wall if all of the logic to satisfy unit tests is hardcoded vs more dynamic however this approach tries to prevent people from adding premature logic before it is required. The idea with this approach to TDD is solutions should evolve to be more sophisticated, as additional tests are added and introduce new requirements that cause breaking changes to more simplistic logic.

A strict TDD approach where you write the "dumbest" thing possible to pass a particular test can lead to writing functioning code that looks like this:

# my_first_calculator.py by AceLewis modified by Monica Powell

print('Welcome to this calculator!')
print('It can add whole numbers from 0 to 10')
num1 = int(input('Please choose your first number: '))
num2 = int(input('Please choose your second number: '))

if num1 == 0 and num2 == 0:
    print("0+0 = 0")
if num1 == 0 and num2 == 1:
    print("0+1 = 1")
if num1 == 0 and num2 == 2:
    print("0+2 = 2")
if num1 == 0 and num2 == 3:
    print("0+3 = 3")
if num1 == 0 and num2 == 4:
    print("0+4 = 4")
if num1 == 0 and num2 == 5:
    print("0+5 = 5")
if num1 == 0 and num2 == 6:
    print("0+6 = 6")
if num1 == 0 and num2 == 7:
    print("0+7 = 7")
if num1 == 0 and num2 == 8:
    print("0+8 = 8")
if num1 == 0 and num2 == 9:
    print("0+9 = 9")
if num1 == 0 and num2 == 10:
    print("0+10 = 10")

The above code is calculator function written in Python that takes in two numbers and adds them. While this particular calculator would pass tests up until a limit because all of the logic is hard-coded it will not know how to add numbers that are outside of its scope. The full version of this code on GitHub can add, subtract, multiply and divide whole numbers from 0 to 50, and is written a similar fashion to the sample above, however the author indicated that handling higher numbers led to Python crashing as the program isn't written in an efficient way. Therefore an important part of TDD is deciding when it makes sense to spend time optimizing a solution to pass several tests versus just hard-coding one's way through the problem.

Thank you Stride Consulting and App Academy for hosting the 2019 New York City Global Coderetreat Day. I enjoyed learning more about various software development practices and having the opportunity to workly closely with a handful of different people!

If you're interested in organizing your own Coderetreat their official website has plenty of resources to help you get started and if you would like to learn more about some of the principles I wrote about above, Corey Haines, one of the founders of the Global Coderetreat Day wrote a book "Understanding the Four Rules of Simple Design" that details his observations and learnings from watching thousands of pairs work through solving Conway's Game of Life.

Conquering the Command Line

Tue, 05 Dec 2017 17:11:11 GMT

A brief guide to getting started on UNIX/Mac OS terminal

Output on Mac OS terminal after typing: telnet towel.blinkenlights.nl

When I was first introduced to the command line I really had to adjust to navigating my computer in a black box with just text. So I avoided the command line as much as possible. I was accustomed to the visual cues and feedback that a computer usually provides. In many ways it felt like I was re-learning how to use a computer via the command line.

Yet, since first learning how to navigate my computer using UNIX commands I’ve learned that the command line doesn’t have to be a scary thing just because there’s no visual feedback when typing a password in on the command line. As security, nothing shows up as you type in your password to indicate that any characters have been entered.

What is the command line?

The command line is a software that executes commands or instructions for a computer to manipulate or interact with its file system.

What is UNIX?

Why Use the Command Line?

Faster to modify, navigate between files
Able to install software as a superuser
Can see hidden dotfiles
dotfiles are UNIX configuration files, they tend to be files that are proceeded with a . and are hidden to normal users.
You can learn more about getting started with dotfiles in this article).

In order to get started on the command line you should navigate to your applications and open the Terminal application.

Above is the Terminal Icon on Mac.

Create a Basic Website Folder on the Command Line

Folder structure of sample project

A folder with the above structure can be create on the command line by typing the commands inside of an empty directory:

We start inside of an empty directory!

Make a directory (also known as a folder) called personal-website
mkdir personal-website

We’ve created a folder named personal-website

Navigate to inside of the directory called personal-website
cd personal-website
create a directory, inside of the personal-website folder called assets
mkdir assets

We’ve created a folder inside of personal-website to contain all of our assets

Navigate inside of the assets folder which is inside of the personal-website folder
cd assets
create a directory, inside of the assets folder named images
mdkir images
create a directory, inside of the assets folder named js
mkdir js
create a directory, inside of the assets folder named css
mkdir css

We’ve created folders inside of personal-website/assets to store our project’s assets

Woops! We forgot to create an index.html file :(

We are in the assets folder and want an index.html file in our main personal-website folder. Typing cd .. will move us out of the assets folder and into the directory above which is personal-website. Now that we are in the personal-website folder if we type touch index.html a blank index.html file will be created.

Some frequently used terminal commands are:

commands to navigate/manipulate the filesystem

**ls
****list** the contents of a directory

pwd
print working directory for the terminal to display the directory you are currently working on

**touch
**create or open a file without making any changes
very handy when wanting to create empty files without leaving the command line

**sudo
**this allows you to run commands as a super user

mv
move a file or directorythis can be used to move or rename a file by updating the file path

cd
change the current directory you are working on so that you can access files on a different part of the system
cd moves you to the root directory (top level folder on computer — usually the current User)
cd . current directory
cd .. navigates to directory two levels up

mkdir
make a new directory (or a folder)

Commands to Install Software

You can install some software from the command line using the following commands:

in Python pip install <package name>.
Pip is a software package manager for Python.
in JavaScript npm install <package name>
NPM is a package manager for JavaScript pages.

Commands to Run Software

In order to run a script on the command line you need to provide a command prompt and file name. Some examples are:

in Java javac filename.java and then java filename compiles java projects and then runs them.
in Python python filename runs python scripts.

If you find you are repeating a lot of commands you can scroll through your recent commands using the up/down arrows and edit them and re-run by navigating to them and then pressing enter.

Additional Resources to Get Started with Command Line Prompts

Decorating the Command Line

You can completely customize the colors and outputs on the command line to better suit your visual and aesthetic needs.

Here’s how I’ve made my command line prettier :

How to install Tomorrow Night
https://github.com/chriskempson/tomorrow-theme/blob/master/OS%20X%20Terminal/Tomorrow%20Night.terminal

Customize the terminal
_I love the terminal. Besides the fact it makes you look awesome while using it, it can also do about a gazillion…_mindthecode.com

If you enjoyed reading this article consider tapping the clap button 👏. Wanna see more of my work? Check out my GitHub to view my code and learn more about my development experience at http://aboutmonica.com.

Gradients with Lerp

Thu, 05 Sep 2024 13:12:21 GMT

import P5Sandpack from "../../components/P5CustomSandpack.tsx" import CodePen from "../../components/Pen.astro"; import cliffordAttractor from "./assets/clifford-attractor.png"; import gradientGrid from "../sketches/gradient-grid/preview.png"; import lerpNumbers from "./assets/lerp-numbers.png"; import purplePinkGradient from "./assets/purple-pink-gradient.png"; import P5ExternalLink from "../../components/p5ExternalLink.astro"; import HexColor from "../../components/hexColor.astro"; import Callout from "../../components/Callout.astro";

Creative coding has given me a better appreciation for how math can be used to generate visuals, like this donut-shaped <a href="https://paulbourke.net/fractals/clifford/" target="_blank" rel="noreferrer noopener">Clifford Attractor</a> I created earlier this year during <a href="https://genuary.art/" target="_blank" rel="noreferrer noopener">#genuary</a>.

This article focuses on <a href='https://p5js.org/reference/p5/lerpColor/' target="_blank" rel="noreferrer noopener">lerpColor()</a> which is one of my favorite creative coding techniques and p5⁎js functions. It uses math to precisely compute the blended output of two colors.

What is Linear Interpolation?

Linear interpolation is a mathematical method used to "fill in the gaps" between two known data points. A straight line known as "linear interpolant" is created between the two data points and when given a desired position between the two that position is mapped to a value based on where it occurs in the straight line.

The above gradient is composed of ~200 rectangles that all have slightly different fill colors that seamlessly create a gradient when they're aligned. Explore the associated p5⁎js code and play around with the gradient below 👇🏾:

<P5Sandpack editorWidthPercentage={50} sketchJS={` const colors = [ "#ffadad", "#ffd6a5", "#fdffb6", "#caffbf", "#9bf6ff", "#a0c4ff", "#bdb2ff", "#ffc6ff" ];

let from; let to; let displayHelperText = true;

function setup() { colorMode(RGB); createCanvas(windowWidth, windowHeight); noStroke(); fill("#FFF"); textStyle(BOLD); textSize(20); from = color(random(colors)); to = color(random(colors)); }

// function draw() { // clear canvas of elements from previous draw clear();

let values = 200; let count = 0;

while (count < values) { let amount = count / values;

let x = (width / values) * count;
fill(lerpColor(from, to, amount));

rect(x, 0, 10, height);

count++;

}

if (displayHelperText) { textSize(windowWidth / 25); fill("#2a2135"); textAlign(CENTER);

text("Click Spacebar To Regenerate", width / 2, height / 2);

} }

function keyPressed() { const SPACEBAR = " "; // pause/play animation when spacebar is pressed for sketches that animate from draw to draw if (key == SPACEBAR) { from = color(random(colors)); to = color(random(colors)); displayHelperText = false; }

if (key === "s") { saveCanvas("gradient"); } }

function windowResized() { resizeCanvas(windowWidth, windowHeight); }

`} client:only="react" />

<br />

Computing color based on position

The same approach of computing the fill color of shapes based on the x or column position is applied in the below <a href="/sketches/gradient-grid">gradient grid</a> of irregular "squares" which uses lerpColor() to transition the colors from <HexColor color="#9f86c0"/> to <HexColor color="#e0b1cb"/> based on the position of the current shape (computed by column/height).

// parameters for lerpColor
lerpColor(c1, c2, amt);

The p5⁎js lerpColor() requires 3 parameters, c1 which is the color it interpolates from , c2 which is the color it interpolates to and amt which should be a number between 0 and 1.

The general algorithm used to create the color distribution of the shapes based on their column:

loop through each the x, y position of each element
set fill color using lerpColor based on the current element's column
draw shape to represent element

Now, let's translate that into p5⁎js code.

The below code shows how we can compute the shape's fill color value between <HexColor color="#9f86c0"/> and <HexColor color="#e0b1cb"/> based on its position.

const from = color("#9f86c0"); // c1
const to = color("#e0b1cb"); // c2
const amt = column / height;

// changes fill color based
// on the position of the element

fill(lerpColor(from, to, amt));

In the below example, the value of column/height varies from 0.206 to 1.646 in this particular grid and we see different color values for each column as they each has a distinct column/height value and therefore maps to a different color value between <HexColor color="#9f86c0"/> and <HexColor color="#e0b1cb"/>.

However, you may notice the latter half of the grid has 4 columns that appear to be the same color. This is due to the fact that the computed value of the column/height is greater than 1 and when you pass in a value less than 0 or greater than 1 then lerpColor() will normalize the value to the closest number between 0 and 1 in order to minimize strange results with the output color. This behavior is distinct from the similar lerp() function which is designed to be used with numbers and will compute values that are out of range of from it's numerical start and stop parameters.

Explore the associated p5⁎js code and play around with the grid of shapes below 👇🏾:

<P5Sandpack editorWidthPercentage={50} sketchJS={` function setup() { createCanvas(windowWidth, windowHeight); background("#faf4fb"); noStroke(); }

function draw() { noLoop(); background("#faf4fb"); let sz = 45; let numOfColumns = windowWidth / 12; let numOfRows = windowHeight / 12; let margin = .25;

const from = color("#9f86c0")

const to = color("#e0b1cb") let spacing = 50; for (let row =spacing; row < windowWidth - spacing ; row+= spacing) {

for (let column = spacing; column <windowHeight - spacing; column+=spacing) {

  const idx = Math.floor(map(row, 0, (windowWidth-spacing), 0, 2));
 

  fill(lerpColor(from, to, row/height))

  square(
    row,
   column,
    sz,
     random(5, 75),
    random(5, 75),
    random(5, 75),
    random(5, 75)
  );
}

} }

function mousePressed() { redraw(); }

function keyPressed() { const SPACEBAR = " "; if (key == SPACEBAR || key == "r") { redraw(); }

if (key === "s") { saveCanvas("random-shapes-grid"); } }

function windowResized() { resizeCanvas(windowWidth, windowHeight); }

`} client:only="react" />

<br />

Conclusion

Thanks for reading this article! I hope you learned something new about how linear interpolation can be applied to generating colors. I'd love to see what you create with lerpColor(). Feel free to share with me on <a href="https://x.com/indigitalcolor" target="_blank" rel="noreferrer noopener">Twitter</a>.

How to Add Search Functionality to a Gatsby Blog

Tue, 26 Nov 2019 02:43:13 GMT

I recently added functionality to this site to allow visitors to filter posts based on the posts description, title, and tags in an effort to allow better discovery of content. This tutorial will is based off of how I implemented a basic search on this site and will cover how to create a search filter on a site built with GatsbyJS. In particular, this tutorial walks through how to create an input field that allows users to filter a list of an entire Gatsby site's posts if the description, title or tags matches the input query. The solution proposed in this tutorial leverages GraphQL and React hooks to update the state to show appropriate data when content is filtered.

<center>Demo of the Search Filter</center>

Getting Started

Prerequisites

Although, some of the implementation details can be abstracted and applied in any React application to get the most value out of this tutorial you should have:

Some knowledge of ES6 and React
Local Gatsby site with Markdown posts
- If you have a Gatsby site without Markdown posts check out the Boilerplate Code or update the code in this tutorial to query posts from your data source instead.

If you do not yet have Markdown files on your site then you should start by adding markdown pages to Gatsby. You can also learn more about creating an index of markdown posts in the Gatsby Docs.

Boilerplate Code: Query All Posts

If you do not already have an index page listing all of your posts then create a new gatsby page for example named "writing.js" in src within the pages directory. This file will be responsible for rendering information about every post on your site.

We will be using a GraphQL page query which allows the data returned from the query to be available to the component in the data prop. The posts are returned by the page query and are equal to data.allMarkdownRemark.edges . Once we have the posts we can .map() through each of the posts and destructure the node.frontmatter with const { tags, title, date, description, slug } = node.frontmatter. This will add the title, date, description, and slug to the DOM for each post.

"Gatsby uses the concept of a page query, which is a query for a specific page in a site. It is unique in that it can take query variables unlike Gatsby’s static queries." Source: Gatsby Docs

Below is the boilerplate code that will be used throughout this tutorial:

import React from "react";
import { Link, graphql } from "gatsby";

const BlogIndex = (props) => {
  const { data } = props;
  const posts = data.allMarkdownRemark.edges;

  return (
    <>
      {/* in my site I wrap each page with a Layout and SEO component which have
    been omitted here for clarity and replaced with a React.fragment --> */}

      {/*in-line css for demo purposes*/}
      <h1 style={{ textAlign: `center` }}>Writing</h1>

      {posts.map(({ node }) => {
        const { excerpt } = node;
        const { slug } = node.fields;

        const { title, date, description, slug } = node.frontmatter;
        return (
          <article key={slug}>
            <header>
              <h2>
                <Link to={slug}>{title}</Link>
              </h2>

              <p>{date}</p>
            </header>
            <section>
              <p
                dangerouslySetInnerHTML={{
                  __html: description || excerpt,
                }}
              />
            </section>
            <hr />
          </article>
        );
      })}
    </>
  );
};

export default BlogIndex;

export const pageQuery = graphql`
  query {
    allMarkdownRemark(sort: { order: DESC, fields: frontmatter___date }) {
      edges {
        node {
          excerpt(pruneLength: 200)
          id
          frontmatter {
            title
            description
            date(formatString: "MMMM DD, YYYY")
            tags
          }
          fields {
            slug
          }
        }
      }
    }
  }
`;

At this point you should be able to view an index of all of the posts on your site by running gatsby develop and going to http://localhost:8000/${NAME_OF_FILE}. For example, the file I created is named writing.js so I navigate to http://localhost:8000/writing to view it. The page output by the boilerplate code above should resemble the below image (i.e., each blog post is listed along with its title, date, and description). Additionally, the header for each article should navigate to the slug for the article and be a valid link.

<center>Index Page of All Posts</center>

Why Query All of The Posts?

Before filtering the posts its helpful fetch all of the posts before we return a filtered subset from all of the posts. On my site, I used a page query on the /writing/ page to retrieve data for all the blog posts from my site so that I can construct a list of posts. The results of the page query are available to this component within the data prop to the component i.e., (const { data } = props).

The boilerplate code above is a variation of the GraphQL query that my site uses to pull in each post along with its excerpt, id, frontmatter (title, category, description, date, slug, and tags). The blog posts are in the allMarkdownRemark as edges and can be accessed like const posts = data.allMarkdownRemark.edges.You can use the above-provided query to return metadata and slugs for all posts OR if you already have a query to return an index of all blog posts then feel free to use that.

Below is a photo that shows the data that the above GraphQL query returned for my site. You can view the data returned by that query for your particular site in an interactive format by running gatsby develop and navigating to http://localhost:8000/___graphql and pressing run. If you go to http://localhost:8000/___graphql and scroll down you should see that there is metadata being returned for every single post on your site which is exactly what we are trying to capture before we filter posts.

<center>Sample Data in GraphiQL</center>

How to Filter Posts by User Input

Capture User Input with Input Event

Now that we have the boilerplate code setup let's get back to the task at hand which is to filter the posts based on user input. How can we capture what query a user is searching for and update the DOM with the appropriate post(s) accordingly? Well, there are various types of browser events including, input, keypress, click, drag and drop. When these events occur JavaScript can be written to respond based on the type and value of the event.

Since we are having users type a search query into a <input> we can process their query as they type. We will be focusing on the inputevent which triggers whenever the value in an input field changes. The input event changes with each keystroke which is in contrast to the change event which is fired once for each submission (i.e., pressing enter) for <input>,<select> and <textarea> elements. You can read more about how React handles events in the React docs.

Create Input Element with `onChange` event handler

We already have the post data we need to filter available in the data prop so let's create an element to allow users to type in their search query. <input/> will have an onChange property that calls a function handleInputChange whenever the <input/> changes and an Input event is fired. In other words, onChange calls another function which handles the Input event which fires every time someone types in our <Input/>. So if someone typed "React" into an <input/>. It will trigger 5 events with the following values ("R", "Re", "Rea", "Reac", "React").

Note: The <input/> should go below the <h1> and outside of the posts.map.


        <h1 style={{ textAlign: `center` }}>Writing</h1>
          <input
              type="text"
              aria-label="Search"
              placeholder="Type to filter posts..."
              onChange={handleInputChange}
          />
        {posts.map(({ node }) => {

The page should now visibly have an <input/> element. However, it will not yet be functional as handleInputChange has not been added yet.

<center>Visible Input Element</center>

useState() to Store Filtered Data and Query Information in State

Before implementing onChange let's set the default state with useState() for our search input with the default query as an empty string and filteredData as an empty array. You can read more about the useState() hook in the React docs.

  const posts = data.allMarkdownRemark.edges
  const emptyQuery = ""
  const [state, setState] = useState({
    filteredData: [],
    query: emptyQuery,
  })
  return (

Implement `onChange` to Filter Posts by `<input/>` Event Value

This handleInputChange function takes the Input event in which the event.target.value is the query string that is being searched for. handleInputChange also has access to our props which contain all of the posts for the site. So we can filter all of the site's posts based on the query and return filteredPosts.

In order to process the event (which fires on each keystroke) we need to implement handleInputChange. handleInputChange receives an Input event. The target.value from the event is the string that the user typed and we will store that in the query variable.

Inside of handleInputChange we have access to the posts and the query so let's update the code to .filter() the posts based on the query. First, we should standardize the casing of the fields and the query with .toLowerCase() so that if someone types "JaVAsCriPt" it should return posts that match "JavaScript". For our .filter() if any of the three conditions that check if the post contains the query evaluates to true then that post will be returned in the filteredData array.

After we filter the data in handleInputChange the state should be updated with the current query and the filteredData that resulted from that query.


  const [state, setState] = useState({
    filteredData: [],
    query: emptyQuery,
  })

const handleInputChange = event => {
  const query = event.target.value
  const { data } = props

  // this is how we get all of our posts
  const posts = data.allMarkdownRemark.edges || []


   // return all filtered posts
  const filteredData = posts.filter(post => {
    // destructure data from post frontmatter
    const { description, title, tags } = post.node.frontmatter
    return (
      // standardize data with .toLowerCase()
      // return true if the description, title or tags
      // contains the query string
      description.toLowerCase().includes(query.toLowerCase()) ||
      title.toLowerCase().includes(query.toLowerCase()) ||
      (tags && tags
        .join("") // convert tags from an array to string
        .toLowerCase()
        .includes(query.toLowerCase()))
    )
  })

  // update state according to the latest query and results
  setState({
    query, // with current query string from the `Input` event
    filteredData, // with filtered data from posts.filter(post => (//filteredData)) above
  })
}

return (
    <>

Now if you type in the <Input/> now it still won't update the list of posts because we are always rendering the same posts regardless of if we have filteredData available in the state or not. But if you were to console.log(event.target.value) in handleInputChange we can confirm that handleInput is firing properly by typing "React". Even though the page doesn't visually change the console output should be something like:

r writing.js:1
re writing..js:1
rea writing..js:1
reac writing.js:1
react writing.js:1

Display Filtered Posts

We are already storing filteredData and query in state but let's rename posts to allPosts so that we can make the value of posts conditional based on whether or not a user has typed a search query and should see their filtered search query results as posts or if they have yet to type a query then we should display all of the blog posts.

const BlogIndex = props => {
const { filteredData, query } = state
const { data } = props
 // let's rename posts to all posts
const allPosts = data.allMarkdownRemark.edgess
const emptyQuery = ""

For the posts we need to decide whether to return all of the posts or the filtered posts by checking state and conditionally rendering either all of the posts OR just the filtered posts based on whether or not we have filteredData and the query != emptyQuery.

The below code updates our render logic accordingly.

const { filteredData, query } = state;
// if we have a fileredData in state and a non-emptyQuery then
// searchQuery then `hasSearchResults` is true
const hasSearchResults = filteredData && query !== emptyQuery;

// if we have a search query then return filtered data instead of all posts; else return allPosts
const posts = hasSearchResults ? filteredData : allPosts;

Summary

You should now have a working post filter on your blog index page (if not check out the Final Code below). At a high-level the steps taken to implement filtering were:

create a page query to implement a blog index page which lists all of the posts
create an input field on the blog index page with an onChange event handler to process keystrokes in our input field
filter all of the posts on the blog index page based on the current query (from input event) and use useState() to update the state with the search query and filtered data
update rendering logic to either display all of the posts or the filtered posts on the blog index page based on whether or not there's a query in state

Below is the final code as outlined in the tutorial. However, this is just the baseline for search and you may want to make the functionality more robust by adding additional features such as autocomplete suggestions, displaying the number of results (based on length of posts) and providing an empty state with messaging for when there are zero results (based on filteredData being an empty array).

Final Code

import React, { useReact } from "react";
import { Link, graphql } from "gatsby";

const BlogIndex = (props) => {
  const { data } = props;
  const allPosts = data.allMarkdownRemark.edges;

  const emptyQuery = "";

  const [state, setState] = useState({
    filteredData: [],
    query: emptyQuery,
  });

  const handleInputChange = (event) => {
    console.log(event.target.value);
    const query = event.target.value;
    const { data } = props;

    const posts = data.allMarkdownRemark.edges || [];

    const filteredData = posts.filter((post) => {
      const { description, title, tags } = post.node.frontmatter;
      return (
        description.toLowerCase().includes(query.toLowerCase()) ||
        title.toLowerCase().includes(query.toLowerCase()) ||
        (tags && tags.join("").toLowerCase().includes(query.toLowerCase()))
      );
    });

    setState({
      query,
      filteredData,
    });
  };

  const { filteredData, query } = state;
  const hasSearchResults = filteredData && query !== emptyQuery;
  const posts = hasSearchResults ? filteredData : allPosts;

  return (
    <>
      <h1 style={{ textAlign: `center` }}>Writing</h1>

      <div className="searchBox">
        <input
          className="searchInput"
          type="text"
          aria-label="Search"
          placeholder="Type to filter posts..."
          onChange={handleInputChange}
        />
      </div>

      {posts.map(({ node }) => {
        const { excerpt } = node;

        const { slug } = node.fields;
        const { tags, title, date, description } = node.frontmatter;
        return (
          <article key={slug}>
            <header>
              <h2>
                <Link to={slug}>{title}</Link>
              </h2>

              <p>{date}</p>
            </header>
            <section>
              <p
                dangerouslySetInnerHTML={{
                  __html: description || excerpt,
                }}
              />
            </section>
            <hr />
          </article>
        );
      })}
    </>
  );
};

export default BlogIndex;

export const pageQuery = graphql`
  query {
    allMarkdownRemark(sort: { order: DESC, fields: frontmatter___date }) {
      edges {
        node {
          excerpt(pruneLength: 200)
          id
          frontmatter {
            title
            description
            date(formatString: "MMMM DD, YYYY")

            tags
          }

          fields {
            slug
          }
        }
      }
    }
  }
`;

Creating New Supabase Users In NextJS

Tue, 09 Mar 2021 12:01:39 GMT

import Callout from "../../components/Callout.astro";

<Callout variant="garden"> This article is the beginning of a series about setting up a NextJS with Supabase for user management and database storage. View the next part of this series:{" "} <a href="/blog/creating-protected-routes-in-next-js-with-supabase"> creating protected routes with NextJS and Supabase </a> </Callout>

This article walks through how to create new users for a Supabase database with an API written in NextJS. Note: at the time of this writing that Supabase is free for <a href="https://supabase.io/beta">beta</a> users which is pretty nifty as they include a hosted Postgres database which makes it faster to get an application up and running with a functional database. After the Beta period wraps up Supabase is <a href="https://supabase.io/docs/pricing">planning on charging for hosting</a> and will offer current Beta users 1 year of base tier usage for free.

I am currently building a SaaS (Software as a Service) website along with some other Egghead folks who are creating different types of SaaS applications. I am building this app from "scratch" and am currently in the phase of setting up authentication. For this project I am focused on learning new technology and documenting my learnings therefore I decided to try out Supabase, which is an Open Source alternative to Google's Firebase. The specific application I am working towards building is, <a href="https://shinedocs.com">Shine Docs</a> which will allow folks to document professional achievements in a granular way.

Here's a blurb from the project's README:

[...]your place to shine, showcase and document more granular professional (or otherwise) achievements. Did you fix a gnarly production bug in record time? Did you give your 1st (or 20th) conference talk? Did you write out some solid documentation? Make sure you capture all of this awesomeness in more in a dedicated space. These types of receipts translate well into future resumes, negotiations, annual reviews and reminders to yourself. Inspired by Julia Evan’s article on getting your work recognized with a brag document.

This application is intended for folks looking for more structure with how they document granular professional achievements as well as those looking to have their achievements be more visible.

Set Up NextJS

If you do not yet have a NextJS site you should set up a boilerplate NextJS site as a starting point. This can be done by running the command npx create-next-app to spinup up a default NextJS site. After going through the prompts you should open your newly created directory containing the site.

The next step in setting up NextJS to interact with Supabase is to install Supabase dependencies with @supabase/supabase-js and then run yarn dev to run the site locally. If everything worked out you should be able to visit localhost:3000 and see your Next site running.

Set up Supabase Project

On Supabase we will create a new project and then retrieve the API key and URL from https://app.supabase.io/project/yourprojecturl]/settings/api which can be navigated to by going to your project > settings > API.

a screenshot of the Supabase settings page

In order for our application to be able to interact with our project's DB we will use environment variables to store the necessary values. As a Mac user, I tend to store environment variables in ~/.bash_profile.

You can add the following your ~/.bash_profile or wherever you store local environment variables:

export SUPABASE_KEY="SUPABASEKEYFROMSETTINGSSCREEN"
export SUPABASE_URL="SUPABASEURLFROMSETTINGSSCREEN"

If you already have a terminal session running then after you save your environment variables you should run source ~/.bash_profile to ensure that the newly exported environment variables are available to your NextJS app to access.

We will then create a supabaseClient.js file (in utils/) to set up the Supabase client that is used to interact with Supabase DB to use the URL and API key that were set in the previous step.

import { createClient } from "@supabase/supabase-js";

// retrieving environment variables
const supabaseUrl = process.env.SUPABASE_URL;
const supabaseKey = process.env.SUPABASE_KEY;

export const supabase = createClient(supabaseUrl, supabaseKey);

Having the Supabase client live in a standalone file will be helpful when we have multiple API endpoints that interact with Supabase that require the same credentials.

Registering Supabase User

Now we will call Supabase to register users by creating a new API function inside of pages/api that uses our Supabase client.

import { supabase } from "../../utils/supabaseClient";

export default async function registerUser(req, res) {
  // destructure the e-mail and password received in the request body.
  const { email, password } = req.body;

  //make a SignUp attempt to Supabase and
  // capture the user (on success) and/or error.

  let { user, error } = await supabase.auth.signUp({
    email: email,
    password: password,
  });
  // Send a 400 response if something went wrong
  if (error) return res.status(401).json({ error: error.message });
  // Send 200 success if there were no errors!
  // and also return a copy of the object we received from Supabase
  return res.status(200).json({ user: user });
}

You can learn more about HTTP status codes on what different status codes mean on my site https://www.httriri.com/.

Now, let's actually use the Supabase endpoint to create users. Our site's visitors will fill out a form to register therefore let's create a form that requires an e-mail and password and calls the previously created Register endpoint upon form submission. This form will then be imported and used in our index file, index.js.

<form onSubmit={registerUser}>
  <label htmlFor="email">Email</label>
  <input id="email" name="email" type="email" autoComplete="email" required />
  <label htmlFor="password">Password</label>

  <input type="password" id="password" name="password" required />
  <button type="submit">Register</button>
</form>

Now let's define what happens onSubmit when registerUser is called by defining registerUser. This function will receive the email and password typed into the form from the form submission event and will make a post request to the register endpoint.

export default function Form() {
  const registerUser = async (event) => {
    event.preventDefault(); // prevents page from redirecting on form submissiomn

    // call default function in pages/api/register
    // send the email and password from form submission event to that endpoint
    const res = await fetch("/api/register", {
      body: JSON.stringify({
        email: event.target.email.value,
        password: event.target.password.value,
      }),
      headers: {
        "Content-Type": "application/json",
      },
      method: "POST",
    });

    const result = await res.json();
  };

  return <form onSubmit={registerUser}>// above form omitted for brevity</form>;
}

Now let's look at the response that we are getting back from the API request to the register endpoint.If we destructure res.json() like const { user } = await res.json() then we can see the user object for a successful request looks something like

user {
  id: '2de33395-b88b-4004',
  aud: 'authenticated',
  role: 'authenticated',
  email: 'test@example.com',
  confirmation_sent_at: '2021-03-09T12:35:02.895833829Z',
  app_metadata: { provider: 'email' },
  user_metadata: {},
  created_at: '2021-03-09T12:08:46.611304Z',
  updated_at: '2021-03-09T12:35:03.466491Z'
}

If we've received a 200 response (no errors!) and a user object back from our SignUp call to Supabase then we can redirect users to a message prompting them to confirm their e-mail address. We can use the NextJS router to handle this redirect:

import { useRouter } from "next/router";

export default function Form() {
  const router = useRouter();
  const registerUser = async (event) => {
    event.preventDefault();

    const res = await fetch("/api/register", {
      body: JSON.stringify({
        email: event.target.email.value,
        password: event.target.password.value,
      }),
      headers: {
        "Content-Type": "application/json",
      },
      method: "POST",
    });

    const { user } = await res.json();
    if (user) router.push(`/welcome?email${user.email}`);
  };

  return <form onSubmit={registerUser}>{/*omitted for brevity*/}</form>;
}

Now we are currently redirecting folks to a Welcome page that doesn't exist so let's create a new page page/welcome.js.

import Footer from "../components/footer";
import { useRouter } from "next/router";

export default function Welcome() {
  const router = useRouter();
  const { email } = router.query;
return (
      <main>
        <p>
          Thank you for signing up. Please check your {email} inbox to verify
          your e-mail address!
        </p>
      </main>
      <Footer />

    </div>

);
}

If all went well then if you fill out the form with an email address and password then you should be redirected to the welcome screen, receive a confirmation e-mail from Supabase to the e-mail you submitted and see under the Authentication section of your project at https://app.supabase.io/project/[yourprojecturl]/auth/users that there is a new user in your users table with the email address that you just submitted. By default Supabase is set up to not allow users to log in until they verify their e-mail address, so unless you've changed that setting you should see the column Last Sign In showing the value "Waiting for verification...".

Example Code on GitHub

Checkout out the example code for this article at: https://github.com/M0nica/register-supabase-users-nextjs-example

That's all I have for now! But I am looking forward to sharing more about how I implement Supabase as I continue my app development.

Creating Protected Routes In NextJS With Supabase

Sat, 13 Mar 2021 23:27:48 GMT

import Callout from "../../components/Callout.astro";

<Callout variant="garden"> This articles walks through how to create protected routes on NextJS with Supabase's user management. It assumes you already have a NextJS site up and running with the ability to create new Supabase users but if not check out the first part of this series on{" "} <a href="/blog/creating-new-supabase-users-in-next-js"> creating new Supabase users in NextJS </a> </Callout>

Supabase Auth Overview

Supabase has various methods in their JavaScript client library to handle user authentication and uses JSON Web Tokens (JWT) under the hood to manage authentication. If you want to learn more about how Auth works in Supabase check out the Supabase auth deep-dive video series. In order to have protected routes on our NextJS site, we'll need a way to register and authenticate users. We can perform these user actions and checks with the following methods from the Supabase Auth client. :

supabase.auth.signUp - We should give users the ability to create an account (covered in the first article on creating new Supabase users in NextJS)
supabase.auth.signIn - We need to give users the ability to sign-in. In this particular article, we'll cover the traditional method of using a username and password for sign-in but Supabase also supports other ways to log in, including OAuth providers (GitHub, Google, etc.) and magic links.
supabase.auth.user - We need a way to determine if a user is currently logged-in in order to ensure that logged-out users are not able to view pages that should only be accessible to logged-in users and that the proper information is displayed in various places like the site navigation.
supabase.auth.signOut - We should give users the ability to sign out and unauthenticate their session.

Create Protected Route

In order to create a protected route we need to have a particular page component we'd like to protect. For this example let's created a protected page at pages/protected.js that we can view at localhost:3000/protected when our site is running locally. This protected page will make a fetch request to a getUser API route to determine if there is currently an authenticated user loading the page. The API call should return the current user when there is one. We can then use this API response to redirect the page to the login page when there is no current user and only display user-specific information on the protected route when there is a user.

The API request can be made with getServerSideProps() which is a NextJS function that is called before a page renders. This allows us to redirect before the page renders based on the response from the getUser API call.

import { basePath } from "../utils/siteConfig";

export async function getServerSideProps() {
    // We need to implement `/api/getUser` by creating
    // an endpoint in `pages/api` but for now let's just call it
  const response = await fetch(`${basePath}/api/getUser`).then((response) =>
    response.json()
  );

  const { user } = response;

 // If the `getUser` endpoint doesn't have a user in its response
 // then we will redirect to the login page
 // which means this page will only be viewable when `getUser` returns a user.

  if (!user) {
    return {
      redirect: { destination: "/login", permanent: false },
    };
  }
  // We'll pass the returned `user` to the page's React Component as a prop
  return { props: { user } };
}
export default function Protected({ user }) {
  return (
          <p>
          // Let's greet the user by their e-mail address
            Welcome {user.email}!{" "}
            <span role="img" aria-label="waving hand">
              👋🏾
            </span>{" "}
          </p>{" "}
          You are currently viewing a top secret page!
  );
}

<Callout variant="danger"> In this instance, NextJS requires absolute paths for the API routes and if you do not have an absolute route then you'll receive the following error: <b>"Error: only absolute urls are supported"</b>. In order to resolve this I created a helper function in <b>utils/siteConfig</b> to set the basePath based on the environment. In order for this to work there needs to be a <b>PRODUCTION_URL</b> set in your deployed site's environment variables.

const dev = process.env.NODE_ENV !== "production";
export const basePath = dev
  ? "http://localhost:3000"
  : process.env.PRODUCTION_URL;

</Callout>

Now, we need to actually implement the getUser API route that the protected route is calling by creating a file pages/api/getUser.js. Within this file we will make a request to supabase.auth.user() which returns the current user when there is a user currently logged-in.

import { supabase } from "../../utils/supabaseClient";

export default async function getUser(req, res) {
  const user = await supabase.auth.user();
  return res.status(200).json({ user: user });
}

The above code assumes that you've already set up a Supabase Client which we covered in the <a href="/blog/creating-new-supabase-users-in-next-js">first post of this series</a>. The Supabase client we are using in this instance looks like the below and uses environment variables to determine the Supabase DB URL and associated key:

import { createClient } from "@supabase/supabase-js";

const supabaseUrl = process.env.SUPABASE_URL;
const supabaseKey = process.env.SUPABASE_KEY;

export const supabase = createClient(supabaseUrl, supabaseKey);

You can retrieve the API key and database URL associated with your Supabase project from https://app.supabase.io/project/yourprojecturl]/settings/api which can be navigated to by going to your project > settings > API.

a screenshot of the Supabase settings page

Sign-in and Redirect to Protected Page

We'll allow folks to log in and log out of the site using the sitewide navigation. In order to show the appropriate links based on authentication status, we can use the state to track if a user is currently authenticated. As a default, we'll set authentication status to false so that the navigation defaults to thelogged-out view.

When a user is authenticated then we will show the Sign Out text in the nav:

If there is no authenticated user then we will link to the Sign-in and Sign Up pages:

import Link from "next/link";
import { useEffect, useState } from "react";

export default function Header() {
  const router = useRouter();
  // Let's use state to track if a user is currently authenticated
  // As a default we'll set this value to false so that the navigation defaults to thelogged-out view
  const [isAuthed, setAuthStatus] = useState(false);

  // We'll set up the nav, on mount to call the getUser endpoint we just
  // created to determine if a user is currently logged-in or not
  useEffect(() => {
    fetch("./api/getUser")
      .then((response) => response.json())
      .then((result) => {
        setAuthStatus(result.user && result.user.role === "authenticated");
      });
  }, []);

  return (
    <nav>
      <div>
        // If user is authenticated then we will show the Sign Out text
        {isAuthed ? (
          <span>
            <h3>Sign Out &rarr;</h3>
          </span>
        ) : (
          // If there is no authenticated user then we will link to the Sign-in and Sign Up pages
          <>
            <Link href="/signup">
              <h3>Sign Up &rarr;</h3>
            </Link>
            <Link href="/login">
              <h3>Login &rarr;</h3>
            </Link>
          </>
        )}
      </div>
    </nav>
  );
}

When a user clicks "Sign In" from the nav we will navigate the user to the login page which contains a form to allow users to sign-in. The form will collect a user's email and password and on submit will fire a function signInUser which makes an API request to an API route for login and passes the email and password values from the form submit event to the API. If all goes well then we will receive a user object and can redirect (using NextJS's client-side router) to the /protected route that serves as a landing page for logged-in users.

import { useRouter } from "next/router";

export default function Form() {
  const router = useRouter();
  const signInUser = async (event) => {
    event.preventDefault();

    const res = await fetch(`/api/login`, {
      body: JSON.stringify({
        email: event.target.email.value,
        password: event.target.password.value,
      }),
      headers: {
        "Content-Type": "application/json",
      },
      method: "POST",
    });

    const { user } = await res.json();
    if (user) router.push(`/protected`);
  };

  return (
    <form onSubmit={signInUser}>
      <label htmlFor="email">Email</label>
      <input
        id="email"
        name="email"
        type="email"
        autoComplete="email"
        required
      />
      <label htmlFor="password">Password</label>

      <input type="password" id="password" name="password" required />
      <button type="submit">Login</button>
    </form>
  );
}

The login API route will use supabase.auth.signIn to sign-in a user. If a user is successfully signed in then the API will return a 200 response, or else the API will return a 401 response. The form is not yet set up to handle this 401 response but ideally, we'd want to return some type of message to the user informing them that their credentials were invalid and prompt them to attempt to sign-in again or reset their password. However, as this app is currently being built the functionality to reset password does not yet exist so this error path cannot be fully handled yet.

import { supabase } from "../../utils/supabaseClient";

export default async function registerUser(req, res) {
  const { email, password } = req.body;
  let { user, error } = await supabase.auth.signIn({
    email: email,
    password: password,
  });
  if (error) return res.status(401).json({ error: error.message });
  return res.status(200).json({ user: user });
}

Sign Out and Redirect to Homepage

Let's update the Sign Out link in the header to be functional by creating a signOut function that fires on click of the Sign Out text.

<span onClick={signOutUser}>
  <h3>Sign Out &rarr;</h3>
</span>

We'll also want to import a router from next/router to handle our client-side redirect.

import { useRouter } from "next/router";

For signOutUser let's make a call to a logout API route that sets the authStatus to false when a user is successfully signed out. We also want to ensure that when a user is not logged-in they are not viewing an authenticated page by redirecting to the homepage if a user logs out on a page other than the homepage. Without explicitly redirecting to the homepage when a user signs out, the state of authStatus would change in the nav as well as the logged-in vs.logged-out specific text however, the actual page regardless of authentication would continue showing protected information for unauthenticated users which we don't want.

const signOutUser = async () => {
  const res = await fetch(`/api/logout`);
  if (res.status === 200) setAuthStatus(false);
  // redirect to homepage when logging out users
  if (window.location !== "/") router.push("/");
};

Now we need to create the /api/logout route so that we can actually use it when the signOutUser function fires.

import { supabase } from "../../utils/supabaseClient";

export default async function logoutUser(req, res) {
  let { error } = await supabase.auth.signOut();

  if (error) return res.status(401).json({ error: error.message });
  return res.status(200).json({ body: "User has been logged out" });
}

Summary

So in conclusion, we created a protected route by creating a page component in NextJS that calls a getUser endpoint in getServerSideProps() and redirects to the log in page, instead of loading the protected route, when there is not a user returned. We also set up client-side routing to redirect users to /protected when they successfully logged-in and to the homepage / when they logged out. The core functionality to update and check authentication was handle in API routes using Supabase's various auth methods (signIn, signOut, user).

Example Code on GitHub

You can view the full source code for the example code at: https://github.com/M0nica/protected-routes-with-supabase-nextjs-example

Looking Ahead

I am looking forward to sharing more about the app development as I progress through my journey of developing <a href="https://shinedocs.com">Shine Docs</a> . As I wrap up the authentication for this site I am considering adding additional functionality like magic links or other auth providers, which are natively supported by Supabase. Before I extend the auth functionality to support additional ways of authenticating I will need to update the site to give users the ability to reset their own password and better handle authentication errors to ensure that the sign-in (are the user credentials invalid? did something go wrong during sign-in?) and sign up (has an e-mail already been claimed? is a password not secure enough?) flow are as seamless as possible.

Custom ZSH Startup Message

Wed, 28 Aug 2024 13:12:21 GMT

import Callout from "../../components/Callout.astro";

This post discusses how to customize the ZSH startup message displayed when opening a new terminal window. I recently synced my iTerm2 settings across my computer. I decided while tidying up my local development to update the ZSH startup message that appears on load to include a message and ASCII art.

[ASCII art] is the most universal computer art form in the world -- every computer system capable of displaying multi-line text can display ASCII art, without needing to have a graphics mode or support a particular graphics file format. — ASCII Art Archive

I browsed the ASCII Art Archive for inspiration from floppy disks to crowns to computers to abstract imagery and eventually settled on this GameBoy-inspired piece by Hayley Jane Wakenshaw.

 ___
|[_]|
|+ ;| hjw
`---'

Displaying Static Text in New ZSH Window

To display these characters when opening a new terminal window I needed to update my ~/.zshrc file (or include it in a file that my ~/.zshrc loads such as my ZSH theme file) to include the ASCII characters with each Line wrapped in double quotes preceded by the echo command.

 # ~/.zshrc OR your zsh theme file
 echo " ___"
 echo "|[_]|"
 echo "|+ ;| "
 echo "\`---'"

<Callout> Note: it is necessary to escape characters like backticks with \ otherwise the ASCII art will truncated prematurely and will not display properly on the command line. </Callout>

After updating my ~/.zsrhc I was able to verify the appearance of the text on start-up by running source ~/.zshrc within an existing terminal window or when opening a new window.

Using Variables with Prompt Text

In addition to printing out static information, one can also display different information depending on the value of a variable such as time. To determine the current hour one can use the following command:

date +"%H"
18 # output at 6PM

I decided based on the current hour to return a different greeting value by checking whether or not the current hour was -ge (greater than or equal to) or -le (less than or equal to) specific time ranges I defined.

# Get the current hour in 24-hour format
hour=$(date +"%H")

# Define time ranges
morning_start=5    # 5 AM
morning_end=11     # 11 AM
afternoon_start=12 # 12 PM
afternoon_end=17   # 5 PM


# Check the time of day and print a message
if [ "$hour" -ge "$morning_start" ] && [ "$hour" -le "$morning_end" ]; then
    greeting="Good morning"
elif [ "$hour" -ge "$afternoon_start" ] && [ "$hour" -le "$afternoon_end" ]; then
    greeting="Good afternoon"
else
    greeting="Good evening"
fi

 echo " ___"
 echo "|[_]|"
 echo "|+ ;|  ✦ $greeting, Monica! ✦" # string interpolation
 echo "\`---'"

The above script in my ~/.zshrc outputs a welcome prompt that appears like the below image:

The exact output that is displayed is one of the following messages depending on the time of day:

✦ Good morning, Monica! ✦
✦ Good afternoon, Monica! ✦
✦ Good evening, Monica! ✦

In summary, you can update your ~/.zshrc with echo to print out messages that only appear when source ~/.zshrc is initially run or a new terminal window is opened. In addition to always displaying the same welcome message, it can be updated based on various variables such as system values like the current time.

The full script for my oh-my-zsh theme, including the welcome message described in this article, is viewable in my dotfiles on GitHub.

Getting Started with SVG Animation

Tue, 13 Apr 2021 02:48:42 GMT

import VanillaCustomSandpack from "../../components/VanillaCustomSandpack.tsx";

export const bobaDemoProps = { html: <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Bubble Tea Animation</title> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" id="bubbletea" viewBox="0 0 346.68 473.2"> <defs /> <g id="tea" stroke="#8574a8" stroke-miterlimit="10" stroke-width="10"> <path fill="#a89bc4" d="M215.61 415.61c-13.45 21.59-38 47.78-45.61 50-20.94 6.15-107.6-8.78-137-46.11-11.27-14.3-24.81-31.32-27.23-48.54-3.89-27.74 8.33-54.38 9.8-59 17.16-53.69 81.06-197.19 94.31-196.67 56.33 2.23 126.71 34.48 177.65 58.63 9.25 4.39 23.16 9.23 22.63 19.92-2.63 52.72-65.04 174.41-94.55 221.77z" /> <path fill="#8574a8" d="M42.34 252.37c13.31-8.4 31.25-14.24 44.16-5.25 16.05 11.18 16.84 40.35 36.06 44 10.64 2 20.53-5.74 31.18-7.75 18.39-3.47 37.45 14.43 35.16 33-.46 3.73-1.62 7.54-.61 11.16 2 7.21 11.64 9.54 18.73 7.13s12.63-7.9 19-11.83 15-6.16 21.09-1.79c6.88 4.93 6.63 15.29 4.14 23.38-3.36 10.87-6 20.3-12.14 29.88-14 22-19.32 39.92-35.14 60.62-7.8 10.2-21.38 29.53-34 32-7.61 1.51-23.94 1.75-31.5 0-15.12-3.5-32.8-10.79-47.92-14.28-19.18-4.44-36.87-12.44-50.8-26.35-6.41-6.4-26.06-39.3-30.63-47.12-12.88-21.97 24-120.97 33.22-126.8z" opacity=".22" /> </g> <g id="cheeks" fill="#de9bb5" stroke="#de9bb5" stroke-miterlimit="10" stroke-width="10"> <ellipse cx="261.24" cy="323.62" rx="4" ry="14.5" transform="rotate(-68.17 110.06 395.85)" /> <ellipse cx="393.21" cy="376.5" rx="4.5" ry="15.5" transform="rotate(-71.17 245.891 442.235)" /> </g> <path id="mouth" fill="none" stroke="#6a5f71" stroke-miterlimit="10" stroke-width="10" d="M181.82 256.64c-8.55 5.26-19.73 5.71-28.93 1.68a36.68 36.68 0 01-19.54-21.78" /> <g id="boba" fill="#6a5f71" stroke="#6a5f71" stroke-miterlimit="10" stroke-width="10"> <circle id="boba-six" cx="47.65" cy="303.03" r="8.95" /> <circle id="boba-five" cx="77.84" cy="407.44" r="16" /> <circle id="boba-four" cx="154.25" cy="415.61" r="15.75" /> <ellipse id="boba-three" cx="115.13" cy="434.94" rx="11.9" ry="11.5" /> <ellipse id="boba-two" cx="52.35" cy="359.82" rx="17" ry="14.5" />  </g> <g id="eyes" stroke-miterlimit="10" stroke-width="10"> <circle cx="133.35" cy="193.96" r="23.5" fill="#6a5f71" stroke="#6a5f71" /> <circle cx="215.61" cy="228.68" r="23.5" fill="#6a5f71" stroke="#6a5f71" /> <ellipse cx="224.23" cy="240.42" fill="#fff" stroke="#fff" rx="1.62" ry="5.61" /> <ellipse cx="142.94" cy="205.18" fill="#fff" stroke="#fff" rx="1.62" ry="5.61" /> </g> <g id="cap" stroke-miterlimit="10" stroke-width="10"> <path fill="#e5dbdf" stroke="#e5dbdf" d="M98.37 79.4c3.74-1.79 20.34-7.92 38.72-10 21.7-2.49 46.27 1.75 56.81 3.31 54.13 8 109.9 38.76 128.83 58.08 4 3.58 5.32 8.7 7.93 13.16 2.41 4.13 11.59 12 11 16.92-1.49 12.16-18.42 29.51-21.17 25.22 0 0-149.18-64-225.64-69.65-9.28-.72-1.23-34.77 3.52-37.04z" /> <path fill="#e3e3e3" stroke="#e3e3e3" d="M339.21 148.15c.55-16 .22-32.88-8.21-46.42-6-9.67-15.52-16.54-24.78-23.16-12.29-8.78-24.68-17.62-38.36-24-45.7-21.37-102-12.26-144.83 16.68 71.57 26.4 146.57 43.9 216.18 76.9z" /> <path fill="#de9bb5" stroke="#de9bb5" d="M201 36.34c-.52-5.11-.88-10.32-2.77-15.1-3.44-8.67-12-14.94-21.28-16.05a29.75 29.75 0 00-25.12 9.7c-9 9.93-10.62 24.42-7.31 39.4a353 353 0 0137.56-9.93c6.48-1.34 13.24-2.6 18.65-6.44.37-.72 1.27-1.07.27-1.58z" /> <ellipse cx="464.34" cy="260.32" fill="#fff" stroke="#f7f7f7" rx="3.77" ry="25" transform="rotate(-68.97 314.274 330.766)" /> <circle cx="319.54" cy="133.41" r="5.75" fill="#fff" stroke="#fff" /> </g> </svg> </body> </html>, css: `:root { background-color: #f5ecf8; }

#bubbletea { display: block; margin-left: auto; margin-right: auto; width: 400px; }

#cheeks { -webkit-animation: blush 4s infinite; animation: blush 4s infinite; }

@-webkit-keyframes blush { 50% { stroke: #b7094c; } }

@keyframes blush { 50% { stroke: #b7094c; } }

#boba-two { -webkit-animation: jiggle 5s infinite; animation: jiggle 5s infinite; } #boba-three { -webkit-animation: jiggle 3s infinite; animation: jiggle 3s infinite; } #boba-four { -webkit-animation: jiggle 4s infinite; animation: jiggle 4s infinite; }

#boba-five { -webkit-animation: jiggle 2s infinite; animation: jiggle 2s infinite; }

#boba-six { -webkit-animation: jiggle 6s infinite; animation: jiggle 6s infinite; }

@-webkit-keyframes jiggle { 25% { -webkit-transform: translateY(3px); transform: translateY(3px); } 50% { -webkit-transform: translateY(6px) scale(0.98); transform: translateY(6px) scale(0.98); }

100% { -webkit-transform: translateY(4px); transform: translateY(4px); } }

@keyframes jiggle { 25% { -webkit-transform: translateY(3px); transform: translateY(3px); } 50% { -webkit-transform: translateY(6px) scale(0.98); transform: translateY(6px) scale(0.98); }

100% { -webkit-transform: translateY(4px); transform: translateY(4px); } } ` };

I attended Cassie Evan's SVG masterclass on getting started with SVG animation in February and have been enjoying creating and animating more SVGs in recent weeks.

Reading and Writing SVGs

You may be wondering what exactly are SVGs. ~~SVG's are magic!~~ The Scalable Vector Graphics (SVG) format is a human-readable image format. You can create and edit SVGs by writing XML or by editing the file in design software like Adobe Illustrator. SVG images are vector files that are mathematically calculated which means that even if you zoom into an SVG on a website or enlargen it for a billboard it will be just as sharp. In contrast, to vector files, pixel based images (generally photographs) will become blurry at different resolutions.

One of the cool things about SVGs is that once you understand how to read an SVG file you can change the colors (known as fill or stroke) programmatically.

</svg>

four squares generated by SVG's XML Markup

The code block below this paragraph represents the four SVG squares above. Each of the squares is a rect with a different fill color. Since the width and height is the same value of 300 these rects appear as squares and all of the squares have the same y coordinate which means they are aligned horizontal but have different x coordinates. If they had the same x and y coordinate they would overlap with each other. The viewBox property in the <svg/> that wraps these components determines how viewed in these shapes appear. Amelia Wattenberger created a great, interactive writeup for getting a better understanding of viewBox.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1728 500">
    <rect x="153.55" y="200" width="300" height="300" fill="#ff499e" />
  <rect x="519.55" y="200" width="300" height="300" fill="#99267e" />
     <rect x="883.41" y="200" width="300" height="300" fill="#9c5ea8" />
  <rect x="1263.41" y="200" width="300" height="300" fill="#798fd4" />
</svg>

I've also written an article about my SVG creation process for more complex SVGs.

Animating SVG elements

Since the visual properties of SVGs are written in a human readable format we can programmatically change different values of SVGs with CSS or JavaScript to create animations by applying a sequence of styling changes over a duration of time.

Below is an example of a Bubble Tea SVG that I animated with CSS to make the cheeks blush and move the bubbles around a bit. You can take a peek at the SVG in the HTML tab of the Codepen below to see how I structured the SVG. You may notice that can group different elements in SVG with a <g> which functions similarly to <div>s and can be target programmatically if there is a specific class or id associated with a group. Individual SVG shapes and paths can also have their own unique identifiers if you want to target more specifically but so far I've found that it's helpful to animate in groups.

The cheeks in the bubble tea SVG are grouped together with the id "cheeks"

<g id="cheeks" stroke="#de9bb5" stroke-miterlimit="10" stroke-width="10">

There's a default fill and stroke color set for the #cheeks based on the original color values in the SVG but we can use CSS to target the #cheeks and change the colors with the below animation that change the color of its thick stroke by applying a blush animation every that last a duration of 4s for an infinite amount of time.

#cheeks {
  /* play the blush animation for 4s and repeat an infinite amount of times */
  animation: blush 4s infinite;
}

Generally, on production sites you'd want to have more control over when an animation is running so that it isn't running continuously as opposed to just when visible or necessary for performance reasons.

The specifics for blush to change the fill color are then defined in @keyframes blush

@keyframes blush {
  50% {
    /* change from original fill color (defined in SVG)
    to #b7094c halfway through the animation */
    stroke: #b7094c;
  }
}

If you view the CodePen you can also see the separate jiggle animation instances that I applied to each of the individual #boba at different time points (offsetting the seconds measurement in animation: jiggle 5s infinite) with the CSS transform property which allows you to move, scale, rotate and more!

/* excerpt of applying the jiggle animation with different timing to different elements*/
#boba-two {
  -webkit-animation: jiggle 5s infinite;
  animation: jiggle 5s infinite;
}
#boba-three {
  -webkit-animation: jiggle 3s infinite;
  animation: jiggle 3s infinite;
}

Cross-Browser Compatibility

You may have noticed some of the CSS in the code examples in this article have prefixe like -webkit. These are vendor prefixes which allows developers to use newer features that aren't yet considered stable within a specific browser. You can use a website like: https://autoprefixer.github.io/ or a PostCSS tool like https://github.com/postcss/autoprefixer to automate adding these prefixes to your animations to ensure any more experimental features have as much cross-browser support as possible. In addition to using these vendor prefixing tools I'd recommend actually doing cross-browser testing for your animation work and being familiar with Can I Use which shows up-to-date information on browser compatibility for specific features.

The CSS animation examples in this article are relatively simple but more complex animations can be created using similar principles with with CSS animations or with animation libraries like GreenSock Animation Platform (GSAP)

Getting Started With Webmention and NextJS

Sat, 03 Oct 2020 16:51:30 GMT

import Callout from "../../components/Callout.astro";

This past week I had the pleasure of being on the Learn with Jason Show to show how to add Webmention functionality to a NextJS website. Webmentions let you pull tweets, other blogs, and other activity from around the web into your site? It was fun live pair programming the implementation of webmentions. Check out the video or read some of the highlights below!

Watch the Learn with Jason Episode

Watch the Learn with Jason episode below for more information about Webmentions and view the transcript at https://www.learnwithjason.dev/webmention-next-js:

</iframe> <br />

What are Webmentions?

Webmention are an IndieWeb specification to allow websites to collect comments from across the decentralized social web (i.e., Twitter, GitHub, Pinterest, Reddit) in a centralized place. A site can be set up to send an outgoing Webmention any time they link to an external website. Websites that receive Webmentions can then decide what content to display and bring the conversation to one place. I've mostly used Webmention to bring conversation from Twitter to my personal site.

Below is an image of how Webmentions appear on one my articles on this site:

Setting up Webmention Functionality

The easiest way to set up your site to start receiving Webmentions is to create an account with webmention.io to accept Webmentions on your behalf. If you'd like to bring in conversation from social media sites like Twitter, I'd recommend creating an account with bridgy which will automatically poll social media at set intervals and send any relevant content as a Webmention to webmention.io. Let's walkthrough how to set up the necessary accounts:

Begin receiving Webmentions with webmention.io Go to https://webmention.io/ and enter your website URL. It will prompt you to set up IndieAuth which requires you link to a social media site like Twitter on the homepage of your website with the HTML rel attribute value set to "me".

<a href="https://twitter.com/waterproofheart" rel="me"> Twitter</a>

This set up is required so that webmention.io can verify that the social media website you use to log in is actually associated with the website you want them to collect Webmentions for.

Once you've successfully set up your account you should see the following markup on webmention.io (with _your_ username) under _settings_:

```html
<link rel="webmention" href="https://webmention.io/username/webmention" />
<link rel="pingback" href="https://webmention.io/username/xmlrpc" />
```

This markup should be added to the head of your website and deployed so that Webmentions will officially begin being collected by www.webmention.io.

The above set up allows sites to start sending Webmentions to your site and allows you to be able to start sending Webmentions manually.

Set up Brid.gy to automatically receive mentions from Twitter and other social media websites Social media websites like Twitter generally don't automatically send Webmention notifications to site despite a lot of link sharing occurring on the site. Therefore, in order to automatically send mentions of your website on Twitter to your site as a Webmention you need to setup Brid.gy. Brid.gy requires that you authenticate with a social media acocunt and also have a link back to the same domain in your social media profile's bio section.

<Callout variant="danger"> {" "} We learned during the Learn with Jason stream that Brid.gy currently doesn't appear to support .app TLD domains and gives a vague error where it doesn't recognize these domains when trying to authenticate. </Callout>

Fetching and Rendering Webmentions

1. Fetch Webmentions

We used useEffect to make a fetch request from webmention.io to retrieve the Webmentions associated with our site and stored its result in state as mentions. The endpoint that the request is made to is https://webmention.io/api/mentions.jf2?[webmentioniousername]&token=[webmentioniotoken]. This URL should be updated with your webmentionio username and webmentionio token. Note the token only provides read-only access you can choose to keep the token a secret but re-generate as needed.

Since useEffect only triggers after the initial hydration of a React site, this request only occurs on the client-side and requires JavaScript to be enabled in order to fetch Webmention data. This means that you don't have to worry about rebuilding your site in order to retrieve the latest Webmention data.

const [mentions, setMentions] = useState([]);
useEffect(() => {
  fetch(
    "https://webmention.io/api/mentions.jf2?[webmentioniousername]&token=[webmentioniotoken]",
  )
    .then((response) => response.json())
    .then((result) => {
      setMentions(result.children);
    });
}, []);

If you are curious what the shape of the initial object returned by the endpoint looks like some recent Webmentions I received were shaped like:

            {
  "type": "feed",
  "name": "Webmentions",
  "children": [
    {
      "type": "entry",
      "author": {
        "type": "card",
        "name": "Debra-Kaye Elliott",
        "photo": "https://webmention.io/avatar/pbs.twimg.com/ca78346285aa621eedce7fa271025576c97a19577b4820c9951853d09a829ad8.png",
        "url": "https://twitter.com/debrakayelliott"
      },
      "url": "https://twitter.com/waterproofheart/status/1312230169491447815#favorited-by-261719963",
      "published": null,
      "wm-received": "2020-10-03T17:29:46Z",
      "wm-id": 864384,
      "wm-source": "https://brid-gy.appspot.com/like/twitter/waterproofheart/1312230169491447815/261719963",
      "wm-target": "https://www.aboutmonica.com/blog/set-yourself-up-for-success-open-source-contributions/",
      "like-of": "https://www.aboutmonica.com/blog/set-yourself-up-for-success-open-source-contributions/",
      "wm-property": "like-of",
      "wm-private": false
    },
    {
      "type": "entry",
      "author": {
        "type": "card",
        "name": "Anders Schneiderman",
        "photo": "https://webmention.io/avatar/pbs.twimg.com/37890c358e8ff1f667c57d89959e583af37ef66d39b6d3c372d9b7988f5a377f.jpg",
        "url": "https://twitter.com/raschneiderman"
      },
      "url": "https://twitter.com/waterproofheart/status/1312230169491447815#favorited-by-270006742",
      "published": null,
      "wm-received": "2020-10-03T15:08:41Z",
      "wm-id": 864330,
      "wm-source": "https://brid-gy.appspot.com/like/twitter/waterproofheart/1312230169491447815/270006742",
      "wm-target": "https://www.aboutmonica.com/blog/set-yourself-up-for-success-open-source-contributions/",
      "like-of": "https://www.aboutmonica.com/blog/set-yourself-up-for-success-open-source-contributions/",
      "wm-property": "like-of",
      "wm-private": false
    },
    ]}

You can also view the shape of the data by going directly to https://webmention.io/api/mentions.jf2?[webmentioniousername]&token=[webmentioniotoken].

2. Render Webmentions

Once we have the mentions stored in state from the request to webmention.io we can map through the mentions and render the a link to the Webmention author's original post, their photo, name and the content of their Webmention.

{
  mentions.map((mention) => (
    <div>
      <a href={mention.author.url}>
        <img
          style={{ width: 100 }}
          src={mention.author.photo}
          alt={mention.author.name}
        />
      </a>
      <div dangerouslySetInnerHTML={{ __html: mention.content.html }} />
    </div>
  ));
}

Final Code

Below is more complete version of the above code with some styling. Check out the demo repo for the application I created with Jason on Learn with Jason here: https://github.com/jlengstorf/next-netlify-webmention

import { useEffect, useState } from "react";

const Index = ({ ...props }) => {
  const [mentions, setMentions] = useState([]);
  useEffect(() => {
    /* add your webmentionio username and webmentionio token.
        Note the token only provides read-only access
        you can choose to keep the token a secret but re-generate as needed */
    fetch(
      "https://webmention.io/api/mentions.jf2?[webmentioniousername]&token=[webmentioniotoken]",
    )
      .then((response) => response.json())
      .then((result) => {
        setMentions(result.children);
      });
  }, []);
  return (
    <>
      <Layout>
        <h2>Discussion about this site on the web</h2>
        <p>This uses Webmention</p>
        {mentions.map((mention) => (
          <div
            style={{
              display: "grid",
              gap: "1rem",
              gridTemplateColumns: "100px 1fr",
            }}
          >
            <a href={mention.author.url}>
              <img
                style={{ width: 100 }}
                src={mention.author.photo}
                alt={mention.author.name}
              />
            </a>
            <div dangerouslySetInnerHTML={{ __html: mention.content.html }} />
          </div>
        ))}
      </Layout>
      <style jsx>{`
        .title {
          margin: 1rem auto;
          font-size: 3rem;
        }
      `}</style>
    </>
  );
};

export default Index;

git is hard, but time travel in git is easy.

Sun, 24 Mar 2019 02:43:13 GMT

This article will explain how it's possible to commit code that is dated in the future.

I always (wrongly) assumed that GitHub determined the time a commit was made based on their website's server time. I made this assumption because for certain user actions GitHub uses their server time, for example when a pull request is opened. However, one day I was debugging a calendar issue that only appeared for certain dates. I was able to reproduce and resolve the bug locally by changing my computer time. I then pushed the git branch with my solution up to the remote git repository on GitHub for code review and realized that GitHub commits reflect the date set in the local version of the git repository which is determined by your computer's system time and not their servers.

GitHub, GitLab and BitBucket are git repository hosting services, that provide a centralized place to host remote versions of git repositories. These websites have additional functionality build on top of git to make the software development process more collaborative through things such as code review interfaces and other features that make it more of a social network than just a command line interface.

If you want to intentionally for whatever reason commit something in the future, do you have to manually adjust your computer's time? No, you can simply pass git environment variables to set the date and time.

The following line:

GIT_AUTHOR_DATE="Wed Mar 27 15:12:30 2019 -0700 GIT_COMMITTER_DATE="Wed Mar 27 15:12:30 2019 -0700”
git commit -m “future commit”

will date a commit as March 27, 2019 whether the current date is before or after March 27th. If you send in a patch to a project and one of the core members applies the patch, both of you get credit — you as the GIT_AUTHOR, and the core maintainer as the GIT_COMMITTER.

You can rewrite your git history and apply changes to any past commit as well.

This post is based off of a lightning talk that I gave with Women Who Code NYC in March 2019. The slides can be viewed here.

Give Your CSS Superpowers with CSS Variables

Fri, 22 May 2020 13:41:29 GMT

import Callout from "../../components/Callout.astro";

What are CSS variables?

CSS variables or CSS custom properties are a way to declare reusable values within a CSS project. CSS variables can greatly reduce the repetition of code and allow us to reference more semantically meaningful names throughout our stylesheets like "--accent-color" versus the actual value they represent "#b5838d".

<Callout> {" "} Most modern browsers support CSS variables. If you need to know whether or not CSS variables are supported in a particular browser without a polyfill it's a best-practice to reference browser-compatibility specifications on sites like{" "} <a href="https://caniuse.com/#feat=css-variables">Can I use?</a> or{" "} <a href="https://developer.mozilla.org/en-US/docs/Web">MDN web docs</a>. </Callout>

Current CSS Variables Browser Support (Source: MDN Web Docs)

How to declare CSS variables

In order to use CSS variables you should create a CSS custom property, which is a string prepended with a double hyphen --. These properties are scoped and available based on their selector. Generally, it is recommended to make the selector the pseudoselector :root so that it will apply throughout an entire site. If you select a more specific selector then the scope of where you can access the value of the variable changes accordingly.

Below is an example showing 5 different CSS variables being declared to represent different colors within a stylesheet.

:root {
  --white: #fff;
  --accent-color: #b5838d;
  --dark-accent-color: #a6757f;
  --main-color: #6d6875;
  --dark-main-color: #56505f;
}

In order to access the these CSS values throughout our CSS we can use the var() method like var(--accent-color). The following example selects the element with the signup class and changes its background-color to #b5838d.

.signup {
  background-color: var(--accent-color);
}

Since the value of --accent-color is being set with a CSS variable if we later decide to change the value of var(--accent-color) we only have to change it in one place, where the variables value is declared. Once the value of the variable is updated its new value will automatically be reflected everywhere var(--accent-color) is referenced. Being able to change the color in one place for a multitude of unrelated elements that are only coupled by color is powerful.

The Power of CSS Variables

CSS variables allow you to quickly play around with a color scheme and tweak the same color everywhere it is referenced without having to do a find and replace. Additionally, setting up CSS variables can improve the developer experience when creating color schemes, as you can switch the variable declaration values between themes without having to explicitly change the values within the rest of the stylesheet.

The two screenshots below show the difference in appearance when one line in the CSS file is changed from --accent-color: orange; to --accent-color: #b5838d; which is used in two completely separate places -- on the card's border-top property and the background color for the signup button. This can be very useful as stylesheets grow and values are re-used throughout.

`--accent-color: orange;`	`--accent-color: #b5838d;`

Explore CSS variables!

Play around with the CSS variable values by editing the below Codepen to see CSS variables in action!

https://codepen.io/M0nica/pen/jObpJma

Grey's Anatomy Lorem Ipsum Generator Tutorial

Sun, 02 Jun 2019 11:43:13 GMT

This tutorial is going to walk through how to create a Grey’s Anatomy or other-themed Lorem Ipsum generator. I’m a huge fan of the show, Grey’s Anatomy (and Shonda Rhimes in general) for a while so I was overdue for creating a Grey’s Anatomy-themed Lorem Ipsum generator. Lorem Ipsum is generated, nonsense text that is used in design and publishing as placeholder text. Traditionally, Lorem Ipsum is written with Latin words but there are variations that involve non-Latin words as well.

The live version of the Grey's Anatomy Lorem Ipsum Generator website can be viewed here and the code for this tutorial can be viewed on Github.

Here’s an example of the type of text that is generated by the Grey's Anatomy Lorem Ipsum generator:

“real hospital Dr. Cristina Yang well a trauma surgical fellow badly chief of pediatric surgery George Ellis orthopedic surgeon Dr. Shane Ross approximately Dr. Callie Torres exactly Dr. Izzie Stevens Izzie chief of plastic surgery an anesthesiologist Meredith’s father Zola Seattle Erica certainly Meredith Dr. Shane Ross basically basically Tucker maybe Dr. Virginia Dixon whoever Chief Richard Sadie significantly nicely Arizona real very Dr. Colin Marlowe Zola mostly things Dr. Teddy Altman rather Arizona Dr. Teddy Altman Seattle Dr. Izzie Stevens my person”

The above paragraph makes absolutely no sense but if you’re familiar with Grey’s Anatomy there are some familiar terms baked in there.

Requirements

To get the most out of this tutorial you should:

Have familiarity with git and JavaScript
Have a GitHub or GitLab account (in order to use Netlify functions).

Set Up

In order to jump-start this project, I used Netlify’s GitHub - netlify/create-react-app-lambda starter. Netlify is a hosting service that specializes in hosting JAMstack websites, as of writing this tutorial, has a pretty comprehensive free tier(Plans and Pricing | Netlify) that integrates well with deploying GitHub projects to the world wide web. JAMstack is used to describe static websites that are compromised of JavaScript, APIs, and Markup. You can learn more about what is or isn’t considered JAMstack here JAMstack | JavaScript, APIs, and Markup ,

The create-react-app-lambda repository integrates Netlify’s functions with create-react-app which means out of the box you can deploy a React application that calls, Serverless functions, which you may know as Amazon Web Services (AWS) Lambdas. These functions can make asynchronous calls and process data but they must be stateless, meaning that given the same inputs the output will be the same. With Netlify you can deploy and manage AWS Lambda’s technology without an AWS account. You can read more about Serverless Lambda Functions on Netlify here: Functions | Netlify.

Let’s get started by copying over create-react-app-lambda . Click on the “Deploy to Netlify” button in the README.

This one-click button allows us to set up React + Netlify Functions without having to do heavy lifting. Essentially when you click the button you are creating a new site in Netlify and a connected GitHub repository. It takes a few minutes for the GitHub repository to populate with the files but once it is done populating you should be able to visit Netlify and view your site. If you’d like a better understanding of why things were set up the way they were in the create-react-lambda-app then check out this video by Shawn Wang (swyx) for more context.

After clicking the "Deploy to Netlify" button you should see something like this:

Note: Comprehensive instructions for interacting with the create-react-lambda-app project live in the README. I will highlight the most important pieces to interact with the app but encourage exploring the README for more information and to further enhance the application.

So once the repository that you created in Netlify is populated with files from create-react-app-lambda you should git clone the repo. The repository that you are cloning should be named after the repo that you created, i.e., git clone git@github.com:your_username/app-just-created. You may have to refresh the repository page before the files are populated.

Once the project is set up you should cd into the project directory and run yarn to install all of the dependencies. You can run yarn test to ensure that all of the tests are passing and the project was set up properly.

The Netlify functions should be created in src/lambda. If you look in that folder there are two sample functions async-dadjoke.js and hello.js. For our use case we don’t need an async function so let’s look at the hello.js example

In hello.js we are getting the queryStringParameters from the event in order to log them. queryStringParameters can be accessed from the event like event.queryStringParameters or by destructuring the event object like const {queryStringParameters} = event.

export function handler(event, context, callback) {

  console.log(“queryStringParameters”, event.queryStringParameters)

  callback(null, {

    statusCode: 200,

    body: JSON.stringify({ msg: “Hello, World!” })

  })

}

Every Lambda function has a handler function. This handler function can take event, context, and callback. The event is based on what the endpoint received when the request was made it can include things like cookie information, headers, queryStringParameters, etc. The context object provides additional insight regarding a Lambda’s execution. You can learn more in the AWS docs here: AWS Lambda Function Handler in Node.js - AWS Lambda

Verify Set Up

In order to tests the functionality of the endpoint we should run yarn start:lambda, in the directory we just clone, which will run all of your Lambda functions. And then you can visit http://localhost:9000/hello or / whatever the name of your function is. On this page, you should see: {“msg”:”Hello, World!”} since that is the body of the endpoint’s response.

Calling the Netlify function from React

Next, I would recommend customizing the naming conventions in the project to better fit your needs. I renamed hello to generate-lorem-ipsum, so first I rename thehello.js file to generate-lorem-ipsum and then in the LambdaDemo component in app.js , I replaced the call to hello on button click to generate-lorem-ipsum . While I was there I also deleted the button related to async-dadjoke and removed the associated file. So I went from

<button onClick={this.handleClick("hello")}>{loading ? "Loading..." : "Call Lambda"}
</button>

<button onClick={this.handleClick("async-dadjoke")}>{loading ? "Loading..." : "Call Async Lambda"}
</button>

to:

<button onClick={this.handleClick("generate-lorem-ipsum")} className=“button”>
            {loading ? “Loading…” : “Generate Lorem Ipsum”}
</button>

The button is calling the Netlify function on click, you can look at the handleClick for more information about what happens when you click on the button, initially It returns loading as the state and then eventually the response.msg.

Note: I updated references to LambdaDemo() to LambdaCall()in App.js because it’s show time!

In order to check the lambda is still being called and returning a response you should run yarn start (while yarn start:lambda is running in another terminal window). You should be able to visit http://localhost:3000 and see the React app with a “Generate Lorem Ipsum” button. If you click then the words “hello world” should appear on the site below the button.

Adding Lorem Ipsum Logic

So now we need to edit the generate-lorem-ipsum.js file so that it returns Lorem Ipsum and not “Hello World”. We will achieve this by creating a word bank of terms in words.js and the following functions in the generate-lorem-ipsum.js file: handler() generateLoremIpsum() generateWords() generateParagraphs() getRandomInt()

The handler() is the entry point into the file, therefore any functions that need to execute should either be called in the handler() or called by the functions that the handler() calls. First, we destructure the event to get the queryStringParameters.

For example, if someone calls our endpoint with the following query string parameter /generate-lorem-ipsum?paragraphs=4&words=0

Then we would de-structure the event object to determine that the endpoint was requested to return 4 paragraphs and 0 words.

const event = {
queryStringParameters: {
paragraphs: “4”,
words: “0”
}
};

The handler will call a function generateLoremIpsum to actually handle generating the text, it takes in whether or not multiple paragraphs or just words should be returned. By default if there are no queryStringParameters it will return 4 generated paragraphs.

The handler() could end up looking something like this:

export function handler(event, context, callback) {
  const { queryStringParameters } = event;
  const { paragraphs = 0, words = 0 } = queryStringParameters;

  let isParagraph = Boolean(paragraphs);
  let count;

  if (paragraphs > 1) {
    count = paragraphs;
  } else if (words > 0) {
    count = words;
  } else {
    isParagraph = true;
    count = 4;
  }

  let response;
  try {
    response = isParagraph
      ? generateLoremIpsum(isParagraph, count).join(" ")
      : generateLoremIpsum(isParagraph, count);
  } catch (error) {
    console.log(error);
  }

  callback(null, {
    statusCode: 200,
    body: JSON.stringify({ msg: response }),
  });
}

In this example generateLoremIpsum() is a function called by the handler() and used as a fork in the road to determine if multiple paragraphs should be generated or just one based on if isParagraph is true or false.

export function generateLoremIpsum(isParagraph, count) {
  if (isParagraph) {
    console.log(`Trying to construct ${count} paragraphs`);
    return generateParagraphs(count);
  } else {
    console.log(`Trying to return ${count} words`);
    return generateWords(count);
  }
}

If we are generating a single paragraph the generateWords() will be called directly. This function creates an array of random words (based on getting a randomInt and adding the word at that index to the array until we reach the desired wordCount. In order to format the words once we have all of the words the words are formatted like const formattedWords = <p>${words.join(" ")}</p>;` in order to easily be able to transform the function’s response into an HTML paragraph later.

export function generateWords(wordCount) {
  let words = [];
  console.log(wordCount);

  for (var i = 0; i < wordCount; i++) {
    words.push(WORDS[getRandomInt()]);
  }
  const formattedWords = `<p>${words.join(" ")}</p>`;

  return formattedWords;
}

The random int in the generateWords() function is calculated with the following function:

export function getRandomInt() {
  return Math.floor(Math.random() * Math.floor(WORDS.length));
}

In the case where we are generating paragraphs we need the function generateParagraphs(). This function will generate X paragraphs with 50 words until it reaches the paragraphCount. It does this by calling the generateWords() function X times where X equals the paragraphCount that was passed in.

export function generateParagraphs(paragraphCount) {
  let paragraphs = [];
  for (var I = 0; I < paragraphCount; I++) {
    paragraphs.push(generateWords(50));
  }
  return paragraphs;
}

In order for any of the above to work we need a word bank to draw from. At the top of generate-lorem-ipsum.js we should import { WORDS } from "./words"; and then in the same directory create a file called words.js. In words.js we are going to create an array called WORDS and export it so that other functions can read it.

I created an array with just filler words( fillerWords) and another with Grey’s Anatomy and medical terms (greysAnatomyWords). Used ES6 spread operator to combine the arrays into one. export const WORDS = […greysAntomyWords, …fillerWords];

The full file should look something like:

const greysAnatomyWords = ["Meredith Grey", "Shonda Rhimes", "Epi", "Cardio"];

const fillerWords = [
  "actual",
  "actually",
  "amazing",
]`export const WORDS = […greysAntomyWords, …fillerWords];`;

Methodology

In a full blown project we would need a lot of words or else it will be too repetitive. If you want to create another type of themed Lorem Ipsum then you would replace the greysAnatomyWords with words from a theme of your choice.

For the grey’s anatomy words I brainstormed and also found some lists like this Grey’s Anatomy Baby Names article that I was able to re-purpose. The process of cleaning up the data and formatting into valid JSON can be a bit tedious, I did find and replace for formatting where I could and some manually updating as needed. This allowed me to get as much data as possible with minimal effort (I.e., automating the scraping of terms). I ended up with about 140 terms for my generator but if I needed a larger data set then it may have made sense to consider exploring a tool like BeautifulSoup or Selenium to automate scraping a data source and saving that data into a valid JS file.

Note: Depending on how repetitive data is can create Map or filter to make sure that the array of words only has unique values.

I decided to add in filler words so that the generated Lorem Ipsum text would have a healthy mix of verbs and adverbs in addition to the themed. I Google’d filler text and found the following repository, I copied the filler words from there: fillers_data.txt at master · words_fillers · GitHub

Now if you run yarn start:lambda and visit http://localhost:9000/generate-lorem-ipsum/you should see 4 generated paragraphs of lorem ipsum returned. It should look something like:

“msg”:”<p>especially surgicial mostly try hospital anyway Seattle Dr. Lucy Fields Alex a trauma surgical fellow Dr. Mark Sloan my person heavily wherever Theodora Duquette Dr. Virginia Dixon cried a nurse a neurosurgeon really Margaret Dr. Mark Sloan Dr. April Kepner Meredithâ€™s father literally Dr. Alex Karev Dr. Izzie Stevens an anesthesiologist Denny much necessarily Surgery a trauma surgical fellow surely hardly Owen rather Shepherd totally cried chief of pediatric surgery Theodora Dr. Robert Stark Olivia an anesthesiologist get her up to CT actually Cristina Dr. Finn Dandridge</p> <p>Tucker Virginia Callie Torres mostly hardly Maggie Maggie get her up to CT hardly get him up to CT quite stuff Dr. Mark Sloan whenever Dr. Richard Webber try George amazing Dr. Sydney Heron Dr. Jackson Avery actual quite nicely Richard stuff might Dr. Owen Hunt get her up to CT orthopedics Yang obviously mostly intubate her wherever orthopedic surgeon typically Margaret Karev effectively Alex Dr. Mark Sloan Seattle Dr. Alex Karev push one of epi try practically Dr. Alex Karev intubate him so</p> <p>start significantly start fairly get him up to CT slightly Dr. Alex Karev chief of plastic surgery slightly Dr. Robert Stark Meredithâ€™s mother Norman actually completely Izzie Dr. Mark Sloan particularly Alex basically Adele clearly like usually Seattle Dr. Alex Karev typically chief of plastic surgery get him up to CT essentially ultimately my person exactly Norman specifically Virginia effectively O’Malley intubate her Virginia Tucker my person a surgery resident largely most a veterinarian basically she’s in V-Fib try simply Seattle</p> <p>heavily Dr. Callie Torres essentially Dr. Jackson Avery whoever a nurse Dr. Mark Sloan definitely my person Olivia Harper Dr. Alex Karev essentially approximately generally my person exactly Dr. Miranda Bailey Dr. Preston Burke right a plastic surgeon Norman Theodora basically a cardiac surgeon chief of plastic surgery chief of plastic surgery essentially Dr. Jackson Avery Tyler Christian much seriously Meredithâ€™s mother slightly easily Mark my person maybe Mercy West Alex Erica Derek certainly badly rather hospital Denny Dr. Norman Shales Dr. Lexie Grey significantly Dr. Jackson Avery</p>”

Formatting Response

This blob of text is not formatted yet but we will worry about that in the React app. So let’s switch back to app.js . We are already printing the messages if you run yarn start and go to localhost:3000 you will see the same body text we just saw. Let’s use a library to format the response as actual HTML.

We will use the “html-react-parser” package. It can be installed by running yarn add html-react-parser and then add this import parse from “html-react-parser”; to the top of your app.js file in order to import it. Instead of just returning the msg in LambdaCall let’s replace msg with {msg && parse(msg)}. This says to parse the HTML of the msg and return it whenever there is a msg.

This part of the tutorial is choose-your-own-adventure. After setting up the Lorem Ipsum text generation logic. I went on to prettify the site to make it look more customized than the standard create-react-app boilerplate. One of the tools I used was this fancy button generator. I recommend playing around with the CSS until it matches the aesthetic that you want.

Deploy

Thanks to Netlify’s continuous deployment, if you clicked the “Deploy to Netlify” button on the first step then your website will be deployed to once you merge your changes into the master branch of your project’s repository. Also, if you open a pull request Netlify will generate a preview. This should mirror what you see when running the site locally.

The final code can be viewed on the loremIpsumTutorial branch of the greys-anatomy-lorem-ipsum-generator repository.

Please share with me on Twitter, @indigitalcolor if you end up creating a Lorem Ipsum generator or another app with the Netlify functions after reading through this tutorial.

Hello, IndieWeb!

Mon, 17 Mar 2025 22:22:11 GMT

For years I’ve considered this website my digital playground but it's not just a playground, it's also a learning space. Through the process of crafting this site I've learned more not only about technology but also about myself as a technologist (and a glimpse of how I'd be as a designer 🪄). I really appreciate this metaphor from Aral Balkan about how hands-on creation is an essential part of the learning process. The act of making itself deepens your understanding of the medium, its constraints, and its possibilities.

Coding is like taking a lump of clay and slowly working it into the thing you want it to become. It is this process, and your intimacy with the medium and the materials you’re shaping, that teaches you about what you’re making – its qualities, tolerances, and limits – even as you make it. You know the least about what you’re making the moment before you actually start making it. - Aral Balkan

It's also fun to have a place to explore and experiment even when it doesn’t have a practical purpose which is what first sparked my interest in web development.

Last week, I updated my website to accept Webmentions again and was reading up on different web standards related to the IndieWeb. I kept discovering new ideas as the week went a long but my main takeaway is that I’m really looking forward to continue tinkering with this site and have no idea what it might look like a year from now. I re-wrote my site last year in Astro which helped make making site updates enjoyable again. Before this switch my website was in a state where there were some outdated packages that my site relied on that couldn't be upgraded and my site always seemed to be at least a major version behind the GatsbyJS framework.

Even though I've since changed the underlying technologies and wrote this README for the previous version of my website, the feeling of this being my personal playground has not changed.

At the beginning of the year, I set the intention of spending more time doing tactile hobbies and activities which has led me to spend more time playing tabletop games, puzzles and journaling. I’ve also started reading more physical books this year although I'm still reading e-books [^1]. This has shifted how I view the infinite scroll and I’ve deleted most-video centric apps from my phone aside from YouTube. Since I've shifted to primarily using a desktop, I've noticed a decline in my interest in certain websites, partly because they're not as readily accessible as apps on my phone, and also because I've discovered a wider range of engaging content online

I'm not opposed to bringing back the concept of a computer room. I already treat my 15" laptop like a desktop. Image source: FreePik

I feel a bit out of the loop now that I’m spending less time on social media. So I'm still sorting out the balance between being informed but not overly distracted by endless notifications and an infinite amount of content. I recently stumbled upon a post about the lack of human curation on the modern web by Cassidy Williams where she says:

In the earlier internet days, you went to a fun website or read the latest thing because you decided to go do it. Now, all of this content is pushed in your face

So far, I’m enjoying spending more of my screen-time, tinkering around with my digital playground, exploring the IndieWeb and other personal websites[^2]. The IndieWeb is an alternative to the corporate web and defines itself as "a community of independent and personal websites based on the principles of: owning your domain and using it as your primary online identity, publishing on your own site first (optionally elsewhere), and owning your content". I'm drawn to the idea of having my own little piece of the internet that I can share with others and it's nice to know that there's a "vast community of fellow web weavers"[^3] out there.

If you have any suggestions or RSS feed recommendations, I'm eager to get more involved with the IndieWeb and would love to hear them! I can be reached via Webmention, BlueSky or Mastodon.

[^1]: I usually borrow e-books from Libby and as of February 2025 I’m looking for a new place to purchase e-books from instead of Amazon. Libby is an app created by OverDrive that allows users to borrow books from their local libraries.

[^2]: I could look at personal sites all day 😄. For years, I've been jotting down personal sites and portfolios that inspire me. I should find a way to showcase or highlight some of them...

[^3]: "There is a vast community of fellow web weavers out there. And with it conversations to be started, friends to be made, visions to forge." - Web Reflections from James

Hide Your API Keys

Thu, 26 Jan 2017 01:23:25 GMT

How to Hide Your API Keys in Python 🔑

Protect your application’s API Keys while committing to Git.

</figure>

If you plan on programming any applications and storing your code in a public GitHub repository then it is important that you protect your API keys 🔑 by ensuring that they are not searchable or otherwise publicly accessible.

What’s an API?

An application programming interface (API) is a structured set of instructions for building applications. If you want to leverage data from services such as Twitter, The New York Times, Slack, Spotify, etc. then you should read their APIs to figure out how to structure your queries to receive data from their service or to post on their service.

Example APIs:

What are API keys?

API keys allow developers to access APIs and are unique keys associated with that particular developer and/or application. Just like you shouldn’t share your passwords you should never share your API keys. It is important to protect your API keys so that people do not take any actions as you which could result in your API key being revoked due to somebody else exceeding rate limits or abusing/violating an APIs terms of service. A rate limit is when an application limits the number of API calls that a specific application or user can make during a specified period of time.

How do I protect my API keys on Github?

Here’s how to hide API keys in Python from GitHub using config.py to store your sensitive API keys and tokens in a separate file from your main script. I used similar code when accessing the Twitter Search API for my blackgirlmagic twitter bot.

Create 3 Files in Your Application

config.py

This file will store your API keys. You just need to update the portion in the strings with your API keys, depending on the service you may or may not need all four types of API keys. These in particular are required to create a Twitter application.

api_key = "YOUR_KEY"
api_secret = "YOUR_SECRET"
access_token = "YOUR_ACCESS_TOKEN"
token_secret = "YOUR_TOKEN_SECRET"

main_script.py

This file will store your main script that needs to access the API keys. This file can be named whatever you like.

import config

from twython import Twython, TwythonError

# create a Twython object by passing the necessary secret passwords
twitter = Twython(config.api_key, config.api_secret, config.access_token, config.token_secret)

.gitignore

A .gitignore file tells GitHub to ignore the noted files, directories or files that end in specific extensions when committing files to GitHub. This step is crucial to ensure that your config.py file does not end up viewable on GitHub! Here’s a collection of useful .gitignore templates.

github/gitignore
_A collection of useful .gitignore templates_github.com

config.py
__pycache__
.ipynb_checkpoints

Feel free to reach out below with any comments or questions that you have. I would love to know how you hide your API keys when creating applications in Python or any other languages.

How to Change Repo Language in GitHub

Tue, 07 Feb 2017 14:17:11 GMT

How to Change Repo Language in GitHub

Is GitHub telling you that your repository is 98.9% CSS or HTML when it isn’t? Here’s how to resolve that issue every time.

I recently started working on a Weather app in Flask to auto-detect a user’s location based off of their IP address. After committing some updates to GitHub my app switched from being labeled as predominately Python to 98.9% CSS even though it was a Flask application in which most of the code I had written was in Python and HTML. Now and again, I do not agree with how GitHub classifies the languages in my repositories so I set out to figure out how to fix this issue.

Before: My Flask App Appeared in GitHub as 98.9% CSS.

Pro-tip: Help GitHub properly detect your repositories main language(s).

GitHub has a linguist library that auto-detects the language within every repository. Upon researching how to resolve GitHub misclassifying the language of your projects I found out the solution is as simple as telling GitHub which files to ignore.

While you still want to commit these files to GitHub and therefore can’t use a .gitignore you can tell GitHub’s linguist which files to ignore in a .gitattribute file.

Upon examining the documentation for the linguist library I learned that adding just one line to a .gitattributes file would resolve my language issues for this particular repo.

My .gitattributes:

static/* linguist-vendored

This one-line file told GitHub to ignore all of my files in my static/ folder which is where CSS and other assets are stored for a Flask app. Vendor files can sometimes take up a lot of relative space so I am telling the linguist to just ignore them (since they were accounting for 98.9% of my project)!

After: My Flask App Appears in GitHub now as 56.2% Python and 43.8% HTML.

Here’s a repository by @with sample .gitattributes files for you try the next time you disagree with the linguist ;). Note: Updates to the .gitattributes may not apply retroactively and if linguist truly is wrong GitHub encourages you to report it as an issue in their /linguist repo.

I hope this article was helpful! I would love to hear some of your tricks for GitHub and am happy to answer any questions you may have.

How to Check Bundled Netlify Function Size Locally

Sun, 02 Jan 2022 19:05:25 GMT

import Callout from "../../components/Callout.astro";

Does your Netlify function appear to be working locally but you're having trouble successfully deploying the function due to it being greater than 50 MB? This article walks through how to use the Netlify CLI to determine the size of the bundled Netlify function locally in order to more quickly optimize the size.

Relationship between AWS Lambda 50 MB and Netlify Functions

Under the hood Netlify functions are an abstraction build on top of AWS Lambda functions. Therefore, Netlify functions are subject to the same limits as AWS Lambda functions and currently AWS restricts zipped Lambda files to 50 MB. During the build process Netlify bundles any Netlify functions, by default with the zip-it-and-ship it bundler and attempts to upload the zipped version. If a Netlify function is greater than 50 MB after the bundling process then during the build process when uploading the zipped function you will receive an error similar to the below:

<Callout variant="danger"> Request must be smaller than 69905067 bytes for the CreateFunction operation </Callout>

How to Determine Size of Zipped Netlify Function Locally

You can often get feedback more quickly on the size of your Lambda functions by testing locally whether or not the zipped artifacts for your Netlify functions are less than 50MB without having to do a full remote build.

I was recently working on a Netlify function to programmatically generate meta images and required the following dependencies dotenv, node-fetch, chrome-aws-lambda and puppeteer. It was working as expected locally and remotely but once I added an additional dependency of Cloudinary I began to encounter issues with the function size being too large and needed to experiment with potential optimizations like, will using puppeteer directly from chrome-aws-lambda meaningfully reduce the overall size of the function? Or, will switching the bundler reduce the size of the function below 50MB? The ability to test the impact of my changes of the overall bundle size locally without having to commit them and wait for remote CI/CD was helpful for reducing the amount of time it took to get feedback on my changes and allowed me to land on a working solution more quickly.

In order to most effectively work with Netlify functions in a development environment you should use the Netlify CLI as it allows you to run a local development server and interact with Netlify in a similar context to your hosted build configuration. The Netlify CLI can be installed globally with:

npm install -g netlify-cli

In order to interact with your hosted Netlify site you will need to authenticate by logging into Netlify and link the local project to a site hosted in your Netlify account:

# Login to Netlify
netlify login

# Link current directory to a remote Netlify site
netlify link

Once everything is configured for the Netlify CLI you should be able to run a build locally that mirrors what happens when Netlify generates a deploy preview remotely which is a similar context to where the error related to file function size occurs.

netlify build --context deploy-preview

This will run a full build of your site and show in the logs each build step as it occurs and whether or not there are any errors. If everything succeeded then you should be able to view the functions generated by the build in a hidden .netlify directory within your site which contains your functions folder and both the zipped and unzipped versions of the functions. Since we're concerned about the size of the generated zipped version of the function that is the file that we need to examine closer.

We can quickly inspect the file path of the zipped function that was generated during the build with du which is a unix command to get information on disk usage and use the -h flag to render the output in a "human-readable" format. Note since this format is human-readable it's an approximation of the actual number.

# du -h .netlify/functions/getMetaImg.zip
du -h path/to/your/generated/netlify/function.zip

For the above du command the example output for a 50MB file would be:

# 50M	.netlify/functions/getMetaImg.zip
50m path/to/your/generated/netlify/function.zip

You can also navigate to the file via your computer's GUI file navigator such as MacOS's Finder or Windows' File Explorer and view more information for the file to view the file size. I found that looking at the file in the MacOS Finder and then right-clicking "more info" provided me with more significant digits for the same file than the number returned by du. File Explorer can also be configured to display file sizes.

Reducing Size of Netlify functions

In order to be able to successfully upload and deploy your function you will need to figure out a way to reduce the size to be no greater than 50 MB by removing unused dependencies, swapping out dependencies with lighter-weight alternatives or updating how your functions are being bundled for production. One of the fastest ways to reduce the overall size of Netlify functions is by using the esbuild bundler instead of the currently default for Netlify functions zip it and ship it (a.k.a zisi). In April 2021, Netlify announced beta support for esbuild as a more modern and faster, alternative to zisi. You can enable esbuild for your Netlify functions by updating the netlify.toml in the root of your project to include the following:

[functions]
  node_bundler = "esbuild"

I updated my netlify.toml and then was able to determine that the same function bundled with esbuild and zisi was ~2MB smaller in the esbuild version by doing a local deploy-preview build of my site with the Netlify CLI and then running du to view the file size. However, if the file is still too large you will need to do a closer evaluation of the dependencies your function relies onto function to determine if there are opportunities to reduce or replace larger dependencies.

Initially, I encountered some issues using esbuild out of the box which caused a Error: spawn ETXTBSY error when running the deployed function as the zipped version excluded one of my dependencies chrome-aws-lambda. I was able to determine this by checking the Netlify logs which output the following tip during the Functions bundling step:

────────────────────────────────────────────────────────────────
  4. Functions bundling
 ────────────────────────────────────────────────────────────────
 
 Packaging Functions from netlify/functions directory:
  - getMetaImg.js
 - gatsby/gatsby.js
 
❯ The following Node.js modules use dynamic expressions to include files:
   - chrome-aws-lambda

  Because files included with dynamic expressions aren't bundled with your serverless functions by default,
  this may result in an error when invoking a function. To resolve this error, you can mark these Node.js modules as external in the [functions] section of your `netlify.toml` configuration file:

   [functions]
      external_node_modules = ["chrome-aws-lambda"]

    Visit https://ntl.fyi/dynamic-imports for more information.

My issues with the deployed function were resolved after I updated my esbuild configuration to include that dynamic dependency of "chrome-aws-lambda" by adding the following to the netlify.toml

#replace functionName with the name of your function or use [functions] to apply to all of the Netlify # functions configured by that netlify.toml
[functions.functionName]
  external_node_modules = ["chrome-aws-lambda"]

If you are noticing differences in behavior between the esbuild and zisi version of your function you should double-check the logs to help determine if dynamic imports that you need were not removed during the esbuild process and if so, update the functions configuration as needed.

Conclusion

Using the Netlify CLI can be a helpful resource for developing and testing Netlify functions locally. By creating a local deploy-preview build of your site with the Netlify CLI you can gain meaningful insight into issues that arise during remote deployments and shorten the feedback loop to debug issues that do not appear during normal local development. If you're using the default, zisi, bundler for Netlify functions you may want to consider switching over to esbuild.

How To Create A GitHub Profile README

Sat, 11 Jul 2020 11:25:50 GMT

import { Tweet } from "@astro-community/astro-embed-twitter";

import Callout from "../../components/Callout.astro";

GitHub recently released a feature that allows users to create a profile-level README to display prominently on their GitHub profile. This article walks through how to access this new feature. I'll also be sharing some fun GitHub profiles I've seen so far. I'd love it if you shared yours with me on Twitter @indigitalcolor.

The above GIF shows what my README looks like at the time of this writing. You may notice I was recently selected to be GitHub star!

Why READMEs?

The GitHub profile-level README feature allows more content than the profile bio, supports markdown which means you can play around with the content more visually (Did someone say GIFs!?) and the README is significantly more visible as it is placed above pinned repositories and takes up as much space above the fold of the webpage as you like.

A solid README is a core-component of well-documented software and often encourages collaboration by sharing helpful context with contributors. In my opinion, a profile-level README seems like a great extension of a convention a lot of GitHub users are already familiar with. If you're looking to make project-level READMEs more awesome and helpful check out matiassingers/awesome-readme for resources and examples of compelling READMEs.

How do I create a profile README?

The profile README is created by creating a new repository that’s the same name as your username. For example, my GitHub username is m0nica so I created a new repository with the name m0nica. Note: at the time of this writing, in order to access the profile README feature, the letter-casing must match your GitHub username.

<Callout variant="danger"> <p> <b>Already have a repo-named username/username?</b> </p> <p> If you are interested in setting up a profile-level README then you can {""} <a href="https://docs.github.com/en/github/administering-a-repository/renaming-a-repository"> rename the repository </a> or repurpose its existing README based on what makes the most sense in your particular situation. </p> </Callout>

Create a new repository with the same name (including casing) as your GitHub username: https://github.com/new
Create a README.md file inside the new repo with content (text, GIFs, images, emojis, etc.)
Commit your fancy new README!
- If you're on GitHub's web interface you can choose to commit directly to the repo's main branch (i.e., master or main) which will make it immediately visible on your profile)
Push changes to GitHub (if you made changes locally i.e., on your computer and not github.com)

Fun READMEs

The GitHub README profiles are written in Markdown which means you aren't just limited to texts and links, you can include GIFs and images. Need to brush up on Markdown Syntax? Check out this Markdown Cheatsheet.

If you're really ambitious you can use GitHub actions or other automation like bdougieYO or simonw to dynamically pull data into your README:

Serverless functions can also be used to dynamically generate information (for example your current Spotify activity):

I'm a huge proponent that folks should maintain a website they have complete ownership over (even if it's a no-code website solution) but this is tempting...

I've been inspired by the creative READMEs I've seen so far and am looking forward to seeing all kinds of profiles in the upcoming months.

{/* we need javascript here to load the twitter embedded media properly, javascript is not required for text-only tweets */}

How to Make Your VSCode Sparkle

Fri, 04 Sep 2020 18:14:40 GMT

import Callout from "../../components/Callout.astro";

This article shows you how to customize your VSCode set up to display animated sparkles while you are typing. There's a VSCode extension, <a href="https://marketplace.visualstudio.com/items?itemName=hoovercj.vscode-power-mode">Power Mode</a> that adds animated flair while you're typing. It has a few different default animations but none of them quite sparkle. If you're not using VSCode, check out these <a href="https://github.com/codeinthedark/awesome-power-mode">Power Mode extensions</a> for various code editors. The implementation of each differ but some of them support customized animations.

Above is a GIF of animated sparkles in my VSCode. The editor's theme is Night Owl and the font is Dank Mono. You can learn more about my VSCode setup on my uses page.

Enable Power Mode Extension for VS Code Typing Animation

<Callout> <a href="https://marketplace.visualstudio.com/items?itemName=hoovercj.vscode-power-mode"> Install </a> the VSCode Power Mode extension </Callout>

In order to add animations to your VSCode first you need to install Power Mode and enable it by updating your VSCode settings to include the following: "powermode.enabled": true.

Depending on your operation system the VSCode settings file is located here:

<ul> <li> <bold>Windows</bold> - %APPDATA%\Code\User\settings.json </li> <li> <bold>macOS</bold> - $HOME/Library/Application Support/Code/User/settings.json </li> <li> <bold>Linux</bold> - $HOME/.config/Code/User/settings.json </li> </ul>

Customize How Power Mode Renders Animations

"powermode.enabled" turns on the extension's default animations when you're typing but if you want sparkles then some additional customization is required. In particular, you need to configure "powermode.customExplosions" in settings and pass in your own animation to be used for the explosions. This setting supports base64 encoded gifs, absolute file path, or https image URLs.

 "powermode.customExplosions": [
// absolute path to custom ✨ GIF on my computer
    "/Users/monica/Dev/power-mode-sparkles/sparkles.gif"
  ],

If you are interested in other animation ideas aside from sparkles check out the vscode-power-mode/Help wanted: explosion gifs issue on GitHub. In fact, this issue is where I found the image for my sparkles ✨ thanks to federicca. You can Download the Sparkle GIF I used for my configuration.

My Final Power Mode VSCode Configuration

My VSCode settings.json includes the following keys and values after configuring Power Mode:

// turn on powermode 🚨
"powermode.enabled": true,
  "powermode.customExplosions": [
// absolute path to custom ✨ GIF on my computer
    "/Users/monica/Dev/power-mode-sparkles/sparkles.gif"
  ],
  // enableShake is true by default which causes the
  // text/screen to shake, the following line disables that
   "powermode.enableShake": false,
  // tweaking settings to reduce amount of explosions
  "powermode.maxExplosions": 1,
  "powermode.explosionFrequency": 4,
  //backgroundMode mask - animation matches the current syntax color
  //backgroundMode image - displays animation with original colors from the image
  "powermode.backgroundMode": "mask",

Optimizing Power Mode

Power Mode recommends tweaking some of the default settings to reduce the frequency of animations if the extension is causing your editor to slow down.

Sparkle GIF to Download

Right-click and save this image to your computer if you're ready to start adding more sparkles to your development workflow.

How To Render Relevant Icons Based on Content

Sat, 12 Sep 2020 13:40:05 GMT

This article walks through how I display relevant, themed icons when linking to content on this site based on the topic or type of content. If you've visited the homepage of this site, I use a variation of this component to display my recent content, featured content, and recent video lessons.

ArticleList: Rendering Article Titles + Icons

The logic for displaying article titles alongside a relevant icon is constructed within an <ArticleList/> component. Below is an example of a fully functioning, interactive <ArticleList/> component (thanks to MDX):

import ArticleList from "../../components/ArticleList.jsx";

In my actual site the article data is programmatically passed in from the result of a GraphQL query, however, a similar component can be used regardless of how your website handles data. I used the below JSX markup with hard-coded data to render the above instance of the <ArticleList/> component:

<ArticleList
  articles={[
    {
      slug: "/blog/create-gatsby-blog-search-tutorial/",
      tags: ["gatsby"],
      title: "How to Add Search Functionality to a Gatsby Blog",
    },
    {
      slug: "/blog/2020-01-29-automating-file-creation-with-javascript/",
      tags: ["javascript"],
      title: "Automating File Creation With JavaScript",
    },
    {
      slug: "/blog/how-to-create-a-github-profile-readme/",
      tags: ["Git/GitHub"],
      title: "How To Create A GitHub Profile README",
    },
  ]}
/>

Essentially the <ArticleList/> component maps through each article in the articles array and displays the article title along with a link to the article and an article icon based on the article tags. A simplified version of the render of <ArticleList/> resembles the below code. Note: Whenever mapping through items to render items in React you should use a unique key in order for React to be able to efficiently differentiate between different items within the generated list:

{
  articles.map(({ slug, tags, title }, index) => (
    <div key={`${index}-${slug}`}>
      <ArticleIcon tags={tags} />
      <Link to={slug} className="article-link">
        {title}
      </Link>
    </div>
  ));
}

ArticleIcon: Returning the Relevant Icon

The logic to determine which icon should render for a given article based on its tags is handed off from the <ArticleList/> component to the <ArticleIcon/> component. Let's take a closer look at the <ArticleIcon/> component.

Setting up Icons

The <ArticleIcon/> component imports multiple SVG image files for each of the potential icons that will be rendered:

import GitHubIcon from "./icons/github.svg";
import ReactIcon from "./icons/react.svg";
import JavascriptIcon from "./icons/javascript.svg";
import PenIcon from "./icons/pen.svg";

Then within the ArticleIcon component there's an object that contains the imported icons with key value pairs that look like [tag]: icon. I have intentionally omitted the PenIcon from this object as it is the default icon that is displayed when there is not a better matching icon available for a given set of tags. I also decided to structure the object this way so that icons could quickly be retrieved based on their tag name which is the name of the properties in the icons object. In the below instance I have two separate keys for Git and GitHub since either tag should be associated with the GitHubIcon.

export default function ArticleIcon({ tags }) {
  const icons = {
    git: GitHubIcon,
    github: GitHubIcon,
    react: ReactIcon,
    javascript: JavascriptIcon,
  };
}

Finding the Most Relevant Icon

After initializing the icons object the method .find() is used to locate the first instance of a tag within the array of the tags (passed in via props) that matches a tag within the icons object. Since .find() returns the first instance that is found if an array of tags contains multiple tags that have icons in the icons object, only the first tag that matches an icon in the icons object will be returned:

const articleTagWithIcon = (tags || []).find((tag) => icons[tag.toLowerCase()]);

If there is an icon associated with any of the article tags then the articleIcon is set to the value of icons[articleTagWithIcon.toLowerCase()] or else the icon will be set to the default icon which is the PenIcon.

const articleIcon = articleTagWithIcon
  ? icons[articleTagWithIcon.toLowerCase()]
  : PenIcon;

Finally we can return an image in the render of the ArticleIcon:

return (
  <img
    src={articleIcon}
    alt={articleTagWithIcon ? `${articleTagWithIcon} icon` : `pen icon`}
  />
);

Summary

This article went over how to create the logic for a component that renders different images based on the data that is passed in. I used CSS flex for the majority of the styling of this component, if you are interested in learning more about the styling behind the <ArticleList/> inspect the <ArticleList/> on my website! For sake of clarity, I may have omitted some markup or classes that were used to style the component from this article.

Final Code

All together the complete ArticleIcon.jsx file looks like:

import React from "react";
import GitHubIcon from "./icons/github.svg";
import ReactIcon from "./icons/react.svg";
import JavascriptIcon from "./icons/javascript.svg";
import PenIcon from "./icons/pen.svg";

export default function ArticleIcon({ tags }) {
  const icons = {
    git: GitHubIcon,
    github: GitHubIcon,
    react: ReactIcon,
    javascript: JavascriptIcon,
  };

  const articleTagWithIcon = (tags || []).find(
    (tag) => icons[tag.toLowerCase()],
  );

  const articleIcon = articleTagWithIcon
    ? icons[articleTagWithIcon.toLowerCase()]
    : PenIcon;

  return (
    <span className="article-icon">
      <img
        src={articleIcon}
        alt={articleTagWithIcon ? `${articleTagWithIcon} icon` : `pen icon`}
      />
    </span>
  );
}

Hanselminutes Podcast: Leaning Into Learning In Public

Thu, 10 Sep 2020 00:16:13 GMT

</iframe>

I recently had the opportunity to speak with Scott Hanselman on Hanselminutes about my recent GitHub article, digital gardening 🌱, the importance of owning your own content, leaning into learning in public and more. Listen to the episode above.

Less JavaScript Makes Font Awesome More Awesome

Sat, 09 Nov 2019 02:43:13 GMT

I decided to use Font Awesome's SVG icons to display social media icons prominently on this site's homepage. I am a long time fan of Font Awesome and supported their Kickstarter campaign in 2017, which was the highest-funded software project on Kickstarter at that time with a total of over 1,076,960 USD pledged. Despite its awesomeness, I did run into a small issue with how the default styles were loaded when adding Font Awesome to this site.

Problem 🐛: CSS loading differently locally vs in-production

Overall, I had a smooth experience implementing Font Awesome and did not experience any major issues when developing but as soon as my site was deployed I noticed that there was a huge discrepancy in the size of the icons as they rendered.

To illustrate this problem using the above GIF, the beginning of the GIF shows how misformatted and large the social icons appeared in production initially (while waiting for JavaScript to fully load or when JavaScript was disabled). Towards the end of the GIF the icons change to the proper styled size. In development the icons only appeared in the proper styled size.

The below screenshot from the Web Page Test further illustrates how the rendering issue manifested in production by showing how the icon appearances changed over time (1.5s to 1.8s) as the page loaded.

Investigating why the icon styling behaved differently in production vs development led me to understand a bit more how the styles were being applied to my icons and to the realization that using Font Awesome's NPM packages out of the box in a server-side rendered (SSR) application you will likely experience some jarring rendering issues. By default, Font Awesome's NPM packages import styles from "@fortawesome/fontawesome-svg-core". While the CSS loaded from "@fortawesome/... was readily available in development this same CSS was consistently not available on the initial load of the production version of my site causing the icons to initially render too large and then to snap to their proper size. As I looked into this I discovered this rendering issue is a known Font Awesome issue that requires a little bit of additional configuration. The Font Awesome site has some suggestions for handling the issue of CSS not being available on load for server-side rendered applications.

TLDR; CSS local to your application is your friend as the underlying issue is that the availability on the initial page load of JavaScript assets is different locally vs in production for a server-side rendered application.

What is Server-side rendering?

Server-side rendering is when an application generates and sends a complete HTML page from the server to the client on the initial load that doesn't require JavaScript to be available before content can be displayed. After the initial load, Client-side rendering can take over to allow better interactivity."Without Server Side Rendering, all your server ships is an HTML page with no body, just some script tags that are then used by the browser to render the application." (source: Flavioscopes).

For this site I am using GatsbyJS which has server-side rendering configured for the production build of the website which means the initial render has HTML/CSS loaded and "[o]nce a site has been built by Gatsby and loaded in a web browser, client-side JavaScript assets will download and turn the site into a full React application that can manipulate the DOM. " (source: Gatsby Glossary). In other words, the HTML/CSS for this site loads but then additional network requests are made to retrieve additional JavaScript files required for full functionality.

Solution 💡

In order to resolve the issue with the icon font size being too large on initial render, I first needed to replicate the issue in development. To replicate in development, I manually blocked JavaScript from loading for my site in the Chrome Dev Tools. For the production version I was able to block JavaScript from loading by opening the Dev Tools and going to settings > preferences > debugger > and then selecting "disable javascript" however, in development I had to block specific JS files from loading in the Network tab instead or else I saw a message that said "This app works best with JavaScript enabled".

You can also generate the production version of the site locally using gatsby build and going to the generated files. Whis will then allow you to disable JavaScript and see how the page appears in production on initial load before JavaScript is downloaded and able to progressively enhance the page.

Create a production build. If the application is already running locally, stop (Ctrl + C) the development server and run gatsby build.
The production build is output to public directory. run gatsby serve to view the production site locally at http://localhost:9000.

Reproduce issue by disabling and blocking external JavaScript

Disabling JavaScript allowed me to see the larger icons and to use CSS that replicated the final styling I wanted without relying on external JavaScript.

After finalizing the styles, I also needed to add the following lines to my layout.jsx file. The layout.jsx file is responsible for rendering the overall layout for all content on this site and is where styles are loaded.

import { config, dom } from "@fortawesome/fontawesome-svg-core";
config.autoAddCss = false;

The above code removed the Font Awesome CSS which is loaded via JavaScript from the site. The CSS I had written with JavaScript disabled now reflected 100% how I wanted the icons to look and didn't rely on Font Awesome for additional styling. Since the CSS no longer had to be fetched from an external JavaScript file, it became available on the initial load in production and did not require the page to hydrate with additional JavaScript.

Verify Solution

Below is a screenshot from Web Page Test after updating the code to not import CSS from fontawesome-svg-core and only rely on my own CSS.

The Web Page Test helped me confirm that the rendering issue was resolved in addition to being able to block JavaScript in Chrome DevTools. Web Page Test and Chrome DevTools can be invaluable when debugging 🐛 something related to loading JavaScript in a SSR application.

Migrating To MDX Talk

Mon, 24 Aug 2020 22:22:11 GMT

Below is a link to a video of a talk I gave at MDX Conf, sharing more about my migration from Remark to MDX, how you can migrate your site and what problems you might run into. MDX allows you to write Markdown that includes React components and enables a lot more flexibility than Markdown traditionally does. You can check out my initial thoughts on migrating to MDX here.

{/* todo fix egghead embed <EggheadLesson lessonId="mdx-migrating-to-mdx" /> */}

View video of my Migrating to MDX talk which is hosted on <a href="https://egghead.io/lessons/mdx-migrating-to-mdx?af=9b5hrz">Egghead.io</a> and the slides are available <a href="/migratingtomdx">here</a>.

My SVG Creation Process

Tue, 13 Apr 2021 04:58:13 GMT

import VanillaCustomSandpack from "../../components/VanillaCustomSandpack.tsx";

export const seaBearDemoProps = { html: <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Sea Bear SVG Animation</title> <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1728 1296"> <defs /> <g id="sea-otter"> <path id="water" opacity="0" fill="#74C2C2" d="M-3.66 51.56h1728v1286.77h-1728z" /> <g id="paws"> <g id="left-top-lines"> <path class="top-ripple" id="_x32_" fill="none" stroke="#FFF" stroke-miterlimit="10" stroke-width="4" d="M493.78 659.03c-9.29-10.6-6.3-29.4 5.81-36.6" /> <path class="top-ripple" fill="none" stroke="#FFF" stroke-miterlimit="10" stroke-width="4" d="M473.71 691.21c-14-16.13-18.42-40.01-11.11-60.07 4.55-12.5 14.43-24.02 27.52-26.34" /> <path id="left-paw" fill="#144F4F" d="M596.38 654.94c-4.11-9.29-8.51-18.95-16.45-25.3-9.17-7.33-21.81-9.03-33.45-7.48-4.03.54-8.11 1.46-11.57 3.6-2.95 1.83-5.32 4.46-7.51 7.16-6.16 7.61-11.25 16.08-16.71 26.47 29.98.36 59.98-.75 89.85-3.32-1.08.3-2.31-.69-4.16-1.13z" /> </g> <g id="right-top-lines"> <path id="_x32__1_" fill="none" stroke="#FFF" class="top-ripple" stroke-miterlimit="10" stroke-width="4" d="M1108.07 585.64c8.01 2.9 14.15 10.44 15.38 18.87" /> <path id="_x31__1_" fill="none" stroke="#FFF" class="top-ripple" stroke-miterlimit="10" stroke-width="4" d="M1137.59 631.1c7.93-15.89 5.01-36.54-7.02-49.61" /> <path id="right-paw" fill="#144F4F" d="M1115.42 656.84c2.65-16.51-7.01-33.51-21.27-42.25-14.26-8.73-32.19-10.01-48.52-6.42-4.99 1.1-9.91 2.63-14.49 4.9-20.04 9.95-30.69 32.49-37.87 56.46 17.91-1.35 35.82-2.69 53.73-4.04 22.49-1.69 45.05-3.39 68.42-8.65z" /> </g> </g> <g id="feet"> <g id="left-foot-group"> <path d="M704.12 888.33c-20.92 28.4-36.66 60.21-52.28 91.83-10.69 21.63-21.68 45.37-16.67 68.98 1.07 5.04 3.06 10.21 7.15 13.35 2.43 1.86 5.4 2.86 8.37 3.58 20.54 5 42.66-2.14 59.55-14.84s29.29-30.45 39.99-48.68c18.78-32 33.42-67.07 37.32-103.97.59-5.6.61-12.1-3.6-15.84-5.21-4.64-13.29-2.21-19.93-.07-19.6 6.34-40.72 7.92-61.05 4.58l4.46-5.93-6.46 1.05c1.5 1.86 3 3.73 3.15 5.96z" opacity=".161" /> <path fill="#144F4F" d="M704.21 900.02c-8.3-31.99-30.55-59.13-37.94-91.34-2.09-9.09-2.9-18.85.39-27.58 3.28-8.73 11.49-16.1 20.82-16.05 13.23.08 21.9 13.54 27.31 25.62-1.65-4.25-3.3-8.69-2.93-13.24.38-4.54 3.42-9.21 7.93-9.88 6.81-1.02 11.34 6.67 13.84 13.09-3.23-4.18-.64-11 4.22-13.07 4.86-2.07 10.74-.12 14.5 3.59s5.76 8.84 7.11 13.95c-.92-5.23-1.11-12 3.68-14.3 3.81-1.82 8.31.66 11.25 3.69 10.34 10.65 11.2 27.04 11.46 41.88l1.17 68.16c-8.04.04-15.37 4.22-22.78 7.33-17.06 7.15-36.36 8.82-54.4 4.73-3.66-.83-7.37-1.94-5.63 3.42z" /> <g id="left-bottom-lines" fill="none" class="bottom-ripple" stroke="#FFF" stroke-miterlimit="10" stroke-width="4"> <path id="_x32__3_" d="M633.55 734.22c-11.01 24.56-4.42 53.44 6.31 78.13 6.65 15.31 15.02 30.21 27.24 41.57" /> <path id="_x31__3_" d="M643.69 870.01c-21.8-16.85-37.31-41.63-42.95-68.59" /> </g> <g id="left-foot-padding" opacity=".8"> <ellipse transform="matrix(0.9936 -0.1129 0.1129 0.9936 -84.0448 91.9986)" opacity="0.9" fill="#E8C089" cx="770.42" cy="788.2" rx="7.84" ry="6.94" /> <ellipse transform="matrix(0.9936 -0.1129 0.1129 0.9936 -83.5524 89.3189)" opacity="0.9" fill="#E8C089" cx="747" cy="782.51" rx="8.72" ry="7.72" /> <ellipse transform="matrix(0.9936 -0.1129 0.1129 0.9936 -83.5991 86.6277)" opacity="0.9" fill="#E8C089" cx="723.21" cy="781.58" rx="9.12" ry="8.08" /> <ellipse transform="matrix(0.9936 -0.1129 0.1129 0.9936 -84.6096 82.7489)" opacity="0.9" fill="#E8C089" cx="688.45" cy="788.57" rx="17.82" ry="15.78" /> <path opacity="0.9" fill="#E8C089" d="M689.89,820.42c1.49,6.85,19.88,64.68,33.32,71.55c7.69,3.93,16.5-1.18,23.79-2.85c20.97-4.8,19.93-46.37,20.76-63.29c0.33-6.72,2.85-16.84-2.34-19.39c-6.27-3.08-26.44-8.4-35.3-6.67C713.94,802.91,687.56,809.66,689.89,820.42z" /> </g> </g> <g id="right-foot-group"> <path d="M1072.93 821.3c-1.61 37.3 17.53 72.62 42.26 87 2.9 1.69 6.05 3.32 7.87 6.9 1.45 2.84 1.8 6.47 1.92 9.95.6 17.16-3.46 33.99-8.62 49.59-11.95 36.15-30.18 68.23-52.69 92.72-1.89 2.06-3.86 4.09-6.14 5.12-5.8 2.6-12.2-2.14-15.9-8.87-8.07-14.67-5.99-35.58-1.95-53.18s9.74-35.56 7.68-53.81c-1.1-9.7-4.34-18.66-7.81-27.2-4.04-9.93-8.49-19.6-13.85-28.23-6.47-10.41-14.69-20.51-15.58-34.23-.88-13.46 6.08-26 14.65-32.31 8.57-6.32 18.5-7.72 28.14-9 6.67-.9 13.33-1.78 20.02-4.45z" opacity=".141" /> <path fill="#144F4F" d="M1008.89 859.42a258.94 258.94 0 01-9.68-74.22c.08-5.32.92-11.62 5.64-14.06 4.67-2.42 10.67.77 13.17 5.39 2.5 4.63 2.45 10.16 2.33 15.41-3.37-5.99-.45-14.94 6.15-16.86 6.6-1.93 14.19 5.38 11.73 11.8-.74-6.39 2.9-13.44 9.06-15.29s13.76 3.26 13.25 9.68c-.21-8.69 6.01-17.12 14.37-19.5 8.36-2.38 18.08 1.52 22.48 9.02 6.54 11.15 1 25.08-2.81 37.43-4.86 15.75-7.51 33.75-20.26 44.18" /> <g id="right-bottom-lines" fill="none" stroke="#FFF" stroke-miterlimit="10" stroke-width="4" class="bottom-ripple"> <path id="_x32__2_" d="M1107.68 828.78c18.24-10.8 25.02-34.07 25.4-55.26.28-15.68-3.36-33.47-16.72-41.68" /> <path id="_x31__2_" d="M1135.85 720.72c16.5 19.23 22 47.29 13.99 71.33" /> </g> <g id="right-foot-padding" opacity=".8"> <circle opacity="0.9" fill="#E8C089" cx="1013.41" cy="794.47" r="6.94" /> <circle opacity="0.9" fill="#E8C089" cx="1030.52" cy="790.24" r="7.72" /> <circle opacity="0.9" fill="#E8C089" cx="1050.17" cy="789.05" r="8.91" /> <circle opacity="0.9" fill="#E8C089" cx="1080.06" cy="785.58" r="15.78" /> <path opacity="0.9" fill="#E8C089" d="M1081.98,817.39c-0.62,6.97-6.68,26.13-17.83,34.48c-6.37,4.77-17.31,1.23-22.51,1.91c-18.93,2.47-29.66-4.85-27.64-22.22c0.77-6.67-4.19-16.41,0.12-19.53c5.21-3.77,22.43-11.33,30.39-10.62C1059.07,802.71,1082.96,806.44,1081.98,817.39z" /> </g> </g> </g> <g id="top"> <path id="shadow" d="M678.17 511.89c-64.14 43.76-84.01 211.03 17.27 186.91 18.05-4.3 31.78 17.42 49.92 21.28 27.77 5.91 48.9-30.89 77.29-30.41 9.27.16 17.92 4.38 26.92 6.61 21.15 5.25 44.84-1.33 60.25-16.74 16.57-16.56 24.92-42.84 46.87-51.04 6.24-2.33 13.5-3.15 18.04-8.02 3.84-4.12 4.72-10.17 4.76-15.81.19-25.97-14.67-51.51-37.32-64.19-43.51-24.35-.3-62.57-58.55-72.09-20.11-3.29-40.73 5.07-56.52 17.95-5.02 4.09-9.7 8.66-15.26 11.98-22.86 13.63-51.72 2.52-78.31 1.41-26.25-1.09-51.71 9.67-55.36 12.16z" opacity=".161" /> <g id="head"> <g id="face"> <path id="fluffy-face" fill="#B8840D" d="M622.31 469.17c35.97 36.58 78.94 66.56 126.03 87.91 10.34 4.69 21.33 9.05 32.72 8.47 9.42-.48 18.31-4.33 26.68-8.57 54.93-27.81 98.65-76.15 117.54-131.9-9.34-11.93-23.86-18.67-37.91-24.78-14.61-6.35-36.16-18.97-49.98-26.97-21.11-12.21-59.47-14.37-79.69-9.45-29.54 7.18-52.97 22.04-79.91 35.8s-56.58 69.34-55.48 69.49z" /> <g id="snout"> <path fill="#E8C089" d="M767.81 563.05c-5.54-3.15-10.94-6.69-15.33-11.3-4.39-4.62-7.74-10.43-8.51-16.76-.71-5.8.77-11.69 3.09-17.05 5.66-13.05 16.78-23.84 30.32-28.2s29.31-1.88 40.29 7.17c2.23 1.84 4.27 3.93 5.84 6.35 1.71 2.64 2.85 5.61 3.75 8.63 2.11 7.04 3.02 14.52 1.85 21.78-1.16 7.25-4.51 14.27-9.96 19.19-6.6 5.96-15.57 8.38-24.17 10.63l-10.71 2.79c-3.89.99-12.36-.9-16.46-3.23z" /> <path d="M769.52 536c-1.5-2.13-2.97-4.62-2.49-7.17.36-1.9 1.74-3.43 3.26-4.63 3.98-3.14 9.14-4.54 14.21-4.65 5.07-.11 10.09 1 14.95 2.45 1.39.41 2.93 1 3.48 2.33.54 1.29-.07 2.75-.71 3.99a53.38 53.38 0 01-12.16 15.49c-1.91 1.68-4.16 3.29-6.71 3.25s-10.73-6.66-13.83-11.06z" /> <path d="M781.61 547.82c-4 3.25-7.79 7.08-9.55 11.92 2.66.26 4.99-1.73 6.71-3.78 1.72-2.05 3.35-4.4 5.86-5.34.74-.28 1.55-.42 2.33-.25.95.2 1.75.84 2.59 1.32 3.36 1.9 7.99 1.19 10.63-1.64-2.31-2.59-6.33-2.36-9.68-3.28-2.26-.62-4.58-1.84-6.8-1.12-1.27.41-2.26 1.39-2.09 2.17z" /> </g> <g id="eyes"> <circle cx="752.87" cy="475.88" r="20.91" /> <circle cx="825.53" cy="475.88" r="20.91" /> <g id="eyes-sparkles"> <circle id="sparkle-right" cx="759.93" cy="484.96" r="7.01" fill="#FFF" /> <circle id="sparkle-left" cx="834.41" cy="482.88" r="7.01" fill="#FFF" /> </g> </g> <path id="fluffy-side-2" fill="#B8840D" d="M630.89 452.18c1.83 2.93 3.17 6.14 4.5 9.32 2.55 6.1 5.1 12.21 7.66 18.31 1.35 3.22 2.71 6.52 2.79 10.19-6.97-1.95-14.73-3.83-21.19-.55 2.33-4.3 5.24-8.29 8.62-11.82-4.77 1.61-9.66 2.89-14.6 3.85 2.76-4.18 6.43-7.75 10.69-10.38a68.59 68.59 0 01-14.51 1.2c4.89-2.98 9.79-5.96 14.68-8.93-4.49.4-9.12-.91-12.73-3.61 3.55-1.2 7.1-2.4 10.64-3.6 2.09-.71 4.55-1.87 3.45-3.98z" /> <path id="fluffy-side-1" fill="#B8840D" d="M905.74 461.35c.64-3.39 1.83-6.66 3.01-9.91 2.26-6.22 4.53-12.43 6.79-18.65 1.2-3.28 2.43-6.63 4.86-9.38 3.8 6.16 8.23 12.8 15.19 14.78a55.35 55.35 0 01-14.35 2.84c4.6 2.06 9.06 4.42 13.34 7.08-4.86 1.2-9.98 1.33-14.9.38 4.13 2.57 7.98 5.58 11.48 8.96l-16.84-3.39c3.57 2.75 6.08 6.85 6.91 11.29-3.42-1.53-6.84-3.05-10.26-4.58-2.01-.9-4.6-1.71-5.23.58z" /> </g> <g id="ears"> <path fill="#B8840D" d="M757.7 389.23c-6.06-7.49-88.9 40.89-94.96 33.4-8.35-10.32-16.94-21.09-20.14-33.98-5.14-20.67 5.07-42.78 20.66-57.29 9.83-9.14 22.77-16.21 36.12-14.83 11.32 1.17 21.35 8.32 28.46 17.21 7.12 8.89 11.75 19.46 16.29 29.9 3.58 8.21 7.15 16.41 10.73 24.62M914.8 427.68c1.33-9.54-90.59-37-89.26-46.53 1.83-13.15 3.83-26.78 11.06-37.92 11.59-17.87 34.71-25.52 55.96-24.04 13.39.93 27.39 5.55 35.51 16.25 6.88 9.07 8.5 21.28 6.88 32.54-1.63 11.27-6.19 21.87-10.7 32.32l-10.65 24.66" /> <path d="M904.64 404.33c.25-.38.51-.76.76-1.14.15.08.23.11.31.15 1.76.63 2.86-1.51 3.1-3.11 1.32-8.6 2.64-17.21 3.95-25.81.9-5.88 1.8-11.83 1.25-17.75s-2.71-11.91-7.09-15.93c-3.03-2.79-6.93-4.47-10.91-5.52-11.8-3.11-24.94-.71-34.88 6.37-9.94 7.08-16.5 18.71-15.11 35.07l-2.07-1.47c16.05 7.48 34.33 11.18 47.66 22.83 1.31 1.14 2.56 2.36 3.97 3.36 3.02 2.14 6.74 3.27 10.46 3.96.15.28-.45.35-.6.07-.15-.28-.13-.67-.39-.84-.24-.18-.47.47-.41-.24z" opacity=".2" /> <path d="M668.95 398.69c-8.62-4.7-12.42-15.61-11.27-25.37 1.15-9.76 6.34-18.55 12.01-26.57 1.66-2.35 3.42-4.7 5.77-6.36 2.97-2.1 6.63-2.92 10.22-3.53 7.14-1.21 15.05-1.58 21 2.54 3.2 2.22 5.48 5.51 7.68 8.72 4.9 7.16 9.8 14.32 14.41 22.11 0 .16 0 .32.56 3.62-21.45 6.49-42.29 14.99-62 25.66 0 .17 0 .33 1.62-.82z" opacity=".212" /> </g> </g> </g> </g> <g id="clouds"> <path id="cloud-2" d="M904.43,206.57c0-24.19-26-43.8-58-43.8a72.78,72.78,0,0,0-28,5.43c-20.29-18.19-57.92-30.4-101-30.4-40.24,0-75.74,10.66-96.77,26.9a67.55,67.55,0,1,0-15.53,114.55c9.9,23.25,34.7,39.75,63.75,39.75,24,0,45.06-11.25,57.26-28.25,15.37,7.87,36.13,12.71,59,12.71,47.34,0,85.72-20.69,85.72-46.22A26.44,26.44,0,0,0,868.78,247C889.72,240.39,904.43,224.78,904.43,206.57Z" transform="translate(1037.17 -51.56)" fill="#020f0f" opacity="0.1" /> <path id="cloud-1" d="M1301,255.92c2.89,10.56,29.85,12.38,60.23,4.07a148.3,148.3,0,0,0,25.87-9.63c21.41,2.67,58.55-1.77,99.39-12.94C1524.62,227,1557,213.1,1575,200.56c12.12,1.08,26.79-.29,42-4.47,35.39-9.68,60.46-30.73,56-47s-36.76-21.63-72.15-11.95a135.67,135.67,0,0,0-24.84,9.42c-12.17-7.58-37.66-8.34-65.2-.8-22.74,6.22-41.39,16.6-50.93,27.19-15.51.55-35.78,3.83-57.47,9.76-44.9,12.29-78.82,31.28-75.77,42.42a7,7,0,0,0,3.25,3.92C1310.88,237.34,1298.78,248,1301,255.92Z" transform="translate(1037.17 -51.56)" fill="#020f0f" opacity="0.1" /> <path id="cloud-3" d="M1802.6,873.51c9.78,43.37-45.59,92.81-123.68,110.43a240.24,240.24,0,0,1-70.4,5.66c-42.1,43.76-128.89,86.36-233.9,110.06-98.12,22.14-189,22.54-246.82,5-24.49,23.19-58.2,41.4-97.4,50.24-91,20.53-177-17.06-192.06-84s46.41-137.78,137.39-158.31a221.25,221.25,0,0,1,67.85-4.79c14.74-47.15,68.52-90.37,139.34-106.35,58.47-13.19,114.42-4.62,151,19.16,34.29-22.58,83-42.68,138.72-55.26,115.42-26,217.36-10.06,227.69,35.71a37.69,37.69,0,0,1-1.08,19.54C1753,821,1795.23,840.86,1802.6,873.51Z" transform="translate(1037.17 -4.61)" fill="#020f0f" opacity="0.1" /> </g> </svg> </body> </html>, css: body { background-color: #74c2c2; margin: 0; overflow: hidden; } svg { width: 100%; height: 100vh; } #clouds { filter: blur(3px); -webkit-filter: blur(3px); } #shadow { filter: blur(1px); -webkit-filter: blur(1px); }, js: `// 1) ripples animate in (opacity 0% -> 100%) // 2) ripples grow (scale 1.2) and rotate as paws rotate! // 3) otter eye sparkle moves around // 4) throughout steps 1 -> 3 the background color is changing slightly between aqua blue and a deeper greenish blue gsap.to("#clouds", { ease: "sine.out", transformOrigin: "50% 50%", x: -3000, y: 600, duration: 12, repeat: -1 });

const tl = gsap.timeline({ defaults: { ease: "sine.out", duration: 2 }, repeat: -1, yoyo: true });

tl.to("body", { duration: 3, backgroundColor: "#4da0a0" }) .to("#left-top-lines", { y: -20 }, "<") .to("#right-top-lines", { y: 20 }, "<") .to(".top-ripple", { scale: 1.5 }, "<") .to("#left-foot-group", { y: -50 }, "<") .to("#right-foot-group", { y: 50 }, "<") .to(".bottom-ripple", { duration: 1.2, scale: 1.25 }, "<") .to("#eyes-sparkles", { transformOrigin: "50% 50%", x: -10, duration: 3 }, "<");` };

I've recently been creating more Scalable Vector Graphics (SVG) animations and wanted to walk through my current process for creating SVGs. In particular I will outline how I created the below Sea Bear SVG. If you're not yet familiar with the SVG file format I'd recommend checking out my article on getting started with SVG animation.

Find visual inspiration. I usually find a reference photo to use as inspiration for the SVG I'd like to create unless it's a more abstract concept. I also tend to start off my <a href="https://www.indigitalcolor.com/">digital illustrations</a> with one or multiple reference photos. I am currently working on developing different skills as an artist and use the photo as a visual guide for colors, anatomy and/or proportions. Some of my go-to places for inspiration are Pinterest, Unsplash, Pexels, Google Image, etc. The cool thing about Unsplash and Pexels is that the photos on those sites are generally directly attributable to a specific creator and allow reuse freely.

<center> <img src="/media/bear-reference-photo.jpg" width="400px" /> <br /> <em> reference photo used for the bear relaxing in the water (attribution unknown) </em> </center>

Create a sketch outline I find it helpful to take time to come up with a rough sketch before creating the final SVG. I generally create this rough sketch on my iPad in Procreate to have more control creating the shapes. This step in particular really helps speeds up the process for me in Adobe Illustrator.

reference or trace sketch in Illustrator or a vector -art based program to create SVG. I then will trace over my previous sketch using an Apple Pencil on iPad with the pen tool in Adobe Illustrator. If the image is less complex or proportions aren't as pertinent then I can more-so eyeball the initial sketch to convert it to an SVG and use it as a looser guide. Once I have the lines in Illustrator I adjust individual points along each path to ensure that the overall shape and quality of the lines is on par with the desired result.
Color the Vector. Once I am happy with the shapes in Illustrator then I begin filling in the colors to get closer to the final image. screenshot of the vector image version of the illustration in Adobe Illustrator on iPad
sketch out the animation timeline This was something Cassie Evan's recommended in her SVG animation workshop which I found helpful for better organizing more complex animations. This involves drawing different versions of the image at different points in timeline. I also note any visual changes I'd like to make during the animation that aren't reflected in a particular sketch (in order to have loose pseudocode to guide me as I animate).

a rough sketch showing how the eyes and water should change over time with the animation along with a note indicating the background color will shift as well

The pseudocode for my Sea Bear animation based on the above sketch looked like:

1) ripples animate in (opacity 0% -> 100%)
2) ripples grow (scale 1.2) and rotate as paws rotate!
3) bear eye sparkle moves around
4) throughout steps 1 -> 3 the background color is changing slightly between aqua blue and a deeper greenish blue

I can use this information as a guide when implementing the code needed to animate the SVG.

Clean up SVG for export. Once I have an animation plan it's time to clean up the SVG so that it is easier to programmatically change the values that are key to the animation. In Adobe Illustrator I make sure all of the layers are named as these layer names will be "id"s in the final exported SVG code and then I also group the layers in Illustrator in the groupings I'd like to animate them in. I then also used a tool like SVGOMG to do some clean up to optimize the organized SVG to simplify paths, ensure no images were embedded, etc. These optimizations should reduce the file size of the SVG and make it easier to work with programmatically. CSS Tricks has a good overview of resources for optimizing SVGs.
Add the cleaned up SVG code to HTML tab in a new Pen on CodePen and started coding animation!

<br/>

Organizing Content with Astro Content Schemas

Thu, 06 Mar 2025 18:12:21 GMT

import Callout from "../../components/Callout.astro";

import Tags from "../../components/Tags.astro";

With Astro’s Content Collection Schema functionality, you can enforce structured data like uniform tags to keep your content organized and SEO-friendly. In this post, we'll dive into how you can define and validate tags using Astro's schema system, ensuring every article follows the same tagging conventions. Whether you're managing a blog, documentation site, or any content-heavy project, understanding how to leverage Astro's Content Collections can help you streamline your workflow and maintain consistency effortlessly.

Defining Content Collection Schemas in Astro

I recently decided to do some housekeeping on this site. I upgraded to Astro 5 (specifically Astro 5.4) and refined the tag functionality on this website.

<Callout variant="info"> {" "} Astro's official docs have a helpful guide that covers how to generate tag pages. </Callout>

After I created the tags index for this site I realized there was some duplication within the tags like Git, GitHub and Git/GitHub depending on the post.

and in some instances there may have been inconsistent casing for tags that were otherwise the same like:

Zod Validation in Astro Content Schemas

One of the nice features of how Astro manages content is that it has built-in Zod support to enforce consistent schemas within a content collection like restricting valid content tags to a predefined list, including those compromised of Markdown or MDX files. Zod describes itself as "TypeScript-first schema validation with static type inference".

"Schemas enforce consistent frontmatter or entry data within a collection through Zod validation. A schema guarantees that this data exists in a predictable form when you need to reference or query it. If any file violates its collection schema, Astro will provide a helpful error to let you know." - Astro Content Collections Documentation

With Astro's content collections you can define a specific schema to ensure that all of your content contains the necessary data. The configuration for content collections should be stored in src/content.config.ts. This is a special file that Astro uses to determine how your content should be structured.

One of the schemas I have defined for this site is for my bookshelf to make sure that the data for each book is an object containing string values for the title, author, and external link. The external link also should be a string that starts with "https://www.google.com/books/edition/".

// import { defineCollection, z } from "astro:content";
// import { glob } from "astro/loaders";
const bookshelf = defineCollection({
  loader: glob({ pattern: "**/[^_]*.json", base: "./src/content/bookshelf" }),
  schema: z.object({
    title: z.string(),
    author: z.string(),
    external_link: z
      .string()
      .startsWith("https://www.google.com/books/edition/"),
  }),
});

a sample valid entry would be:

{
  "title": "The Nature of Code",
  "author": "Daniel Shiffman",
  "year": 2024,
  "external_link": "https://www.google.com/books/edition/The_Nature_of_Code/Iv_REAAAQBAJ?hl=en&gbpv=0"
}

However the below object would be invalid as it's missing the external_link

{
  "title": "The Nature of Code",
  "author": "Daniel Shiffman",
  "year": 2024
}

Articles have a different schema than books. Before normalizing the data for the tags the schema defined for this site's articles looked similar to the below object which indicates that Astro expects the tag field in all of the posts to be an array of strings and tags are optional. The keys without optional() in their value like the title, description and pubDate are required for every valid post.

// import { defineCollection, z } from "astro:content";
// import { glob } from "astro/loaders";

const blog = defineCollection({
  loader: glob({ pattern: "**/[^_]*.{md,mdx}", base: "./src/content/blog" }),
  schema: z.object({
    title: z.string(),
    long_title: z.string().optional(),
    description: z.string(),
    featured: z.boolean().optional(),
    pubDate: z
      .string()
      .or(z.date())
      .transform((val) => new Date(val)),
    tags: z.array(z.string()).optional(),
  }),
});

Each key in the schema maps to the frontmatter of my articles. For example the below would be considered valid:

---
title: Organizing Content with Astro Content Schemas
pubDate: 2025-03-06T18:12:21.580Z
description: With Astro's Content Collection Schema functionality, you can enforce structured, uniform tags to keep your content organized and SEO-friendly. In this post, we’ll dive into how you can define and validate tags using Astro’s schema system, ensuring every post follows the same tagging conventions. Whether you’re managing a blog, documentation site, or any content-heavy project, this guide will help you streamline your workflow and maintain consistency effortlessly.
tags: ["Astro", "TypeScript"]
---

Using Enums in Zod for Predefined Valid Content

The inconsistency within the tagging naming conventions revealed that limiting the tags to an array of strings was not restrictive enough so I decided to create a predefined list of valid topics and codified this by defining a Zod enum of valid topics.

The Zod enum looks something like:

// import { z } from "astro:content";
const topics = z.enum([
  "Astro",
  "Animation",
  "Community",
  "Creative Coding",
  "CSS",
  "Developer Productivity",
  "Functional Programming",
  "Git/GitHub",
  "JavaScript",
  "MDX",
  "Netlify",
  "NextJS",
  "p5⁎js",
  "React",
  "VSCode",
]);

and once the topics enum was defined it could be used in the schema for articles to expect that valid tags existed within topics.

- tags: z.array(z.string()).optional()
+ tags: z.array(topics).optional()

With this set up I can easily view the list of valid tags and extend it as needed.

What happens if content is not aligned with the Astro schema?

Now that valid tags are restricted to a predefined list of topics whenever a new post is created it must match the schema or Astro will throw an error. Attempting to include an invalid tag results in an error that must be resolved before the app will build and the error looks something like:

[ERROR] [UnhandledRejection] Astro detected an unhandled rejection.
Here's the stack trace:
InvalidContentEntryDataError: blog → tagging-schema-in-astro data does not match collection schema.
tags.1: Invalid enum value. Expected 'Astro' | 'Animation'| 'Community' | 'Creative Coding' | 'CSS' | 'Developer Productivity' | 'Functional Programming'| 'Git/GitHub' | 'JavaScript' |  'MDX' | 'Netlify' | 'NextJS' | 'p5⁎js' | 'React' |'VSCode' | 'WebMention', received 'Git'

Astro's InvalidContentEntryDataError errors can help developers quickly identify any content that has invalid data such as tags. In my case, the errors saved me time since there was a limited number of articles that needed to be edited and I was manually (or finding/replacing) to make sure all content was valid with the new schema.

Enforcing Character Limits with Zod

I am looking forward to further refining the schemas that I use in Astro and exploring more of Zod's functionality. In addition to normalizing tags, Zod can define other specific data types. For example, I am considering updating my schema to distinguish how a valid long_title and title diverge by using .max(chars) from Zod. When a long_title is defined for a post it's displayed throughout my site, however, a shorter title might be better for meta images. Every article must have a valid title but the long_title is an optional field that can be used, when space is not limited, to convey more context than the 47-character limit set for titles below.

long_title: z.string().optional()
title: z.string().max(47),

Zod can also be configured to enforce a .min(chars) or an exact .length(chars). I encourage you to explore the Zod documentation and the Astro Content Collection Schema documentation for more details and ideas.

Overcoming the Goldilocks Complex

Tue, 18 Apr 2017 00:12:34 GMT

Learning how to code — when you’re stuck in-between novice and expert.

<figcaption>Image of three bears chasing Goldilocks. Courtesy of <a href="https://commons.wikimedia.org" class="figcaption-link">Wikimedia Commons</a></figcaption></figure>

“I’m over 101 courses. I want to try 201 and 301.” — thoughts on the lack of classes for self-taught developers between novice and expert.

Lately, I’ve felt a bit stuck with my progress on learning how to code as I think I’m comfortable with the fundamentals. As I’m starting to immerse myself in coding, reading articles like the Viking Code School’s “Why Learning to Code is So Damn Hard” strongly resonate with me. I recommend checking out that article if you are currently transitioning from breadth knowledge of an area to depth knowledge of a more specific domain.

I have picked up a habit of attending technical Meetup events regularly, but I find myself pausing when signing up for a class or workshop as I am afraid I will feel like Goldilocks, disappointed by a class that is not the right fit. The material in the courses I’ve come across is often too elementary or too advanced.

After taking a handful of classes and having a strong grasp on the essentials, it becomes more important to ask yourself questions about your goals before jumping from one class to the next.

Why am I interested in taking this class? Are the perquisites too advanced or too rudimentary for me? Will the material feel repetitive and if so, will the value outweigh the initial boredom? Would it be more beneficial for me to roll up my sleeves and use my current knowledge and skills to tackle a challenging project?

I’ve learned the fundamentals of programming. Now what?

Contribute to open-source software (OSS).

GitHub and GitLab have large communities of developers contributing to various projects across every sector and technology stack. I am still learning a lot about software development but I recently contributed to CodeCorps, a friendly community that uses EmberJS and works on open source for social good. The great thing about OSS is that anyone can contribute.

If you need help getting started in OSS check out Your First PR and Up for Grabs which are both sites that help surface open issues that work well for individuals new to contributing. Additionally, Free Code Camp has a nice Medium article on landing your first open-source contribution, from your browser, in 15 minutes.

If you are more seasoned in open-source software or just curious about the landscape, check out this piece on top GitHub projects in each country. It shows interesting patterns about the most popular types of open-source software, and it may help you find the next project you can contribute to.

<figcaption>Image via <a href="https://giphy.com" class="figcaption-link">Giphy</a></figcaption></figure>

Share what you learned (even if it is just for your future self).

Be sure to document your learnings. You gain a better grasp of the material by teaching someone what you know. Presenting the information to others — via blog or in person — will reinforce what you’ve learned and allows you to prioritize the information in a meaningful way that you otherwise might not have.

I recently had to call myself out for imposter syndrome — I seriously considered signing up for a college-level Python class where I already knew ~90% of the content. It wasn’t until after I requested a copy of the syllabus that I realized I’d be disappointed. If you have a strong grasp on the main topics a course and have satisfied any applicable prerequisites, then perhaps you could gain more as a TA than as a student. In addition to teaching others, written documentation in a README or blog is a great way to allow you to look back at your learnings. Your future self will thank you for writing meaningful comments in your code.

Challenge yourself.

Don’t be afraid to attend conferences and technical events that are outside the comfort of your current scope.

<figcaption>Image courtesy of <a href="https://medium.com/u/fbfa235a954c" class="figcaption-link">O’Reilly Media</a></figcaption></figure>

Earlier this month I was awarded an O’Reilly Media scholarship to attend O’Reilly’s Software Architecture Conference in New York City. The “Who Should Attend” section of the conference advertisement reflected their openness to novice techies, calling for “Aspiring software architects seeking the skills necessary to move up”. If you identify as a member of an underrepresented group within the tech community, apply here for a scholarship to an upcoming O’Reilly conference.

My biggest takeaways from the Software Architecture conference included learning first hand from Google Developers about how Accelerated Mobile Pages (AMP) and progressive web apps (PWA) can increase user engagement and increase second-visit performance in addition to the technical ways cutting-edge technology such as AMP can be implemented. I was able to bring that valuable information back to my job.

I found out about this scholarship opportunity through Elizabeth Ferrao of Women Who Code NYC and Jessica Waite of Hello World. Being involved in communities like Women Who Code, Ladies Storm Hackathons, and Ladies Get Paid is a great way to find out about local opportunities and meet up with other women in the tech industry.

In addition to the technical topics that I was exposed to at the conference, I was able to engage in a discussion with other scholarship recipients about how important it is to speak at conferences even if you don’t feel like an “Expert” on a subject. There is some realm where you are the expert — sharing valuable information from personal experience is a great way to be an expert (e.g., How I overcame imposter syndrome, How I broke into tech without a CS degree, My experience as a bootcamp grad, etc.)

Despite initially feeling like I was just an aspiring software architect, I was able to walk away with invaluable information from not only the various speakers but also the other attendees.

If learning how to code has taught me anything it is that learning how to learn is crucial to advancing. To conclude this article, I want to share an important quote from a Harvard Business Review article about how to get better at Learning to learn:

It speaks to the uncomfortable experience that accompanies letting go of the training wheels:

“I’m not talking about relaxed armchair or even structured classroom learning. I’m talking about resisting the bias against doing new things, scanning the horizon for growth opportunities, and pushing yourself to acquire radically different capabilities — while still performing your job. That requires a willingness to experiment and become a novice again and again: an extremely discomforting notion for most of us.” — Erika Andersen, Harvard Business Review

Do you have any tips for leaping from a Novice coder to Expert programmer? If so, I’d love to hear your tips.

Egghead Podcast: "Personal Growth From Open-Source And Meetups"

Sun, 22 Dec 2019 02:43:13 GMT

I recently spent some time talking with Joel Hooks from Egghead.io about my journey to landing my first engineering role, attending and organizing meetups and contributing to open-source. Give it a listen if you'd like to learn more about my journey into tech.

How I automatically created a Twitter List of FreeCodeCampers in 5 minutes

Wed, 17 Jan 2018 17:11:11 GMT

Using Twython Twitter API wrapper to add users to a Twitter List

We are going to create a Python script that will automatically search Twitter for individuals who use the #freeCodeCamp hashtag and add them to a Twitter list of "FreeCodeCampers". Twitter lists are a way to curate a group of individuals on Twitter and collect all of their tweets in a stream, without having to follow each individual accounts. Twitter lists can contain up to 5,000 individual Twitter accounts.

We can accomplish this by doing the following:

Installing the necessary Python packages
Registering an application with Twitter
Generating and accessing our Twitter credentials
Making Twitter Search and List API calls

So lets get started.

1. Installing the necessary Python packages

Create a file named addToFreeCodeCampList.py, that will contain our main script and then import two Python modules into this file:

Import Config: In the same directory as ouraddToFreeCodeCampList.py script, create a file named config.py that stores our confidential Twitter API credentials. We are going to import our API credentials from that file into our addToFreeCodeCampList.py script by including the line import config. Twitter requires a valid API key, API secret, access token and token secret for all API requests.
Import Twython: Twython is a Python wrapper for the Twitter API that makes it easier to programmatically access and manipulate data from Twitter using Python. We can import Twython with the following line from twython import Twython, TwythonError.

Your addToFreeCodeCampList.py script should now look like this.

    import config
    from twython import Twython, TwythonError

2. Registering an application with Twitter

We need to authenticate our application in order to access the Twitter API. You need to have a Twitter account in order to access Twitter's Application Management site. The Application Management site is where you can view/edit/create API keys, API secrets, access tokens and token secrets.

In order to create these credentials, we need to create a Twitter application. Go to the Application Management site and click on "Create New App". This should direct you to a page that looks similar to the one below.

Fill out of the required fields and click on "Create your Twitter application". You will then be redirected to a page with details about your application.

3. Generating and accessing our Twitter credentials

Click on the tab that says "Keys and Access Tokens" and copy the "Consumer Key (API Key)" and "Consumer Secret (API Secret)" into the config.py file
Scroll down to the bottom of the page and click on "Create my access token". Copy the generated "Access Token" and "Access Token Secret" into the config.py file.

Currently, all of our Twitter credentials live inside our config.py file and we've imported config into our addToFreeCodeCampList.py file. However, we have not actually passed any information between the files.

Let's change that by creating a Twython object and passing in the necessary API key, API secrets and API token from our config.py file with the following:

    twitter = Twython(config.api_key, config.api_secret, config.access_token, config.token_secret)

The addToFreeCodeCampList.py file should now look similar to this:

  import config
  from twython import Twython, TwythonError
  # create a Twython object by passing the necessary secret passwords
  twitter = Twython(config.api_key, config.api_secret, config.access_token, config.token_secret)

4. Making Twitter Search and List API calls

Let's make an API call to search Twitter and return the 100 most recent tweets

        # return tweets containing #FreeCodeCamp
        response = twitter.search(q='"#FreeCodeCamp" -filter:retweets', result_type="recent", count=100)

Look at the tweets returned from our search

 # for each tweet returned from search of #FreeCodeCamp

 for tweet in response['statuses']:

 # print tweet info if needed for debugging

 print(tweet)
 print(tweet['user']['screen_name'])

A single tweet returned by this API call looks like this in JSON:

 {'created_at': 'Sun Dec 24 00:23:05 +0000 2017', 'id': 944725078763298816, 'id_str': '944725078763298816', 'text': 'Why is it so hard to wrap my head around node/express. Diving in just seems so overwhelming. Templates, forms, post…
  'truncated': True, 'entities': {'hashtags': [], 'symbols': [], 'user_mentions': [], 'urls': [{'url': 'https://t.co/ae52rro63i', 'expanded_url': 'https://twitter.com/i/web/status/944725078763298816', 'display_url': 'twitter.com/i/web/status/9…', 'indices': [117, 140]}]}, 'metadata': {'iso_language_code': 'en', 'result_type': 'recent'}, 'source': '<a href="http://twitter.com" rel="nofollow">Twitter Web Client</a>', 'in_reply_to_status_id': None, 'in_reply_to_status_id_str': None, 'in_reply_to_user_id': None, 'in_reply_to_user_id_str': None, 'in_reply_to_screen_name': None, 'user': {'id': 48602981, 'id_str': '48602981', 'name': 'Matt Huberty', 'screen_name': 'MattHuberty', 'location': 'Oxford, MS', 'description': "I'm a science and video game loving eagle scout with a Microbio degree from UF. Nowadays I'm working on growing my tutoring business at Ole Miss. Link below!", 'url': 'https://t.co/dfuqNNoBYZ', 'entities': {'url': {'urls': [{'url': 'https://t.co/dfuqNNoBYZ', 'expanded_url': 'http://www.thetutorcrew.com', 'display_url': 'thetutorcrew.com', 'indices': [0, 23]}]}, 'description': {'urls': []}}, 'protected': False, 'followers_count': 42, 'friends_count': 121, 'listed_count': 4, 'created_at': 'Fri Jun 19 04:00:44 +0000 2009', 'favourites_count': 991, 'utc_offset': -28800, 'time_zone': 'Pacific Time (US & Canada)', 'geo_enabled': False, 'verified': False, 'statuses_count': 199, 'lang': 'en', 'contributors_enabled': False, 'is_translator': False, 'is_translation_enabled': False, 'profile_background_color': 'C0DEED', 'profile_background_image_url': 'http://abs.twimg.com/images/themes/theme1/bg.png', 'profile_background_image_url_https': 'https://abs.twimg.com/images/themes/theme1/bg.png', 'profile_background_tile': False, 'profile_image_url': 'http://pbs.twimg.com/profile_images/777294001598758912/FVOIrnb4_normal.jpg', 'profile_image_url_https': 'https://pbs.twimg.com/profile_images/777294001598758912/FVOIrnb4_normal.jpg', 'profile_banner_url': 'https://pbs.twimg.com/profile_banners/48602981/1431670621', 'profile_link_color': '1DA1F2', 'profile_sidebar_border_color': 'C0DEED', 'profile_sidebar_fill_color': 'DDEEF6', 'profile_text_color': '333333', 'profile_use_background_image': True, 'has_extended_profile': True, 'default_profile': True, 'default_profile_image': False, 'following': False, 'follow_request_sent': False, 'notifications': False, 'translator_type': 'none'}, 'geo': None, 'coordinates': None, 'place': None, 'contributors': None, 'is_quote_status': False, 'retweet_count': 1, 'favorite_count': 0, 'favorited': False, 'retweeted': False, 'lang': 'en'}

Add Tweet-ers to our Twitter list

In order to add the author of the tweet to our Twitter list we need the username associated with the tweet tweet['user']['screen_name']

Let's try to add the users from these tweets to our Twitter list "FreeCodeCampers". I created my Twitter list at https://twitter.com/indigitalcolor/lists/freecodecampers which means for my script the slug is freecodecampers and the owner_screen_name is mine, waterproofheart.

for tweet in response['statuses']:

# try to add each user who has tweeted the hashtag to the list
try:
twitter.add_list_member(slug='YOUR_LIST_SLUG', owner_screen_name='YOUR_USERNAME', screen_name= tweet['user']['screen_name'])

#if for some reason Twython can't add user to the list print exception message
except TwythonError as e:
print(e)

You can create your own Twitter list by navigating to your Twitter profile, clicking on "Lists" on desktop and clicking on the right hand side to "Create new list". View the official Twitter List documentation for more information.

You can test your script by running python addToFreeCodeCampList.py in the terminal.

My final script looks like this:

import config

from twython import Twython, TwythonError

# create a Twython object by passing the necessary secret passwords
twitter = Twython(config.api_key, config.api_secret, config.access_token, config.token_secret)

# return tweets containing #FreeCodeCamp
response = twitter.search(q='"#FreeCodeCamp"  -filter:retweets', result_type="recent", count=100)


# for each tweet returned from search of #FreeCodeCamp
for tweet in response['statuses']:
 # print each username if needed for debugging
 # print(tweet['user']['screen_name'])

 # try to add each user who has tweeted the hashtag to the list
 try:
     twitter.add_list_member(slug='YOUR_LIST_SLUG', owner_screen_name='YOUR_SCREEN_NAME', screen_name= tweet['user']['screen_name'])
 except TwythonError as e:
     print(e)

This script can be set to automatically run locally or remotely via a cron job which allows tasks to be performed at a set schedule.

Feel free to tweet at me if you have any questions, suggestions or want to share how you modified this script!

Keeping Server-Side Rendering Cool With React Hydration

Fri, 14 Aug 2020 20:34:26 GMT

import Callout from "../../components/Callout.astro";

Server-side rendering can be powerful but it does require thinking in multiple contexts so it's important to be familiar with some of the common gotchas when developing Server-Side Rendered websites. This article is a written version of a talk I gave at React Rally 2020, where I shared some helpful things to keep in mind to render a seamless experience as a Server-Side Rendered (SSR) site transitions from a window-less (server) environment to a browser.

<Callout> A version of "Keeping Server-Side Rendering Cool With React Hydration" is also available at <a href="https://github.com/M0nica/react-ssr-hydration-talk"> {" "} GitHub/m0nica/react-ssr-hydration-talk </a> . </Callout>

What is Server-Side Rendering (SSR)?

Let's take a step back. First, what is server-side rendering? When a server generates the initial HTML that loads in a browser. Frameworks like NextJS and GatsbyJS support SSR out of the box. Server Side Rendered applications tend to initially load content faster and lead to higher SEO ranking than their Client-Side Rendered counterparts.

There are different types of server-side rendering for example server-side rendering can be used to render every single page request or only the initial page request. NextJS offers two forms of server-side rendering. You may be familiar with Create React App, a default React app boilerplate which does not come with SSR functionality configured out of the box.

What is Client-Side Rendering (CSR)?

In contrast to Server-Side Rendering, a website that only supports Client-Side Rendering requires visitors to have JavaScript enabled to view content on the site. Often visitors will see a largely blank page when visiting a Client-Side rendered application if they do not have JavaScript enabled.

If you look at the DOM in the developer tools of a Create React App (or client-side only rendered application) you'll notice very little HTML markup in the DOM. The markup might resemble something like the below code:

<html>
  <head>
    <!-- SEO/Metadata here -->
  </head>
  <body>
    <div>You need to enable JavaScript to run this app.</div>
    <div id="root"></div>
    <script>
      <!-- all of the JavaScript -->
    </script>
    <script src="/static/js/2.6158a3d8.chunk.js"></script>
    <script src="/static/js/main.ba831a9f.chunk.js"></script>
  </body>
</html>

Generally this markup will include the root where React is injected, a message saying you need to enable JavaScript to run the app as well as script tags that link to the JavaScript that needs to be loaded to hydrate the page.

Overview of SSR (in static context)

Let's walk through what happens in Server-Side Rendered applications like NextJS or Gatsby when all the pages for the site are statically generated at once in the server.

First, you write the site in React ⚛️ then Gatsby or Next (Static Site Generation) creates a production build of your site using ReactDOMServer, a React server-side API to generate HTML from React. When someone visits your website the first thing they'll see is the HTML generated from the server. JavaScript then loads after the initial page load and the ReactDOM.hydrate() API kicks in to hydrate the HTML page that was rendered from the server with JavaScript. After Hydration the React reconciler APIs take over and the site becomes interactive.

Toggling JavaScript: SSR vs. CSR

Let's compare how a Server-Side and Client-Side rendered applications appear when JavaScript is enabled or disabled. For these two examples, I used Gatsby and Create React App for these technologies.

The above image is of a Gatsby site, where when JavaScript is toggled on/off there is very little visible change on the left aside from the image loading as most of the HTML was available without JavaScript.

In contrast, in the above image of a Create-React-App which uses client-side rendering and the browser is responsible for constructing the initial HTML. Due to this we just see the bare-bones HTML as opposed to a full HTML document when JavaScript is disabled.

My server-side app looks great in development...What could go wrong? 😅

We just looked at an example of Server-Side rendering that looked great in production both with or without JavaScript! What could go wrong? There are some common issues you might run into with Server-Side rendered applications that only occur during the initial hydration process in production such as layout shifts or errors that only appear at build-time.

1. Missing Data on Server-Side

Something helpful to keep in mind is that some data just is not available in the static server context like user or browser-specific data. For example, window size, authentication status, local storage, etc.

In the above image of Target's navigation, you'll see that the store location data, my name, and items in the shopping cart were not available on the initial page load. Once the data was available it hydrated on the page without shifting the layout. Loading patterns like this can be common on server-side rendered applications.

2. Unavailable JavaScript

Let's debug the above hydration issue that caused my site to have multiple unnecessary rendering changes during load. Something huge that is not available on initial load and can cause issues in server-side rendered applications is JavaScript! It's considered a best practice to load CSS before JavaScript therefore you need to consider how the HTML and CSS on a page load BEFORE JavaScript is available since JavaScript is not required for the page to load.

You may end up noticing weird changes on the initial page load that change too quickly to properly inspect - especially if you have a faster internet connection. But there are ways to slow down and really see what is going on. In particular, I'd recommend disabling JavaScript in your browser or using a site like web page test to generate film strip thumbnails that show you exactly how the page is loading step by step.

Above is the waterfall I took of the issue on my site before it was resolved. You can see one of the issues is that the size of the FontAwesome icons changes drastically between 96% and 99% loaded which can be a disjointing experience.

The solution for getting rid of the resizing of the icons during load involved replicating the final styling with local CSS and removing any dependency on FontAwesome's external CSS which required JavaScript to be available.

I disabled JavaScript which allowed me to see in development that the ways the icons look before they were fully loaded mirrored the app without JavaScript. This led me to realize Font Awesome was using its own styling that was coming in through JS that conflicted with my local CSS style. Since CSS loads before JS, disabling Font Awesome's external CSS (loaded via JavaScript) and replicating the CSS styles I wanted locally resolved the issue

You'll notice after (above image) removing the dependency on Font Awesome's CSS that the styling of the icons remains consistent as the application loads.

<Callout> <a href="/blog/less-javascript-is-more/">I wrote an article</a> with more information about my experience resolving the Font Awesome rendering issues. </Callout>

3. Immutable Layout

The previous issue of changing styles is related to a much larger issue of handling layouts on the server-side. Generally, you should avoid unnecessary layout shifts during page load by implementing layouts with placeholder/gap for expected client-side content and avoiding using JavaScript to position or style content instead of CSS. It is common for some data to be unavailable as the page loads, however, you can develop in a way that can handle missing data by leaving room in the UI for the data to load. In the Target navigation example you can see there is no shift as the user/store specific data is loaded.

4. Strange Conditional Rendering in Server Context

If you write React you may have conditionally rendered content like the below code snippet based on screen size using the MatchMedia API. However, this approach might lead to some unnecessary frustration...

if (small) {
  return <MobileApp />;
} else {
  return <DesktopApp />;
}

The matchMedia() API can't reliably detect the browser or device size in the server context which can lead to some strange rendering issues as the page loads if the originally set media size doesn't match the actual browser.

It's preferable to use CSS or a library like fresnel which wraps all Media components in CSS instead of MatchMedia in Server-Side rendered applications to layout content. Since CSS loads before JS, styles applied via CSS, unlike JavaScript should visibly match what you expect on page load.

Below is an example of how Fresnel can be used. First, you need to import createMedia from Fresnel then define the breakpoints and export MediaContextProvider from the object created from createMedia to wrap the entire app. Then you can use Fresnel's Media component throughout your app to render components based on the predefined breakpoints.

import React from "react";
import ReactDOM from "react-dom";
import { createMedia } from "@artsy/fresnel";

const { MediaContextProvider, Media } = createMedia({
  breakpoints: {
    sm: 0,
    md: 768,
  },
});

const App = () => (
  <MediaContextProvider>
    <Media at="sm">
      <MobileApp />
    </Media>
    <Media greaterThan="sm">
      <DesktopApp />
    </Media>
  </MediaContextProvider>
);

ReactDOM.render(<App />, document.getElementById("react"));

The final step is inject the CSS in the server by passing mediaStyle into a <style> tag in the head of the document so that CSS can be generated from fresnel markup and be rendered on the server. You can read more about setting up Fresnel for SSR in the Fresnel docs.

5. Error: Window is undefined

If you attempt to access browser-specific elements in a server context JavaScript will not be able to resolve those elements.

When building a site you might run into the window is undefined or document is undefined error. This happens when logic within an app assumes the browser window is defined in a server and reference browser-specific elements in the server.

Your first inclination to resolve the undefined Window error might be to write something like:

typeof window !== undefined ? //render component : // return null

However, if your app is using the ReactDOM.hydrate API to transform the site from HTML to the virtual DOM you need to be aware of ReactDOM.hydrate's constraint. ReactDOM.hydrate():

👯‍♂️ expects that the rendered content is identical between the server and the client.
🙅🏾‍♀️ does not guarantee that attribute differences will be patched up in case of mismatches.

The Hydrate API that converts HTML to full-fledged React expects that the content is always identical between the server and client and does not guarantee that matches will be patched up in case of mismatches. Due to this lack of guarantee, it is NOT a good idea to conditionally render based on elements that will differ between the server and client.

<Callout> Check out{" "} <a href="https://joshwcomeau.com/react/the-perils-of-rehydration/"> this article </a>{" "} by Josh W Comeau for examples of visual discrepancies that can occur when React.Hydrate() fails to reconcile an unexpected difference.{" "} </Callout>

Safely accessing browser elements enables you to avoid reconciliation errors when ReactDOM.hydrates a site from HTML to React. In order to avoid issues with the hydration reconciliation process, you can wrap any side effects that rely on the Window or Document in a useEffect hook since that only fires after the component has mounted.

useEffect() Example:

function Example() {
  const [count, setCount] = state(0);
  useEffect(() => {
    document.title = `You clicked ${count} times`;
  });
}

This is an example from the React Docs of referencing a browser element, document.title within useEffect(). This code will never be executed on the server as it executes after the React Virtual DOM is available and therefore avoids running into issues with React.Hydrate().

Rule of Least Power

With JavaScript comes great responsibility, sometimes JavaScript just isn't the right tool for the job:

"JavaScript is a powerful language that can do some incredible things, but it’s incredibly easy to jump to using it too early in development when you could be using HTML and CSS instead. Consider the rule of least power: Don’t use the more powerful language (JavaScript) until you’ve exhausted the capabilities of less powerful languages (HTML)." - Iain Bean, Your blog doesn’t need a JavaScript framework

I recently used the rule of least power to speed up the initial load time of my header and eliminate relying on JavaScript to dynamically load different headers images on my site based on screen size.

I was looking into how to display different images based on screen size and stumbled up HTML art direction which can be used to dynamically load images based on the screen size using HTML srcset attributes instead of JavaScript. Swapping images at different screen sizes can be done with JavaScript or CSS instead of native HTML attributes however using HTML can improve page loading performance as it prevents unnecessarily preloading two images.

The cool thing about the HTML approach is that it can improve page loading performance as it allows the browser to only preload the image that is visible within the viewport. This can be especially beneficial if you need to display multiple images at various places within a site depending on the screen size.

<picture>
  <source media="(min-width: 625px)" srcset="animonica-full.png" />

  <source srcset="animonica-headshot-cropped.png" />

  <img src="animonica-full.png" alt="Illustrated Monica" />
</picture>

In order to set up this functionality in HTML you can use the picture attribute and set media queries on each source image. It will return the first condition the is true and as a fall back it'll return the image from the img tag.

<Callout> It's also possible to use the art-direction API in Gatsby with gatsby-image which is Gatsby's package for loading and transforming images from GraphQL. I wrote <a href="/blog/2020-06-24-exploring-art-direction-in-gatsby/">an article</a> with more information about my epxloration into using art direction with Gatsby. </Callout>

Summary

In a Server-Side Rendered context it's important to consider how the page loads both when data is and is not available.
CSS is the right tool for handling layout, especially in a Server-Side Rendered Application. Using JavaScript for styling in SSR apps can lead to strange loading experiences for some users.
It's important to guard references to browser-specific elements like document or window within useEffect() to avoid reconciliation error as the page hydrates to transform SSR apps from HTML to React.

Resources & Further Reading

Below are some resources I recommend if you're looking to further explore the rendering process for server-side rendered React applications.

https://nextjs.org/docs/basic-features/pages#server-side-rendering
https://reactjs.org/docs/reconciliation.html
https://www.gatsbyjs.org/docs/react-hydration/
https://joshwcomeau.com/react/the-perils-of-rehydration/
https://www.webpagetest.org/
https://github.com/artsy/fresnel
https://www.speedpatterns.com/patterns/immutable_layout.html

Set Yourself Up For Success During Hacktoberfest

Thu, 01 Oct 2020 13:08:03 GMT

import Callout from "../../components/Callout.astro";

Throughout Hacktoberfest (October) people are encouraged to contribute to open-source to secure a t-shirt along with other swag. I have long been a fan of Hacktoberfest as some of my initial contributions to open-source software occurred during Hacktoberfest. Although, a downside to Hacktoberfest for some project maintainers is that people are encouraged to submit low-quality, spammy pull requests which directly increases the time required for them to maintain their projects without the benefit of being able to incorporate the code that was submitted [Update: As of 10/03/2020 project maintainers must opt-in to participating in Hacktoberfest]. A lot of project maintainers for projects without large corporate funding are unpaid (or underpaid) volunteers.

As I've contributed to larger open-source projects and maintained smaller projects over the years I've learned more about what types of open-source contributions are generally accepted. I recently read through Working in Public by Nadia Eghbal (and shared my notes) which is a great primer if you are interested in learning more about the labor that goes into maintaining open-source software and norms for participating in various types of open-source communities. Below are some of my thoughts on how to make quality contributions to open-source during Hacktoberfest and beyond! I plan on updating this post over time.

1. Finding Issues

If you're newer to contributing and are looking for issues that are designed to be smaller in scope, instead of opening pull requests with unsolicited, 1 character changes, I'd recommend using GitHub's issues filter to search for "Hacktoberfest" or "Good First Issue" or checking out these sites that help people find beginner-level issues that you're interested in contributing to:

https://goodfirstissue.dev/
https://www.firsttimersonly.com/
https://github.com/MunGell/awesome-for-beginners

The benefit of spending the time to find issues that are well-scoped to your interest and experience level is that if you make an attempt at resolving an issue based on the requirements usually maintainers are more willing to work with you to help get your changes accepted into a project.

In addition to using the above resources to find good first issues, I'd also recommend contributing to projects you already use or check out the following projects:

awesome-uses • share your developer setup, gear, software and configs.
httriri: HTTRiRi - HTTP Status Codes as Portrayed by Rihanna GIFs ✨💄 • submit your favorite Rihanna GIF that accurately potrays a status code and improve an educational resource for those looking for an HTTP status code reference.
twilio-labs/open-pixel-art • Contribute to a fun, collaborative pixel art project to teach people how to contribute to open-source.
selfdefined/web-app: Dictionary database with future API and bot integrations • submit definitions and enhancements to the selfdefined dictionary.

<Callout variant="danger"> Hacktoberfest has been updated to require maintainers to opt-in to having contributions to their projects count towards Hacktoberfest. If you would like your contributions to count towards the Hacktoberfest requirements, explore the{" "} <a href="https://github.com/topics/hacktoberfest"> Hacktoberfest topic on GitHub </a> to find projects that have explicitly opted-in to participating. </Callout>

2. Claiming Issues

Different projects have different norms for indicating that someone is planning on working on an issue. As a starter, I would recommend commenting on any issues that you are interested in working on to reduce the chances of multiple people submitting duplicate changes to resolve the same issues. Generally, unless a maintainer already had someone in mind to work on an issue whoever "claims" an issue first and submits a pull request first will be prioritized and later submissions may be viewed as spammy. Also, note that not all issues are opened by project maintainers and core contributors so it's helpful to read the conversation and tags on an issue to determine if a maintainer is interested in resolving the issues that were raised in the issue.

3. Read the Documentation

I would recommend focusing on contributing to projects that have at least a basic README that outlines how to get started with contributing and what the expectations are for contributors. Another file that some repositories have to help provide more context for contributors is a CONTRIBUTING.md which indicates what the expectations are for how people should contribute to a project. For example, for my project https://www.httriri.com/ I've shared guidelines for how files should be named and how to make changes that are more likely to be accepted (i.e, not submitting duplicate content, checking open issues before submitting unsolicited changes) in the README file to help make it easier for new contributors to get new status code submissions accepted:

The GIF should include Rihanna and not already be included on https://www.httriri.com/. In rare cases, a GIF that already exists in the HTTRIRI collection can be used for another status code but within the same set of proposed changes, a new GIF should be chosen for the other status code to ensure there are no duplicate images and the overall size of the collection is growing. Excerpt from HTTRIRI Documentation

If there are things specified within a repository regarding naming conventions, testing practices, where files should live, etc. these are usually requirements and not suggestions unless otherwise indicated. Therefore, it's in your best interest to follow those guidelines to hopefully have your changes accepted and to reduce the back and forth required to finalize your pull request.

4. Opening a Pull request

Once you feel like your changes adequately address an issue you should open a pull request in the repository. It's generally a best practice to reference the issue that you are resolving in your pull request and to add a link to your PR on the issue. Some projects will include a checklist or template when opening a new pull request, this generally should be filled out completely unless something is not applicable and gives you another chance to check that your contribution meets the requirements. For example, if a checklist indicates that unit tests should be updated or added for all changes then you should make sure that is done in your pull request and if not indicate why you have decided to forgo a particular requirement.

If you're not quite ready to submit a PR for feedback but need assistance I'd recommend opening a draft PR or sharing a link to your branch on the issue and requesting guidance from other contributors. Depending on the project they may indicate that other forums like Discord should be used to solicit help with contributing. Not all projects have the same capacity to help newer contributors, so you may have to ask for help from others that aren't necessarily directly involved in the project. For example, if you're contributing to a popular, React repository a project maintainer may not be able to answer a lot of follow-up questions but someone in a popular React Discord might be able to help you.

Summary

Overall, to increase the chance of your pull request being accepted I would recommend first identifying an open issue that a maintainer has already given the green light to be worked on, indicating that you are interested in that issue if it's still up for grabs and hasn't been claimed, reading through the project documentation and guidelines to make sure your contribution is aligned with their expectations for contributions and opening a pull request once you've completed the previous steps. I hope these tips help you get closer to successfully contributing to open-source software!

Setting Up Shell with zsh and Autosuggestions

Fri, 14 May 2021 13:12:21 GMT

import Callout from "../../components/Callout.astro";

This post is an overview of how I recently migrated my bash history and settings from Bash to zsh and set up autosuggestions for my terminal. For a while whenever I opened a new terminal window,the below message greeted me to prompt me to migrate to zsh, which is the default shell for newer macOS versions (as of macOS Catalina):

              *
              *
            * | *
      * * * \|O|/ * * *
       \o\o\o|O|o/o/o/
       (<><><>O<><><>)
        '==========='

The default interactive shell is now zsh.
To update your account to use zsh, please run `chsh -s /bin/zsh`.
For more details, please visit https://support.apple.com/kb/HT208050.

Migrating to zsh while carrying over some of your bash settings is a bit more involved then just running chsh -s /bin/zsh. When I was migrating to zsh I knew that I wanted to be able to use autosuggestions out of the box to auto-populate and enable more robust re-use of commands than setting up aliases. Aliases involve mapping a shorter or more memorable command to another.

Set zsh as default for macOS account

Update macOS account to use zsh as the default by running chsh -s /bin/zsh. After running this command your terminal should look different. For me , after running this command then when I opened a new terminal window my terminal looked different as I prior to converting to zsh I had the Yoncé Bash It theme set up which zsh doesn't support.

Set zsh as the default for VSCode

If you use VSCode or another IDE with an integrate terminal then you may need to update it to use zsh as the default for the integrated terminal or else it will default to the previous default.

Open VSCode
Press SHIFT + COMMAND + P
type in "Terminal" and select "Terminal: Select Default Profile" from the dropdown
select zsh
new terminals opened in VSCode should now use zsh.

Migrate information from bash to zsh

Copy bash history over to zsh

It is helpful to migrate over some of the contents from ~/.bash_history in order to better take advantage of zsh's autocomplete features shortly after migrating. Bash has a file ~/.bash_history that stores previously run commands and zsh has ~/.zsh_history.

<Callout> I copied 1000 of the most recent commands (a.k.a 1000 lines) from my ~/.bash_history to ~/.zsh_history. But you can adjust this number to accommodate the amount of history that you're interested in migrating over. </Callout>

Copy environment variables from Bash to zsh

zsh should be aware of any relevant env variables that are in ~./bash_profile. Env variables in zsh live in ~./zshenv. Depending on what's contained in your ~./bash_profile some items may be better suited to be placed in other zsh files like ~/.zshrc.

Install a zsh plugin manager

Software like oh-my-zsh can help enable more robust zsh configurations than the default zsh. You can install oh-my zsh with the following steps:

Run the following to install ohmyzsh on your computer.

sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Visit https://ohmyz.sh/ for the latest installation instructions.

After successfully installing oh my zsh you may see the following confirmation in your terminal

Cloning Oh My Zsh...
Cloning into '/Users/monica/.oh-my-zsh'...
remote: Enumerating objects: 1210, done.
remote: Counting objects: 100% (1210/1210), done.
remote: Compressing objects: 100% (1175/1175), done.
remote: Total 1210 (delta 20), reused 1096 (delta 15), pack-reused 0
Receiving objects: 100% (1210/1210), 843.85 KiB | 9.48 MiB/s, done.
Resolving deltas: 100% (20/20), done.

Looking for an existing zsh config...
Found ~/.zshrc. Backing up to /Users/monica/.zshrc.pre-oh-my-zsh
Using the Oh My Zsh template file and adding it to ~/.zshrc.

         __                                     __
  ____  / /_     ____ ___  __  __   ____  _____/ /_
 / __ \/ __ \   / __ `__ \/ / / /  /_  / / ___/ __ \
/ /_/ / / / /  / / / / / / /_/ /    / /_(__  ) / / /
\____/_/ /_/  /_/ /_/ /_/\__, /    /___/____/_/ /_/
                        /____/                       ....is now installed!


Before you scream Oh My Zsh! please look over the ~/.zshrc file to select plugins, themes, and options.

• Follow us on Twitter: https://twitter.com/ohmyzsh
• Join our Discord server: https://discord.gg/ohmyzsh
• Get stickers, shirts, coffee mugs and other swag: https://shop.planetargon.com/collections/oh-my-zsh

Check out the docs https://github.com/ohmyzsh/ohmyzsh/wiki to view some of the available themes and plugins.

Setup zsh-autosuggestions

zsh-autosuggestions is a plugin that add nice autocomplete functionality to zsh. Below are instructions for installing it as a plugin for oh-my-zsh to use.

Clone Oh My Zsh repository into $ZSH_CUSTOM/plugins git clone https://github.com/zsh-users/zsh-autosuggestions \${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
Open ~/.zshrc and add the plugin to the list of plugins for Oh My Zsh to load inside of ~/.zshrc.

<Callout> {" "} My plugins in ~/.zshrc looked like "plugins=(git)" when I opened the file so I updated to add zsh-autosuggestions like "plugins=(git zsh-autosuggestions)"`.{" "} </Callout>

Start a new terminal session and commands should now autocomplete based off of the history in ~./zsh_history` (which is added to every time you type a new command)

I am planning on cleaning up my ~./zsh_history a bit if I run into previous commands that had typos or misconfigure paths in order to ensure that autosuggestions isn't recommending my previous mistakes.

I am looking forward to learning more about the zsh ecosystem as so far I am enjoying the autosuggestions plugin and I've heard that the ecosystem has some nice functionality including how it recursively search files, spell checking and robust themes and plugin support.

Initial Thoughts On Migrating from gatsby-transformer-remark to gatsby-plugin-mdx

Tue, 26 May 2020 11:28:31 GMT

import Callout from "../../components/Callout.astro";

Yesterday, I decided tackle two things at once, live-streaming for the first time on Twitch 🎉 while updating this site to support MDX in addition to Markdown. MDX allows developers to write JSX in Markdown documents. I was interested in upgrading this blog to support MDX because from what I've seen it will enable me to produce more interactive and engaging blog content.

Move the slider below to navigate through my MDX journey so far and see MDX in action:

import Slider from "../../components/SliderExample.jsx";

I adapted this slider from the one in this article on The Year of The Interactive Blog Post which features various examples of articles with immersive and engaging interactive experiences.

Here are some of my initial thoughts and findings from migrating this Gatsby site from using Markdown to MDX

Beware of Conflicting Plugins

While I was migrating from gatsby-transformer-remark to gatsby-plugin-mdx to allow my site to support .MDX files in addition to .MD files I followed the steps in this Gastby article on converting an existing Gatsby blog to use MDX. However, along the way I ran into an error accessing some of the fields that should be available for mdx nodes like body,timeToRead and excerpt.

<Callout variant="danger"> {" "} error Cannot query field "body" on type "Mdx". Did you mean "rawBody"? graphql/template-strings </Callout>

While debugging the issue I ended up commenting out all of the plugins in gatsbyRemarkPlugins and confirming that all of the data that should be available to query from mdx was available. I then re-added each plugin one-by-one to determine the culprit. In my case there was a conflict with gatsby-plugin-mdx and the plugin I use to generate Open Graph images for all of my posts (gatsby-plugin-my-social-cards). Until I replaced gatsby-plugin-my-social-cards with gatsby-remark-twitter-cards the plugin body,timeToRead and excerpt were not available to query.

I am not sure how common plugin conflicts like this are but it's definitely something to be aware of when migrating from gatsby-transformer-remark to gatsby-plugin-mdx.

Upgrade Your Syntax Highlighting

So far I am impressed with the developer experience of being able to use React components within MDX. However, in order to have better syntax highlighting for the AST of MDX files I needed to install an MDX specific plugin, VSCode MDX Plugin. The syntax highlighting with this plugin is signficantly better than without but it does seem a bit off. I am curious if there's a better syntax highlighting option for MDX.

Create Reusable Components for Repetitive Markdown

Aside from being able to support more interactivity in my writing I most excited about using MDX to be able to isolate certain functionality into distinct components. After migrating to MDX I was able to replace my ad-hoc Markdown based Table of Contents with a React component

The above screenshot of the code diff shows how I was able to replace the multiple lines of Markdown that were previously required for me to generate a Table of Contents with a one-line component that is able to parse the tableOfContents from the mdx nodes.

This article is very much a garden post 🌱 as I wanted to document my initial learnings and thoughts from updating my site to support mdx.

Tips for Debugging Software like a Detective

Sat, 15 May 2021 15:35:06 GMT

import Callout from "../../components/Callout.astro"; import { Tweet } from "@astro-community/astro-embed-twitter";

Being an effective web developer when investigating a software issue, locally or in production, requires some detective-like debugging skills. As I've grown as a developer I've not only improved the breadth of my knowledge about various ways software can break in unexpected ways but I've also enhanced my debugging skills over time.

In this article, I share a longer-form version of the above Twitter thread which highlights some of my thoughts on various ways to approach understanding why the computer doesn't appear to be doing what you tell it to do. Computers interpret instructions literally and to resolve a discrepancy between actual and expected functionality you may need to revisit your assumptions!

<Callout> {" "} Software engineers can hold a lot of ill-informed assumptions or falsehoods which can lead to subpar handling of "edge cases" like assuming a user's name is permanent or that a name must by X characters or that a name is only structured as first name, middle name, last name when in reality that is not a universal fact. Check out{" "} <a href="https://github.com/kdeldycke/awesome-falsehood"> awesome-falsehood </a>{" "} if you'd like to learn more about common falsehoods that engineers believe about things like time, names, addresses, and more.{" "} </Callout>

If an issue seems to be isolated to my local environment and has gone from working to not working without any notable software changes I may try "turning it on and off again" by trying some of the following: rebuilding database, doing a fresh install of node_modules, restarting docker or your computer, etc. But what do you do when just turning it on and off again doesn’t resolve the issue?

Run linting and read any errors Is there a blaring syntax error? Is your code referencing an undefined variable? More times than I care to admit my code wasn't compiling locally because there was a rouge letter 'f' that I somehow added to a random line. This misplaced char is often picked up by my linting but if I do want to manually skim my changes since the app successfully compiled then I will use the VSCode Git Lens Integration to see if anything stands out as off with my changes. Similar to linting errors, if there are other errors in your terminal, browser console, or webpage that are appearing when your app fails to compile or under the unexpected condition they can help guide your search to figure out what is going wrong. When I first was learning how to program, I more so stared 😳 at error messages instead of reading them. If you're still getting comfortable with error messages check out Nicky Meuleman tips on learning to appreciate errors.
Only change one thing at a time. It can be tempting to change everything at once. But try just changing one thing and before you change it think through how that one change will help you confirm or reject your current assumptions of the problem and ultimately help you further your understanding and bring you closer to a potential solution. Automated tests can be helpful to confirm how changes work under different test cases and to ensure as you progress through the problem you don't unknowingly break preexisting test cases that were previously passing.
Confirm all of your assumptions. Consistently reproduce the issue manually or with tests. Under what conditions does the system fail? To better understand an underlying issue you should determine what conditions it behaves unexpectedly in. Using logs, breakpoints, tests, check network calls, etc to sort out when it fails will get you closer to understanding why it's not working as expected. Is your API actually returning the data you expect? Is it an environment-specific issue? Are there missing environment variables?
Lean on tests to automate confirming your assumptions and testing potential solutions Approaching development with a red-green refactor development approach of defining desired functionality in test, implementing code to make the test go from red to green, and then refactoring without having to worry about unknowingly breaking the desired functionality. This approach prevents building out too much of a feature without testing its functionality and if bugs are resolved in a test-driven way then that means that if a similar regression is made in the future in the codebase that there will be a clear failing test warning future developers that something is amiss. Git also has command, bisect which can be used to quickly find a problematic commit, by strategically checking out specific commits from the git history and then based on whether or not that commit is identified as being before or after the software regression was introduced then the next commit is either earlier or later in the git history until the culprit can be identified. Git bisect can be combined with automated testing to make the process of identifying the problematic commit even more efficient.
Walk through your code line by line. Try to read it with fresh eyes even if that means taking a 5 min break and revisiting. I'm always amazed how sleeping on a problem that stumped me usually makes a lot more sense in the morning. It's definitely possible for your mind to continue working through a problem even when you are not directly in front of a screen.
Look at the source code of the third-party package. check for open issues. If the error may be related to third-party software look at its source code. I’ve looked at React, misc. packages with types, Webmention, etc on GitHub to better understand their functionality and find relevant open issues. Oftentimes others may have encountered a similar issue.
Google is your best friend A quick search can be a developer’s best friend. Are you using a new function or package? Can you find an example where it's working? If you want to see code that uses the same APIs in context then recommend searching your local repo or https://grep.app to search open source repos.
Phone a friend. I recommend integrating git blame into your development environment I use the Git lens plugin which shows you, directly within files in a code editor, who authored certain file changes and the PR which can be helpful for quickly getting more context regarding decisions by looking at the associated Pull Request or having the opportunity to connect directly with the committer. Pair programming can be an effective way to debug and share knowledge. Similar, to the magic of figuring out the solution to a bug in the shower or overnight there is a phenomenon called rubber ducky debugging in which just explaining the issue to someone else (even an inanimate rubber duck) can help make the solution more obvious.

Once you’ve sorted out a gnarly or even an "obvious" in hindsight bug remember to document your learnings. Even if it’s just a quick note for your future self.

6 Transformative Tech Conference Talks

Sat, 22 Aug 2020 11:59:17 GMT

Here's a round-up of some of my favorite conference talks that have shaped the way that I think about web technologies, the workplace and community organizing. I hope some of these talks will also cause you to reflect and in some ways become a better technologist.

1. Glue Talk by Tanya Reilly

</iframe> <br />

I had the pleasure of hearing Tanya Reilly give this talk at a Write/Speak/Code event in NYC. She walks through how to approach "the less glamorous - and often less-promotable - work that needs to happen to make a team successful" through a strategic lens. Often the burden of performing less-promotable work falls on the shoulders of marginalized folks within technology. Her talk is an actionable guide to navigating conversations with your manager to ensure you're contributing to the type of projects that will be recognized and reduce the chance of any surprises during formal reviews. I (unfortunately) have had to recommend this talk to a lot of women in technology who have experienced being delegated to do a significant share of glue work. You can check out the slides and sketch notes on Tanya's site: https://noidea.dog/glue.

<br />

2. JavaScript is AsynchroWAT? By Crystal Martin

</iframe> <br /> Crystal Martin breaks down how asynchronous JavaScript works. I feel like this is a topic that a lot of folks new to JavaScript may have difficulty understanding and Crystal assures folks that don't yet fully understand asynchronous JavaScript that they're not alone. I found her talk very relatable and informative. I especially appreciated her bring in examples of an intense (hair) wash day to describe how JavaScript functions work. <br /> <br />

3. How to Build a Magical Living Room by Saron Yitbarek

</iframe>

Saron Yitbarek, the founder of CodeNewbie is not only a prolific podcaster but also a phenomenal community organizer and one of my heroes! Her keynote at RubyConf is a master class in building inclusive communities. Saron shares what she's learned about building a magical living room to make people feel like they're welcome in your community. You'll walk away from this talk with actionable advice for becoming a stronger community leader.

<br />

4. Tautology and Business Value Presented by Heidi Waterhouse

Heidi presented this talk at You Got This 2020: From Home. I was able to see a live version at Adulting.dev. Heidi talks through how to strategically understand your value within a business context. I think this talk is especially crucial for folks who have not worked through a recession and/or need additional resources and tips to advocate for themselves in the workplace.

5. Building a Custom React Renderer by Sophie Alpert

</iframe>

One of the coolest talks I've seen live was Sophie Alpert walking through how to use the npm package react-reconciler to you build your own React renderer. It inspired me to one day (far away) attempt to give a technical talk with just a text editor. I felt that I had a better understanding of the React reconciliation process after listening to her talk.

<br />

6. Let’s Program Like It’s 1999 by Lee Byron

</iframe> Lee Bryon also gave a phenomenal talk at React Conf where afterward I felt like I traveled a bit through time. He provided an overview of how much the web has not changed over the last 20 years. As a JavaScript developer who has only dabbled in PHP, I found it especially fascinating to learn how many of the PHP and LAMP Stack abstractions and mental models have found their way into the modern JavaScript development ecosystem. More often than not developers discuss how rapidly web development changes so it was helpful for Lee to share some of the principles that have, so far, stood the test of time (a.k.a the past 30 years) through various technical implementations.

What conference talk has most inspired you? What's the most interesting presentation you've seen so far? Share your favorite conference talks with me on Twitter: @indigitalcolor.

Working In Public Book Notes

Sun, 09 Aug 2020 19:41:03 GMT

import { Tweet } from "@astro-community/astro-embed-twitter";

import Callout from "../../components/Callout.astro";

<Callout variant="garden"> This reflection was written as I was reading "Working in Public". Below are my thoughts/notes from the reading along with some direct quotes. </Callout>

I recently picked up a copy of the book Working In Public by Nadia Eghbal. I was especially interested in reading this book as I recently became a GitHub Star and am currently working full-time on open-source work for the first time.

I am hoping to walk away from this book with a better understanding of how to help folks newer to open-source who are interested in making meaningful contributions to open-source as well as, what does (or could) sustainable open-source look like.

In the introduction of Working in Public, Eghbal discusses the tension between initiatives to help more developers contribute to open source and the fact that often the responsibility of working with new contributors is delegated to a few people (maintainers) who might feel overwhelmed by an influx of casual contributors. Casual meaning they only make one-off contributions and might even disappear before submitting their first contribution!

<Callout variant="book"> "In my conversations with maintainers, I heard them express a genuine conflict with wanting to encourage newcomers to participate in open source and feeling unable to personally take on that work." (Page 9, Working in Public) </Callout>

Knowing that maintaining takes time, energy and is often volunteer-based leaves me wanting to further explore how can I help people make meaningful contributions to open-source? I believe that for most projects that welcome contributions, a high-quality contribution outweighs the cost of maintenance, but I also am not the maintainer of an open-source project that gets a significant amount of casual contributors.

I've viewed open-source as a community effort but the most popular open-source projects are often predominately the resulting work of a few active contributors or maintainers. This lopsided distribution of work within open-source is evident in contributor graphs and Eghbal points out that 73% of commits to the popular design framework, Bootstrap can be attributed to three developers (Working in Public, Page 10). The amount of people that benefit from a particular open-source can far outweigh the amount of contributors.

GitHub as a Platform

GitHub has risen as the predominate platform for sharing open-source code, although there are some notable projects that have decided to not use GitHub (for example GNU). Some projects choose to use GitLab over GitHub, as GitLab is open-source. However it is noted that Python project felt compelled to move from GitLab to GitHub because of its better developer tooling for automation (Working in Public, Page 30). GitHub is popular largely because it's convenient, has strong developer tooling and a lower learning curve as a lot of developers are already familiar with its interface.

Further Reading: The history behind the decision to move Python to GitHub

Things like package managers have shifted how easy it is to install seemingly trivial but out-sourced logic. Tools like NPM and GitHub may have lowered the barrier to entry to contribute to or use open-source software but have they also increased the obligation of end-users to contribute to improving the software that they use? What are the responsibilities of a user of open-source software?

<Callout variant="book"> "I'm just a 'user,' and contributing a little is part of being a user" (Mikeal Rogers, Page 34, Working in Public) </Callout>

As the community of folks who contribute to open-source grows, how can one be a "good" contributor or user? How can maintainers set up new contributors for success?

Effective onboarding is crucial

Part of the "cost" of onboarding new contributors is newcomers aren't intimately familiar with the norms and standards for a specific project. There are some universal contributing practices you can take from project to project but there are also certain things that are more salient or specific to a particular community. I think taking advantage of GitHub Actions to automate things like linting and testing as well as using and their tools for building a strong community can help alleviate some of the responsibility that falls on both maintainers and contributors.

If you are working on a project that welcomes new contributors what tools, types of automation and documentation do you need to get newcomers up-to speed as quickly as possible? As new contributor I generally look for documentation in the form of READMEs and Contributor Guidelines or Code of Conducts.

The Structure of an Open Source project

<Callout variant="book"> "Developers don't contribute to open source for lack of technical ability, but rather due to fear of committing a faux pas." (Working in Public, Page 43) </Callout>

Where do you even start with contributing?

Contributing to open-source can seem more intimidating than someone's day to day work, regardless of skill-level required, as when new contributors often onboard to a new project they aren't familiar with the social conventions of the project. This is why if you're looking to onboard new contributors it's crucial to set them up for success by documenting certain norms in an obvious place (i.e, README, issue template, PR template).

Open Source is not monolithic. Eghbal reminds us that "The term 'open source' refers only to how code is distributed and consumed. It says nothing about how it is produced" (Working in Public, 44). There are certain trends within open source but a lot can vary from project to project.

What types of contributions are valued or accepted?

While open source projects allow contributions from everyone there is generally a review process and it may be more or less thorough from one project to another. I find that unless there's already an open issue that a maintainer has given a green light to or a glaring bug it's often best to run a change by a maintainer before going through the effort to implement it. If you want to add a one-off feature that mostly only benefits your use-case and you're not a significant stakeholder then your proposal likely won't make it past the approval process.

I've previously used Open-Source software that I wanted to function differently (i.e, adding pagination) but sometimes the maintainer would rather someone fork (copy and modify the software) as opposed to commit directly to the main repository and change that functionality for everyone. Maintainers balance different interests and can be opinionated in different ways about their project than contributors based on having more context regarding usage and long-term goals.

Getting the keys to an open-source project (write-access)

Getting commit access to a larger open source project unlocks the ability to directly merge changes into the main codebase and be more closely a part of the review process of PRs. How does one get commit access?

<Callout variant="book"> "I gained my commit privileges like people still do today on the Python project: I consistently contributed good patches and eventually a core developer noticed and asked if I wanted to join the team" (Brett Cannon, Working in Public, Page 48) </Callout>

There might not be just one way to get commit access to a project but I imagine a lot of people are similar to Brett and end up getting direct write access to a project once they've shown that they have a long-term investment in contributing high-quality updates to a project. Most communities function similarly, generally when you're a positive contributor and more active within a community you are offered more responsibility to contribute back to a community.

Eghbal points out that "it's common among JavaScript developers to give away commit access more freely" as Javascript "is designed to be modular" (Working in Public, Page 46). In the JavaScript ecosystem the benefits (distributing the responsibility of maintenance) of prematurely giving someone commit access may outweigh potential risks (a project being compromised but having minimal impact on the larger ecosystem). I've mostly contributed to the JavaScript open-source community and therefore am not sure how easy or difficult it is to get write access to projects within other ecosystems but I can imagine the effects being devastating for projects that are less modular.

An open-source project can extend beyond just a repository on GitHub. Its community can also live on Stack Overflow, mailing lists, Discord, etc.

Open-source projects are fluid and evolve over time.

There can be a creation phase where there's a lot of foundational work being put into the project and the project isn't seeking or advertising for outside contributors or users. After the creation phase there's an evangelism phase where open source authors want to encourage new users to try out their software and gather as much feedback as possible to use to iterate on the future development of the software. Some projects reach the growth phase where there is significantly more adoption and which Eghbal uses "when maintainers start doing more non-code than code work on the project, such as triaging issues and reviewing others' pull requests" as a signifier of this stage being reached (Working in Public, 55). This growth phase is often when maintainers have to shift to be more selective with what type of contributions and issues they'll entertain from external contributors in order to be mindful of their time.

I would think overall maintainers would be most eager for new external contributors during the evangelism phase as opposed to the creation or growth phase. I also wonder if a project can switch between the evangelism and growth phase...i.e, when a new version of Python is released, although Python is a mature project is there a huge initiative to encourage people to submit feedback and start adopting the newer version.

Aside from projects changing over-time due to adoption and maturity Eghbal also mentions that there are 4 types of open source projects classified by user and contributor growth:

Federations - High User Growth, High Contributor Growth (very active open-source project, may be the first thing that comes to mind when you think of open source - Rust, Node, Linux, etc.)
Stadiums - High User Growth, Low Contributor Growth (Widely used but don't have many contributors, i.e. Babel)
Clubs - Low User Growth, High Contributor Growth (Niche programming languages such as Clojure and Haskell attract a narrow range of users and thus contributors)
Toys - Low User Growth, Low Contributor Growth (i.e, a side project you didn't create with the intention of distributing to other developers although who knows it could develop traction)

Measuring the value of code

Eghbal brings up questions surrounding how do you measure the value of code? Is it based on the amount of dependencies and their value?

Infamously the JavaScript library, Left-pad, broke a lot of things when it was briefly deleted from the NPM registry as it was an underlying dependency for important and prevalent software. Babel relied on left-pad and Babel is a dependency of millions of software projects. Once something is released into the open source universe it takes on a life of its own and isn’t just yours, it becomes part of a complex ecosystem. Due to the interdependent nature of software on an 11-line package (left-pad) NPM decided to restore the package against the original authors' wishes.

<Callout variant="book"> Do you think NPM should have restored left-pad or not? Read{" "} <a href="https://qz.com/646467/how-one-programmer-broke-the-internet-by-deleting-a-tiny-piece-of-code/"> "How one programmer broke the internet by deleting a tiny piece of code"{" "} </a> to learn more about the left-pad incident. </Callout>

Monetizing Open-Source

You might think that the inherent value derived from open-source software would make it easy to monetize, however, there are some things that make code difficult to monetize:

Developers are sensitive to price for a good that they could theoretically create themselves. Some software is more prone to this like web frameworks vs databases. Developers are more likely to build their own frontend technology solutions vs. infrastructure related solutions.
The diversity and breadth of open-source is both a blessing and a curse when it comes to monetization. There’s a lot of variety in the open source world and a lot of software can be substituted or easily replaced with alternative open source solutions

Eghbal shares an example of Sorhus who is able to work full-time in open source based on financial support from patreon and GitHub sponsors. However she believes that it’s his reputation and visibility and not the value of his software alone that has given him enough traction to live off of sponsorship. His sponsors aren’t sponsoring a specific project of his but overall investing in him based on his reputation.

Outside of crowd-sourced sponsorship from individuals, sometimes companies find it worthwhile to support a project’s maintainers as full time employees for reasons like branding, reputation purposes or to have a more direct influence on the future of a project.

The Law and Distribution of Software

The law can’t keep up with software.The US government used to regulate the export of cryptography related software and treated it as a munition export that required tighter regulations. The Pretty Good Privacy (PGP) author Phil Zimmerman ended up releasing the source code as a book PGP source code and internals which could then be more easily distributed around the world since it was protected under free speech (page 157) unlike the actual software in its digital form.

Participatory Open-Source

Eghbal explores various metaphors for how people interact with open source software. What stood out from the metaphors is that a lot of people expect open-source software to welcome participation regardless of the project. Some creators of open-source projects may be perfectly happy sharing their code freely but have no desire to spend additional time tweaking their library to appeal to other users as the intended user of their software is themselves and open-sourcing it is just a "bonus". Eghbal compares this to how some people put up elaborate holiday light displays on their houses for their own enjoyment, as a byproduct their neighbors and travelers also enjoy their light display but the people who put up the lights are not planning on updating details of their light display based on feedback.

“Much of the fatigue that open source developers experience comes not from making their code public but from the expectations around making their code participatory” (page 161).

External participants to a software project often have different interests than maintainers and too many opinions outside of the core group that contributes to and maintains and project can lead to too many cooks in the kitchen.

Final Thoughts

I enjoyed reading Working in Public and having the opportunity to discuss it with the Party Corgi Community, an inclusive community of content creators helping each other grow. Eghbal's research and claims provided important historical context for open-source and pushed me to adopt a more critical lens to how I view the open-source ecosystem. I think the biggest takeaway for me, as someone who wants to make contributing to open-source more approachable (especially as a GitHub Star), is that it is crucial to proactively encourage meaningful contributions and to educate people on open-source norms in an effort to ease some of the responsibilities that are often placed on maintainers.

Monica's Digital Playground

2019 into 2020, Year in Review

Redesigning My Site

More Public Speaking and Community Involvement

Automating File Creation With JavaScript

Why Scaffolding?

Is scaffolding "worth it"?

Micro-generator tool: PlopJS

How does Plop work?

Plop Set Up

Plop Example to Generate JSX Page

Formatting Output

Conclusion

Create Your Own Template

Additional Resources

Understanding Reduce in JavaScript

Reducing an array to a single number

Mapping Items with map() and reduce()

Using map()

Using reduce()

Filtering Items with filter() and reduce()

Using filter()

Using reduce()

Reducing an array to a single object

Notes

Refactoring useState() To useReducer()

Managing form state with useState();

Setting the initial state with useState()

Updating form state with useState()

Managing form state with useReducer();

Setting the initial state with useReducer()

Updating form state with useReducer()

Full Source Code of Examples

source code using useState():

source code using useReducer():

Top Gatsby Plugins For Developer Blogs

Recommended Gatsby Plugins

Exploring Art Direction With Gatsby-Image

4 Meetups That Helped Me Grow as A Woman of Color in Tech

Attending various tech Meetups over the years has been pivotal to my growth as a technologist

1. Women Who Code NYC

2. Girl Develop It NYC

3. Write/Speak/Code NYC

4. Black Software Engineers NYC

Not in New York?

Adding Environment Variables To GitHub Actions

How to Add Instagram Timeline To a NextJS Site

Install and import instagram-web-api

Setup getStaticProps to Fetch Data at Build Time

Setup Instagram Client Authentication

Confirm Instagram Client is Functional

Resolving 4xx Authentication Errors

Request Timeline Data from Instagram

Render Instagram Data with InstagramFeed component

Advent of Code - Day 01 2022

Helper Functions

Day One: Part One

Reading the data

Finding Highest Number of Calories Carried by an Elf

Day One: Part Two

Finding The Three Highest Number of Calories Carried by the Elves

Fetch Webmentions Automatically with GitHub Actions

Displaying Webmentions

Setting Up the Webmention Pipeline

Automating the Script with GitHub Actions

Future Ideas

Automating Outgoing Webmentions

AI-Assisted PR Review

Delete Your Code and Other Reflections from Coderetreat Day

What is Global Coderetreat Day?

What is Conway's Game of Life?

The Simplified Rules of Conway's Game Of Life (source: Wikipedia)

The Format of the Coderetreat

Getting familiar with Conway's Game of Life, Coderetreat and greenfield development

Ping-Pong Pair Programming Approach

Red, Green, Refactor and Mob Programming Approach

Naming Conventions Approach

Writing Test Cases Upfront Approach

Takeaways

Conquering the Command Line

Mapping Items with `map()` and `reduce()`

Using `map()`

Using `reduce()`

Filtering Items with `filter()` and `reduce()`

Using `filter()`

Using `reduce()`

Install and import `instagram-web-api`

Create Input Element with `onChange` event handler

Implement `onChange` to Filter Posts by `<input/>` Event Value