Forem: Joel Hooks 🌩

Content Modeling and Data Design with Sanity.io

Joel Hooks 🌩 — Sun, 07 Feb 2021 05:00:25 +0000

Data is the bedrock of most applications and challenging to get right. It's
vital for the long-term health of an application to have data that is
understandable, flexible, and relevant to users.

This article discusses how we are reconsidering content modeling at a data level for egghead to allow for more flexible collaboration and design.

Where we were at when this started

We have two APIs available that access the same underlying postgres database. One is a REST API that has nice hypermedia capabilities and is pretty slow built on top of jbuilder. The other is a well-formed GraphQL API that is much more performant and provides immediate and direct access to slices of the data we want.

Both of these APIs are fairly 1:1 with the underlying database and define what I've come to look at as a "hyper specified" content model that got the job done, but has been a serious constraint that we've had to live with for many years 😅

Both of these APIs take 30-40 minutes to deploy and require fairly deep knowledge of Rails, GraphQL, and Ruby.

The deeply technical API layer provides a massive barrier to entry, and because everything is very closely tied to the database changes can have rippling side-effects that were never intended

Resources and Collections

When egghead was a sparkling fresh app I started out modeling what was obvious at the time.

Lessons: people come to egghead to watch lessons, not videos.
Series: sometimes people want to watch a series of lessons (not videos)

Later we added Playlists, called them collections, and then decided that both a series and a playlist were actually courses. lol

Fundamentally what we are dealing with are resources and collections, where a collection is just a resource with a list of other resources referenced.

Where we want to be

We want to build a digital garden. We want to curate, update, associate, and present relevant resources to users so that they can quickly find what they need and reach the outcomes they desire.

For us, this requires a "metadata" layer that sits above the APIs without a rigid schema or the need for deep levels of technical know-how to operate.

For years we've done this by creating various JavaScript/JSON data structures in flat files that get compiled in with the application.

You can see an example here where we keep various metadata about egghead courses. Another example is this one that describes the data for our curated home page.

This honestly isn't bad, but it's still tedious, error-prone, and requires us to use IDEs as UI for updating content. Not ideal, but very flexible.

Content Modeling with Sanity.io

After exploring several alternatives and living with the flat json files for years, a product has emerged that checks most of the boxes that we need. Deep flexibility. Ease of use. An incredibly nice authoring experience and a welcoming team and community.

Sanity.

What first stands out to me about Sanity is that it installs into your project via their CLI (command line interface). This was so different to me that it was hard to understand at first, but once I got the CLI installed with a default starter dataset, it started to make sense.

Once I read the docs and started to explore the flexible potential it really clicked.

The core atom of our emerging system is the resource type. You can see how it evolved here on Github if you're interested.

A resource as a type property. It can describe any of the content types that we deal with at egghead, and we can always add additional types as needed. Types are resources like podcasts, videos, courses, collections, and features.

We are able to sync our existing database with Sanity, so all of the items that are in postgres are represented in Sanity. It could potentially replace a huge portion of our data needs, but for now, we are keeping them synced manually.

Modeling resources, not layout

What's stood out as important for us is that we want to create a robust resource model that describes and augments core content. We want it to be flexible and longer-lived than a typical layout and withstand heavy changes to design and presentation.

We want our data to work in different contexts across our app (and beyond) so we are intentionally avoiding any layout concerns in the content model. The data describes what, not where, the content will ultimately be displayed.

This means that instead of modeling pages, we are describing content and layering on supporting assets and metadata that allow us to choose content that's appropriate and relevant, when and where you need it.

A Practical Example

To illustrate, on the egghead homepage we present a large banner that showcases a resource, a new course, an evemt, etc

It's represented in home-page-date.ts as a property called jumbotron

{
  id: 'jumbotron',
  title: 'Introduction to Cloudflare Workers',
  byline: 'new course',
  description:
    `Follow along with Kristian Freeman as you build a localization engine that
     renders data based on the Edge location nearest to the application's user.`,
  image: '/banner.jpg',
  path: '/playlists/introduction-to-cloudflare-workers-5aa3',
  slug: 'introduction-to-cloudflare-workers-5aa3',
  instructor: {
    name: 'Kristian Freeman',
    slug: 'kristian-freeman',
    path: '/q/resources-by-kristian-freeman',
    twitter: 'signalnerve',
    image: '/headshot.jpg',
  },
},

This works pretty well. When we want to swap it out we just go in and enter new data. It's not great though, and requires a deploy.

When I sat down to model this in Sanity, the first impulse was to create a document called "Home Page Jumbotron". Then I can query Sanity using their GROQ query language on the server and create a similar data structure to render the header graphic:

export const getServerSideProps: GetServerSideProps = async ({res, params}) => {
  const load = async () => {
    const data = await sanityClient.fetch(groq`
      *[slug.current == 'home-page-jumbotron'][0]{
        name,
        title,
        description,
        summary,
        byline, 
        meta,
        path,
        'slug': resources[][0]->_id,
        'instructor': collaborators[]->[role == 'instructor'][0]{
          title,
          'slug': person->slug.current,
          'name': person->name,
          'path': person->website,
          'twitter': person->twitter,
          'image': person->image.url
        },
        'background': images[label == 'background'][0].url,
        'image': images[label == 'badge'][0].url,
      }
  `)
    return data
  }

  const resource = await load()

  res.setHeader('Cache-Control', 's-maxage=1, stale-while-revalidate')
  return {
    props: {
      resource,
    },
  }
}

This is getting better. It produces the same data structure, and we can now live-update the header component inside of Sanity Studio and don't need to redeploy. While that is creating documents that are tied to specific pages, it isn't modeling data for layout and gives us a ton of flexibility.

If this is your first time seeing GROQ it might look strange, but it's actually a fascinating and relatively simple way to query data. Here's the official GROQ Cheat Sheet that gives a great overview.

Taking that a step further I can consider replacing the entire home-page-date.ts with a loader that looks like this using what is referred to as an "outer reflection" in Sanity's GROQ query language:

import {sanityClient} from 'utils/sanity-client'
import groq from 'groq'

export async function loadHomePageData() {
  const slugs = {
    jumbotron: 'home-page-jumbotron',
  }
  const data = await sanityClient.fetch(
    groq`
      {
        'jumbotron': ${jumbotronQuery},
      }
  `,
    slugs,
  )

  return data
}

const jumbotronQuery = groq`
*[slug.current == $jumbotron][0]{
  name,
  title,
  description,
  summary,
  byline, 
  meta,
  path,
  'slug': resources[][0]->_id,
  'instructor': collaborators[]->[role == 'instructor'][0]{
    title,
    'slug': person->slug.current,
    'name': person->name,
    'path': person->website,
    'twitter': person->twitter,
    'image': person->image.url
  },
  'background': images[label == 'background'][0].url,
  'image': images[label == 'badge'][0].url,
}
`

This approach would allow me to add a structured query to load the data for each section, feature, and call to action (CTA) on the home page of the site and give the team the ability to update, curate, and tend our collaborative digital community garden without requiring a deploy of the front end.

If we want to change the design or switch out the data we are loading, that starts to become simpler as well.

We are able to layer assets on top of our resources with ease and allow our designers and editorial team members to have more collaborative creative control over the resulting page.

Where we are headed...

This is a great start. Sanity has a lot of potential and we haven't even begun to scratch the surface. We are going to be tuning our content model and importing more data first. Then we will start to explore Sanity's Structure Builder, which can be used to design content pipelines and workflows that give us even more flexibility in our digital gardening process.

Having a bespoke, contextual, lovely content authoring tool at our disposal is exciting, and I'm looking forward to digging in more.

Questions? Please feel free to ask on twitter!

TailwindCSS Dark Mode in Next.js with Tailwind Typography Prose Classes

Joel Hooks 🌩 — Wed, 27 Jan 2021 02:16:37 +0000

When you release a modern website one thing is clear... users expect dark mode out of the box. They aren't interested in your excuses. They don't care about the time it will take to implement, they just want dark mode. Now. 😅

What you will learn about in this article.

This article is going to explain in clear steps how to add TailwindCSS native
dark mode to a Next.js site, including the TailwindCSS Typography plugins prose
classes.

There is an assumption that you have a working knowledge of both TailwindCSS and
Next.js and a site that you'd like to implement a toggle between a dark and a
light theme.

To do this, you will use:

Next.js: A React "meta-framework"
TailwindCSS: A utility-class system for styling web applications
TailwindCSS Typography: A plugin that provides a set of prose classes that provide consistently nice looking typographic defaults (useful for Markdown files, for instance)
next-themes: React Hooks based utility library for Next.js that let's you switch themes in your application.

Motivation for dark mode

With a recent relaunch of egghead.io there were daily requests for a "dark mode" for
the website. In the past our site had had a default singular dark theme, meaning a theme where the background is dark, and the text is light. The new site presented a solid
white–incredibly bright–theme that wasn't very pleasant for many users viewing experience.

Bright themes are particularly aggravating when you are working in a dark room, and
some users have vision troubles that are exacerbated by light or dark themes. This
means that the ability to choose between one or the other is often critical for some
users' ability to use the site at all.

Getting Started

If you don't have a Next.js + TailwindCSS site to work from, here's a github branch
from my Next.js Tailwind Starter that is "pre-dark mode" that you can use.

From this point we need to update some configuration files.

The Tailwind Config

tailwind.config.js is in the root directory of the project and provides TailwindCSS
the information it needs to correctly run in your environment. The TailwindCSS team
has done a great job giving us sensible defaults, but almost every project will have
specific needs and requirements that require custom configuration.

module.exports = {
  purge: ['./src/**/*.tsx'],
  theme: {
    typography: (theme) => ({}),
    extend: {},
  },
  variants: {},
  plugins: [require('@tailwindcss/typography')],
}

This config is almost as basic as it can be. Since you are using the TailwindCSS Typography plugin, this config let's TailwindCSS know that you want to use it. The config also has a purge property that provides an array o globs letting TailwindCSS know which files it should analyze for purging extra classes not used in your application. If we didn't configure purging, the result would be every single class TailwindCSS has to offer being shipped with our application.

That might not be the end of the world, but it is a lot of extra bundle size that your users will never actually need.

So we purge.

After the purge configuration the see the theme, variants, and plugins. Right now these sections are sparse, but that's about to change.

Enabling Dark Mode in TailwindCSS

Enabling dark mode in TailwindCSS is effectively the flip of a switch:

module.exports = {
  darkMode: 'class',
  purge: ['./src/**/*.tsx'],
  theme: {
    typography: (theme) => ({}),
    extend: {},
  },
  variants: {},
  plugins: [require('@tailwindcss/typography')],
}

By adding darkmode: 'class' to the config, you've instructed TailwindCSS to include all of the CSS utility classes for dark mode. This enables a dark variant that you can now add as classes to your React elements like className="bg-white dark:bg-gray-900" and the correct class will be provided when dark is active on your html element.

To test out dark mode in the Next.js app, you'll need to make a couple of changes to the /src/_document.tsx source file that is used to provide custom document structure to the Next.js application.

<Html className="dark">
  <body className="dark:bg-gray-800">
    <Main />
    <NextScript />
  </body>
</Html>

First we add the dark class to the Html element. This enables the dark mode for the entire application. Then we add dark:bg-gray-800 to the body element to provide a dark background for the Next'js application when it is in dark mode.

yarn dev will run the application, and you should see a dark background. Delete dark from the Html elements className and your app should refresh with a default white background.

We've achieved dark mode! 🌑

Obviously your users aren't going to change source code to enabled toggling, so the next step is to add a button that will toggle the dark mode on and off.

Creating a theme with next-themes and React Hooks

Technically your app is going to have two themes: light and dark

Potentially your app could have many themes up to and including hot dog stand. That's amazing if you want to provide your users with that level of flexibility! lol

There are several relatively complicated ways you might approach the problem of toggling themes. As with many things in the React.js and Next.js world, somebody else has already solved the problem very well, and for this the community favorite is next-themes which promises (and subsequently delivers) a "perfect dark mode in two lines of code".

Yes please.

yarn add next-themes

Open /src/_app.tsx

function MyApp({Component, pageProps}: AppProps) {
  return (
    <>
      <DefaultSeo {...SEO} />
      <Component {...pageProps} />
    </>
  )
}

Now, in /src/_app.js import the ThemeProvider and wrap your application Component with it:

import {ThemeProvider} from 'next-themes'

function MyApp({Component, pageProps}: AppProps) {
  return (
    <>
      <DefaultSeo {...SEO} />
      <ThemeProvider>
        <Component {...pageProps} />
      </ThemeProvider>
    </>
  )
}

So far, nothing has really changed in the app. Since dark is hard-coded in your _app.tsx and there is no mechanism to toggle the mode, your application is stuck in dark mode.

Go ahead and delete the className from the Html element:

<Html>
  <body className="dark:bg-gray-800">
    <Main />
    <NextScript />
  </body>
</Html>

Your application will reload, and will once again have the default white background that got us into this situation in the first place.

Toggling between light and dark modes with just a click

Open /src/pages/index.tsx:

export default function Home() {
  return (
    <div>
      <h1 className="text-3xl text-pink-500" css={{backgroundColor: 'teal'}}>
        Welcome to Your App
      </h1>
    </div>
  )
}

This is relatively simple React page component that is located at the root of the site. It defines a div as a container and an h1 element with a bit of welcome text and some questionably stylish classes applied.

To make the toggle work, we need to import a hook from next-themes, manage a little piece of state, and wire it all together in a button.

First, import the useTheme hook:

import {useTheme} from 'next-themes'

export default function Home() {
  return (
    <div>
      <h1 className="text-3xl text-pink-500" css={{backgroundColor: 'teal'}}>
        Welcome to Your App
      </h1>
    </div>
  )
}

Now call the useTheme hook to gain access to theme and setTheme.

import {useTheme} from 'next-themes'

export default function Home() {
  const {theme, setTheme} = useTheme()
  return (
    <div>
      <h1 className="text-3xl text-pink-500" css={{backgroundColor: 'teal'}}>
        Welcome to Your App
      </h1>
    </div>
  )
}

Now, add a button element with an onClick handler to use as a toggle:

import {useTheme} from 'next-themes'

export default function Home() {
  const {theme, setTheme} = useTheme()
  return (
    <div>
      <h1 className="text-3xl text-pink-500" css={{backgroundColor: 'teal'}}>
        Welcome to Your App
      </h1>
      <button onClick={}>toggle</button>
    </div>
  )
}

To toggle, we want to check and see what the current theme is, and set the appropriate theme based on that:

import {useTheme} from 'next-themes'

export default function Home() {
  const {theme, setTheme} = useTheme()
  return (
    <div>
      <h1 className="text-3xl text-pink-500" css={{backgroundColor: 'teal'}}>
        Welcome to Your App
      </h1>
      <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
        toggle
      </button>
    </div>
  )
}

A couple of things to note are:

The button is completely unstyled and doesn't really look like a button
clicking it does absolutely nothing 😭

The first issue just means you need to use tailwind to make the button look awesome, but the second issue is more concerning and you need to address that to get this toggle working at all. It's a multi-faceted problem resulting from how we've configured dark mode.

In the tailwind.config.js you set darkMode with the class option. This configuration property also has a media option that uses the prefers-color-scheme media of modern browsers and operating systems to look at how the user has configured their system. The class option, however, means we can select and toggle the mode. In fact, you could delete the button, set the darkMode config to media and call it a day.

For many use cases the class config is the most flexible and is preferred.

In /src/_app.js you need to tell the ThemeProvider to use the class attribute:

<ThemeProvider attribute="class">
  <Component {...pageProps} />
</ThemeProvider>

Let your app compile, refresh the page, and start toggling. Back and forth. Dazzling. A fully configured dark mode powered by Tailwind CSS in a Next.js app.

The future is now.

Solving some problems with our TailwindCSS config and dark mode

This is great. It works!

There are still a couple of problems to solve:

Build times are slooooooow (on large projects they can also completely run out of memory)
If you visit /hi - an mdx file rendered and presented with TailwindCSS Typography prose class, you notice that the text is black.

Slow builds with TailwindCSS Dark Mode and Next.js

This is a known problem that is at the core a webpack issue and both the Next.js team and the TailwindCSS team are aware of it. Basically, TailwindCSS + Dark Mode is a massive CSS file, and webpack hates building source maps for massive CSS files.

👋 If you know how to solve this please hit me up on{' '}
Twitter

For our application this is a huge hassle and requires that we run the development environment with additional memory allocated to node:

NODE_OPTIONS=--max-old-space-size=4048 yarn dev

Ultimately it's a small price to pay for dark mode, and will eventually be fixed upstream. It was also alleviated a bit for us by turning on purging for the dev environment in tailwind.config.css

module.exports = {
  darkMode: 'class',
  purge: {
    enabled: true,
    content: ['./src/**/*.tsx'],
  },
  theme: {
    typography: (theme) => ({}),
    extend: {},
  },
  variants: {},
  plugins: [require('@tailwindcss/typography')],
}

These options require purge to be an object instead of an array. We set enabled: true and content: ['./src/**/*.tsx'] which is the same array as we had previously set purge to.

Purging CSS means that TailwindCSS tries it best to analyze the source that you've pointed to in content and not remove any CSS classes that you've used.

You can test it now by running the following commands:

yarn build
yarn start

Controlling the Purge

If all is well, your app should function as expected. If toggling dark mode doesn't work or appear to do anything, it could mean that the dark CSS class variants have been stripped from your application because the dark class isn't assigned to a className by default.

In this example, that doesn't appear to be happened, but if you encounter this in your application where it works in development, but not in production you might need to add a safelist property to your tailwind.config.js purge options:

module.exports = {
  darkMode: 'class',
  purge: {
    enabled: true,
    content: ['./src/**/*.tsx'],
    options: {
      safelist: ['dark'], //specific classes
    },
  },
  theme: {
    typography: (theme) => ({}),
    extend: {},
  },
  variants: {},
  plugins: [require('@tailwindcss/typography')],
}

The safelist allows you to specify classes that TailwindCSS will always keep around for you and not purge. At the time of this writing the only documentation for this is buried in some Github issue comments.

Dark Mode for TailwindCSS Typography Prose Classes

By default TailwindCSS Typography doesn't support dark mode. Prose classes are also notoriously challenging to customize. You can't just set a className instead you need to override defaults in your tailwind.config.js:

module.exports = {
  //...
  theme: {
    extend: {
      typography: (theme) => ({
        dark: {
          css: {
            color: 'white',
          },
        },
      }),
    },
  },
  //...
}

In the theme section of the config you a typography property under extend which allows us to extend the @tailwindcss/typography plugin. The configuration property takes a function that passes in the theme and returns an object that extends the theme for that plugin.

It makes me a little dizzy to think about, but the extension we return adds a dark property with a css property that sets color: 'white'

Now, in /src/layouts/index.tsx on line 28 you'll find the prose class being applied to a div. This file is the default layout that mdx files use in your application.

<div className="prose md:prose-xl max-w-screen-md">
  {title && <h1 className="text-xl leading-tight">{title}</h1>}
  {children}
</div>

Now add dark:prose-dark and dark:md:prose-xl-dark to the className of the div:

<div className="prose md:prose-xl dark:prose-dark dark:md:prose-xl-dark">
  {title && <h1 className="text-xl leading-tight">{title}</h1>}
  {children}
</div>

Refresh...

Nothing happens. No changes. There's another step in the tailwind.config.js in the variants config add typography: ['dark']:

module.exports = {
  darkMode: 'class',
  purge: {
    enabled: true,
    content: ['./src/**/*.tsx'],
    options: {
      safelist: ['dark'], //specific classes
    },
  },
  theme: {
    typography: (theme) => ({}),
    extend: {
      typography: (theme) => ({
        dark: {
          css: {
            color: 'white',
          },
        },
      }),
    },
  },
  variants: {
    typography: ['dark'],
  },
  plugins: [require('@tailwindcss/typography')],
}

Voíla! You should see the body text of http://localhost:3000/hi become white as configured.

There are a lot of options for customizing the look and feel of your markdown. If you want some inspiration, Lee Rob has done a wonderful job for his personal site and you can check out the config here.

Summary

Users want dark mode and to set it up with TailwindCSS and Next.js it requires some configuration and basic state management. What you've done so far is just a start, and there is a lot of room to expand on the styles to make your application shine.

If you'd like to look more closely at a larger scale full-featured application (the one you are looking at right now in fact), you can checkout the repository for the egghead website on Github.

Here's the end state of the project you've been working on in this article on Github as well.

If you've got any questions, please ask them on Twitter!

There's also an edit link below if you'd like to send any corrections or updates directly ⭐️

🆓 Configuration based reactive Angular Forms with ngx-formly

Joel Hooks 🌩 — Mon, 06 Jan 2020 21:56:23 +0000

Juri Strumpflohner released this excellent 78 minute collection of 20 (free)lessons covering ngx-formly to create robust manageable forms in Angular.

click here to check it out

Angular is particularly popular at large enterprises. Most of the time those line of business apps are very data-driven and forms heavy. While Angular gives us two different approaches to implementing forms, neither of them is very satisfying, nor do they help keep the maintainability high especially in large enterprise apps.

In this course we're going to learn about ngx-formly, a library that helps cope with some of the mentioned issues. With Formly you define the form structure once in your component code and the HTML will be taken care of by the library. This helps reduce maintainability and moreover Formly has some nice reactive features built-in that help you reduce your form code even more.

Ship Accessible [React] Apps

Joel Hooks 🌩 — Tue, 17 Dec 2019 19:01:30 +0000

Assuming for a moment that you can see...

Have you ever blindfolded yourself and tried to use your computer or phone?

When was the last time you navigated your current project with a screen reader?

Maybe that's somebody else's problem?

🙄

A large number of people with impairments or disabilities are unable to use the web effectively.

This is not their fault.

It's unacceptable to ignore this fact.

As web developers, we have a responsibility to try harder. To do more. To learn what it takes to make our applications as accessible as possible.

This means we need to understand the modern tools and techniques to make this happen and deliver a consistent user experience to as many folks as possible.

Listen, we're not here to lecture you, but as a society, we have to come together.

This isn't about wagging our fingers or posturing for internet points.

Accessibility matters!

Humans with disabilities have a right to access the same wealth of knowledge and utility the internet provides able-bodied folks.

We have a responsibility to do the right thing and take a stand for accessible web applications.

None of us are perfect, but we can choose to do better.

Erin Doyle is an expert in creating accessible React applications and has put together a course for you that presents a concrete process to test and develop with accessibility in mind.

After watching her new course, you’ll be prepared to audit and fix issues in your existing apps and have a better understanding of how to approach development from the perspective of your users.

Even if you aren't building React apps right now, these concepts carry over and the course is an exploration of common patterns and solutions for accessible modern web applications

-> Building Accessible React Apps (this course is egghead members only, but the first couple of lessons are free to view)

Erin and I also recorded a podcast on this subject!

How to get invited to teach on egghead.

Joel Hooks 🌩 — Fri, 13 Dec 2019 22:55:07 +0000

At egghead, we would love to be able to work with everybody and take the time and care that is required to craft world-class educational materials with as many folks as possible.

Unfortunately, we can't.

The good news? We've got some suggestions on how you can start building the skills needed to get invited as an egghead instructor and generally improve your own career generally in the process.

You don't need our permission to create screencasts.

This is important to understand. egghead is a platform. We curate learning content for professional web developers. egghead is a small team focused on quality learning materials.

You don't need us.

You can start today. You can use this guide to understand some of what goes into making screencasts for egghead and just freaking do it.

Please share what you make with us and the rest of the world, and keep it up.

That's how you get noticed. Doing and creating.

Teaching everything you know. ❤️

It can be challenging and intimidating to learn in public, particularly if you are just starting out.

Writing is a skill.

Presenting screencasts is a skill.

Hosting a live stream is a skill.

It takes consistent focused practice to get good at these skills, just like web development itself. The good news is that they are related and make powerful levers for your career and personal growth.

They can all be practiced in parallel with your continued growth as a professional developer and showcase your ability to communicate effectively and a willingness to share with others that ultimately has the potential to set you apart from others that aren't willing to put in the same level of effort.

Write about what you are learning right now

Keep a learning journal! Post publically, preferably on your own domain, but dev.to is fantastic too.

You don't have to post 5000-word technical tutorials.

Keep it simple and informative. Provide context and links. Write for yourself. Pick a friend or colleague and write for them. It's often easier to "just f'n do it" if you have a specific individual you are writing for.

Give it a try!

Practice sharing what you know and what you learn. It's a habit. A skill.

Share what you write on Twitter!!

Creating Screencasts

We maintain an egghead instructor guide that details our process for creating content at egghead.

In the guide, we talk about the technical and content development aspects for producing high-quality screencasts for web developers. You can safely ignore the fancy equipment we recommend. We have to have consistent audio quality across thousands of screencasts so the gear is meant to help ensure that for our paying members.

We think Screenflow is fantastic on the Mac and Camtasia is great for Windows.

Follow the guide. Share what you know. Post it on twitter. Share here.

Start live streaming your learning.

Live streaming is incredibly powerful and rewarding

Live streaming is also intimidating to get started!

Some of the technical details are related to screencasting with some significant differences.

This guide from Suz Hinton is great.

Chris Biscardi has also started a community for folks that are creating live stream content:

:party-corgi:

@chrisbiscardi

discord.gg/kagheT

The community is heavily focused on supporting each other to start streaming code (or design), writing blog posts, and talking shop about consulting and product businesses.

We include people that write about GraphQL, Docker, K8s, Gatsby, Vue, and more.

03:56 AM - 01 Dec 2019

0 14

What else?

These are difficult skills to master, but worth the effort to hone. They are superpowers. Learning in public benefits your career and paves the way for others. It's a way to actively participate in a community you help to build.

🌱 My blog is a digital garden, not a blog

Joel Hooks 🌩 — Fri, 13 Dec 2019 21:26:20 +0000

Organizing information is hard. I'm not a taxonomist. I don't have an information design background. For the most part, I just wing it ad hoc and hope for the best. We are constantly bombarded with information, a lot of it is really good information too, but the challenge is absorbing it and applying it to the context of our lives and careers.

Recently I revamped my blog to use Gatsby, and in doing so I went with the "traditional" blog style website. A linear newest-first sorted chronologically oriented list of posts.

And I think it f'n sucks.

The blog is fine, and I love Gatsby, what I don't like is how it's presented and formatted.

Seriously, who cares when anything on my site got posted. For the vast majority of things, I'm writing it makes absolutely no difference what-so-ever.

Using this newest-first approach makes the site impenetrable and less useful for me and especially for anybody that might be visiting to learn or research.

There are two articles that really got me thinking about this lately. The first is from Amy Hoy. How the Blog Broke the Web, which is a direct discussion of this idea of sorting posts by dates and how it effectively ruined the best parts of the internet. We've moved away from handcrafted home pages that required us to curate and present our best content in the best light.

The second article is from Tom Critchlow titled Building a Digital Garden. What I really like about Tom's piece is his discussion of the idea of "non-performative blogging" in your personal space on the web.

I love this idea. Instead of "content marketing" we can use our websites to get back to what made the web awesome while also creating better resources for ourselves and our users.

Right now I'm very inspired by both of these pieces, and I'm considering how it affects the way I approach my little slice of the web at https://joelhooks.com. It is a blog, sure, but it is also a wiki. It's a spot where I can post ideas, snippets, resources, thoughts, collections, and other bits and pieces that I find interesting and useful. Instead of always being a "performance" level of blogging, it can be a looser more human endeavor that drops the idea of robots sorting the content (in this case simply by date created) and embraces the idea of curation, by me, for you.

It's very exciting, and I look forward to exploring this idea more.

First up for me is adding my reading notes to the site. One of my favorite books of all time is Badass: Making Users Awesome by Kathy Sierra. It's been one of the major influencers for me in terms of how we run egghead.io and is one of the best books on education that I've ever read. When it was published, I read through it, but now I am going back and re-reading it with a highlighter in hand for a deeper understanding.

Check it out, and let me know what you think.

React Suspense w/ concurrent mode is not for everybody (yet)

Joel Hooks 🌩 — Fri, 13 Dec 2019 19:54:28 +0000

The way we write web applications is changing.

React is at the forefront of many of the changes.

The React team takes great care in testing, communicating, and delivering these changes to us incrementally over time.

They aren't sensationalist or prone to excessive enthusiasm.

They are a small and talented team, mostly heads down working on a UI framework that Facebook's 2.3 BILLION monthly active users rely on to browse their feeds and communicate with friends, family, clubs, businesses, fans, and any other human also on Facebook.

Not to mention the rest of us that benefit from React as an open-source project.

Hopefully, we can all appreciate that challenge of scale, and at egghead, we have a lot of respect for the work they are doing.

As happy React developers ourselves, we are grateful. 🙏

Recently the React team has been showing us how Suspense and concurrent mode will work in our production applications. The experimental implementations are accessible through and experimental build of React.

In the docs introducing concurrent mode, you'll find a bright red warning to tread carefully into the deep waters ahead:

On Twitter, they've warned us repeatedly that under no circumstances should you use concurrent mode in a production app. If you are new to React, you don't even need to worry about concurrent mode at all.

It's extremely good advice that I will most certainly follow.

Here's who might consider learning more about concurrent mode with Suspense in React is for right now:

library authors - the primary target of these APIs that will eventually provide abstractions on top of the low-level core building blocks of Suspense and concurrent mode that will blow our minds
early adopters - folks that ride the bleeding edge and want to understand what's coming on the horizon, decision-makers, and senior-level developers evaluating tools with a long-term strategy in mind
curious developers - folks that think this stuff is fun and love to tinker and aren't exactly happy with just using tools as "black boxes" with little understanding of what's going on under the hood.
you, probably - here's the thing, watching this excellent course I'm about to tell you about will just give you some insight into a cool new way to think about React and web application development in general. It's fine 😂

Are you a responsible developer that won't unleash the kraken 🦑 on unsuspecting production users and clients?

Can we trust you with this knowledge about Suspense w/ concurrent mode in React??! 🤠

Then this course from Michael Chan is going to be a real treat!

As host of The React Podcast, Michael has been keeping an eye on Suspense w/ concurrent mode for a long time.

In this new egghead course, Michael guides you through building a full app with Suspense w/ concurrent mode, Hooks, and Context.

Like Hooks and Context, Suspense w/ concurrent mode is changing the way we approach building with web applications with React.

Tread carefully. React responsibly.

This is a good course!

-> Click here to Build an App with React Suspense (this course is requires a membership to watch completely, but the first couple of lessons are unlocked and free to watch)

Transforming exported CSV data for use in a React chart.

Joel Hooks 🌩 — Sat, 09 Feb 2019 04:58:16 +0000

There are many ways to build a new feature for your applications. For me, when I need a new tool, component, or functionality I like to take a step back and think about it in terms of data. What data do I have, what data do I need, and how am I going to present and interact with the data.

At egghead, we are constantly working to improve our processes and the content that the creators we work are producing. One of the key performance indicators (KPI) we can look at to better understand how content is being consumed is dropoff rates.

When somebody sits down to watch a course they start lesson one. Sometimes they don't even finish the first lesson, sometimes they finish all the lessons, and then of course people stop at various points in between.

In a perfect world, most folks that start will also finish. We live in reality though, and as we start to seriously consider various aspects of our core format, we need to also consider how we will understand and prove that our improvement efforts are getting real results.

Otherwise you're just changing shit.

We track lesson views. We do this so we can persist progress for folks using the site, as well as part of our royalty payment system for our badass content creators. While all the data that we need to calculate dropoff rates is there in the database, it isn't presented in that format anywhere in our application.

We've got some options at this point:

add api endpoints, data model changes, and UI to our existing rails app
export some data and put together a lightweight presentation

I strongly prefer getting the data and working in a lightweight environment like codesandbox.io

It's faster and more disposable so I can iterate and explore solutions quickly. There's no build to deal with. Nothing needs to load over the wire. It's easy to share and collaborate.

Basically, it's great!

To get data out of our Rails application I have access to a gem called Blazer. It's an incredibly handy tool. You give it some SQL, define any variables, and it performs the query. You can look at the data in the browser, or download it as a comma-separated variable (CSV) file.

I grabbed the CSV.

My data has all the aspects I need. Each of the lesson videos that belongs to a "series" (course) is output with its position in the series, how many starts it has had, and how many completions.

The format is cumbersome though, so I am going to transform it with a node script.

This process is very similar to what I did in this post

Here's the full script, check it out and then I'll go through each section and explain what's happening:

const _ = require('lodash')
const fs = require('fs')
const csv = require('csv-parser')
var reduce = require('stream-reduce')

const csvFilePath = './series-drop.csv'

fs.createReadStream(csvFilePath)
  .pipe(csv())
  .pipe(
    reduce((acc, row) => {
      const series = _.find(acc, { title: row.series }) || {
        lessons: [],
        totalStarts: 0,
        totalCompletions: 0,
      }
      const filtered = _.filter(acc, series => series.title !== row.series)

      return [
        ...filtered,
        {
          title: row.series,
          totalStarts: series.totalStarts + parseInt(row.starts, 10),
          totalCompletions:
            series.totalCompletions + parseInt(row.completions, 10),
          lessons: _.sortBy(
            [
              ...series.lessons,
              {
                title: row.lesson,
                starts: row.starts,
                completions: row.completions,
                position: row.position,
              },
            ],
            'position',
          ),
        },
      ]
    }, []),
  )
  .on('data', function(dropoffData) {
    fs.writeFile(
      'series_dropoff.json',
      JSON.stringify(dropoffData),
      'utf8',
      () => {
        console.log('done')
      },
    )
  })

Up top we have some imports.

lodash: I love this library quite a lot and use it in every project. It provides an infinitly useful set of tools for dealing with objects and collections ❤️
fs: this is part of the node standard library and is used for dealing with the file system. We are going to be loading a CSV and saving a json file, so it is required.
csv-parser: this is a stream based library for consuming CSV data and converting it to JavaScript objects for each row/line of the CSV.
stream-reduce: this is a reduce function for streams. Because I need to transform data from one "shape" to another, reduce is the tool I reach for.

To kick the script off the first step is to load the data:

const csvFilePath = './series-drop.csv'

fs.createReadStream(csvFilePath)

We use fs to createReadStream which streams the data from the file on disk into our application.

.pipe(csv())

Streams allow us to chain together steps. In the next step we pipe the data stream into csv() which converts the binary data stream into rows. The csv-parser library is powerful and can do more interesting things, but luckily for us we don't need to do anything interesting so we can just call csv() and have what we need.

.pipe(
  reduce((acc, row) => {
    //we'll look at this part later...
  }, []),

We are calling pipe again, and this time we are piping the result of the previous step that converts our file on disk into JavaScript data objects into a reduce function. If you aren't familiar with reduce, or want to dig a bit deeper, I highly recommend mykola bilokonsky's awesome egghead course on the topic!

The reduce function takes two arguments.

the reducer function. This function also takes two arguments. The accumulator and the current item. Reducers typically work on collections or objects. Things that can be iterated on. It's similar to a forEach or map, but the accumulator is what makes the reducer interesting.
The second argument is the starting state of the accumulator. In our case we want to reduce all of the rows in our CSV file into an array of javascript objects that each represent a course so this second argument is a []

reduce((acc, row) => {
  const series = _.find(acc, {title: row.series}) || {
    lessons: [],
    totalStarts: 0,
    totalCompletions: 0,
  }
  const filtered = _.filter(acc, series => series.title !== row.series)

Inside of our reducer we want to take the current row and add the lesson data to the series object. We use _.find(acc, {title: row.series}) to see if the accumulator already has an object for this series. If it doesn't we create an object to work with and assign it sensible defaults.

We also create another array that filters out the existing series object so that we don't end up with doubles.

return [
  ...filtered,
  {
    title: row.series,
    totalStarts: series.totalStarts + parseInt(row.starts, 10),
    totalCompletions: series.totalCompletions + parseInt(row.completions, 10),
    lessons: _.sortBy(
      [
        ...series.lessons,
        {
          title: row.lesson,
          starts: row.starts,
          completions: row.completions,
          position: row.position,
        },
      ],
      'position',
    ),
  },
]

Our reducer function returns a new array that becomes the acc accumulator for the next row.

We spread the filtered array ...filtered so that all of the items in that array are in our new array. Then we add a new object that represents the current row series into the array.

Notice we didn't mutate any data. We built a new array to return as our new accumulator.

{
  title: row.series,
  totalStarts: series.totalStarts + parseInt(row.starts, 10),
  totalCompletions:
    series.totalCompletions + parseInt(row.completions, 10),
  lessons: _.sortBy(
    [
      ...series.lessons,
      {
        title: row.lesson,
        starts: row.starts,
        completions: row.completions,
        position: row.position,
      },
    ],
    'position',
  ),
}

This is the new (or updated) series object. It sets the title, adds the current row's starts and completions to the previous count (we set it to 0 if it's a newly accumulated series), and finally we add the lessons.

lessons: _.sortBy(
  [
    ...series.lessons,
    {
      title: row.lesson,
      starts: row.starts,
      completions: row.completions,
      position: row.position,
    },
  ],
  'position',
)

The lessons get added with sortBy from lodash, which sorts an array based on the second argument. In this case we just pass the string 'position' which tells lodash to sort on the position property of the objects in the array.

Inside of sortBy we use ...series.lessons to spread any existing lessons in the accumulated series back into the new series object. Then we can add the data from the current row as a new lesson into the accumulated series object.

This part gets a little weird if you aren't used to reducers and (re)building objects using the ... spread operator, but it's worth practicing and thinking about because it is a very useful tool. If you'd like a really great explaination of this, I highly recommend this egghead video from Dan Abramov.

To get a clearer picture of what just happened, we have reduced/transformed this csv data:

add-internationalization-i18n-to-a-react-app-using-react-intl,react-install-and-configure-the-entry-point-of-react-intl,-5,530,428
add-internationalization-i18n-to-a-react-app-using-react-intl,react-convert-a-hard-coded-string-using-react-intl-formattedmessage,4194299,498,370
add-internationalization-i18n-to-a-react-app-using-react-intl,react-render-content-with-placeholders-using-react-intl-formattedmessage,6291451,305,233
add-internationalization-i18n-to-a-react-app-using-react-intl,react-render-content-with-markup-using-react-intl-formattedhtmlmessage,7340027,259,234
add-internationalization-i18n-to-a-react-app-using-react-intl,react-format-date-and-time-using-react-intl-formatteddate-and-formattedtime,7864315,244,210
add-internationalization-i18n-to-a-react-app-using-react-intl,react-format-a-date-relative-to-the-current-date-using-react-intl-formattedrelative,8388602,201,192
add-internationalization-i18n-to-a-react-app-using-react-intl,react-format-numbers-with-separators-and-currency-symbols-using-react-intl-formattednumber,8388603,216,197
add-internationalization-i18n-to-a-react-app-using-react-intl,react-render-content-based-on-a-number-using-react-intl-formattedmessage,8388604,203,174
add-internationalization-i18n-to-a-react-app-using-react-intl,react-use-a-react-intl-higher-order-component-to-format-messages-and-get-current-locale,8388605,251,199
add-internationalization-i18n-to-a-react-app-using-react-intl,react-write-tests-for-react-intl-output-using-enzyme-and-jest,8388606,242,144
add-internationalization-i18n-to-a-react-app-using-react-intl,react-use-webpack-to-conditionally-include-an-intl-polyfill-for-older-browsers,8388607,187,154

Into a nicely structured JS object like this:

[{
  "title": "add-internationalization-i18n-to-a-react-app-using-react-intl",
  "totalStarts": 3136,
  "totalCompletions": 2535,
  "lessons": [
    {
      "title": "react-install-and-configure-the-entry-point-of-react-intl",
      "starts": "530",
      "completions": "428",
      "position": "-5"
    },
    {
      "title": "react-convert-a-hard-coded-string-using-react-intl-formattedmessage",
      "starts": "498",
      "completions": "370",
      "position": "4194299"
    },
    {
      "title": "react-render-content-with-placeholders-using-react-intl-formattedmessage",
      "starts": "305",
      "completions": "233",
      "position": "6291451"
    },
    {
      "title": "react-render-content-with-markup-using-react-intl-formattedhtmlmessage",
      "starts": "259",
      "completions": "234",
      "position": "7340027"
    },
    {
      "title": "react-format-date-and-time-using-react-intl-formatteddate-and-formattedtime",
      "starts": "244",
      "completions": "210",
      "position": "7864315"
    },
    {
      "title": "react-format-a-date-relative-to-the-current-date-using-react-intl-formattedrelative",
      "starts": "201",
      "completions": "192",
      "position": "8388602"
    },
    {
      "title": "react-format-numbers-with-separators-and-currency-symbols-using-react-intl-formattednumber",
      "starts": "216",
      "completions": "197",
      "position": "8388603"
    },
    {
      "title": "react-render-content-based-on-a-number-using-react-intl-formattedmessage",
      "starts": "203",
      "completions": "174",
      "position": "8388604"
    },
    {
      "title": "react-use-a-react-intl-higher-order-component-to-format-messages-and-get-current-locale",
      "starts": "251",
      "completions": "199",
      "position": "8388605"
    },
    {
      "title": "react-write-tests-for-react-intl-output-using-enzyme-and-jest",
      "starts": "242",
      "completions": "144",
      "position": "8388606"
    },
    {
      "title": "react-use-webpack-to-conditionally-include-an-intl-polyfill-for-older-browsers",
      "starts": "187",
      "completions": "154",
      "position": "8388607"
    }
  ]
},
...
]

All that's left is to write it out to a file so we can use it elsewhere:

.on('data', function(dropoffData) {
  fs.writeFile(
    'series_dropoff.json',
    JSON.stringify(dropoffData),
    'utf8',
    () => {
      console.log('done')
    },
  )
})

Streams can listen for standard events. In this case we are listening for data which is ommitted by stream-reducer when it is done. We can then use fs.writeFile to write out our reduced array of series objects to disk!

Armed with well formated data it was a lot easier to open up codesandbox and start playing with it. I ended up choosing react-charts and a bargraph.

Feel free to explore the codesandbox to see how the data gets used to create a chart.

If you'd like to watch me stumble around and figure this all out in realtime, today's your lucky day. I recorded it all and posted it to this playlist. 🙂

A handy npm script for creating a new Gatsby blog post

Joel Hooks 🌩 — Thu, 31 Jan 2019 01:10:14 +0000

My blog is built with Gatsby and uses MDX for the post content. It's a great setup, and so far I've enjoyed using it very much.

One thing I missed from my old Octopress/Jekyll configuration was the ability to run a rake task to create a new post with all of the basic required frontmatter metadata filled in.

---
slug: a-handy-npm-script-for-creating-a-new-gatsby-blog-post~M3MyBb6Fd
guid: M3MyBb6Fd
date: 2019-01-30
title: 'A handy npm script for creating a new Gatsby blog post'
published: false
---

Here's an example of markdown meta for this post. Gatsby uses this frontmatter when it builds the site to create the appropriate corresponding pages.

It was kind of a pain in the ass to manually type it out every time, so I decided to solve my frustration via the power of code.

$ npm run newPost "This is the title of my blogpost"

This is the basic structure of the command I want to be able to run from the terminal command line. Once this is executed, a new folder should be created and named appropriately. Inside the folder will be an index.mdx file that has all of its basic/required frontmatter inside and all that I need to do is hop in and write the post.

/content
  - blog
    -- 2019-01-30-a-handy-npm-script-for-creating-a-new-gatsby-blog-post
      --- index.mdx

This is the result for my setup after running the script.

So let's take a look at how I built it by first looking at what needs to happen.

execute a node script with arguments
parse the arguments
extract the title
"slugify" the title for use in filenames and the url
capture the current date
write the file to disk

I made a sub-folder called scripts and created newPost.js inside.

To get the command line arguments we need to access process.argv in node. The contents of newPost.js look like this:

console.log(process.argv)

Now we can take a look at what process.argv contains by running the following command:

node ./scripts/newPost.js "this is my test post"

Assuming there are no errors, the output is an array looks like this:

;[
  '/Users/joel/.nodenv/versions/10.6.0/bin/node',
  '/Users/joel/Code/joelhooks-com/test.js',
  'this is my test post',
]

The contents of process.argv is an array that contains the location of the node executable that is being used, the location of the script being executed, and finally the argument that we passed in.

We can try again with some more arguments:

node ./scripts/newPost.js "this is my test post" 1 "gopher"

And you'll see that it simply adds to the array:

;[
  '/Users/joel/.nodenv/versions/10.6.0/bin/node',
  '/Users/joel/Code/joelhooks-com/test.js',
  'this is my test post',
  '1',
  'gopher',
]

We want to make sure that we actually have an name to work with, so I'm going to check and make sure with a simple if/else guard in my script.

const title = process.argv[2]

if (!title) {
  throw 'a title is required!'
}

Try and run it now with no name argument. It should throw an error and crash out.

Now that we have a name, we want to create a "kebab case" slug. Slugs can be a little tricky to get right in all cases, so for this I'm going to use a small library. npm i slug will get me exactly what I need:

const slugify = require('slug')

const title = process.argv[2]

if (!title) {
  throw 'a title is required!'
}

console.log(slugify(title))

This outputs This-is-the-title-of-my-blogpost which is close, but typically a slug will be all lowercase, so it will look more like this:

const slugify = require('slug')

const title = process.argv[2]

if (!title) {
  throw 'a title is required!'
}

const slug = slugify(title.toLowerCase())

For sorting purposes I also like to add the date to the post's folder name. My goto is the tiny date-fns library that provides most of the date/time utility that you'll ever need in a tiny package with npm i date-fns and using it as so:

const slugify = require('slug')
const dateFns = require('date-fns')

const title = process.argv[2]

if (!title) {
  throw 'a title is required!'
}

const slug = slugify(title.toLowerCase())
const date = dateFns.format(new Date(), 'YYYY-MM-DD')

You could manually extract and format a date, but... who has time for that?? This works great, and I have all the pieces I need to assemble and output my file.

First I'm going to create the path:

const slugify = require('slug')
const dateFns = require('date-fns')

const title = process.argv[2]

if (!title) {
  throw 'a title is required!'
}

const slug = slugify(title.toLowerCase())
const date = dateFns.format(new Date(), 'YYYY-MM-DD')
const dir = `./content/blog/${date}-${slug}`

Now I can use the node fs, or file system, module to create the folder:

const fs = require('fs')
const slugify = require('slug')
const dateFns = require('date-fns')

const title = process.argv[2]

if (!title) {
  throw 'a title is required!'
}

const slug = slugify(title.toLowerCase())
const date = dateFns.format(new Date(), 'YYYY-MM-DD')
const dir = `./content/blog/${date}-${slug}`

if (!fs.existsSync(dir)) {
  fs.mkdirSync(dir)
} else {
  throw 'That post already exists!'
}

The fs module needs to be "imported" using require, and then I also added an if/else around the call to fs.mkdirSync(dir) to ensure that I wasn't going to overwrite an existing post. Better safe than sorry. Once that runs, you'll see an empty folder is created. Now we can us fs.writeFileSync to create the actual file itself:

const fs = require('fs')
const slugify = require('slug')
const dateFns = require('date-fns')

const title = process.argv[2]

if (!title) {
  throw 'a title is required!'
}

const slug = slugify(title.toLowerCase())
const date = dateFns.format(new Date(), 'YYYY-MM-DD')
const dir = `./content/blog/${date}-${slug}`

if (!fs.existsSync(dir)) {
  fs.mkdirSync(dir)
} else {
  throw 'That post already exists!'
}

fs.writeFileSync(
  `${dir}/index.mdx`,
  `---
slug: ${slug}
date: ${date}
title: "${title}"
published: false
---`,
  function(err) {
    if (err) {
      return console.log(err)
    }

    console.log(`${title} was created!`)
  },
)

fs.writeFileSync takes three arguments. The first is the path or destination, and the second is the file contents. Since this is modern node, we have access to string template literals using the backticks. This is particularly nice because they allow us to create relatively clean formatted strings that respect whitespace and don't require special linebreak characters.

The final argument is a callback function that is called when the operation is complete. If there is an error it is logged out, and we also get a friendly message if it was a success.

And with that, you now have a handy script for creating new markdown blogposts for your Gatsby app.

Since this is strictly for my personal use I didn't take any time to make the command line argument handline robust. This is a script with a very specific single task for a single user. That means it can be a little dodgy and not have any negative effects. It took about ten minutes to write, and will now save me a lot of pointless typing in th future.

More importantly it removed a bit of friction/pain from my blogging experience, which means I might actually do it more 🙂