The BHolmesDev Blog

Build a Self-Updating LLM Knowledge Base

Mon, 06 Jul 2026 12:00:00 GMT

You may have seen Andrej Karpathy talk about "LLM Wikis." They turn your unorganized thoughts into easy-to-navigate notes, wikis, or visualizations. It's an incredibly powerful tool for researchers, software developers, scattered notetakers... basically everyone. Here's the system to have agents organize your second brain automatically:

Start taking notes as markdown
Add an /enrich-note skill that instructs agents to add tags, sources, and backlinks
Add a wiki skill that compounds notes into a persistent knowledge base
Create automations that run these skills on a schedule
Add visualizations built live from your notes

Let's go set this up.

Step 1: one directory of raw markdown

We're going to take our notes as Markdown to make them easily accessible to agents. You can use Obsidian for this, or if you want a friendlier app that feels more like Apple Notes, I built one: Hubble.md.

Following Andrej Karpathy's recommendation, we'll put all of our handwritten (or voice-transcribed) notes in a raw/ directory. These files are raw, unfiltered thoughts, for our agents to work with.

raw/
├── rick-rubin-s-philosophy-of-simplicity.md
├── nvidia-blackwell-architecture.md
├── insights-from-sell-like-steve-jobs.md
└── acquired-pod-ferrari.md

Here's a sample I rambled out using a voice transcription tool after listening to Acquired's Ferrari episode:

# Ferrari (Acquired)

It was super interesting how they described Ferrari as a brand, where
it's both a combination of a luxury brand, like a Hermes or a Gucci,
but also a sports team, which explains why they can put their logo on
everything down to an Acer laptop...

Note there's no metadata and no backlinks. Honestly, you don't even need the header. The agent will handle those details for you.

Step 2: the /enrich-note skill

Let's have agents enrich these notes with details for easy retrieval. I wrote the /enrich-note skill to do this. You can grab it (and every other skill in this post) with one command:

npx skills add bholmesdev/llm-knowledge-base-skills

The skill does three things:

1. Tags: The skill maintains a shared tag registry as a tags.md file listing every tag with a one-line description. I suggest tags relating to the medium of the source (blog, podcast, video) and others relating to topics / areas of interest (ai-hardware, business, rust). The agent is also told to reuse existing tags and be reluctant to coin new ones. Otherwise, I've found agents invent tags too liberally.

2. Sources: If the note came from somewhere (a podcast, a book, a video) the agent does some web research to find the source URL and records it in frontmatter.

3. Related notes: The agent greps the rest of the vault for genuinely related notes and adds them as wikilinks in a ## Related section. This can be an expensive operation, but no more expensive than asking an agent to complete a coding task in a small-to-medium-sized codebase. I personally have hundreds of notes. If you test this on a larger corpus let me know what you've learned or optimizations you've found.

After a pass, that Acquired podcast note on Ferrari looks like this:

---
tags: [podcast, business, branding]
source: "Acquired podcast — \"Ferrari\""
url: "https://www.acquired.fm/episodes/ferrari"
enrichedAt: "2026-06-27T23:40:26Z"
---
# Ferrari (Acquired)

...

## Related

- [[raw/walt-disney.md|Walt Disney on Acquired]]

Note the enrichedAt stamp. That's how an automation knows which notes have been enriched in the past. Idempotency matters when we start running this skill on a schedule.

Step 3: the wiki skill

Enriched notes are searchable, but they're still fragments. The next layer up is a wiki: a persistent, interlinked knowledge base that an agent builds from your notes.

This comes directly from Karpathy's llm-wiki gist, which I'd recommend reading in full. The core idea: have an agent generate a frontpage around an area of interest (in my case, coding agent tips or religious studies) that is easy-to-navigate.

This is useful for you since it creates an easy-to-scan index of people, places, and things. But it's also useful for agents to navigate whenever you ask questions relating to your notes. Instead of RAG-style retrieval where the LLM rediscovers your knowledge from scratch on every question, the agent maintains a compounding artifact: entity pages, topic syntheses, an index, a log. As Andrej puts it: "the LLM is the programmer; the wiki is the codebase."

To get started, paste the gist into your agent and add a sentence about what you want. Something like:

Read this: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f. Set up a wiki in wikis/latest-ai/ that tracks coding agent tips from my notes - model prompting, orchestration patterns, useful agent skills, etc. Seed it from anything relevant in raw/.

The agent scaffolds the directory, writes its own AGENTS.md schema with wiki maintenance instructions, and ingests your existing notes.

From then on, I wrote a skill to "refresh" that wiki over time: /refresh-wiki. This looks for new or changed notes in raw/, ingests the relevant ones into each wiki, updates entity and concept pages, and runs a lint pass for contradictions, orphan pages, and stale claims.

Here's a trimmed view of the index.md for my "Latest in AI" wiki. This was built from podcast and video notes I've taken over the past few months, and every entry links to a full page the agent writes and maintains:

# Index — Latest in AI wiki

## Sources (20)

- [[nvidia-blackwell|NVIDIA Blackwell Architecture]] — Gavin Baker note on GB200/B200, token efficiency, and the shift from raw intelligence to usefulness.
- [[ralph-loops|Ralph Loops in Claude Code]] — Theo note on wrapping Claude Code in external scripts for REPL-like loops.
- [[ai-music-production|The Impact of AI on Music Production]] — Adam Neely/Suno note about curation vs. creation.
...

## Concepts (16)

- [[agent-loops|Agent Loops]]
- [[software-factories|Software Factories]]
- [[inference-economics|Inference Economics]]
...

## People (8)

- [[boris-cherny|Boris Cherny]] — Creator of Claude Code; cited as saying his work has shifted from prompting Claude to writing loops.
- [[andrew-wilkinson|Andrew Wilkinson]] — Quoted on Claude Code helping him move at the speed of his ADHD.
...

I also keep a wiki for my Bible study through Lee Strobel's The Case for Christ. The book is a long series of expert interviews, so the agent built out a "people" index with a page for every interviewee: who they are, and what they argued. I've found this super helpful for revisiting arguments weeks later, since names tend to blend together for me without a glossary:

## People (18)

- [[lee-strobel]] — author/journalist; the investigator and convert.
- [[craig-blomberg]] — New Testament scholar; gospel reliability & early dating.
- [[alexander-metherell]] — physician; the medical reality of the crucifixion.
- [[william-lane-craig]] — apologist; the empty tomb & the God hypothesis.
- [[gary-collins]] — psychologist; the mental health of Jesus.
...

Step 4: automations

These skills are useful, but I'd rather not re-run these every time I go to browse my notes or ask an agent a question. Both skills have loop variants designed to run on a schedule:

/enrich-notes-loop wraps /enrich-note and walks every note you've taken recently, using enrichedAt to ignore previously crawled entries.
/refresh-wiki walks through your wikis/ directory and updates every wiki it finds. (You'll want your wikis in a wikis/ directory. You can tweak all of this to taste.)

There are two options I'd suggest trying: local automations to get started, and cloud automations to make the workflow durable.

Local Automations with Codex

You can schedule these in a few ways. One is a local automation that runs on your computer, waking up to organize the notes folder on a cron. The Codex app offers this from the Scheduled tab:

From here, click "Create with chat," select the directory where your notes live, and specify the skill to run. I suggest scheduling to run daily on an overnight schedule. I also suggest a lower reasoning level for /enrich-notes-loop since it's a less ambiguous skill. For wiki generation, a higher reasoning level may let the model be more thoughtful / creative. Tweak to taste.

Cloud Automations

While local automations are the easiest way to get started, they do have a pretty obvious drawback: your computer will need to be awake and running for the task to execute. Codex in particular did ensure that scheduled jobs run even when a laptop lid is closed. Still, I noticed when I went out of town for a few days that my automations stopped running since I forgot to plug in my laptop... 🤦‍♂️

Given that, I'd suggest trying cloud runners. Here's a setup guide with the tools I use:

oz.dev to create a cloud sandbox connected to open-weight models
Obsidian Sync to sync markdown notes to the cloud
Obsidian's headless CLI to access those notes programmatically from a cloud sandbox

Oz is Warp's cloud hosting platform for agents. It charges mostly at token cost, yes. But open-weight models like Kimi k2.6 are highly token efficient (3-4x fewer tokens than Claude's models) and high quality.

Here's the flow each scheduled run follows:

The agent uses the Obsidian CLI to pull the vault down into the cloud sandbox
It runs /enrich-notes-loop or /refresh-wiki
It pushes the results back up, which sync down to your machine

I wrote two more skills to run these with the necessary cloud sandbox setup: /enrich-notes-loop-cloud and /refresh-wiki-cloud. They're thin wrappers that sync the vault down, run the base skill, and sync back up.

The environment and schedule setup is a handful of oz CLI commands, so I encoded that as a skill too: /setup-oz-automations. First, make an account: go to oz.dev and click "start an agent." That takes you through login, where you can create an account. Then install the skills (if you haven't already) and hand the rest to your agent:

npx skills add bholmesdev/llm-knowledge-base-skills

Run the /setup-oz-automations skill

The skill checks for Warp's Oz platform skill (installing it with npx skills add warpdotdev/oz-agent-skill if it's missing), asks for your vault name and Obsidian auth token, then creates the environment and both schedules: nightly note enrichment, weekly wiki refresh. You can pause a schedule anytime with oz schedule pause, and every run leaves a session transcript you can review from the Oz dashboard.

Step 5: visualizations

Alright, now we have beautiful webs of markdown with tags, backlinks, index pages, and deep wikis to explore. But what if we go beyond text?

Since everything is markdown files in a directory, an agent can build interactive visualizations on top of them using HTML. I've built a few examples you can plug into your setup, assuming you have your notes in a raw/ directory:

Notes burndown: a GitHub-style activity graph of your note-taking over time. I'm using it to build a consistent journalling habit.

Thought constellation: display notes as a graph clustered by your most-used tags (a payoff of /enrich-note). It helped me find my most referenced notes for a second read, and figure out gaps where I should focus next (clearly I need to read more...)

You can build these as one-off visualizations updated on a schedule, similar to our /enrich-note and wiki examples. But if you want these to live-update by reading files from disk, you can view these visualizations within Hubble.md. This is the markdown notes app I mentioned earlier. This lets you view HTML apps alongside your notes, and injects runtime APIs to read files in the current directory to build visuals that update programmatically.

Go write things down!

All the skills and visualizations are in this GitHub repo. To start, just ask your agent to convert your existing notes into Markdown (Apple Notes, Notion, Granola, etc. all support this). Then try some of the skills I shared here to see if they help you. Build a wiki around your next research project, side hobby, or agentic coding session. Invent a new visualization and share it here. I'm curious what you come up with!

Also, give Hubble.md a try. It's free and open-source :)

Hubble Note

Mon, 22 Sep 2025 02:21:57 GMT

So... I'm building a notes app. And it's called Hubble Note.

What is it?

Hubble Note helps you remember everything you wrote down. It combines your notes, your chats, and your web browsing into a single tool, backed by a smart little assistant called Hubble. It's as simple as Apple Notes, but as powerful as Notion or Obsidian, without the learning curve.

Why Hubble?

Apple Notes is awesome. You open it up, write something down, and close it when you’re done. It’s the default writing tool for pretty much everyone because of how dead simple it is.

And yet... you can’t find anything you wrote down. It’s a junk drawer where everything useful gets thrown and forgotten forever.

Except, unlike a junk drawer, some of your most important and valuable things get thrown in there. That Thai curry recipe your friend sent you a year ago that would be perfect for the house party this weekend. That incredible YouTube lecture you pasted in your notes that would really help for this job interview coming up. Those years of weeknight writing sessions you’d love to catalog into one big list. But if you want to do any of these things, you’re handed tools straight out of 1995: a dumb search engine, and a chronological history. GLHF.

Why can’t there be an Apple Notes wizard to clean everything up for you? A wizard to come up with the right search term for anything you ask? A wizard to organize your thoughts into neat little folders? A wizard to condense a web of research rabbit holes into a clean abstract with backlinks?

I tried to be that wizard once. I followed the Zettelkasten method, and spent months perfecting Notion and Obsidian templates to find the perfect workflow. And after years of trying… I went right back to Apple Notes like the rest of you. Nothing beats a simple scratchpad you can open, write something down, and close when you’re done.

So why can’t we have something as simple as Apple Notes, but as powerful at organizing and expanding your thoughts as something like Notion or Obsidian? All without the learning curve and upkeep those tools demand?

That’s what Hubble Note is here to do. Hubble Note is a notes app that’s as simple to use as Apple Notes. But when it’s time to find, organize, or research ideas further, you can talk to Hubble to do what you need. Call it… Claude Code for your notes. Except without the code, and maybe without the Claude if GPT-5 proves smarter.

[this is where a slick prototype will go. It’s coming, I swear]

Why me?

I have… an unhealthy obsession with writing things down. Both as a content creator and as a Markdown-loving engineer.

I think a timeline will help:

2018: Started a technical blog to talk about web technologies (hey dev.to)
2019: Built a self-hosted blog using web technologies to talk about web technologies (hey bholmes.dev)
2021: Rebuilt that website without a framework, and accidentally invented my own. It was based on Vite and… yeah, Markdown (hey Slinkity)
2022: Got hired to work on a new framework people actually used, and made it easier to build, organize, and extend your Markdown-based content (hey Astro)
2024: Started working with LLMs, and realized they’re really good at writing. Like, better than me. And like me, they love Markdown too (hey GPT and Claude et al.)

Present: Decided it’s time to build a notes app that combines everything I’ve learned into one tool: a Markdown-backed writing app with a lovable agent that helps you build, organize, and extend your thoughts (hey Hubble)

When can I try it?

Hubble is an experimental side project, so I won’t make any promises on release dates. But to watch the sausage get made, and hear when the sausage gets made, follow my Twitter and YouTube for updates, like this:

🔥 NEW DATABASE JUST DROPPED 🔥
It's this thing called a "file system" apparently. Cross-platform, local first, zero dependencies. Idk if it'll scale though pic.twitter.com/iLHe4sNhXq
— Ben Holmes (@BHolmesDev) September 7, 2025

Excited to have you on this journey!

Response to DHH on the gift of open source

Sun, 20 Jul 2025 21:13:41 GMT

I listened to the DHH x Lex Fridman podcast this past week. It’s 6 hours long, and genuinely I wish it were 10+. There are phenomenal lessons in here about the beauty of programming language design, the power of open source, the importance of family… just go listen to it.

I was originally going to write a TLDR about everything I learned. But there was one part of the podcast that I wanted to focus on: DHH’s comparison of open source to gift giving. It speaks to a lot of my past work as an open source maintainer at Astro, and DHH takes a stance that I… almost agree with. But also kind of don’t.

Open source is a gift exchange

Here’s a direct quote to start:

In open source, the customer is a receiver of gifts. We are having a gift exchange. I show up and give you my code. If you like it, you can use it. And if you have some code that fits in with where I’m going with this, I would love to get those gifts back. And we can keep trading like that… Together, we pull all the gifts such that someone showing up that’s brand new gets a mountain of gifts.

I love this analogy. Sharing Ruby on Rails with the world was an extraordinary gift that changed the course of web development for decades to come. What’s more, that gift wasn’t a one-sided act; it became a two-sided exchange. One person (DHH) shared an idea with the world, it solved real problems for like-minded people, and they shared their own libraries and contributions in return. No money was exchanged, but ideas and gratitude were.

That said, let’s hear the next line:

This is the magic thing of open source. It increases the total sum value of what’s in the commons when we all pursue our own self-interest.”

Increases the value of what’s in the commons… when we pursue our own self-interest.

Why self interest?

I agree with this idea on the surface; since open source projects are “gifts,” not paid services, you, the maintainer, should follow the path that you set for that project. A clear path keeps you in the game without causing burnout. It also keeps the direction of the project certain without a “designed by committee” roadmap. And crucially, it puts up boundaries around the open source relationship. I give this gift to you… but it’s ultimately built for my self interest. I will not be swayed by your self interest. Don’t like what I’m doing? Well I don’t care! Fork it and build what you wish. This is what you might call a “benevolent dictatorship,” which is common across the largest open source projects out there.

There’s nothing inherently wrong with that level of detachment. It may be a healthy line to draw when you’re opening yourself up to community scrutiny. Still, I don’t think that’s what gift giving truly means.

What gift giving means

There was a recent interview between Jony Ive and Stripe CEO Patrick Collison about the importance of designing for other people.

Jony Ive makes this point on designing for other members of your team:

Make things for other people. If you can put that in your daily routine, making things for others on your team, that really puts you in a lovely place.

In Jony Ive’s view, designing for someone else is a very vulnerable and necessary practice. You’re forging a relationship by building with someone else in mind. You’re also opening yourself to criticism, which can be scary.

But there’s a reason that the vulnerability is worth pursuing: gratitude. When you build something for someone else, that someone will be grateful for the time and effort you put into it.

Vulnerability is rewarded by gratitude.

Building relationships this way is a very human and “lovely” practice. And it’s what I’d call… good gift giving.

Going back to DHH’s view on open source, there’s a lot less sacrifice involved. Ruby on Rails is a gift to the community, but it’s still for Basecamp. It’s designed for the needs of their company, and not necessarily yours. If Ruby on Rails happens to map onto the needs of your company, great! You can enjoy the open source gifts that they’ve shared. But if it doesn’t map onto your needs… well, there’s no guarantee that they’ll ever build with your needs in mind.

Now don’t get me wrong: Ruby on Rails is a gift. It shows a lot of vulnerability to share a framework for building websites, and the community was certainly grateful for DHH's contribution. But if the roadmap to follow is driven by self-interest alone, he’s not selflessly designing for other people as Jony Ive might suggest. It’s gift giving, but a kind of… selfish gift giving.

The consequence of selfish gift giving

Now, a disclaimer: I’m not a member of the Ruby on Rails community. I don’t know how the community has influenced the Ruby on Rails roadmap. I only have DHH’s stance on this podcast and a few spare tweets to go off of. Still, I saw an example of how selfish gift giving can rub people the wrong way: TypeScript support in Stimulus.

Stimulus is an open source library from Basecamp that makes working with web components simpler. It’s the backbone of interactivity across Basecamp’s products, with Hey.com being a recent example. Naturally, those outside of Basecamp wanted to adopt Stimulus as well. The problem is, some of these interested users didn’t share DHH’s ideals about how software should be written: The ideals of raw text editing without completions, or of using JavaScript without types. So, despite DHH’s preferences, they’d prefer to have TypeScript support built into the library.

And TypeScript support was a feature of Stimulus for some time. Community members decided to be vulnerable with their views and contribute this gift TypeScript support to the project.

Did they receive gratitude in return? Well, with the next major release… DHH decided to remove type completions entirely. The community was understandably upset. In the eyes of DHH, TypeScript completions didn’t match how he wanted software to be developed. He also didn’t want to maintain something he didn’t like. So, out they went. Gift rejected.

Was DHH wrong to make this call? It’s honestly not my place to say. Maybe maintaining TypeScript types was leading to burnout on Stimulus, so it needed to be removed for DHH to continue stewarding the project. Or maybe his wider narrative on how software should be written is a core principle of the project worth sticking to. If some community members disagree, they aren’t worth serving. Or better yet, he can change their mind.

On the other hand, maybe removing types was a selfish choice that DHH didn’t need to make. Using Jony Ive’s design philosophy, TypeScript types were a design decision suggested by, and built for, other people. It comes with a level of vulnerability (I built these completions for you, hope you like them), and the expected payoff is gratitude from the library’s community and maintainers. But DHH wasn’t interested in the gratitude of the TypeScript community, and didn’t want to build a relationship with the TypeScript community. So the gift exchange ended there.

My time at Astro

For the past few years, I’ve been a core maintainer of Astro, an open source framework for building content-driven websites. From the beginning, this project was built by a core team (not a benevolent dictator), attracting a larger and larger community over time. Today, Astro sits at nearly 935 contributors to the core repo, and over a thousand contributors to documentation.

There are a number of reasons the Astro community grew to that size. For one, there was the openness of our docs team. Our docs leaders set clear guidelines for what good documentation looked like, and made the contribution process as accessible as possible. Just look at this post Sarah wrote back in June 2022. A community member asked “have you written anything about your community-driven approach to docs at Astro?” And she wrote an essay on the subject. Never change Sarah :)

After setting these expectations, the core team stepped back, and let the community step in. Internationalization is my favorite example, since translations are notoriously hard for open source projects to get right (or get at all). I18n contributions were slow at first. But overtime, contributors started translating our docs to Spanish, then French, then Japanese… until we hit a serious tipping point. The Astro docs sit at 14 supported languages today.

How did we get so many translations? The answer’s the same as any good gift exchange: reward vulnerability with gratitude. If a community member translates a single page of our docs into their language, we don’t just say "LGTM" and merge the PR. We give them a special badge in our discord community. We give a thorough PR review with kind, thorough feedback about what to improve for next time. Multiple maintainers stop by the PR to say thanks, even if that PR has already been merged. I’ll say it again: reward vulnerability with gratitude.

This principle is the backbone of Astro core as well. We have a core team that guides the direction of the project, yes. But we also have a public roadmap, and a public discussion board for anyone to share ideas. The system isn’t perfect (we’re working on ways to make roadmap contribution more accessible), but it’s led to many features landing in Astro that the core team wouldn’t have thought of. Server islands, Vercel ISR, and first-party font support to name a few.

We easily could’ve said “we don’t want the hassle of managing Spanish translations,” or “sorry, we don’t believe in serverless hosting.” But we decided to let the community shape the roadmap a bit more. The community showed us what was possible with the gifts they gave.

Of course, there's a balance between accepting and rejecting gifts. We draw boundaries between what should exist in core vs. what should be maintained by the community (ex. adapters for exotic deployment hosts), with an integration system to make the framework extensible. We also formalized which i18n translations our docs would and would not support, with a blog post describing our process. In all cases though, there's a common theme: clear communication. If we're going to reject gifts from a certain community, they deserve to know why. They also deserve an accessible discussion forum to voice their opinions.

I’ll make one more contrast between Astro and Ruby on Rails: Astro doesn’t belong to any company. Astro isn’t built for a Basecamp, it’s built for Astro’s own sake. Instead of designing for a single party, we design for a broad community. We design for other people.

Sure, Astro could be a much more focused project if we partnered with a company and built for their needs. But I imagine the community would be much smaller, and community sentiment would be more mixed.

Conclusions

I guess I’ll leave off with this: yes, free and open source software is a gift exchange. Maintainers are sacrificing their time and their brainpower without asking for a cent in return. And for this gift exchange to continue, and to grow, we need to keep rewarding vulnerability with gratitude.

You may prefer to keep your community small and only exchange gifts with like-minded individuals. Reject the TypeScript heads, find the text editor junkies. Or you may want to attract a broader community, and try to design for people that aren’t necessarily like you. It’s harder to do, but in my opinion, very rewarding.

So, contributors: keep being vulnerable. And maintainers: keep showing gratitude. Open source is a powerful thing, so let’s make it flourish together.

The python environment setup cheatsheet

Sun, 01 Sep 2024 22:02:02 GMT

Python seems to have a million different options to set up an environment. So I did what any good developer does: I asked Claude. Here's the checklist I used.

Setup

Prerequisite: you'll want to have python3 installed on your machine.

Create a virtual environment in your current directory with python3 -m venv .venv. .venv/ will be a generated folder, so add this to your .gitignore.
Activate the environment with source .venv/bin/activate. Run this every time you open your project directory from your editor, or when you open a new terminal instance.
List all dependencies in a requirements.txt file.
Install dependencies with pip install -r requirements.txt. Run this again whenever you add a new dependency to your requirements.txt.
Run your scripts with python3 name.py.

Editor tooling

VS Code seems to generate helpful prompts when creating a new environment to set up editor tooling.

Outside of VS Code, I would install the pyright LSP. You can install this into neovim environments, or use the built-in pyright LSP when using Zed (my editor of choice).

To tell pyright where your python env is located, add a pyrightconfig.json with a path to your project directory (. for the current directory) and the name of your venv folder (.venv):

{
  "venvPath": ".",
  "venv": ".venv"
}

Building serverless applications with Fauna + GraphQL

Thu, 24 Mar 2022 22:48:29 GMT

This article is sponsored by Fauna. If you are interested in producing similar content, apply to Write with Fauna.

Serverless and GraphQL have become pretty prolific buzzwords in the backend space. They each serve (heh) fairly different needs; the former takes the infrastructure management out of the backend, while the latter handles the efficiency and documentation pieces.

So, how do these approaches compliment each other? Let’s explore:

🤷 why you’d try serverless and GraphQL
🤝 the intersection of needs they both address
🔨 building a GraphQL backend using Netlify serverless
🗄 connecting to a persistent database using Fauna
🚀 deploying a live static website using Astro

Key terms

Before diving in, let’s define some import terms we’ll explore throughout the walkthrough.

Serverless - a method of deploying backend logic to isolated functions executed and managed on a pay-as-you-go model
GraphQL - a protocol for requesting information via HTTP, comparable to REST
Jamstack - building web apps with a decoupled architecture. Your website’s frontend handles its own routing and view logic (often as an SPA), and sends requests to APIs as-needed.

Why serverless?

Have you seen those pay-as-you-play games gaining traction over the past few years? Let’s take Fortnite as an example. It’s 100% free to download and play for life, with optional paid extras for enthusiasts that want to get more from the game. This is perfect for people planning an impromptu game night for instance. If your buddy doesn’t have the game installed, no sweat! Just download the launcher and you’re battle royale-ing in no time.

This is a pretty good analogy for serverless in my opinion. Instead of building, deploying, and managing a routed server of your own (like a traditional video game charging $X up-front), you’re free to start with a single serverside function that someone else maintains. No need to pay for a complete Linux server instance yourself. Instead, write a single function in a (supported) programming language that receives a user request, computes the response necessary, and deploys to an existing server infrastructure. For here, you’re simply charged by the number of requests each functions fulfills. Free to enter, pay at scale.

This is perfect for “game night,” when your team needs to rapidly prototype a new project and get it deployed both quickly and cheaply. It should also save your team from managing the infrastructure surrounding each of those one-off serverless functions you write. Sure, you’ll be at the whim of AWS, Azure, Google Cloud, and more, but that might be more reliable than a personal IT department.

Why GraphQL?

To best understand GraphQL, let’s start with a food-based analogy for REST. I personally think of REST like ordering from an upscale, sit-down restaurant. Hungry for the steak dinner? Make a request to your server (heh, see what I did there) and get back a gourmet response 🥩

GET /kitchen/steak-dinner

> 200
> {
	steak: {
		cooked: 'medium-rare',
		size: 'xl',
	},
	spinachSalad: {
		prepared: 'steamed',
		toppings: ['tomato', 'pepper'],
	},
	chimichurri: {
		numGarlicCloves: 2,
		cupsParsley: 1.5,
	},
}

This response is hand-tailored by the chef for the perfect meal. Still, some people might not need all these bells and whistles. What if you don’t need the chimichurri sauce? Or you aren’t hungry for spinach salad? Or you don’t care how the steak is cooked? If you’re at an upscale restaurant where the chef always knows best... good luck changing that prebuilt plate.

How GraphQL turns menus into buffets

GraphQL turns this experience into a buffet model. Instead of a single option for everyone, GraphQL gives you, the user, the power to choose what you want.

Say we want that steak from earlier with no extra sides, and we don’t care how it’s cooked. We can pass these options on the request body like so:

POST /kitchen
body: {
	steak {
		size
	}
}

And kitchen can take this request back to the /kitchen, responding with your tailor-made meal:

> 200
> {
		steak: {
			size: 'xl'
		}
}

There’s a few important distinctions to make from our REST example:

You’re now making a POST request instead of a GET. This is because you now have an opinion on what gets served. To “post” that request to the kitchen, you need to pass a body with your request.
You post generically to the /kitchen, instead of requesting a specific item like /kitchen/steak-dinner. This stems from the inverse of control we discussed in #1. In GraphQL, all requests are passed to a single handler (the kitchen) that receives and “resolves” incoming requests.

This approach is similar to a buffet. There’s one row of options available for you to inspect, and you’re free to choose the exact options you prefer. GraphQL even offers a “playground” to explore all available options from a given API. Like a buffet, you’re free to browse this self-documented schema of options to help craft a well-formatted request.

To summarize these benefits:

GraphQL brings power back to the client. Instead of requesting needlessly large payloads from prebuilt REST endpoints, you can choose the exact information a given frontend view needs.
GraphQL is self-documenting. Like a buffet, you can browse your API’s schema so there aren’t any surprises on that response body. This even helps with type generation in your codebase when you choose TypeScript 👀

Why serverless + GraphQL?

We’ve discussed the selling point for each of these. So what makes the combination of both so special?

Well, there’s a cross-section of needs that each of these help to address: teams want to ship experiences fast without asking questions. I personally identify with this as a mostly frontend developer. I don’t want to host, document, and maintain a server of my own; I just want to build efficient frontends with pits of success to save me as I scale. Here’s how serverless and GraphQL can help your team get there:

By hosting GQL resolvers on serverless, you’re free to start for free and scale cheaply. Platforms like Netlify and Vercel also offer incredible developer experience to deploy these functions alongside your existing frontends (if you build using web tech).
With a GQL API in place, you’re given a self-documenting “buffet” endpoint to hand-pick the right data for views in your application. This saves you from managing separate routes for each REST endpoint, and stitching together documentation as your backend scales.

Both of these offer a bias towards frontend-leaning teams planning to work fast.

When is serverless + GraphQL a bad choice?

To be honest, there isn’t a strong reason this combination in particular would be worrisome. It truthfully comes down to flaws with each technology in isolation.

Flaws with serverless

Serverless may be a poor choice for larger teams that plan to manage their own infrastructure. At scale, it might be preferable (and even cheaper) to purchase an AWS box to host your application and manage that server yourself.

There’s also the “cold start problem” to consider when using serverless. Since each function is automatically spun up and spun down on request, some requests may be slower as your hosting provider manages your function’s lifecycle.

Flaws with GraphQL

GraphQL may be a poor choice for simpler APIs, or for teams completely new to the technology. Now don’t get me wrong; GraphQL is preferable from the frontend layer most of the time due to its granular control and self-documentation. The real struggle emerges when implementing the backend behind this magical request buffet.

If you like batteries-included options, popular database services like Fauna and content management services (CMSs) like Contentful each generate GraphQL backend automatically. But when you’re implementing these resolvers yourself, managing a well-crafted API on a single endpoint can get complex. I recommend exploring Apollo’s getting started guide to decide whether this learning curve is right for your team.

Let’s build a simple app with GraphQL, Netlify serverless, Astro, and FaunaDB

It’s best to get our hands dirty discussing new tools. As an example, let’s build a small Jamstack website to display photos of far-out galaxies, courtesy of the NASA API 🌌

Here’s a brief overview of the tech we’re using:

Netlify to spin up and host our serverless backend
Apollo to generate a small GraphQL endpoint
Fauna to persist our galaxies in a database
Astro to build a static site that surfaces this information

Clone the starter code on your machine

Before jumping into the code snippets, I recommend cloning the “getting started” branch on this repository. It’ll offer a nice base for our frontend application, and set up some config files for linting and environment variables.

Clone the repository here →

Overview of the project

Let’s break down our starter project’s structure:

📂 netlify/functions/
	nasa.mjs # our serverless endpoint
📂 utils/
	getFaunaClient.js # helper for our Fauna DB connection
	mockGalaxies.js # static dummy data to get started
	seed.js # small script to throw this dummy data on the DB
📂 www/
	📂 src/
		📂 layouts/ # template shared across our website
		📂 pages/ # individual routes on our website
	📂 styles/ # styles for space aesthetic 👩‍🚀
	.env.development # env variable to store our API route
package.json # all our CLI scripts and dependencies
# other miscellaneous config files...

Most of our frontend has been pre-built so we can focus on GraphQL + serverless. We’ll jump into netlify/functions and those utils/ to get to the action!

Spin up your function locally with the Netlify CLI

You’ll notice some starter code under netlify/functions/nasa.mjs:

export const handler = async () => {
  return {
    statusCode: 200,
    body: 'hello galaxy!',
  }
}

As you might imagine, we should get the response “hello galaxy!” whenever we call this endpoint.

Let’s try querying this function locally. First, ensure you have node + npm installed on your machine. Now you can install the Netlify CLI globally like so:

npm install netlify-cli -g
netlify --version

If you get a --version output in your terminal, you should be good to go! Note: you might need to close and restart your terminal if you run into issues with this check.

You’ll also need a Netlify account for simpler debugging and deployment in a moment. Go ahead and make a free Netlify account here.

Next, authenticate from your terminal and follow the prompts:

netlify login

If all goes well, you’re ready to spin up a local Netlify server:

npm install # install project dependencies first
npm run ntl:dev

☝️ If you check the package.json at the base of this project, you’ll see that ntl:dev maps to the netlify dev command. You’ll also see a whole host of scripts we’ll try in the coming sections!

You should see a console output like this:

◈ Netlify Dev ◈
◈ No app server detected. Using simple static server
◈ Running static server from "fauna-serverless-graphql/netlify"
◈ Loaded function nasa.
◈ Functions server is listening on XXXXX

◈ Static server listening to XXXX

   ┌─────────────────────────────────────────────────┐
   │                                                 │
   │   ◈ Server now ready on http://localhost:8888   │
   │                                                 │
   └─────────────────────────────────────────────────┘

All your serverless functions will be visible from the .netlify/functions route. Assuming your console says http://localhost:8888, you should find a nice “hello galaxy!” message a http://localhost:8888/.netlify/functions/nasa.

Write a simple GraphQL resolver using Apollo lambda

Now that you’re up-and-running, let’s jump into some GraphQL!

You may have noticed a static array of info under utils/mockGalaxies.js:

module.exports = [{
  title: 'Galaxy Centaurus A',
  description: 'This image of the active galaxy Centaurus A was taken by NASA Galaxy Evolution Explorer on June 7, 2003. The galaxy is located 30 million light-years from Earth and is seen edge on, with a prominent dust lane across the major axis.',
  credits: 'NASA/JPL/Caltech',
  imageUrl: 'https://images-assets.nasa.gov/image/PIA04624/PIA04624~orig.jpg',
}, ...]

Let’s use this as our “database” for now. Right off the bat, you’ll notice a common structure for each entry: title, description, credits, and imageUrl. We can consider this our GraphQL schema.

We’ll define this schema using the gql helper provided by apollo-server-lambda:

// netlify/functions/nasa.mjs
import { gql } from 'apollo-server-lambda'

const typeDefs = gql`
type Galaxy {
  title: String,
  description: String,
  credits: String,
  imageUrl: String
}
`
export const handler = async () => ...

This defines the structure of information that we’ll return in a moment.

Next, let’s define the “resolvers” for this endpoint. We just need a single resolver for this example: galaxies. This returns our array of Galaxy entries.

// netlify/functions/nasa.mjs
...
const typeDefs = gql`
type Query {
  galaxies: [Galaxy!]!
}
type Galaxy {
  title: String,
  description: String,
  credits: String,
  imageUrl: String
}
`
...

Notice that we place this galaxies resolver on the Query type. We’ll reference this type when defining the galaxies resolver.

Now that we have this schema defined, let’s start returning some data! We’ll use the ApolloServer dependency here. This helps us:

Define what each resolver returns using JavaScript functions
Match this up with our typeDefs
Generate a request handler to use for our export const handler. This is modeled to work with AWS Lambda, which is the backbone for Netlify serverless.

We’ll write a resolver to return our mockGalaxies:

// netlify/functions/nasa.mjs
import { ApolloServer, gql } from 'apollo-server-lambda'
import mockGalaxies from '../../utils/mockGalaxies'

const typeDefs = gql`
type Galaxy {
  title: String,
  description: String,
  credits: String,
  imageUrl: String
}
type Query {
  galaxies: [Galaxy!]!
}
`

const resolvers = {
  Query: {
    galaxies() {
      return mockGalaxies
    }
  }
}

const server = new ApolloServer({ typeDefs, resolvers })

export const handler = server.createHandler()

Try visiting http://localhost:8888/.netlify/functions/nasa again. Now, you should see an entire playground interface to explore 👀

If you click on the “docs” tab, you’ll see that galaxies resolver that we just defined. Clicking through reveals some information about the return value as well.

This is automatically returned for all GET requests to your GraphQL endpoint. Let’s try crafting a query in that lefthand menu to get our feet wet. I invite you to type this by hand instead of copy / pasting! You’ll be greeted by some handy autocomplete 🙃

For instance, let’s retrieve just the title and description fields from that array:

{
	galaxies {
		title
		description
	}
}

Hitting the “run” button should reveal that subset of info from our mockGalaxies.

Query this serverless endpoint from your Astro frontend

So we’ve generated a playground to try out new queries. How can we use this inside a real-world application?

Head over to www/src/pages/index.astro in our example project. You should see the following TODO at the top of the file:

let galaxies = []
// TODO: fetch galaxy summary info

Don’t worry too much about the fancy templating being used at the bottom of the file. Just know that anything inside those --- blocks will be plain ole JavaScript that’s run whenever we build our site. You can always explore Astro’s getting started guide to go further 🚀

Let’s try generating an overview page of all the galaxies in our “database.” That view should look something like this once it’s working:

☝️ You’ll notice we only need each galaxy’s title and description. Let’s write a GraphQL query to reflect this.

---
// www/src/pages/index.astro
import Layout from '../layouts/base.astro'
import slugify from 'slugify'

let galaxies = []
const { data, error } = await fetch(`${import.meta.env.API_URL}`, {
	method: 'POST',
	body: JSON.stringify({
		query: `{
			galaxies {
				title
				description
			}
		}`
	}),
}).then(res => res.json())

galaxies = data.galaxies
...

To summarize what’s going on:

We make a fetch request to our serverless function using the web-standard fetch API
We use import.meta.env.API_URL as the URL to request from. This is referencing an environment variable in our application defined under www/.env-development. Tweak this to match wherever you’re running that Netlify development server from.
We use POST as our method here. Remember, since we have a preference for what data we want, we need to “post” a body to our server.
We write our query as a string. Feel free to copy / paste the example request we wrote in the playground, placed under the query key as shown.
We convert the response to JSON using res.json()
We assign the response to our galaxies variable. Feel free to add to add any try / catch boundaries or error handling you want based on that error object (example here).

Assuming your Netlify server is still running from that npm run ntl:dev command, you’ll need to open a second terminal window to see this frontend in action. Create a new window and run the following:

npm run astro:dev

You should see an output like 06:23 PM [astro] Local: http://127.0.0.1:3000/. Clicking this link, you’ll find a nice summary of galaxies to explore 🚀

Generate routes for each galaxy

You may have hit this error trying to click any of those homepage links:

[getStaticPaths] route pattern matched, but no matching static path found. (/Galaxy-Centaurus-A)

That’s because, well, these routes don’t exist yet! Let’s generate unique pages for each galaxy to reveal more information. Head over to www/src/pages/[galaxy].astro. Here, you’ll find a helper to generate routes from API data like so:

export async function getStaticPaths() {
  // TODO: generate pages for each galaxy
  return []
}

If you come from NextJS, you’ll notice this is very similar to their static path generator. This function should return an array of website pages for Astro to generate, each displaying the whole suite of Galaxy info: title, description, credits, and imageUrl.

We can write a similar fetch query to that earlier example, this time requesting all 4 keys:

---
import Layout from '../layouts/base.astro'
import slugify from 'slugify'

export async function getStaticPaths() {
	// same format as before, now with a new query body
  const { data, error } = await fetch(`${import.meta.env.API_URL}`, {
      method: 'POST',
      body: JSON.stringify({
        query: `{
          galaxies {
            title
            description
            imageUrl
            credits
          }
        }`
      }),
    }).then(res => res.json())

  return data.galaxies.map(galaxy => ({
      // params.galaxy -> the URL you can visit in your browser
      // ex. the galaxy with title "Andromeda Galaxy"
      // will be visible at http://127.0.0.1:3000/Andromeda-Galaxy
      params: { galaxy: slugify(galaxy.title) },
      // props -> all information available to our galaxy page
      // see the Astro.props being used below
      props: galaxy,
    }))
}

const { title, description, imageUrl, credits } = Astro.props
...

This should generate unique URLs for all of our galaxies, and grab each galaxy’s info for display using Astro.props. Now, clicking any of your homepage links should reveal a beautiful galaxy image like so:

Persist these galaxies in a database with Fauna

This is great for demo purposes, but you probably can’t store all your information in a static mockGalaxies file.

Let’s try throwing these galaxies in a Fauna database. To get the most up-to-date info, I recommend visiting Fauna’s prerequisite doc section to get started. This will walk you through setting up an account, generating your first database, and getting an API secret for connecting to that database. Don’t worry, I’ll wait 😁

...

Got that secret key? Great! Let’s store this in a .env file for our serverless function to use. Create a .env file at the base of the project with the following contents:

FAUNA_SECRET=secret-you-copied-from-fauna

Also take note of the region used to generate this new project. Our starter code assumes you’ll use a US region. If not, feel free to update the “domain” field under utils/getFaunaClient.js. See this documentation for properly setting the domain URL. Warning: If configured improperly, none of your queries will run 🚨

Load `mockGalaxies` into your database

Let’s “seed” this new database with our sample data. We’ve written a handy script under utils/seed.js to handle this. If you’re curious about Fauna’s fancy FQL query syntax, we recommend checking the FQL fundamentals guide.

You can run this script by executing:

node ./utils/seed.js

Once this is finished, you should see a new galaxies collection under the “collections” tab in your dashboard.fauna.com window.

Query this data from your GraphQL resolver

With this data in place, we’re ready to start querying from our GraphQL resolver! Start be establishing a connection with your Fauna server. We included a handy helper function for this under utils/getFaunaClient.js, but here’s the code for the sake of completeness:

const { Client } = require('faunadb')
// set up our fauna secret from that .env file
require('dotenv').config()

module.exports = function getFaunaClient() {
  return new Client({
    secret: process.env.FAUNA_SECRET,
		// whichever domain you (hopefully!) configured earlier
		// docs: https://docs.fauna.com/fauna/current/drivers/connections?lang=javascript#connection-options
    domain: "db.us.fauna.com",
  });
}

Then, call this helper from the top of our nasa.mjs function handler:

// netlify/functions/nasa.mjs
import { ApolloServer, gql } from 'apollo-server-lambda'
import { query as q } from 'faunadb'
import getFaunaClient from '../../utils/getFaunaClient'

const faunaClient = getFaunaClient()
...

Now, let’s query our galaxies collection from our galaxies GraphQL resolver. If you want to learn Fauna’s FQL language, I highly recommend trying the “shell” tab from dashboard.fauna.com first. You can use this for sandboxing queries before their implementation. I was personally quite new to FQL, so it was pretty helpful to try out the Document and Lambda helpers 🙃

Sample output from the “shell.” Check Fauna’s FQL fundamentals to learn more about querying documents.

☝️ As you can see, this test query returned our galaxy data as expected. We can use Fauna’s JavaScript library to translate this into our demo app:

// netlify/functions/nasa.mjs
import { query as q } from 'faunadb'
...
const resolvers = {
  Query: {
    async galaxies() {
      const galaxiesRaw = await faunaClient.query(
        q.Map(
          q.Paginate(q.Documents(q.Collection("galaxies"))),
          q.Lambda("galaxyRef", q.Get(q.Var("galaxyRef")))
        )
      )
      try {
				// Fauna returns each object on a nested “data” key
				// Let’s flatten this
        return galaxiesRaw.data.map(galaxyRaw => galaxyRaw.data)
      } catch {
        console.error(`The fauna galaxies query returned malformed data: ${JSON.stringify(galaxiesRaw, null, 2)}`)
        return []
      }
    }
  }
}

If you check out our Astro dev server from earlier, we should see... exactly the same output 😁 But now we’re free to add more documents in the future, or even create a /upload route to submit new galaxies.

Now, your code is ready to ship! If you hit any rough patches along the way, or want to see everything in its final form...

Check our finished solution on GitHub →

Can you use Fauna’a GraphQL resolvers instead?

You might be aware that Fauna has a built-in GraphQL API you can query. This is a great option to consider as well! It’ll save you from writing these Apollo resolvers + serverless functions yourself, and it should ensure more complex queries stay efficient.

So why did we write these resolvers by hand? There’s a couple reasons:

I’m not sure what database you plan to use. If you’re reading this article coming from a non-Fauna storage option, I want to show how you can build your own GraphQL + serverless flow using Apollo. Fauna’s GraphQL setup is a natural next step if you like what you see.
It’s helpful to explore serverless hosting options. Fauna hosts the serverless GraphQL backend for you, which is extremely convenient for spinning up new projects. Still, I’d assume most projects with mid-to-high complexity need to manage their own infrastructure in some way. Whether your stitching together different microservices, or exploring edge computing for distribution, it’s best to understand your options before using the batteries-included option.

Deploy this serverless function for production use

Finally, let’s try deploying our serverless endpoint to a “live” server. We have a couple pre-written commands to try here:

npm run ntl:deploy → Deploy to a URL of your choosing
npm run ntl:deploy-preview → Deploy to a randomized test URL

I’d recommend trying the deploy-preview first. This will run netlify env:import .env to ensure FAUNA_SECRET is visible from your serverless function. You’ll see an output like this in your console if all goes well:

.---------------------------------------------------------.
|             Imported environment variables              |
|---------------------------------------------------------|
|     Key      |                  Value                   |
|--------------|------------------------------------------|
| FAUNA_SECRET | secret-you-copied-from-fauna             |
'---------------------------------------------------------'

Then, it will upload a live deploy preview under your Netlify account. You should be free to explore this preview by visiting random-url.netlify.app/.netlify/functions/nasa.

Deploy your frontend for production use

With this serverless function live, you’re ready to build your static website as well.

Remember that www/.env.development from earlier? This set our API_URL to reference our local Netlify instance. To configure your production builds, you’ll need a www/.env.production just alongside this:

API_URL=https://where-you-deployed-your-serverless-fn/.netlify/functions/nasa

Now, you’re ready to run either of the following scripts:

npm run astro:preview → generate a local preview of your production build
npm run astro:deploy → deploy your website for production

Conclusion

I hope this walkthrough opened your mind on some new tooling! If there’s any takeaways you find from this article, I hope they’re along the lines of:

GraphQL + serverless are a great pairing for frontend-leaning devs looking to ship quickly and cheaply
You can absolutely deploy GraphQL to a serverless function, all with minimal effort thanks to packages like apollo-server-lambda
Fauna’s built-in GraphQL endpoints are worth exploring for a batteries-included option to backend management
Netlify is pretty helpful for hosting frontends and backends these days
NASA’s public APIs are awesome for interstellar imagery 🪐

As always, there’s no “silver bullet” to building applications. So, keep sampling this renaissance of new tooling and find what sticks!

Understanding single page apps & client-side routing

Tue, 06 Jul 2021 20:01:36 GMT

"SPA" has been a hot topic ever since "modern" JS frameworks like React hit the scene. They promise all sorts of benefits like dynamic user interactions, lightning-fast load times, solving world hunger, etc. (okay that last one is a stretch...)

But have you ever stopped to wonder what's actually going on behind the scenes? And if you're not using an SPA, are you stuck in the past? Well, let's explore:

🤔 How non-SPAs work + how they perform on the modern web (spoiler, they're a great choice as always!)
⚙️ The key benefits and inner workings of an SPA
🍔 A side-by-side visual comparison feat. juicy burgers

Onwards!

🤔 First off, how do non- SPAs work?

Web development has been soaking in acronym soup lately, so I think it's worth clarifying what isn't an SPA first 🙃

If your site isn't an SPA, you're likely using what's called "server-based routing." A metaphor is in order here. Say you're at a formal, sit-down restaurant with a waiter (a server if you will 😉). If you want food, you'll have to:

Ask the waiter for the food you want
Wait a moment for the dish to get prepared
Receive your finished plate once it's done

This is how all websites work when you first visit them. You ask for what you want (visiting a URL like https://breakfast.club)), wait for the server to get back to you (loading spinner), then enjoy your "meal" once it's ready (the page is done loading! 🎉)

But what if you want to order dessert? Heading back to our restaurant scenario, you'll go through the same flow as last time:

Ask the waiter for the yummiest dessert
Hand them your dirty plates
Wait a moment for the dish to get prepared
Receive a shiny new bowl with your ice cream sundae 🍨

There's an important bit I want to reiterate there: you hand over your dirty plates, and get back a brand new one. This is why you'll see a little loading bar re-appear every time you jump to a new page. Here's an example of 11ty's documentation using server-based routing:

Watch the loading bar engage whenever we click a link

At first, it looks like you're still on the same page whenever you click those navigation links, and the browser's only refreshes the bits that change (the documentation).

🚨 But that's not really the case! Whenever you click a link, your browser is "clearing your plate" (removing everything from the page) and pulling in a fresh meal, navigation and all. So you're really reloading all those pieces of navigation every time you visit a new page, even if they were already on your plate to begin with.

Wait, is that wasteful?

It may sound like the browser's doing a lot of extra work here! Although this is still an issue that SPAs can help with, it's not as problematic as it used to be. Here's a few efficiency points to consider:

1. HTML is super cheap to load and render

Even though the browser is "re-painting" the page from scratch every time, it only takes a few milliseconds to load that HTML skeleton. The truly expensive bits are the styles, scripts, and images the browser needs to fetch, which leads us to...

2. Shared resources don't need to get re-loaded

For instance, say every documentation page pulls in the same CSS file: <link rel="stylesheet" href="documentation.css">. When you click another link that also pulls this CSS, the browser's smart enough to say "oh, I loaded this already! I'll just use that and apply it to the page." The same goes for images and fonts as well.

💡 Note: This is all thanks to caching. If you want to go deeper, the Remix team has an excellent walkthrough on caching documents, resources, and more over here 😄

So the actual loading of these shared resources isn't a problem. But what about painting those resources to the page over and over again? This brings us to...

3. The next page only appears when it's ready

Back in the day, there was a risk you'd see a flash of white nothingness between "clearing the plate" and "receiving the new one." But modern browsers have pretty much resolved this! In short, web browsers wait for the signal that the next page isn't just "done loading," but is also ready for you to view and interact with. Think of this like bringing out your plate when it's ready to eat, instead of bringing you a plate of ingredients you have to assemble yourself.

Hibachi rendering: showing you the page painting process before it's ready to eat (it's less cool when browsers do it) 😉

This especially helps out pages that rely on blocking resources like JavaScript to render everything on the page. Here's a quick before-and-after shot by the Chrome team when they launched this concept 🚀

Source article by Addy Osmani

Disclaimer: The browser won't always wait for the next page to be interactive before showing it; It'll still show the half-finished page if you're on a slow internet connection and the browser decides it's waited too long. Still, for snappier sites like that 11ty documentation from earlier, it shouldn't be a problem!

💁 Now, let's talk single page apps

So how do SPAs compare? Well, let's revisit that restaurant example from before. When you first visit a site using the SPA approach, everything works pretty much the same:

Ask the server for the food you want (visit https://spa-breakfast.club)
Wait a moment for the dish to get prepared (browser loading spinner)
Receive your finished plate once it's done (the page is done loading! 🎉)

Now the interesting part comes when you go back for seconds. When you click a link on an SPA, it replaces the typical, server-based routing with clientside routing 😮 In other words, we process all link requests using JavaScript we wrote ourselves, instead of sending those requests to the server right away.

Here's a code snippet to get your brain moving 🧠

<a href="/desert">Go eat desert</a>
<script>
	document.addEventListener('click', (event) => {
      if (
        // if you clicked on an A-nchor tag (link)
        event.target.tagName === 'A' &&
        // and you're going to a page on this domain (like /desert)
        event.target.origin === location.origin
      ) {
        // don't ask the server for that resource!
        event.preventDefault()
        // instead, we'll go fetch the resource ourselves
        const response = fetch('https://buffet.table/desert')
        // ...convert that response to something we can work with
        const htmlString = await response.text()
        const desert = new DOMParser()
          .parseFromString(htmlString, 'text/html')

        // ...and do something with that desert element
        // ex. append desert to our "plate" in the DOM
        document.querySelector('.my-plate').appendChild(desert)
      }
    })
</script>

Pretty weird, right? This is the super-simplified crux of an SPA: you never truly "leave" the page you started on. Instead, you intercept all future requests (link clicks) and handle the fetching yourself. You'll often do this using the fetch API native to all modern browsers as demo-d above.

This is why I'd think of SPAs and clientside routing like a buffet. Instead of ordering your meal and waiting for it to get prepared, you can get out of your seat and grab that pre-prepared food yourself!

Key benefits to this approach

There are 2 major benefits to single page apps that clientside routing unlocks 🔓

First, load-time efficiency can go up 🚀 I say "can" because of all the serverside routing optimization I mentioned previously (which may cancel out any performance gains). But there is a noticeable difference for resource-hungry frameworks like React, Vue, and Svelte. All of these use some form of clientside routing to keep JavaScript load times to a minimum.

For instance, if I went from one page of a React app to another using serverside routing, the browser would re-parse and re-render the whole page using JavaScript! This can severely impact your "time to interactive," an accessibility concern you can learn more about here.

Second, you can now build dynamic, app-like interactions ⚙️ Animated page transitions are the easiest to point out here. Since you're fully in control of loading new content and applying it to the page, you can pull off all sorts of CSS trickery like cross-fades, pop-up modals, tab sliders, and more. Here's an example from my personal site using clientside routing:

🍔 A juicy visual comparison

Now that we've introduced SPAs + clientside routing as a concept, lets see a side-by-side comparison with serverside routing.

Say you receive your order for a juicy burger that's cooked medium rare, but would rather have a patty that's well done.

We'll imagine this moment as "clicking a link," requesting to go from /medium-rare-burger to /well-done-burger.

Here's what that "click" may do with a server-based approach:

Animation showing the 3 step rendering process

Then, here's how clientside routing may handle the request:

Animation showing our new 4 step rendering process

Notice that we never clear our page in the SPA approach! We just request the resource (a well-done burger), pick out the pieces we want to add to our page (the patty), and perform the DOM manipulation with JavaScript.

This doesn't have much performance benefits when we're talking HTML files. But if that HTML has some JavaScript and styles attached to it that we can also fetch (like, say, a React component), there's a lot of room for performance gains.

Wrapping up: so which should I choose?

Although SPAs seem like the "silver bullet" for any website, there's a case to be made for either approach.

The most obvious win for server-side routing is, well, it's just simpler. No need to write and maintain all those click listeners; just let the browser do the serving for you. Yes, you'll often use a framework-specific library for SPAs like React Router, but learning and updating JS libraries is always more overhead.
The second win for server-side is no accessibility worries. When you handle all the routing clientside, you run the risk of hurting screenreader and keyboard experiences. For instance, you'll need to alert screenreader users that new content has appeared on the page whenever they click a link. And for keyboard-ists, you need to make sure their focusing the right element when something new swipes into view.

☝️ But if you're addressing these concerns confidently (or using a robust library to do it for you), SPAs are a great way to go!

Grabbing subsets of JS object properties with... GraphQL?

Mon, 07 Jun 2021 20:01:36 GMT

Messing with JavaScript objects is pretty easy these days. Destructuring syntax is convenient and the spread ... operator helps with merging objects together. But what about grabbing just... a portion of an object?

This question deserves some visuals. Let's jump into the problem we're trying to solve, and a flexible solution we can add to any existing JavaScript project 💪

What we want

Say I have a big document of structured data. Without manually writing a new object by hand, I just want to pull the little slices that I actually care about.

Here's one such scenario:

In this case, we want a copy of our original fridge, but we only care about those isEdible subkeys.

My gut reaction is to reach for some declarative tools in my ES6 arsenal. Object destructuring comes to mind at first:

const whatsInMyFridge = {
  weekOldPasta: {
  ...
}
const { weekOldPasta: { isEdible: pastaIsEdible },
	panSearedSalmon: { isEdible: panSearedSalmonIsEdible }
	} = whatsInMyFridge

There's a few issues with this:

We can't easily destructure keys of the same name. Notice I had to convert each isEdible variable to the verbose pastaIsEdible and panSearedSalmonIsEdible
Destructuring leads to some pretty gnarly code as it gets more complex. Just with a few keys, we're already hitting multi-line { curly hell }.

And most of all, we still have to build our new object at the end! Our destructuring statement actually just made some one-off variables for each key in the object. We'll still have to do this:

const whatsEdible = {
  weekOldPasta: {
    isEdible: pastaIsEdible,
  },
  panSearedSalmon: {
    isEdible: panSearedSalmonIsEdible,
  }
}

...which is hardly better than just writing the object from scratch 😢

What we really want is some magical syntax for just the keys we want to retrieve. Something like this really:

whatsInMyFridge.giveMeTheseKeys({
	weekOldPasta {
		isEdible
	},
	panSearedSalmon {
		isEdible
	}
}) // -> a beautiful formatted JS object

📈 Enter: GraphQL

If you've worked with GraphQL before, you probably noticed how close that example comes to a GraphQL query!

A brief rundown for those unfamiliar: GraphQL is a "querying" language originally built for API calls. It was mainly born from the frustrations with REST requests, as API endpoints had to predict all the data a client might want to retrieve.

GitHub recently migrated to GraphQL because of this. Imagine this scenario:

User A wants to get information about their GitHub profile. They want to send off a username and get back the accounts name and profile picture
User B also wants some GitHub profile info. However, they're looking for a different set of info: the list of user recovery emails and their personal bio.

As you could imagine, User C might want a new combination of fields, as might users D-Z. So instead of returning a massive JSON payload to satisfy everyone, GitHub exposed a GraphQL API for you to describe exactly which fields you want.

Here's how User A might request a name and profile picture as part of their request body This is from demo purposes, and won't actually work if you send to GitHub

{
	userProfile(email: '10xengineer@genius.club') {
		name
		picture {
			src
			alt
		}
	}
}

...And GitHub will "fill in the blanks" by providing values to those requested keys. As you can imagine, this syntax is flexible enough to use on any blob of JSON you want to filter down 👀

📖 Applying GraphQL to reading JSON objects

💡 TLDR: If you want the final solution without all the walkthrough, jump down to the finished product!

Let's figure out how to use that fancy syntax for our use case. The biggest question to resolve is "how do we interpret a GraphQL query in JS land?" Sadly, there isn't a nice "plain JS" solution, so we will be reaching for a library here.

Go ahead and install this graphql-query-to-json package. It does have a fair amount of sub-dependencies like the core graphql package and the complimentary json-to-graphql-query, so if that bothers you... my apologies 😢

Let's see what we get from our old "what's edible in my fridge" request:

const { graphQlQueryToJson } = require("graphql-query-to-json")
// or if you prefer: import { graphQlQueryToJson } from 'graphql-query-to-json'

const asJson = graphQlQueryToJson(`{
  weekOldPasta {
    isEdible
  }
  panSearedSalmon {
    isEdible
  }
}`)
console.log(asJson)
/* 👇
{
  query: {
    weekOldPasta: { isEdible: true },
    panSearedSalmon: { isEdible: true }
  }
}
*/

Neat! Toss in a string, get back a JS object. You'll notice that it wraps our requested object with the query key. This would be useful if we were sending this request to an API, but for our purposes, we'll just ignore that key in our helper function. It also stubs out any unknown key values with true, which we'll use to track down unfilled values later 👀

Traversing our query

With this JS object in hand, it's time to walk through all the keys and figure out which values to fill in. Let's start with a simple example that only goes 1 level of keys deep:

const myFridge = {
	numEggs: 5,
	pintsOfIceCream: 3,
	degreeUnits: 'celsius',
}
const whatIWant = `{
	numEggs
	degreeUnits
}`
// grab the ".query" straight away, since we won't need that nested key
const whatIWantAsJson = graphQlQueryToJson(whatIWant).query
// 👉 { numEggs: true, degreeUnits: true }

Now we have our set of keys (numEggs and degreeUnits) each with a value of true. To assign our actual values in place of those true flags, we can

loop through all the object keys in whatIWantAsJson, and
assign values from the same key in myFridge.

// loop over the object keys...
for (const key of Object.keys(whatIWantAsJson)) {
	// and if that key has a value of "true"...
    if (whatIWantAsJson[key] === true) {
		// replace "true" with the value from myFridge
		whatIWantAsJson[key] = myFridge[key]
	}
}
console.log(whatIWantAsJson)
// 👉 { numEggs: 5, degreeUnits: 'celsius' }

Handling nested objects

This basic loop handles 1 level of nesting. But what if we have a request like this?

{
  // level 1
  weekOldPasta {
	// level 2
    isEdible
  }
  ...
}

For this, we'll need a way to run our loop over Object.keys for every level of keys in our object. Get ready to put on your computer science hat, because we're using recursion 😨

Pay attention to this new else statement we're adding:

// wrap our loop in a function we can call
function assignValuesToObjectKeys(whatIWant, myFridge) {
	for (const key of Object.keys(whatIWant)) {
		if (whatIWant[key] === true) {
			whatIWant[key] = myFridge[key]
		} else {
			// if the value isn't "true", we must have found a nested object
			// so, we'll call this same function again, now starting from
			// the nested object inside whatIWant
			assignValuesToObjectKeys(whatIWant[key], myFridge[key])
		}
	}
}

This is a classic example of a recursive function. We have 2 clauses here:

The base case: When we hit a value of true, we stop looking for nested objects
The recursive function call: When we haven't hit the "base" of our nested object, keep drilling down the chain of nested keys using the same function

With this in place, we have a reusable JS function for anywhere in our codebase 🥳

const myFridge = {  
	weekOldPasta: {  
		noodleSogginess: “high”,  
		numMeatballs: 4,  
		isEdible: false,  
	},  
	panSearedSalmon: {  
		oilUsed: “avocado”,  
		numSpices: 3,  
		isEdible: true,  
	}
}

const whatIWant = graphQlQueryToJson(`{
  weekOldPasta {
    isEdible
  }
  panSearedSalmon {
    isEdible
  }
}`).query

assignValuesToObjectKeys(whatIWant, myFridge)
console.log(whatIWant)
/* 👉 {
	weekOldPasta: {
		isEdible: false,
	},
	panSearedSalmon: {
		isEdible: true,
	},
}
*/

Cleaning this up a little

You'll notice that our assignValuesToObjectKeys function doesn't return anything; it just modifies the whatIWant object we passed in. For added readability, we might add a wrapper function to handle the graphQlQueryToJson call and actually return our requested object:

function grabPartialObject(originalObject = {}, query = "") {
	const whatIWant = graphQlQueryToJson(query).query
	assignValuesToObjectKeys(whatIWant, originalObject)
	return whatIWant
}
...
const whatsEdible = grabPartialObject(myFridge, `{
  weekOldPasta {
    isEdible
  }
  panSearedSalmon {
    isEdible
  }
}`)
console.log(whatsEdible) // gives us the same object as before!

Handling arrays

So we've conquered nested objects. But what if we have an array of objects that we want to filter?

For instance, say our fridge data was structured just a bit differently:

const myFridge = {
  food: [
    {
      name: 'Week old pasta',
      noodleSogginess: 'high',
      numMeatballs: 4,
      isEdible: false,
    },
    {
      name: 'Pan Seared Salmon',
      oilUsed: 'avocado',
      numSpices: 3,
      isEdible: true,
    },
  ],
}

...and we just care about the name and isEdible keys for every object in that array. Following how GraphQL requests normally work, we'd expect this sort of syntax to work:

{
	food {
		name
		isEdible
	}
}

In other words, treat food like it's a regular object in the request, and we'll be smart enough to handle arrays of data.

This answer is a bit more involved than our previous examples. So, I'll leave you with a thoroughly commented codeblock:

function assignValuesToObjectKeys(whatIWant, myFridge) {
  for (const key of Object.keys(whatIWant)) {
    if (whatIWant[key] === true) {
	  // 👇 If the fridge data happens to be an array...
    } else if (Array.isArray(myFridge[key])) {
      // first, keep track of the object they requested
      const originalRequest = whatIWant[key]
      // then, create an array where that request used to be
      // for us to "push" new elements onto
      whatIWant[key] = []
      // loop over the items in our array of food...
      for (const fridgeItem of myFridge[key]) {
        // make a variable to store the result of assignValuesToObjectKeys
        // we use { ...originalRequest } here to create a "copy"
        const requestedItem = { ...originalRequest }
        // grab the keys we want out of that array element
        assignValuesToObjectKeys(requestedItem, fridgeItem)
        // then, push our shiny new object onto our running list
        whatIWant[key].push(requestedItem)
      }
    } else {
      // ...
    }
  }
}

That's a fair amount of code! To briefly summarize, you'll need to:

Check when our actual data is an array, rather than a simple object
Loop over the actual data and assignValuesToObjectKeys for each one
Push the results onto a running array in whatIWant, with necessary helper variables to keep track of your original request

🚀 The finished product

Here's how our finished product looks! I've renamed myFridge 👉 actualObj and whatIWant 👉 requestedObj so our naming conventions are more universal. I also added a hasOwnProperty check to assert we're requesting a key that actually exists. If not, raise an exception.

Remember, you'll need to add the graphql-query-to-json package package to your project for this to work.

const { graphQlQueryToJson } = require("graphql-query-to-json")

function assignValuesToObjectKeys(requestedObj, actualObj) {
  for (const key of Object.keys(requestedObj)) {
	if (!actualObj.hasOwnProperty(key)) {
		throw `You requested a key that doesn't exist: ${key}`
	} else if (requestedObj[key] === true) {
      requestedObj[key] = actualObj[key]
    } else if (Array.isArray(actualObj[key])) {
      // keep track of the object they requested
      const originalRequest = requestedObj[key]
      // then, create an array where that request used to be
      // for us to "push" new elements onto
      requestedObj[key] = []
      for (const actualItem of actualObj[key]) {
        // make a variable to store the result of assignValuesToObjectKeys
        // we use { ...originalRequest } here to create a "copy"
        const requestedItem = { ...originalRequest }
        assignValuesToObjectKeys(requestedItem, actualItem)
        requestedObj[key].push(requestedItem)
      }
    } else {
      console.log(requestedObj[key])
      // if the value isn't "true", we must have found a nested object
      // so, we'll call this same function again, now starting from
      // the nested object inside requestedObj
      assignValuesToObjectKeys(requestedObj[key], actualObj[key])
    }
  }
}

// 👇 Function you'll actually `export` for others to use
function grabPartialObject(actualObj = {}, query = '') {
  const requestedObj = graphQlQueryToJson(query).query
  assignValuesToObjectKeys(requestedObj, actualObj)
  return requestedObj
}

Usage example

const { grabPartialObject } = require('./some/helper/file')

const myFridge = {  
	weekOldPasta: {  
		noodleSogginess: “high”,  
		numMeatballs: 4,  
		isEdible: false,  
	},  
	panSearedSalmon: {  
		oilUsed: “avocado”,  
		numSpices: 3,  
		isEdible: true,  
	}
}

const whatsEdible = grabPartialObject(myFridge, `{
  weekOldPasta {
    isEdible
  }
  panSearedSalmon {
    isEdible
  }
}`)
console.log(whatsEdible)
/* 👉 {
	weekOldPasta: {
		isEdible: false,
	},
	panSearedSalmon: {
		isEdible: true,
	},
}
*/

Sexy, accessible show-hide animations in any web framework

Mon, 24 May 2021 20:01:36 GMT

Using JS to show and hide something is a web dev rite of passage. Heck, it's the first demo that comes to mind when you think about "state management" (just behind building a counter 😆).

But when you do the classic "hide whenever X variable is false," there's some accessibility concerns you might be forgetting:

can keyboard users still access that hidden element?
do screen readers actually know what your button is trying to show and hide?

Don't worry, I have the answers for you! Let's explore a universal solution you can bring to React, Svelte, Vue, etc, along with some debugging tips using a real screen reader 🚀

Starting with a naive solution

Okay, wait, why isn't this post a 2 minute read? I just whipped up this fade transition in a CodePen and it works great!

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

If you don't recognize this meme, go culture yourself

I'll admit that a simple opacity shift works pretty well for non-interactable elements like this img. But what if you're showing and hiding clickable elements, like a navigation bar of links?

This can spell problems for those using keyboard navigation or screenreaders. It's (embarrassingly) a problem across some of my own sites that I'm working to fix, but it can be tricky to debug.

Here's an example of hitting the tab key through our Hack4Impact.org site. I've adjusted the dropdown overlay to opacity: 0.1 to show which items are focused, but you can expect the same behavior for opacity: 0:

Follow either the focus ring around the elements, or the activeElement query in the console view (which prints the element being focused)

Uh oh, I'm still able to focus and select these links! What's more, our opacity solution poses a problem for visually impaired users, since they won't know that our visual opacity shift really means showing and hiding a dropdown.

What we really want is the best of all worlds:

A nifty fade in-and-out animation for sighted users
The ability to focus interactable links and buttons only when the element is revealed
A callout for screenreaders whenever we show and hide something

⌨️ Let's accommodate keyboard users

Note: This section only applies when showing / hiding interactable elements like a list of links.

Focusing on that tab key first, we need to find a way to make sure that a not-so-visible element can't be accessed at all.

You might remember a nifty property for this already: display: none. This makes element nonexistent in the document, right?

Well it's worth a shot! Let's toggle to display: none when our element is hidden, and add display alongside opacity in our list of transitions.

We'll be using this basic navigation dropdown as fuel for the rest of our code examples. Nothing fancy on the JS + HTML sides! The important piece are those .dropdown and .dropdown.expanded selectors in our CSS. That's where we toggle between our display states like so:

.dropdown {
	opacity: 0;
	display: none;
}
.dropdown.expanded {
	opacity: 1;
	/* since we're using flexbox in our dropdown */
	display: flex;
	/* to (hopefully) fade from expanded to collapsed in 0.2 seconds */
	transition: opacity 0.2s, display: 0.2s;
}

Full example:

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

But wait, where's our fade transition? Sorry to say this is the big limitation of the display property: it cannot be used in CSS transitions ( full list of animatable CSS properties here) This means, when we toggle off our expanded class, it immediately switches to display: none (ignoring our 0.2s transition) before our opacity has time to sexily fade out 😥

What we need is a way to toggle off display only after our element fades out of view. And no, we can't use keyframes to set up this sequence. But fear not! There's a neat property called visibility that can do exactly what we want. Just hot swap display: none for visibility: hidden and update the transition:

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

And BAM! Our fade animation remains in-tact, but we've successfully hidden our element from keyboard-ists 👍

You can click on that CodePen preview above and start hitting tab to test our solution. Your focus should immediately jump from the hamburger button to the CodePen zoom controls, instead of trying to focus those invisible links. And once you focus the button, hit space, and start tabing through, those links become selectable.

💡 Note: There is 1 subtle difference between display: none and visibility: hidden. When using the former, an element gets completely removed from the document, so any elements next to it will shift to take up the space it left behind. By contrast, visibility: hidden just hides the element visually, while leaving the gap for where it used to sit. This prevents your website layout from shifting around when you toggle elements on and off.

👁 Let's accommodate screen readers

Okay, so we know what our website looks like... but what does it sound like? 🤔

Well, I'd recommend breaking out a screen reader for this next part! You can reach for the VoiceOver tool if you're running MacOS, but there's also a screen reader for Chrome you can try on any computer.

If you're interested, you can follow along with this video walkthrough to see the VoiceOver tool in action 👇

Communicating toggle states with `aria-expanded`

Our navigation toggle button is the first issue to address. If you try expanding and collapsing our menu as-is, the screenreader won't read anything new to the user. This is because, well, it's a plain old button at the moment. We need to tell our reader that it's actually an on-off toggle.

We can pull this off by adding an aria-expanded attribute to our button. This boolean should call out whether our menu is in the "expanded" or "collapsed" state. Just set the initial state in our HTML:

<!-- collapsed by default -->
<button aria-expanded="false" aria-label="Nav toggle" class="toggle-dropdown">

And keep that value up-to-date wherever we're tracking button clicks. Here's a basic version for plain-JS:

const toggle = document.querySelector(".toggle-dropdown");
toggle.addEventListener("click", () => {
  // toggle our CSS class
  dropdown.classList.toggle("expanded");
  // and if our "expanded" class is turned on...
  if (dropdown.classList.contains("expanded")) {
	// set aria-expanded to true
    toggle.setAttribute("aria-expanded", "true");
  } else {
	// otherwise it's false
    toggle.setAttribute("aria-expanded", "false");
  }
});

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

VoiceOver output as we toggle our button. Notice we get a new announcement for every click saying either "expanded" or "collapsed"

You can also add the attribute aria-haspopup="true" to your button. This will just added the word "popup" to the screenreader output to make behavior just a bit more understandable. Optional, but recommended!

Focusing our dropdown on expanded

Note: This should only be used when showing / hiding interactable elements. If you're just revealing images or paragraphs, the aria-expanded piece should be sufficient!

So now we're telling the user that they're expanding and collapsing something. But what is this something their actually toggling?

Sadly, there's no straightforward way to tell the user "you just expanded my fancy dropdown!" There is an aria-controls attribute you can try, but it's only supported by the premium JAWS screen reader (which many users don't have access to).

So, we're going to offer the next best thing: just focus the first element in our dropdown to read out the contents immediately. This means shifting keyboard focus (yes, visually impaired users tend to navigate navigate using a keyboard) from our menu button to our first link whenever aria-expanded="true". Of course, this only applies when revealing interactable elements like buttons or links, so it should

Should be simple enough! Just add a call to focus() whenever we expand the element, right?

toggle.addEventListener("click", () => {
  if (dropdown.classList.contains("expanded")) {
	// use firstElementChild to grab the first link
	dropdown.firstElementChild.focus()
    toggle.setAttribute("aria-expanded", "true");
  } else {
	  ...
});

Well, this doesn't work super reliably when we have our fancy CSS transition. There's a chance we'll try to focus the first link while visibility is still hidden, which prevents our focus() call from going through 😕

Luckily, there's an easy way to "wait" on our CSS transition to finish before setting focus. We just need to listen for the transitionend event on our dropdown like so:

dropdown.addEventListener('transitionend', () => {
  if (dropdown.classList.contains("expanded")) {
	// instead of calling focus() in our 'click' listener,
	// we'll call it from here!
    dropdown.firstElementChild.focus()
  }
})

With this in place, we should get reliable link focusing with a matching screen reader output 👍

Finished product

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

⚙️ Applying this to your favorite framework

We've covered a lot of ground using plain JS, but it's quick-and-easy to apply to any component framework!

We just need a couple pieces:

an expanded state variable to keep track of showing / hiding
a callback to focus() our first dropdown element on transitionend. For most frameworks, we can just attach a callback function to an element's onTransitionEnd attribute.

A simple React solution

import { useState } from "react";

export default function DropdownExample() {
  const [expanded, setExpanded] = useState(false);
  const focusFirstDropdownLink = ({ target }) => {
	// if we apply this function to our dropdown,
	// the "target" should be a reference to the dropdown itself!
    target.firstElementChild.focus();
  };
  return (
    <>
      <nav>
        <button
          className="toggle-dropdown"
          aria-expanded={expanded}
          aria-haspopup="true"
          aria-label="Nav toggle"
          onClick={() => setExpanded(!expanded)}
        >
          ...
        </button>
      </nav>

      <div
		{/*toggle our "expanded" CSS class*/}
        className={expanded ? "dropdown expanded" : "dropdown"}
		{/*trigger our focus() once the dropdown's fade effect finishes*/}
        onTransitionEnd={focusFirstDropdownLink}
      >
        <a href="/">Home</a>
        <a href="/about">About</a>
        <a href="/projects">Projects</a>
        <a href="/contact">Contact</a>
      </div>
    </>
  );
}

Pretty straightforward rewrite! The ability to bind our focus() function to the onTransitionEnd listener saves us a lot of work. We don't even need a useRef to grab the element, in fact.

Here's a working sandbox demo for you to try 🚀

Svelte example

This should be equally trivial in Svelte:

<script>	
	let expanded = false;
	
	const focusFirstDropdownLink = ({ target }) => {
	    // again, "target" should be a reference to our dropdown
		target.firstElementChild.focus()
	}
</script>

<style>
...
</style>

<nav>
	<button class="toggle-dropdown" aria-expanded={expanded} aria-haspopup="true" aria-label="Nav toggle" on:click={() => expanded = !expanded}>
		<svg viewBox="0 0 448 512" width="100" title="bars">
      <path d="M16 132h416c8.837 0 16-7.163 16-16V76c0-8.837-7.163-16-16-16H16C7.163 60 0 67.163 0 76v40c0 8.837 7.163 16 16 16zm0 160h416c8.837 0 16-7.163 16-16v-40c0-8.837-7.163-16-16-16H16c-8.837 0-16 7.163-16 16v40c0 8.837 7.163 16 16 16zm0 160h416c8.837 0 16-7.163 16-16v-40c0-8.837-7.163-16-16-16H16c-8.837 0-16 7.163-16 16v40c0 8.837 7.163 16 16 16z" />
    </svg>
	</button>
</nav>

<!--Note we can use class:expanded to bind our "expanded" CSS class to the "expanded" state variable-->
<div class="dropdown" class:expanded on:transitionend={focusFirstDropdownLink}>
	<a href="/">Home</a>
	<a href="/about">About</a>
	<a href="/projects">Projects</a>
	<a href="/contact">Contact</a>
</div>

Here's another working sandbox demo for you to try 🚀

Want CSS variables in media query declarations? Try this!

Wed, 12 May 2021 14:01:23 GMT

If you're like me, you've probably been stretching CSS variables / custom properties to their limits while building your own design systems. But this "silver bullet" can lead to a nasty roadblock: you can't use them in media query declarations.

To clarify, this is the behavior you might want:

:root {
	--mobile-breakpoint: 600px;
	--tablet-breakpoint: 900px;
}

@media(max-width: var(--mobile-breakpoint)) {
	.obligatory-hamburger-menu { visibility: visible }
}

...which sadly won't work.

Why var() can't work in a @media declaration

This may seem confusing at first. If our variables are declared at the :root of the page, why can't a media query access them?

Well, it comes down to what the :root selector actually means: the root element of the HTML document. Unlike CSS selectors, media queries aren't attached to HTML elements at all; they belong to the global scope.

If this seems confusing, let's consider a CSS variable like this one on the body element:

body {
	--mobile-breakpoint: 600px;
}
@media(max-width: var(--mobile-breakpoint)) { /* ... */ }

Since our @media query is global, it cannot know about this --mobile-breakpoint variable. This extends to the :root selector as well.

SASS / SCSS can make this even more confusing by allowing @media blocks to be nested inside of other rulesets. Don't be fooled! When your SASS gets compiled, those media queries will be hoisted to the base of your CSS document.

For SASS and SCSS users: use SASS variables for media queries

If you're using SASS or SCSS, I recommend falling back to SASS variables for media queries and using CSS variables everywhere else.

This is because, unlike CSS variables, SASS variables are replaced at build-time with the values you set. This allows the SASS compiler to find-and-replace all instances of a variable, including variables referenced by @media query declarations.

@media (min-width: $mobile-breakpoint) { /* ... */ }
/* compiled output: */
@media (min-width: 600px) { /* ... */ }

Build-time replacement means you won't be able to dynamically update the value of a SASS variable from JavaScript. Still, you can use SASS variables to define static values in a design system like a $mobile-breakpoint.

Note that you'll need to fall back to Sass for math calculations as well, instead of using the dynamic calc() function:

/* ✅ good */
@media(max-width: $mobile-breakpoint + 50px) { /* ... */ }
/* ❌ bad */
@media(max-width: calc($mobile-breakpoint + 50px)) { /* ... */ }

For everyone else: use the incoming CSS environment variables spec

The W3C community isn't happy about the limitations of CSS variables either. Their proposal for environment variables addresses this very issue, letting you declare static variables that can be read from @media queries.

Browsers have followed this level 1 spec to let you read environment variables via the env() function. Similar to var(), you can call env() to read a variable's value like so:

@media (min-width: env(...)) { /* ... */ }

Before you go off and use it, there's a surprising show-stopper: you can't declare variables of your own yet 😅 Browser engines like webkit include a set of predefined environment variables for a different use case: setting the allowed area for notification popups when building web apps. Useful, but it doesn't address our @media query dilemma.

PostCSS polyfill for declaring environment variables

Luckily, there's a PostCSS plugin to let you define custom environment variables with a similar syntax to CSS variables. Install the plugin with npm like so:

npm install postcss postcss-env-function --save-dev

And define variables from your PostCSS configuration using the environmentVariables object:

postcssEnvFunction({
    environmentVariables: {
        '--mobile-breakpoint': '600px',
    },
})

Then, you can refer to variables from @media breakpoints using the env() function:

@media (min-width: env(--mobile-breakpoint)) { /* ... */ }

This has the same limitation as SASS variables: values are set at build-time and can't be updated dynamically. That also means dynamic functions like calc() won't work in @media queries. Still, this is a helpful workaround to reference environment variables using the familiar CSS variable syntax.

⚠️ Word of caution: This PostCSS plugin is a "stage 0" prototype, and it may not match browser behavior if environment variable declarations come to native CSS. Be sure to document your usage of this plugin and keep an eye on the spec for updates.

Picture perfect image optimization for any web framework

Tue, 04 May 2021 20:01:36 GMT

If you've been building websites for a while, "optimize your images" probably sounds like "eat your veggies." It's good for your website's health, it'll make your SEO big and strong... but compressing every image by hand doesn't sound appetizing to me 🤢

So we're going to talk easy wins for 1) optimizing image file formats and sizes with the picture element, and 2) an automation process using 11ty that you can take with you to your build setup of choice 💪

💁 Intended audience: This is meant for developers building "template-driven" static sites (11ty, Jekyll, Hugo, plain HTML) or "component-driven" web apps (NextJS, Gatsby, etc). If you're working with site builders like Wordpress or Shopify, this probably isn't the article for you!

🥦 So what's wrong with my images right now?

To show what's at stake, here's the lighthouse rating from one of my recent blog posts (images compressed with tinyJPG mind you!)

Yikes! 10 seconds to grab all those images? Chromium definitely does some throttling to test on "slower" internet connections, but it's clear those KB rating are quite high (especially for mobile users).

This just to show that there's much more to image optimization than compression! There's also:

Serving the right format, with JPGs preferrable and .webp or .avi especially so
Serving the right size, ideally with multiple copies of the same image at different widths and heights
Loading at the right time, reaching for "lazy" loading when we can
Heck, even including alt text can affect your site from both accessibility and SEO standpoints

I learned a bit about addressing those format and size problems using picture elements, and my lighthouse definitely thanked me for it 😄

Dang, at first my performance on https://t.co/iTZUPe5aBp was getting destroyed by a *ton* of fat JPGs I never condensed down (especially on blog posts). Installed @eleven_ty 's image plugin, put in an hour of work... and just look at it 🤩 pic.twitter.com/l5GLACk8F7
— Ben Holmes (@BHolmesDev) April 5, 2021

🌅 Fixing format + size problems with the `picture` element

So how can we deliver different image files for the right people? Well, let's start with a humble image element like this one:

<img src="/assets/mega-chonker.jpg" width="1000" height="600" alt="A perfectly sized cat" />

<details><summary>Chonk level chart</summary>

</details>

Now, say we've opened our image editor and saved a smaller version for mobile users sitting at, say, 600 pixels wide. You could probably set up some CSS to hot-swap your images depending on your screen width:

<img class="desktop" src="/assets/chonker-1000w.jpg"
    width="1000" height="600" alt="A perfectly sized cat" />
<img class="mobile" src="/assets/chonker-600w.jpg"
    width="600" height="300" alt="A perfectly sized cat" />

@media(max-width: 600px) {
  .desktop { display: none; }
}
@media(min-width: 601px) {
  .mobile { display: none }
}

...But this isn't very scalable. What if we're, say, working in a markdown file where we can't append class names? Or we have different formats we want to switch between depending on browser support (JPEG vs WEBP for example)?

This is where the picture element comes in. Take this example here:

<picture>
  <!-- List out all the WEBP images + WEBP sizes we can choose from -->
  <source type="image/webp"
    srcset="/assets/chonker-600w.webp 600w, /assets/chonker-1000w.webp 1000w"
    sizes="100vw">
  <!-- In case a browser doesn't support WEBP, fall back to this set of JPG sources -->
  <source type="image/jpeg"
    srcset="/assets/chonker-600w.jpg 600w, /assets/chonker-1000w.jpg 1000w"
    sizes="100vw">
  <!-- The actual, style-able img element that "receives" these sources -->
  <!-- Also includes a default src in case no <source> can be applied -->
  <img src="/assets/chonker-600.png" alt="A perfectly sized cat" />
</picture>

Some big takeaways:

We can wrap our image tags in a picture to unlock a "switch" case of sorts, with your browser picking the first source element that it's able to render. But admittedly, most modern browsers will reach for those shiny .webp files listed under type="image/webp" without needing the JPG fallbacks (current browser support here).
Each source has a srcset property, which takes in a list of source URLs for a given image format. These sources are comma-separated, plus a pixel-value width using that w on the end. The browser will then decide which source to use based on the sizes property (more on that in the next section)
Picture elements are not images themselves! This is an interesting gotcha when you start trying to style those images. So, you'll want to keep putting all your image-specific CSS (ex. object-fit) on that img element instead of the picture.

The `sizes` attribute

Sizes is an interesting beast. It almost looks like CSS actually, with some small syntax differences.

Remember those mobile and desktop helper classes from earlier? Well, sizes let us do something rather similar.

Key takeaways from the video:

In general, the sizes attribute is a way to tell the browser which image to use for a given screen size.

Let's say we have a banner image that takes up the full width of the screen for mobile users, but we have a table of contents that takes up half the width at 500px wide and above.

Putting on our CSS hat, this means our image is 100vw (100% screen width) below 500px, and 50vw when we hit @media (min-width: 500px). This perfectly translates to sizes 👉 sizes="(min-width: 500px) 50vw, 100vw"

And in the context of a picture element:

<picture>
  <!--stack up your media queries as sizes, delineated by commas ","-->
  <source type="image/webp"
    srcset="/img/6dfd7ac6-600.webp 600w, /img/6dfd7ac6-900.webp 900w..."
    sizes="(min-width: 500px) 50vw, 100vw">
  <img alt="Blue and purple cluster of stars" src="/img/6dfd7ac6-600.jpeg">
</picture>

As a rule-of-thumb, you should probably use 100vw as a "base case" for smaller devices, and rack up media queries on top depending on how your layout changes. This does mean sizes will be different depending on the context your images are living in, so look out for that if you're using a component-based framework!

Note: You may be wondering why browsers can't do all this work for us. Well, this comes down to the unpredictable nature of "width" when you're throwing around CSS everywhere. If you're like me, you tend to use a lot of percentages like width: 100% for image blocks, which may adjust depending on the container, padding, margins, etc that get applied. If the browser tried to decipher all this styling before loading an image, you'd be waiting a lot longer than you might want!

Respecting HD displays

Note that our screen's pixel density can also affect which image gets picked from a given srcset. For high-density mobile displays, it'll actually choose an image that's roughly double the width you specify! Say we have a simple picture declaration like this for instance:

<picture>
  <source type="image/webp"
    srcset="/img/galaxy-600.webp 600w, /img/galaxy-1200.webp 1200w"
    sizes="100vw">
</picture>

We're using 100vw here, so the browser should match the image source's width to the width of the display. Intuitively, we'd think that a 600px wide display would receive /img/galaxy-600.webp... but for HD displays like Macbooks or modern smartphones, it'll actually reach for an image at 600 x 2 pixels wide (/img/galaxy-1200.webp 1200w in this case). So when you're generating multiple image sizes, always reach for those higher values 💡

🔨 Applying this to your site with 11ty image

Alright, so we see how useful the picture element can be... but it's only as powerful as the pictures we can supply to it. Do we really want to create all those beautifully resized, optimized, multi-format images by hand?

Luckily, there's a lot of tools to handle this process for us, and I'm going to hone in on the simplest I've found: 11ty's image plugin.

🚨 Now before you start scrolling to the next section, no, you don't need to build your site with 11ty to use this. Playing around with this tool, I realized it's perfect for generating optimized images on-the-fly for any use case, no command line prowess required 🔥

Generating optimized images

Let's play along at home! Seriously, drop everything and go open your code editor 🧑‍💻 Then, make a fresh directory / folder and create a basic package.json. We'll be installing the @11ty/eleventy-img dependency:

mkdir woah-11ty-image-is-cool && cd woah-11ty-image-is-cool
npm init -y # Make a package.json with defaults for everything
npm i @11ty/eleventy-img

Now make a random JavaScript file for us to play with (I'll call mine image-generator.js). Inside, just paste the example code at the top of 11ty's documentation:

const Image = require("@11ty/eleventy-img");

(async () => {
  let url = "https://images.unsplash.com/photo-1608178398319-48f814d0750c";
  let stats = await Image(url, {
    widths: [300]
  });

  console.log(stats);
})();

Hm, this looks pretty straightforward. Let's run it from our terminal and see what happens:

node ./image-generator.js

With any luck, you should see a couple new faces appear:

A /img directory with 2 images inside: 1 JPG picture of a galaxy that's 300 pixels wide, and a matching webp image of the same size. Notice how this matches up with our widths array from the code snippet 👀
A /cache directory with some strings of characters. Think of this like a note-to-self for the plugin about the image we downloaded. It's expensive to download images off the internet, so to avoid loading it every time we run the script, 11ty checks the cache to see if we've already loaded the image in the past 👍

You'll also see a blob of "stats" logged to your console. Most of these properties are self-explanatory, and some should look familiar from our picture walkthrough earlier on (namely the sourceType and srcset attributes). We even get the output size of the image in bytes, in case you want to inspect the differences between formats and sizes.

But wait, there's more! Let's try experimenting with different widths and formats:

...
let stats = await Image(url, {
  widths: [300, 1000, 1400],
  formats: ['jpg', 'webp', 'gif']
});
...

We should get a plethora of resolutions inside that img directory. As you can imagine, this is perfect for our picture element from earlier. You can whip up all the sources and size attributes by hand as a learning exercise...

Automating our picture elements

...Or let the plugin do this for us! Along with that handy array of stats, 11ty image will splice everything into a valid <picture> element. All we need is a call to the generateHTML helper:

const Image = require("@11ty/eleventy-img");

(async () => {
  let url = "https://images.unsplash.com/photo-1608178398319-48f814d0750c";
  let stats = await Image(url, {
    widths: [300, 1000, 1400]
  });
  const html = Image.generateHTML(stats, {
  	alt: "A blue and purple galaxy of stars", // alt text is required!
	sizes: "100vw" // remember our training with "sizes" from earlier...
  })

  console.log(html);
})();

With any luck, we should see a beautiful picture we can use anywhere on our site:

<picture>
	<source type="image/webp"
          srcset="/img/6dfd7ac6-300.webp 300w, /img/6dfd7ac6-1000.webp 1000w,
                  /img/6dfd7ac6-1400.webp 1400w"
          sizes="100vw">
	<source type="image/jpeg"
          srcset="/img/6dfd7ac6-300.jpeg 300w, /img/6dfd7ac6-1000.jpeg 1000w,
                  /img/6dfd7ac6-1400.jpeg 1400w"
          sizes="100vw">
	<img alt="A blue and purple galaxy of stars" src="/img/6dfd7ac6-300.jpeg" width="1400" height="1402">
</picture>

Going further

This plugin has a whole host of extra options to explore too, like

messing with cache options for faster build times
generating image stats + picture elements synchronously, so you don't have wait for the images to actually get generated
fine-tuning the Sharp image processor to tweak the output to your needs

📣 Using 11ty image with any framework

If all this <picture> madness excites you, go throw this 11ty image plugin at your own /assets directory! I wrote this handy little script to crawl all the images in a directory (not recursively mind you) and spit out some optimized files:

const Image = require('@11ty/eleventy-img')
const { readdir } = require('fs/promises') // node helper for reading folders
const { parse } = require('path') // node helper for grabbing file names

;(async () => {
  const imageDir = './images' // match this to your assets directory
  const files = await readdir(imageDir)
  for (const file of files) {
    const stats = await Image(imageDir + '/' + file, {
      widths: [600, 1000, 1400], // edit to your heart's content
      filenameFormat: (id, src, width, format) => {
        // make the filename something we can recognize.
        // In this case, it's just:
        // [original file name] - [image width] . [file format]
        return `${parse(file).name}-${width}.${format}`
      },
    })
    console.log(stats) // remove this if you don't want the logs
  }
})()

If you happen to use 11ty on your personal site (or at least want to try), you can automate the picture element insertion as well. Their guide covers building your own "shortcode" function to insert the right picture for every unoptimized image on your site.

Even without this luxury though, this script is a great addition to any JS-based build step. Here's a basic Image component I could slap into any React app based on that script above:

// consider using TypeScript for checking all these props!
const Image = ({ fileName, sizes, ...imageProps }) => (
	<picture>
	  <source
		type="image/webp"
		srcSet={`/img/${fileName}-600.webp 600w, /img/${fileName}-1000.webp 1000w, /img/${fileName}-1400.webp 1400w`}
		sizes={sizes}
	  />
	  <source
		type="image/jpeg"
		srcSet={`/img/${fileName}-600.jpeg 600w, /img/${fileName}-1000.jpeg 1000w, /img/${fileName}-1400.jpeg 1400w`}
		sizes={sizes}
	  />
	  <img src={`/img/${fileName}-600.jpeg`} {...imageProps} />
	</picture>
)

Assuming all my images get generated with this file naming convention (and I always have images at 600, 1000, and 1400 widths), this should pull all our optimized images no problem 👍

Here's a brief rundown on applying these learnings to create-react-app:

Go try it yourself

You can check out a running example of create-react-app + 11ty image in this CodeSandbox 🪄

This version will listen for new images during development as well. Feel free to fork the source code to try in your own project (and find the edge cases I inevitably missed 😉).

Other options for Next, Nuxt, Gatsby and more

As cool as 11ty image can be, I should definitely highlight some "native" options for popular meta-frameworks:

For Next, their built-in Image component is perfect. They'll also cover our sizes, formats, and image compression automatically, plus some neat props for eagerly loading images that are "above the fold" using priority.
For Nuxt, their <nuxt-img> and <nuxt-picture> components should have you covered. These offer most of the same benefits as our 11ty image plugin, letting you specify different formats, a sizes attribute, and background image compression. Just be sure to use nuxt-picture if you want to allow multiple image formats instead of just one!
For Gatsby, you've got the gold standard of image optimization 🏆 Their image plugin was actually my main reason for using the framework a few years back, and it's only gotten better. The nicest feature (beyond matching everything we've talked about) is their loading animations for images. You can fade in over vector traces of an image, use a blur effect, and a lot more. The only downside is the hefty JS bundle it loads into the browser to pull this off, which I've given my opinions on over here.
Beyond the framework, you can optimize remotely using something like Cloudinary. This is a great option if you don't own the build process for your website, or don't want to store your images inside your code repository. For example, you can point all your Wordpress images to a cloudinary bucket and pull different image widths and formats for there. The only downside is the cost, since Cloudinary is doing all this image processing and storage for you.

How ES Modules have redefined web development

Wed, 31 Mar 2021 20:01:36 GMT

You know the inspirational phrase "skate to where the puck is going?" Well, in web development... it feels like the puck is teleporting across the rink at Mach 30 sometimes.

That's how I felt diving into how ES Modules work. Turns out, there's been some huge shifts right under my framework-laden nose these past few years. After discovering that this is valid JS across all major browsers...

const js = await import('script.js')

...I had to make a post about it. So let's explore

🥞 My misconceptions about what bundlers do these days
🧩 What ES Modules + dynamic imports can do
🚀 How build tools are evolving for the post-IE era

Onwards!

Foreward: Personal delusions in a webpack world

What I'm sharing here is probably common knowledge to some. Heck, import-able JavaScript modules have lurked in the ECMAScript standard since 2017! But if you've been using "traditional" project configs like create-react-app for a long time, you might think that old-school bundling is how the world works.

So let me ahem unpack the traditional definition of "bundling." In short, it's the concept of taking a chain of JS files like this:

// toppings.js
export {
  blueberries: async () => await fetch('fresh-from-the-farm'),
  syrup = "maple",
}

// ingredients.js
export { flour: 'white', eggs: 'free-range', milk: '2%', butter: 'dairy-free' }

// pancake.js
import { blueberries, syrup } from './toppings'
import { flour, eggs, milk, butter } from './ingredients'

const pancake = new Pancake()

pancake.mixItUp([ flour, eggs, milk, butter ])
pancake.cook()
pancake.applyToppings([ blueberries, syrup ])

And "flattening" the import / export chains into a big bundle pancake 🥞

// bundler-output-alksdfjfsadlf.js
const toppings__chunk = {
  blueberries: async () => await fetch('fresh-from-the-farm'),
  syrup = "maple",
}

const ingredients__chunk = { flour: 'white', eggs: 'free-range', milk: '2%', butter: 'dairy-free' }

const { blueberries, syrup } = toppings__chunk
const { flour, eggs, milk, butter } = ingredients__chunk
const pancake = new Pancake()

pancake.mixItUp([ flour, eggs, milk, butter ])
pancake.cook()
pancake.applyToppings([ blueberries, syrup ])

So we're compressing all the JavaScript files we're developing into a single file for the browser to consume. Back in 2015-era web development, this really was the only way to pull off "importing" one JS file into another. import wasn't even valid JavaScript! It was just some neat trickery that build tools like webpack could pick up and understand.

But silently, in the depths of the ES spec, import and export syntax did become valid JavaScript. Almost overnight, it became feasible to leave all your import and export statements in your code or even gasp ditch your JS bundler entirely 😨

This innovation became what we call modules.

ES Modules

There's an in-depth article from MDN on this topic that's well worth the read. But in short, "ES Modules" (sometimes denoted by .mjs files) are JavaScript files with some exported values for others to import and use. As long as you load your "entry" files with the type="module" attribute:

<script type="module" src="pancake.js"></script>

That file is ready to import all the other scripts it wants! Well, as long as those other scripts exist in your project's build of course (we'll ignore CORS issues for now 😁).

This concept of importing what's needed over "flattening all the things" has some nice benefits:

You don't need to load and parse everything up front. By default, anything imported is "deferred" for loading as needed. In other words, your computer won't turn into a fighter jet trying to load JS when you first visit your website.
The need for tooling like webpack can (one day) disappear ✨ Bringing browsers closer to how humans write their code is a huge win for newbies and pros alike 🏆

Dynamic imports take it a step further

Dynamic imports are the spicier side of ES Modules that really make things interesting. As this article from the V8 team describes (creators of Google Chrome's rendering engine), a dynamic import is an asynchronous fetch for some JavaScript whenever you need it.

It's very similar to the fetch API in a way! But instread of grabbing some JSON or plain text, we're grabbing some real, executable code that we want to run.

All you need is a humble one-liner:

const lookAtTheTime = await import('./fashionably-late.js')

...and you just grabbed all the exports from that file. Loading JS on-the-fly like this has a ton of benefits if you're working with single page apps like NextJS or create-react-app. The V8 team offered this elegantly simple take on client-side routing, only loading the JS you need when you click on a link:

const links = document.querySelectorAll('nav > a');
for (const link of links) {
  link.addEventListener('click', async (event) => {
    try {
      // go grab whatever JS the route may need
      const module = await import(`${event.target.href}/script.mjs`);
      // The module exports a function named `loadPageInto`,
      // Which might render some HTML into the body
      module.loadPageInto(document.body);
    } catch (error) {
      document.body.innerHTML = `
        <p>404 page not found</p>
      `
    }
  });
}

I basically just implemented a router in 10 lines of code. (yes, that's a serious overstatement, but it's closer than you might think).

This falls into code splitting, aka loading "components" (or modules) of code whenever the user needs them. Back in the dark ages of bundle all-the-things, you'd have to load all these components up front. This could mean thousands of lines of dead code!

So wait, it's 2021... why does all my tooling look the same?

This was certainly my first question when I read up on this. I recently graduated from create-react-app to NextJS as my React boilerplate go-to, but there's still that same webpack configuration + bundle process to think about 🤷‍♀️

A lot of this is just the curse of abstraction. Looking under the hood, these tools have made great strides since ES modules hit the scene. Namely, tools like NextJS can magically "split" your React app into bite-sized chunks that get loaded as-needed. This means:

only load the JS for a page when you actually visit that page
only load React components when they actually need to display
(bonus) pre-fetch JS when someone is likely to need it. This is a more advanced feature (documented here), but it lets you do all sorts of craziness; say, grabbing resources for a page when you hover over link

There's also the benefit of backwards compatibility when using a bundler. For instance, Internet Explorer has no concept of "modules" or "import" statements, so any attempt to code split will blow up in your face 😬 But with a meta-framework like NextJS by your side, you can polyfill such use cases without having to think about it.

Approaching the post-IE age

If you haven't heard, a major announcement sent ripples through the web dev community recently: Microsoft will officially drop IE 11 support for its products in August 2021 😱

Many are treating this as the ticking timebomb for legacy browser support. When it goes off... we might be safe to lose our polyfills for good. Yes, certain sites for governments and internal business operations will probably stick to their PHP-laced guns. But for us bleeding-edge developers, we may have a whole new frontier to explore 🚀

A world of bundlers that... don't bundle

The tides have certainly shifted in the JS bundler community in the past year. With the prospect of dropping polyfills and aggressive bundling for good, people started turning to the real reasons you want a bundler:

To process all your fanciness that isn't valid JS. Think JSX for React components, TypeScript for type checking, Styled Components and CSS modules for CSS-in-JS, etc etc.
To spin up your app locally. You could always open HTML files in your browser directly, but you'll loose all that immediate feedback! You should see all your new JS and CSS the millisecond you hit "save."
To optimize code for production. You'll probably want some last-minute stripping for added speed, like removing console.logs, minifying everything, linting, and so on.

Because of this refined feature set, the new wave of JS processors are just calling themselves "build tools" to stay more generalized.

Snowpack is really what got the ball rolling from my perspective. They promise all the selling points I listed above, plus the absolute fastest live-reloading in the biz. This is mainly because of that code splitting I mentioned earlier. Since they leave all those modules and dynamic imports in-tact, they avoid re-processing the JavaScript that didn't change. So if you just updated a single React component, it'll reprocess those 10 lines of code and blast it onto the page in a flash ⚡️

Vite is a major contender to note as well. This one was spearheaded by Evan You (the overlord of VueJS) to tackle a similar feature set to Snowpack. It's far too early to say whether I'd prefer this setup to Snowpack, but here's a nice comparison piece if you're considering either for serious apps.

There's also the crazy world of using different programming languages to process your code. ESBuild is a big contender right now, using GoLang to process JavaScript in no time flat.

Call to action: explore these new build tools!

It's definitely worth your time to whip up a sandbox and start compiling some code. Vite's create-app tool is a great one for it's beginner friendliness, with options to use any major framework out-of-the-box (React, Vue, Svelte, and even Lit Element!).

I was caught off guard to find there's no build directory when working in development. The code your write gets mapped to the browser directly, processed on-the-fly whenever you save ❤️

So go forth and see what the future is like! With any luck, we'll get to have our bundle pancake and eat it too 😁

4 Git shortcuts that define my workflow

Thu, 18 Feb 2021 23:38:56 GMT

I started my first full-time job as a programmer this year, which means I've been picking up a lot of new tricks in a pretty quick timeframe. Naturally, I started automating the workflows I use day-in and day-out 😁

Stop me if you've seen this workflow before:

I picked up a ticket on JIRA
I need to pull the latest main branch
I need to checkout a new branch
I need to push that branch to origin before opening my PR

I'll probably do this 5+ times in one day if we're in a bug-squashing flow. But when I'm hurrying, it's so easy to either a) work off an old "main" branch, or b) do the copy-paste of shame before your PR:

To push the current branch and set the remote as upstream, use

    git push --set-upstream origin crap-not-again

You know you cringe a little every time this pops up 😬

So let's discuss:

🍾 The importance of pushing and popping your stash

🙈 The joys of upstream HEAD

🧶 Writing aliases for your terminal to tie it all together

Onwards!

The fantastic 4 aliases

Alright, let's do the big reveal. Here's my 4 shortcuts for slamming through daily tasks 💪

# Stash what I'm working on and checkout the latest master
alias gimme="git stash push -u && git checkout main && git pull -r"

# Grab the latest master and come back to the branch I was on (with stashing!)
alias yoink="gimme && git checkout - && git stash pop"

# Checkout a new branch and push it to origin (so I don't forget that set-upstream)
woosh() {
  git checkout -b $1 && git push -u origin HEAD
}

# ALL TOGETHER NOW
# Stash my current WIP, checkout a new branch off the latest master, and push it to origin
alias boop="gimme && woosh"

These commands are written in bash. So if you want to use these in your own terminal, go find your bashrc and paste away! This is usually found in your user directory: ~/.bashrc. And for all you windows users out there: you'll probably need to install the Git Bash terminal (included with Git) and create the file like so.

✋ But wait! Before you blindly copy these, let's unpack each of them a little.

`gimme` ✊

alias gimme="git stash push -u && git checkout main && git pull -r"

This is my "return to home base" command. It assumes you might not be on the main branch just yet, so it'll stash everything you're working on using the stash command. It also saves "untracked" / new files with the -u flag.

Next, it checks out your main branch and pulls the latest contents. That -r flag will be sure to "rebase" onto the latest, preventing unecessary merge conflicts.

This is the simplest command of the bunch, but it's also my most-used! On my team, we run a lot of automated scripts on pull for installing dependencies and pulling content from our CMS. So, it's super useful to return to main and grab all this new content in one go.

`yoink` 🎣

alias yoink="gimme && git checkout - && git stash pop"

This phrase is certainly a close relative to gimme. For some etymology, I'll include the urban dictionary entry on what it means to yoink:

An exclamation that, when uttered in conjunction with taking an object, immediately transfers ownership from the original owner to the person using the word regardless of previous property rights.

...In other words, we are grabbing the main branch and bringing it back to the branch we're on 😁 We pull this off using the git checkout - command after running gimme. This is super convenient for grabbing the latest changes to force rebase the branch we're working on.

💡 Note: is easy to achieve with a fetch command as well:

git fetch origin master:master

...but if your team runs automated scripts whenever you pull, you'll probably want the original command I described.

Clarification on using `stash` vs `stash push`

You also may be new to using push and pop on your stash, instead of apply and clear (as I often used to do). Here's the distinction:

Whenever you run "vanilla" git stash, you're merging your current changes with all the other changes in the stash. Think of this like throwing all your belongings in a bag, and git stash apply is like dumping everything out onto the floor.
Whenever you run git stash push, you're putting your current changes in a separate compartment from all the other changes in the stash. Think of this like choosing a different bag pocket every time you go to "stash" something. Then, when you pop, you pull from the last pocket you just used.

This is the reason we use push inside the gimme command, and pop inside the yoink command. It guarantees that we grab the same thing we just stashed, without getting mixed up with anything already in your stash. If you've ever dug around your bag trying to find one tiny thing stuck at the bottom, you know what I'm talking about here 😁

`woosh` 💨

woosh() {
  git checkout -b $1 && git push -u origin HEAD
}

This is the solution to your --set-upstream woes. Instead of pushing to origin later, this lets you check out a new branch and push right away so you don't forget.

Yes, there's some cases when you don't want your local branch on the remote just yet, but this is pretty rare in my experience. I often create a branch corresponding to a given task on our Kanban board that I'm ready to push up right away.

And if you've never seen the HEAD parameter before... remember that one! It's a super slick way to auto-fill the name of your current branch instead of typing it out by hand 🔥

`boop` 👇

alias boop="gimme && woosh"

Shout out to "lord of boops" Jason Lengstorf for the inspiration

This command goes full-circle. If you're somehow too lazy to check out the latest main branch before starting anew, this will let you gimme and woosh all in one go!

Not much to explain with this one. Just go forth into perfect boop-dom.

4 Conference talks that changed my perspective as a web dev

Wed, 10 Feb 2021 21:44:22 GMT

I've resolved to make 2021 my biggest year of learning yet. My blogging game has been pretty sporadic up until now... but I've finally decided to go all-in on the learning in public mantra with 1 post a week!

I used to believe blog posts had to be shining nuggets of wisdom only I could find. But with all the notes I take on a weekly basis, why not share my journal with the world too? 😁

So, here's some of the most impactful conference talks I've found in the last year or so. I hope to check-in with more entries in the future, and I'd love to hear your own favorite talks in the comments!

Rich Hickey - Simple Made Easy 🧶

🎥 View the talk + transcript here

If you've ever heard the someone say that something is "easy, but not simple," this is probably the talk they're referencing. This is an easy recommend to programmers in general (not just web devs). That said, I think this talk is especially relevant to frontend-ers nowadays with all the tools at our disposal.

It feels like web frameworks and "best practices" are moving towards some powerful new opinions:

Everything is a component
Functional programming is king
State management is complex and deserves a rethink (hello state machines 👋)

☝️ These are the points Rich was getting at with this talk a decade ago! This is why I've resisted this talk multiple times throughout my web dev journey. As a junior getting comfortable with enterprise-grade React apps, it's helped me understand the why behind my team's architectural decisions.

Personal notes

Simple is an objective measure, no matter the person, reflecting how many interwoven pieces (complexity) there are in a given system
Easy is relative to every individual, reflecting how "familiar" or "near at hand" something feels
Agile programming encourages us to move fast without taking a step back
- Complexity and tech debt pile up when we ignore signs of bad abstraction
- Favorite quote of the talk: "But programmers fire the starting pistol every 100 yards and call it a (new) sprint!"
Replace complecting (knotted-up code with lots of interdependent pieces) with composing (modularity a la modern frontend frameworks)
- Think building a castle from Legos instead of a "knitted castle" from interweaving
- Separate horizontally, stratify vertically
Concrete improvements to make
- "Stateful" variables complect values with change overtime; make transition from one state to another predictable (see state machines
- Stay close to what the system does; consider the behavior over implementation details
  - Example: Declarative over imperative programming
  - Example: test-driven-development done right (incredible talk by Ian Cooper here)
- Work with rules over conditional / switch case spaghetti
  - Given some data X, here's some rules to make it become Y
  - Lean on pure functions, which give you a consistent output for a given input

Dan Abramov - The Wet Codebase 🌊

🎥 View the talk + transcript here

Here's another architecture-y talk that also reaches far beyond web development. If you're unfamiliar with Dan Abramov, he's one of the most prolific members of the React core team from a teaching standpoint alone. So if you want advice on architecting your web apps, this is your guy 😁

This talk goes hand-in-hand with Kent C Dodd's post on "AHA programming". Generally, they're both addressing the biggest pitfall of component-based thinking: copy / paste feels like bad practice, so you abstract every piece of logic to its own little file.

Sure there's a place for abstraction, but there's also a place for duplication! This talk has a lot of examples and funny quotables to keep things light; definitely worth the watch.

Personal notes

If left unchecked, abstractions can become Frankenstein code overtime
- An abstraction almost fits are use case, but not quite 👉 we wittle away that round hole to fit our square peg
- When bugs arise for one use case, we introduce fixes affecting tons of other use cases
👍 When abstraction is good
- Makes your code more declarative / focus on a specific intent (see that Rich Hickey talk above 😉)
- Avoids missed bug fixes 👉 fix it once, fix everywhere
👎 When abstraction is bad
- Creates coupling - when it doesn't quite fit, you can create a monster of refactors
- Adds indirection - creates layers and layers overtime; "We avoid spaghetti code, but we create lasagna code" 🇮🇹
Ways to improve going forward
- Test code that uses an abstraction, not the abstraction itself
  - If you remove that abstraction later, your tests explode!
  - Abstractions are just another implementation detail (again, TDD is king)
- Don't commit to abstraction layers until you need them; "If a girl is into the same obscure bands as you are... that doesn't mean you're meant to be together"
- Be ready to remove abstractions later; Be the one asking "Please inline this abstraction!" in a PR review!

Rich Harris - Rethinking Reactivity ⚛️

In my opinion, this is the biggest bombshell to drop since React was first revealed 💣

A trigger warning is probably in order here: if you're a diehard React follower, this talk questions many practice React holds dear (including the virtual DOM itself!).

But even if you disagree with Rich's points, this talk is a serious landmark in the web framework canon. It also exposes what "bundlers," "compilers," and "reacting to change" all really mean under the hood. If you aren't convert to a Svelte fan after this, you'll at least understand where the web has been, and where it might be heading!

Personal notes

What is reactive programming?
- It all started with spreadsheets
  - I change a value in one cell, and other cells "react" to those changes with formulas
  - Earliest example of only re-rendering values that change
- It's 1) about tracking values and 2) updating dependents on that value
Problem with React's model
- When state changes in a component, that whole component re-evaluates itself from the top
- Treats your HTML like a black box; apply the change, then diff against the previous chunk
- Really, React doesn't know about your "state values" or how they affect the DOM!
- Bad signs for efficiency: I shouldn't need useMemo, useCallback, shouldComponentUpdate, etc
Instead of opting out of reevaluating state (a la useMemo), we could opt in by flagging state variables that depend on other state variables
- Much like a spreadsheet; write formulas that flag which variables affect a given value
- Svelte uses a custom $: operator to "flag" state that is computed from other state (example here)
Svelte is a compiler, not a runtime
- In other words, a "Svelte" component compiles to JS your browser understand
- No "runtime" (like React's virtual DOM) needs to get imported
- Also means Svelte can bend the JS language to its will
  - Evan You, creator of VueJS - Svelte is too magical, since it lets you write JavaScript that isn't totally valid
  - Rich Harris' response - this opinion is like believing HTML, CSS and JS should live in separate files. CSS-in-JS is weird too, so what's wrong with this?
Some other cool demos of Svelte
- CSS scoping by component just by using a <style> tag
- Transition directives with sensible out-of-the-box options

Shawn "swyx" Wang - Getting Closure on React Hooks 🎣

This is a fast-paced and code-heavy talk, so you'll probably want 1x speed on this one.

That said... this is the most enlightening talk I've seen on React. Period. It's only 30 minutes long, but it gave me holistic understanding on how React hooks, state management, and re-rendering all work together. It also shows some huge use cases for "closure" in JS. If you have a web dev interview coming up, point to this! 😉

Personal notes

Hard to write a succinct, bulleted list for this one. So, I just annotated the finished product to explain how everything works. Fair warning: it's a lot to take in!

🚀 Functioning codepen to see it in action

const React = (function () {
  // create an array for all the state variables in our "React app"
  let stateValues = [];
  // start our state index at 0. We'll use this
  // to throw state into that array ☝️ everytime someone calls "useState"
  let index = 0;
  function useState(initValue) {
    // state should be set to either:
    // 1. the initial value (aka React.useState(initValue))
    // if this is the first time our component rendered
    // 2. the value from the *last* render
    // if we're re-rendering our component (aka stateValues[index])
    const state = stateValues[index] || initValue;
    // "freeze" our index to this particular useState call with _index.
    // prevents the index from changing before we try to call setState later!
    const _index = index;
    const setState = (newValue) => {
      stateValues[_index] = newValue;
    };
    // increment index so our next useState call doesn't override the state
    // we just stored above
    index++;
    return [state, setState];
  }
  function render(Component) {
    // every time we re-render our app,
    // update all our state variables starting from the top
    index = 0;
    const C = Component();
    // "render" the component (which calls the useState function)
    C.render();
    return C;
  }
  // return all our functions from this foe React "module"
  return { useState, render };
})();

function Component() {
  const [count, setCount] = React.useState(2);
  return {
    // whenever we "render" this component with React.render, 
    // just log the value of our state variable
    render: () => console.log({ count }),
    click: () => setCount(count + 1)
  };
}

let App = React.render(Component) // logs { count: 2 }
App.click() // sets the state at stateValues[0] to 3
App.click() // sets the state at stateValues[0] to 4
React.render(Component) // logs { count: 4 }

Another way to understand JavaScript's array.reduce

Fri, 05 Feb 2021 16:26:05 GMT

If you've run the guantlet of array methods in JavaScript, you've probably hit this roadblock a few times:

Wait, how do I use the reduce function again?

I actually led a JS bootcamp with this topic for my college's Hack4Impact chapter (material 100% free-to-use here!). Questions on reduce have come up so many times, and I think I've finally found an explanation that clicks 😁 Hope it works for you too!

🎥 Video walkthrough

If you prefer to learn by video tutorial, this one's for you. You can fork this CodePen for the source material to follow along 🏃‍♂️

📝 Step-by-step cheatsheet

Let's walk our way to reduce by using what we know: good ole' for loops.

Here's an example. Say we have our favorite album on a CD (remember those? 💿), and our stereo tells us the length of each track in minutes. Now, we want to figure out how long the entire album is.

Here's a simplified approach for what we want to do:

// make a variable to keep track of the length, starting at 0
let albumLength = 0
// walk through the songs on the album...
album.songs.forEach(song => {
  // and add the length of each song to our running total
  albumLength += song.minutesLong
})

No too bad! Just loop over the songs, and accumulate the album runtime while we walk through the songs. This is basically the process you'd use in real life, tallying up the album length as you skip through the tracks on your stereo.

That word "accumulate" is pretty significant here though. In essence, we're taking this list of track lengths, and reducing them to a single accumulated number: the albumLength. This process of reducing to an accumulator should set off a light bulb in your head: 💡 we can use array.reduce!

Going from `forEach` to `reduce`

Let's try reduce-ifying our function from earlier. This is a simple, 4 step process:

Change forEach to reduce:

let albumLength = 0
album.songs.reduce((song) => {
  albumLength = albumLength + song.minutesLong
})

Move albumLength to the first parameter of the loop function, and the initial value (0) to the second parameter of reduce

// accumulator up here 👇
album.songs.reduce((albumLength, song) => {
  albumLength = albumLength + song.minutesLong
}, 0) // 👈 initial value here

Change albumLength = to a return statement. This isn't too different conceptually, since we're still adding our song length onto our "accumulated" album length:

album.songs.reduce((albumLength, song) => {
  // 👇 Use "return" instead of our = assignment
  return albumLength + song.minutesLong
}, 0)

Retrieve the result of our reduce loop (aka our total album length). This is just the value returned:

const totalAlbumLength = album.songs.reduce((albumLength, song) => {
  return albumLength + song.minutesLong
}, 0)

And that's it! 🎉

So wait, why do I even need `reduce`?

After all that work, reduce might feel like a slightly harder way of writing a for loop. In a way... it kind of is 😆

It offers one key benefit though: since reduce returns our total, function chaining is a lot easier. This may not be a benefit you appreciate right away, but consider this more complex scenario:

// Say we have this array of arrays,
// and we want to "flatten" everything to one big array of songs
const songsByAlbum = [
  ['Rap Snitches Knishes', 'Beef Rap', 'Gumbo'],
  ['Accordion', 'Meat Grinder', 'Figaro'],
  ['Fazers', 'Anti-Matter', 'Krazy World']
]
let songs = []
songsByAlbum.forEach(albumSongs => {
  // "spread" the contents of each array into our big array using "..."
  songs = [...songs, ...albumSongs]
})

This isn't too hard to understand. But what if we want to do some more fancy array functions on that list of songs?

// Ex. Make these MF DOOM songs titles all caps
let songs = []
songsByAlbum.forEach(albumSongs => {
  songs = [...songs, ...albumSongs]
})
const uppercaseSongs = songs.map(song => song.toUppercase())

This is fine, but what if we could "chain" these 2 modifications together?

// grab our *final* result all the way at the start
const uppercaseSongs = [
  ['Rap Snitches Knishes', 'Beef Rap', 'Gumbo'],
  ['Accordion', 'Meat Grinder', 'Figaro'],
  ['Fazers', 'Anti-Matter', 'Krazy World']
]
// rewriting our loop to a "reduce," same way as before
.reduce((songs, albumSongs) => {
  return [...songs, ...albumSongs]
}, [])
// then, map our songs right away!
.map(song => song.toUppercase())

Woah! Throwing in a reduce, we just removed our standalone variables for songsByAlbum and songs entirely 🤯

Take this example with a grain of salt though. This approach can hurt the readability of your code when you're still new to these array functions. So, just keep this reduce function in your back pocket, and pull it out when you could really see it improving the quality of your code.

Also, if this helped you out, you can learn more about ❤️ Hack4Impact here.

A shiny-on-hover effect that follows your mouse (CSS) ✨

Thu, 28 Jan 2021 17:40:13 GMT

Hover states are probably the most fun a developer can have when a designer isn't looking. You've seen the basics at this point; fade-ins, growing and shrinking, color shifts, animated rainbow gradients, etc etc etc.

But there was one animation that inspired me recently (props to Keyframers for shouting it out!)

It's Astro Community Day! 🥳
You might be wondering...

Who are some 💯 Astro contributors?
Where does Astro's sponsorship 💰 go?
How does Astro give back to OSS?

Let's get into it! A thread 🧵 pic.twitter.com/PrCThabHYM
— Astro (@astrodotbuild) April 7, 2022

This isn't some "static" hover state that always looks the same. It actually tracks your mouse moment to make the page even more interactive. This seemed like such a cool idea... that we threw it all over our Hack4Impact site 😁

So let's explore

🎈 Why CSS variables can help us
✨ How we style our button
🪤 How we map mouse movements to a metallic shine
🔨 How to adapt this animation to any UI framework

Onwards!

🎈 Brief primer on CSS variables

In case you haven't heard, CSS variables are kind of taking web development by storm right now. They're a bit like those $ variables preprocessors like SASS and LESS let you pull off, but with one huge benefit: you can change the value of these variables at runtime using JavaScript 😱

Let's see a simple example. Say we want to make a balloon pump, where you hit a button as fast as you can to "inflate" an HTML-style balloon.

If we didn't know anything about CSS variables, we'd probably do some style manipulation straight from JavaScript. Here's how we'd pump up a balloon using the transform property:

const balloon = document.querySelector('.balloon');
// make the balloon bigger by 50%
balloon.style.transform = 'scale(1.5)';

Or, to make the balloon just a little bit bigger on every button click:

...
const pump = document.querySelector('.pump')
// keep track of the balloon's size in a JS variable
let size = 1;
pump.addEventListener('click', () => {
  size += 0.1;
	balloon.style.transform = `scale(${size})`;
})

There's nothing wrong with this so far. But it has some growing pains:

We need to keep track of a CSS property (the balloon's scale size) using a JS variable. This could ahem balloon into a suite of state variables overtime as we animate more elements throughout our app.
We're writing our CSS using strings. This leaves a sour taste in my mouth personally, since we loose all our syntax highlighting + editor suggestions. It can also get nasty to maintain when we want that size variable in other parts of our styles. For example, what if we wanted to change the background-position as the balloon inflates? Or the height and width? Or some linear-gradient with multiple color positions?

CSS variables to the rescue

As you may have guessed, we can store this size from our code as a CSS variable!

We can use the same .style attribute as before, this time using the setProperty function to assign a value:

let size = 1;
pump.addEventListener('click', () => {
  size += 0.1;
	balloon.style.setProperty('--size', size);
})

Then, slide that variable into our transform property from the CSS:

.balloon {
  /* set a default / starting value if JS doesn't supply anything */
  --size: 1;
  ...
  /* use var(...) to apply the value */
  transform: scale(var(--size));
}

Heck, you can ditch that size variable entirely and make CSS the source of truth! Just read the value from CSS directly whenever you try to increment it:

pump.addEventListener('click', () => {
  // Note: you *can't* use balloon.style here!
  // This won't give you the up-to-date value of your variable.
  // For that, you'll need getComputedStyle(...)
	const size = getComputedStyle(balloon).getPropertyValue('--size');
  // size is a string at this stage, so we'll need to cast it to a number
  balloon.style.setProperty('--size', parseFloat(size) + 0.1)
})

There's some caveats to this of course. Namely, CSS variables are always strings when you retrieve them, so you'll need to cast to an int or a float (for decimals) as necessary. The whole .style vs. getComputedStyle is a little weird to remember as well, so do whatever makes sense for you!

Here's a fully working example to pump up your confidence 🎈

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

✨ Let's get rolling on our shiny button

Before putting our newfound CSS variable knowledge to the test, let's jump into the styles we'll need for this button.

Remember that we want a smooth gradient of color to follow our mouse cursor, like a light shining on a piece of metal. As you can imagine, we'll want a radial-gradient on our button that we can easily move around.

We could add a gradient as a secondary background on our button (yes, you can overlay multiple backgrounds on the same element!). But for the sake of simplicity, let's just add another element inside our button representing our "shiny" effect. We'll do this using a pseudo-element to be fancy 😁

.shiny-button {
  /* add this property to our button, */
  /* so we can position our shiny gradient *relative* to the button itself */
  position: relative;
  /* then, make sure our shiny effect */
  /* doesn't "overflow" outside of our button */
  overflow: hidden;
  background: #3984ff; /* blue */
  ...
}

.shiny-button::after {
  /* all pseudo-elements need "content" to work. We'll make it empty here */
  content: '';
  position: absolute;
  width: 40px;
  height: 40px;
  /* make sure the gradient isn't too bright */
	opacity: 0.6;
  /* add a circular gradient that fades out on the edges */
	background: radial-gradient(white, #3984ff00 80%);
}

Side note: You may have noticed our 8-digit hex code on the gradient background. This is a neat feature that lets you add transparency to your hex codes! More on that here.

Great! With this in place, we should see a subtle, stationary gradient covering our button.

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

🪤 Now, lets track some mouse cursors

We'll need to dig into some native browser APIs for this. You probably just listen for click 99% of the time, so it's easy to forget the dozens of other event listeners at our disposal! We'll need to use the mousemove event for our purposes:

const button = document.querySelector('.shiny-button')
button.addEventListener('mousemove', (e) => {
	...
})

If we log out or event object, we'll find some useful values in here. The main one's we're focusing on are clientX and clientY, which tell you the mouse position relative to the entire screen. Hover over this button to see what those values look like:

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

This is pretty useful, but it's not quite the info we're looking for. Remember that our shiny effect is positioned relative to the button surrounding it. For instance, to position the effect at the top-left corner of the button, we'd need to set top: 0; left: 0; So, we'd expect a reading of x: 0 y: 0 when we hover in our example above... But this definitely isn't the values that clientX and clientY give us 😕

There isn't a magical event property for this, so we'll need to get a little creative. Remember that clientX and clientY give us the cursor position relative to the window we're in. There's also this neat function called getBoundingClientRect(), which gets the x and y position of our button relative to the window. So if we subtract our button's position from our cursor's position... we should get our position relative to the button!

This is probably best explored with visuals. Hover your mouse around to see how our mouse values, boundingClientRect values, and subtracted values all interact:

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

💅 Pipe those coordinates into CSS

Alright, let's put two and two together here! We'll pass our values from the mousemove listener:

button.addEventListener("mousemove", (e) => {
  const { x, y } = button.getBoundingClientRect();
  button.style.setProperty("--x", e.clientX - x);
  button.style.setProperty("--y", e.clientY - y);
})

Then, we'll add some CSS variables to that shiny pseudo-element from before:

.shiny-button::after {
  ...
  width: 100px;
  height: 100px;
  top: calc(var(--y, 0) * 1px - 50px);
  left: calc(var(--x, 0) * 1px - 50px);
}

A couple notes here:

We can set a default value for our variables using the second argument to var. In this case, we'll use 0 for both.
CSS variables have a weird concept of "types." Here, we're assuming we'll pass our x and y as integers. This makes sense from our JavaScript, but CSS has a hard time figuring out that something like 10 really means 10px. To fix this, just multiply by the unit you want using calc (aka * 1px).
We subtract half the width and height from our positioning. This ensures that our shiny circle is centered up with our cursor, instead of following with the top left corner.

Fade into our effect on entry

We're pretty much done here! Just one small tweak: if we leave this animation as-is, our shiny effect will always show in some corner of our button (even when we aren't hovering).

We could fix this from JavaScript to show and hide the effect. But why do that when CSS lets you style-on-hover already?

/* to explain this selector, we're */
/* selecting our ::after element when the .shiny-button is :hover-ed over */
.shiny-button:hover::after {
  /* show a faded shiny effect on hover */
  opacity: 0.4;
}
.shiny-button::after {
  ...
  opacity: 0;
  /* ease into view when "transitioning" to a non-zero opacity */
  transition: opacity 0.2s;
}

Boom! Just add a one-line transition effect, and we get a nice fade-in. Here's our finished product ✨

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

🔨 Adapt to your framework of choice

I get it, you might be dismissing this article with all the eventListeners thinking well, I'm sure that JS looks much different in framework X. Luckily, the transition is pretty smooth!

First, you'll need to grab a reference to the button you're shine-ifying. In React, we can use a useRef hook to retrieve this:

const ShinyButton = () => {
  // null to start
  const buttonRef = React.useRef(null)
  React.useEffect(() => {
    // add a useEffect to check that our buttonRef has a value
    if (buttonRef) {
      ...
    }
  }, [buttonRef])
  
  return <button ref={buttonRef}>✨✨✨</button>
}

Or in Svelte, we can bind our element to a variable:

<script>
  import { onMount } from 'svelte'
  let buttonRef
  // our ref always has a value onMount!
  onMount(() => {
    ...
  })
</script>

<button bind:this={buttonRef}>✨✨✨</button>

Aside: I always like including Svelte examples, since they're usually easier to understand 😁

Once we have this reference, it's business-as-usual for our property setting:

React example

const ShinyButton = () => {
  const buttonRef = React.useRef(null)
  // throw your mousemove callback up here to "add" and "remove" later
  // might be worth a useCallback based on the containerRef as well!
  function mouseMoveEvent(e) {
    const { x, y } = containerRef.current.getBoundingClientRect();
    containerRef.current.style.setProperty('--x', e.clientX - x);
    containerRef.current.style.setProperty('--y', e.clientY - y);
  }

  React.useEffect(() => {
    if (buttonRef) {
      buttonRef.current.addEventListener('mousemove', mouseMoveEvent)
    }
    // don't forget to *remove* the eventListener
    // when your component unmounts!
    return () => buttonRef.current.removeEventListener('mousemove', mouseMoveEvent)
  }, [buttonRef])
  ...

Svelte example

<script>
  import { onMount, onDestroy } from 'svelte'
  let buttonRef
  // again, declare your mousemove callback up top
  function mouseMoveEvent(e) {
    const { x, y } = buttonRef.getBoundingClientRect();
    buttonRef.style.setProperty('--x', e.clientX - x);
    buttonRef.style.setProperty('--y', e.clientY - y);
  }
  onMount(() => {
		buttonRef.addEventListener('mousemove', mouseMoveEvent)
  })
  onDestroy(() => {
    buttonRef.removeEventListener('mousemove', mouseMoveEvent)
  })
</script>

The main takeaway: 💡 don't forget to remove event listeners when your component unmounts!

Check out our live example on Hack4Impact

If you want to see how this works in-context, check out this CodeSandbox for our Hack4Impact site. We also added some CSS fanciness to make this effect usable on any element, not just buttons ✨

To check out the component, head over here.

And if this helped you out, you can learn more about ❤️ Hack4Impact here.

Mocking browser APIs in Jest (localStorage, fetch and more!)

Tue, 19 Jan 2021 22:48:29 GMT

I hit a snag recently trying to test a localStorage helper written in React. Figuring out how to test all my state and render changes was certainly the easy part (thanks as always React Testing Library 🐐).

But soon, I found myself wondering... is there an easy way to "mock" a browser API like storage? Or better yet, how should I test any function using X API?

Well, hope you're hungry! We're gonna explore

🚅 Why dependency injection doesn't feel like a silver bullet
📦 How we can mock localStorage using the global object
📶 Ways to go further mocking the fetch API
🔎 An alternative approach using jest.spyOn

Onwards!

Let's grab something to eat first

Here's a simple (and tasty) example of a function worth testing:

function saveForLater(leftoverChili) {
  try {
		const whatsInTheFridge = localStorage.getItem('mealPrepOfTheWeek')
    if (whatsInTheFridge === undefined) {
      // if our fridge is empty, chili's on the menu 🌶
     	localStorage.setItem('mealPrepOfTheWeek', leftoverChili) 
    } else {
      // otherwise, we'll just bring it to our neighbor's potluck 🍽
      goToPotluck(leftoverChili)
    }
  } catch {
    // if something went wrong, we're going to the potluck empty-handed 😬
    goToPotluck()
  }
}

This is pretty straightforward... but it's got some localStorage madness baked-in. We could probably start with the inject all the things strategy (TM) to address this:

function saveForLater(leftoverChili, {
  // treat our storage calls as parameters to the function,
  // with the default value set to our desired behavior
  getFromStorage = localStorage.getItem('mealPrepOfTheWeek'),
  setInStorage = (food) => localStorage.setItem('mealPrepOfTheWeek', food) 
}) => {
  try {
    // then, sub these values into our function
    const whatsInTheFridge = getFromStorage()
    ...
    setInStorage(leftoverChili)
		...
}

Then, our test file can pass some tasty mock functions we can work with:

it('puts the chili in the fridge when the fridge is empty', () => {
  // just make some dummy functions, where the getter returns undefined
  const getFromStorage = jest.fn().mockReturnValueOnce(undefined)
  // then, make a mock storage object to check
  // whether the chili was put in the fridge
  let mockStorage
  const setInStorage = jest.fn((value) => { mockStorage = value })
  
	saveForLater('chili', { getFromStorage, setInStorage })
  expect(setInStorage).toHaveBeenCalledOnce()
  expect(mockFridge).toEqual('chili')
})

This isn't too bad. Now we can check whether our localStorage functions get called, and verify that we're sending the right values.

Still, there's something a bit ugly here: we just restructured our code for the sake of cleaner tests! I don't know about you, but I feel a little uneasy moving the internals of my function to a set of parameters. And what if the unit tests move away or get rewritten years down the line? That leaves us with another odd design choice to pass onto the next developer 😕

📦 What if we could mock browser storage directly?

Sure, mocking module functions we wrote ourselves is pretty tough. But mocking native APIs is surprisingly straightforward! Let me stir the pot a little 🥘

// let's make a mock fridge (storage) for all our tests to use
let mockFridge = {}

beforeAll(() => {
  global.Storage.prototype.setItem = jest.fn((key, value) => {
    mockFridge[key] = value
  })
  global.Storage.prototype.getItem = jest.fn((key) => mockFridge[key])
})

beforeEach(() => {
  // make sure the fridge starts out empty for each test
  mockFridge = {}
})

afterAll(() => {
  // return our mocks to their original values
  // 🚨 THIS IS VERY IMPORTANT to avoid polluting future tests!
	global.Storage.prototype.setItem.mockReset()
  global.Storage.prototype.getItem.mockReset()
})

Oh, take a look at that meaty piece in the middle! There's some big takeaways from this:

Jest gives you a nice global object to work with. More specifically, Jest gives you access to JSDOM out-of-the-box, which populates global (a standard in Node) with a treasure trove of APIs. As we've discovered, it includes our favorite browser APIs as well!
We can use the prototype to mock functions inside a JS class. You're right to wonder why we need to mock Storage.prototype, rather than mocking localStorage directly. In short: localStorage is actually an instance of a Storage class. Sadly, mocking methods on a class instance (i.e. localStorage.getItem) doesn't work with our jest.fn approach. But don't fret! You can mock the entire localStorage class as well if this prototype madness makes you feel uneasy 😁 Fair warning though: it's a bit harder to test whether class methods were called with toHaveBeenCalled compared to a plan ole' jest.fn.

💡 Note: This strategy will mock both localStorage and sessionStorage with the same set of functions. If you need to mock these independently, you might need to split up your test suites or mock the storage class as previously suggested.

Now, we're good to test our original function injection-free!

it('puts the chili in the fridge when the fridge is empty', () => {
	saveForLater('chili')
  expect(global.Storage.prototype.setItem).toHaveBeenCalledOnce()
  expect(mockStorage['mealPrepOfTheWeek']).toEqual('chili')
})

There's almost no setup to speak of now that we're mocking global values. Just remember to clean the kitchen in that afterAll block, and we're good to go 👍

📶 So what else could we mock?

Now that we're cooking with crisco, let's try our hand at some more global functions. The fetch API is a great candidate for this:

// let's fetch some ingredients from the store
async function grabSomeIngredients() {
  try {
  	const res = await fetch('https://wholefoods.com/overpriced-organic-spices')
  	const { cumin, paprika, chiliPowder } = await res.json()
		return [cumin, paprika, chiliPowder] 
  } catch {
    return []
  }
}

Seems simple enough! We're just making sure that the Cumin, Paprika, and Chili Powder get fetched and returned in an array of chili spices 🌶

As you might expect, we're using the same global strategy as before:

it('fetches the right ingredients', async () => {
  const cumin = 'McCormick ground cumin'
  const paprika = 'Smoked paprika'
  const chiliPowder = 'Spice Islands Chili Powder'
  let spices = { cumin, paprika, chiliPowder, garlicSalt: 'Yuck. Fresh garlic only!' }
  
  global.fetch = jest.fn().mockImplementationOnce(
    () => new Promise((resolve) => {
      resolve({
        // first, mock the "json" function containing our result
        json: () => new Promise((resolve) => {
          // then, resolve this second promise with our spices
          resolve(spices)
        }),
      })
    })
  )
  const res = await grabSomeIngredients()
  expect(res).toEqual([cumin, paprika, chiliPowder])
})

Not too bad! You'll probably need a second to process that doubly-nested Promise we're mocking (remember, fetch returns another promise for the json result!). Still, our test stayed pretty lean while thoroughly testing our function.

You'll also notice that we used mockImplementationOnce here. Sure, we could have used the same beforeAll technique as before, but we probably want to mock different implementations for fetch once we get into the error scenarios. Here's how that might look:

it('returns an empty array on bad fetch', async () => {
    global.fetch = jest.fn().mockImplementationOnce(
      () => new Promise((_, reject) => {
        reject(404)
      })
    )
    const res = await fetchSomething()
    // if our fetch fails, we don't get any spices!
    expect(res).toEqual([])
  })
  it('returns an empty array on bad json format', async () => {
    global.fetch = jest.fn().mockImplementationOnce(
      () => new Promise((resolve) => {
        resolve({
          json: () => new Promise((_, reject) => reject(error)),
        })
      })
    )
    const res = await fetchSomething()
    expect(res).toEqual([])
  })

And since we're mocking implementation once, there's no afterAll cleanup to worry about! Pays to clean your dishes as soon as you're done with them 🧽

🔎 Addendum: using "spies"

Before wrapping up, I want to point out an alternative approach: mocking global using Jest spies.

Let's refactor our localStorage example from before:

...
// first, we'll need to make some variables to hold onto our spies
// we'll use these for clean-up later
let setItemSpy, getItemSpy

beforeAll(() => {
  // previously: global.Storage.prototype.setItem = jest.fn(...)
	setItemSpy = jest
    .spyOn(global.Storage.prototype, 'setItem')
    .mockImplementation((key, value) => {
      mockStorage[key] = value
    })
  // previously: global.Storage.prototype.getItem = jest.fn(...)
  getItemSpy = jest
    .spyOn(global.Storage.prototype, 'getItem')
    .mockImplementation((key) => mockStorage[key])
})

afterAll(() => {
  // then, detach our spies to avoid breaking other test suites
  getItemSpy.mockRestore()
  setItemSpy.mockRestore()
})

Overall, this is pretty much identical to our original approach. The only difference is in the semantics; instead of assigning new behavior to these global functions (i.e. = jest.fn()), we're intercepting requests to these functions and using our own implementation.

This might feel a little "safer" to some people, since we're not explicitly overwriting the behavior of these functions anymore. But as long as you pay attention to your cleanup in the afterAll block, either approach is valid 😁

Leaving Notion to build a second brain in VS Code

Mon, 11 Jan 2021 22:34:17 GMT

Okay, I'll be honest: I have a serious problem with notetaking apps. I've whipped through every service imaginable for a few months each... but I've never truly felt "at home."

I think this is my problem above all: I need to write something down, but I don't know what magical folder / page / service / tag to stuff it into. So, I just choose the first note app I find on whatever device I'm using. I swear to myself I'll move it to the right place someday, but the thought of organizing everything is too overwhelming to take action 😬

So, let's talk about:

🙅‍♂️ Why Notion isn't cutting it for me
📜 What the second brain / Zettelkasten method is
🕺 How Foam + VS Code helped me find a groove with personal notetaking

Onwards!

Why not Notion?

Notion has quickly become the go-to recommendation for personal notes and journals. There's definitely a lot to fall in love with from a developer's perspective:

Easy to whip up code snippets with syntax highlighting
Easy export to markdown
Tons of integration options for data tables, if you're into that kind of thing
Keyboard shortcuts galore

etc etc etc. But from what I've found, getting into Notion is a lot like getting into Vim. You spend 30% of your time in efficiency heaven, and another 70% setting up the tool itself! As a UI designer and developer myself, I just can't deal with all these knobs and switches. It's so tempting to tweak everything to perfection... and once the dust has settled, I still can't find that code snippet I made a week ago 😔

I also don't see any updates helping me from this perspective. My problem is really the fundamental approach of Notion: let the user build their own UI with as much flexibility as possible. I don't really need all this flexibility if I'm just journaling my thoughts and todos.

Ignoring the bells and whistles doesn't help much either

Yes of course, I can just cast away my temptations and stick to basic note pages. But this still doesn't address other elephants in the room.

First, fuzzy finding notes isn't the easiest. Notion did add a "quick find" option that helps, but dang, the load times are still pretty slow 😢 Just trying to find a page by its name, I've waited a few beats before finding the result I'm looking for (or no results at all). I expect this to improve overtime of course. But since the data is owned by Notion instead of your personal machine, there's always going to be loading spinners.

I also can't shake the niceties of VS Code. Right now, Notion doesn't offer options to globally find using regex, search by "directory" (or parent pages in Notion I suppose), or other useful tools developers take for granted. And let's not forget the shortcuts while you're editing! Find-and-replace, or multi-cursors, quickly bumping lines higher or lower? Truly a text editor's greatest hits.

My dream workflow

With all that aside, let's get to the heart of what I really want:

Go from zero to writing a note with no effort. Ideally, I just whip up a new file without worrying where it goes
Easily find my notes later. Fuzzy find, tags, file names... whatever it takes.
Keep the UI simple! A vast majority of the time, markdown syntax is all I need to get my ideas down.

Turns out, there's an entire notetaking strategy that addresses these concerns!

Enter the second brain 🧠

I'd been hearing about this concept for a while now, but never realized it's an actual strategy to notetaking. As you'd expect, it's all about writing as much as possible so you can, well, have a second brain in note form.

This concept starts with the Zettelkasten Method used back in the pen-and-paper ages. It's built on some pretty basic principles:

Every note is treated as a unique collection of thoughts, tagged by a unique ID of some sort
Notes should form an ever-sprawling tree of connected ideas / thoughts. This is pulled off with "links" between notes (references to those unique IDs), much like hyperlinks on the web!
You may index multiple "trees" of notes with tags or tables of contents, assuming your Zettelkasten grows pretty large

There's countless nuggets of advice on how to do a Zettelkasten right. But overall, it's clear that a physical Zettelkasten maps perfectly to how the web works. So, why not use a bunch of HTML files to create one? Or better yet, markdown files?

Let's get back to basics with VS Code + Foam

If we're gonna simplify our notetaking process, there's nothing simpler than a text editor 😁

I discovered a project called Foam recently that's... not really a stand-alone project; it's a collection of extensions that work well together, with some helpful guides on how to make the most of them.

All you need to do is clone a repository and watch the magic happen! It'll recommend all the extensions you should need to edit, link, and view your notes. But at the end of the day, you're really just writing a bunch of markdown files on your computer. Let's understand how powerful this can really be:

Getting a birds-eye view 🗺

It's worth discussing a crucial part of the Foam style of notetaking: you never need to group notes by directory. We're so used to using file systems to organize everything, but let's be honest, that's not how our brain works!

Foam thrives on connecting notes with links, rather than folder hierarchies. This makes it much easier to define notes that might be referenced in a ton of places. Instead of finding the exact directory where a note lives, you just need to reference the file itself.

Foam will help you find any patterns that naturally emerge from links with a graph visualization extension. It's basically one big map of your head that you can click into and explore!

This is the graph generated by my recent challenge to learn Rust lang. Notice how this doesn't quite match up to a parent-child relationship that directory trees demand. For instance, "Intro to structs" on the far left gets referenced by "Enums" and "Rust ownership." But you couldn't have the same file sitting in multiple directories at once! That's the beauty of using free-form links; anything can reference anything else, so it's less of a tree and more of a purposeful, tangled-up birds nest.

Solving the "I need to write this ASAP" problem

This beautiful graph solves our organization paralysis from earlier! Now that we've ditched the whole directory paradigm, there's a much lower barrier to entry when writing down something new.

And if we happen to write a note that doesn't reference any other notes, no worries! Our graph visualization will help us find those stragglers later on. This helped me consolidate some stray notes on books and podcasts into a table of contents like so:

# The Logs

This is where I'll record everything I consume that _taught me something._ Topic? Doesn't matter. Length of the summary? Could be a couple words. Just need to record everything I possibly can!

## Podcasts
- **11-28-20** [[writing-for-software-developers-with-Philip-Kiely]]

## Blog posts
- **12-20-20** [[Kent-C-Dodds-Avoiding-re-renders a-useDebounce-example.md]]

## Books
- **11-26-20** [[the-dark-forest-Cixin-Liu]]
- **12-29-20** [[the-case-against-education-bryan-caplan]]

...

Side note: If you haven't read the Three Body Problem, do it. It's unlike anything I've seen before.

This fixes a painpoint I found using Notion as well. Though it's great for quickly linking pages from other pages, you can never get a high-level overview of how everything fits together. Now, all your notes can fit together like puzzle pieces 🧩

Other niceties

Foam seems to have a solid community of contributors adding new features. For example, there's an easy way to discover all the pages referencing the current page you're own using backlinks.

This shows all the references for that "Intro to Structs" note I mentioned earlier, right from the VS Code toolbar. It's a nice lay-of-the-land without scanning the entire graph visualization yourself.

There's also a way to add tags to your notes to group common topics. All you need is a little metadata at the top of your note:

---
tags: [learning-rust]
---

And boom! It's globally discoverable in VS Code as well 💪

So is this the silver bullet to notetaking?

To be honest... I don't think so. At least not for all of my notetaking across devices. This is due to some pretty fundamental limitations:

There's no practical way to view these notes on a phone, let alone edit them
I can't add handwritten notes and drawing from my tablet, unless I want to upload screenshots everytime

Notion had these issues too, so it's definitely not a step back for me (yes I know Notion has a mobile app, but it's full of loading spinners and far too many buttons for my tastes 😬).

Still, I'm seriously impressed with how much I can accomplish with just a text editor and a couple extensions. It's also comforting to actually own my notes instead of using a cloud-based system.

So, I'll definitely be sticking with Foam as I enter 2021 🎉 If you have any tips on getting more out of a "second brain," please leave them in the comments on the DEV version of this post.

The web dev tools that helped me get s*** done in 2020

Mon, 04 Jan 2021 16:33:47 GMT

At long last... the great dumpster fire that was 2020 is no more. There's certainly a lot I'd like to leave behind us. But like a phoenix rising from the ashes, I want to highlight some amazing tools and practices that actually made my life better as a web developer 🚀

I wrote a similar post back in 2019 once I really found my footing in the web dev space. Now, I'm gonna make this a yearly tradition! 🥳

Let's jump into:

🌳 4 Git snippets that defined my workflow
🧠 My mission to build a second brain in VS Code
⚙️ Discovering that everything is a state machine with XState
🐏 The joys of functional programming in JS using Ramda

Onwards!

4 Git snippets I use daily

Stop me if you've seen this workflow before:

I picked up a ticket on JIRA
I need to pull the latest main branch
I need to checkout a new branch
I need to push that branch to origin to and collaborate with my team and open my PR

To push the current branch and set the remote as upstream, use

    git push --set-upstream origin crap-not-again

You know you cringe a little every time this pops up 😬

To mitigate this, I've created my fantastic 4 shortcuts for slamming through my daily tasks 💪

# Stash what I'm working on and checkout the latest master
alias gimme="git stash push -u && git checkout master && git pull -r"

# Grab the latest master and come back to the branch I was on (with stashing!)
alias yoink="gimme && git checkout - && git stash pop"

# Checkout a new branch and push it to origin (so I don't forget that set-upstream)
woosh() {
  git checkout -b $1 && git push -u origin HEAD
}

# ALL TOGETHER NOW
# Stash my current WIP, checkout a new branch off the latest master, and push it to origin
alias boop="gimme && woosh"

Let's understand what these commands are doing a little more:

gimme: This command assumes you might not be on the main branch just yet. It will first stash anything you're working on, including "untracked" / new files with the -u flag. Then, it will head over to the main branch and pull the latest. That -r flag will be sure to "rebase" onto the latest, preventing unecessary merge conflicts.
yoink: This builds off of gimme a little bit. Instead of remaining on the main branch when we're done, we'll head back to the branch we were just on using the - parameter. This is super convenient for grabbing the latest changes to force rebase the branch we're working on.
woosh: This fixes our --set-upstream problem from earlier. Instead of pushing to origin later, this lets you check out a new branch and push right away. Yes, there's some cases when you don't want your local branch on the remote, but this is pretty rare in my experience. And if you've never seen the HEAD parameter before... remember that one! It's a super slick way to auto-fill the name of your current branch instead of typing it out by hand 🔥
boop: This command goes full-circle. It'll stash your current work, grab the latest main branch, and push it up to origin before you start working. This is the command I use the most!

Also gonna mention Jason Lengstorf (the lord of boops) for the naming convention here 😁

Building a second brain in VS Code

This year was all about writing, writing and more writing for me. There's just so much knowledge to pick up as a new full stack developer, yet it always feels so difficult to find what I wrote even a week ago!

I've struggled from notetaking app fatigue for years now. But at long last... I think I've found a semi-perfect home for everything I write both on and off the clock.

Enter the second brain 🧠

I'd been hearing about this concept for a while now, but never realized it's an actual strategy to notetaking. As you'd expect, it's all about writing as much as possible, so you can build a brain's worth of knowledge in note form.

This concept starts with the Zettelkasten Method used back in the pen-and-paper ages. It's built on some pretty basic principles:

Every note is treated as a unique collection of thoughts, tagged by a unique ID of some sort
Notes should form an ever-sprawling tree of connected ideas / thoughts. This is pulled off with "links" between notes (references to those unique IDs), much like hyperlinks on the web!
You may index multiple "trees" of notes with tags or tables of contents, assuming your Zettelkasten grows pretty large

Using VS Code + Foam

Getting a birds-eye view 🗺

Foam will help you find any patterns that naturally emerge from links with a graph visualization extension. It's basically one big map of your head that you can click into and explore!

Metaphor for my brain

If you use VS Code every day like me, this is super easy to dive into for the first time. Definitely give it shot if blog more is one of your New Year's resolutions 🎉

Everything is a state machine

You're a state machine. I'm a state machine. The world is a state machine.

...okay jokes aside, state machines really do apply to everything 😆

You may have heard of XState as a solution to "global state management" in your JS apps. This is true, but the idea of state machines is more of a way of thinking than just another library to learn.

Visualizing your state

Diagramming is really XState's bread and butter. With most state management tools, the actual progression from one action / state / reducer to another can be pretty tough to trace. In XState, they have a dedicated sandbox to work from!

Let's break down some important XState lingo here:

Finite states are those words surrounded by a rectangle (idle, loading, etc.). If you come from Redux like me, you can look at each of these like mini-reducers. They each have unique actions that they're listening for, which may cause you to progress from one reducer to the next.
Actions are defined by those gray bubbles between our finite states (FETCH, RESOLVE, etc.). These can do a few interesting things: progress you to another finite state, set some "global" state for the whole machine (see the next bullet), or fire off some "side effects" that do things outside the machine. For instance, the FETCH action might kick off an API call of some sort. If that API call comes back successfully, we'll fire the RESOLVE action (which our "loading" state picks up).
Context is some global state shared by all states in the machine. This is just one big JS object you can assign new values to and read from whenever you want. In this case, we have a count of how many times we "retried" our fetch, which gets updated on the RETRY action with do / assign retries

This approach has countless benefits, but the biggest one for me: you can use any framework you want with XState, or even no framework at all! This makes me super comfortable going all-in on the library since I can take it with me wherever I go 😁

To get your feet wet in this brave new world, I found some high quality demos around the Internet worth checking out:

This one on modeling UI with state machines across frameworks. Best conference talk on the subject hands down.
This one on building a more complex ReactJS form. It's longer, but worth your time!
This one on creating a Vanilla JS drag-and-drop interaction. This is more CSS-intensive and speaks to the className trick I showed above.

One-line state machines with TypeScript

I started using this pattern more and more throughout the year. This actually doesn't use any libraries at all! In short, it's neat shorthand to collapse an ever-growing sea of booleans:

const [formIdle, setFormIdle] = React.useState(true);
const [formInvalid, setFormInvalid] = React.useState(true);
const [formSubmitting, setFormSubmitting] = React.useState(true);
const [formSubmitted, setFormSubmitted] = React.useState(true);

...into a single, type-safe state:

type FormState = 'idle' | 'invalid' | 'submitting' | 'submitted'
const [formState, setFormState] = React.useState<FormState>("idle");

This fixes the age-old problem tools like Redux seemed to encourage: you have a bunch of booleans representing unique states, but only one boolean should be flipped "on" at a given time. It's a hassle making sure all your boolean's are false when they're supposed to be, so why not have a boolean with more than 2 states?

There are a number of other benefits to this approach like flipping CSS classes at the right times. Check out this article for some interactive code examples ✨

Functional programming with RamdaJS

Across the tech stack my full-time job demands, functional programming has been the common thread for me to pick up.

The functional programming community has flourished with all the static type checking goodness that TypeScript brought. Heck, there's an entire helper library for nearly every concept in the category theory book!

My knowledge of true, mathematical FP is still very surface level right now. Still, I've definitely found my "gateway drug" into this new world: I need to transform a big blob of data into a different looking blob of data, and I'm gonna chain 10 functions together to do it 😎

RamdaJS really is the missing toolkit JS needs for these acrobatics. I could ramble about each little function in their every-sprawling docs, but let's hit the biggest highlights.

Boolean operations

First off, Ramda throws you some nice shortcuts for combining multiple arrays. Let's consider some basic inventory management for our coffee shop. Before someone can check out, we need to exclude any items that are out of stock. Normally, we'd write some function like this one:

const orders = ["Macchiatto", "Cold brew", "Latte"]
const outOfStockItems = ["Macchiatto"]
const validOrders = orders.filter(order => !outOfStockItems.includes(order))

This works well enough... but it's not super readable. Watch us rewrite this sort of operation in a single stroke:

// subtract out all the outOfStockItems from orders
const validOrders = difference(orders, outOfStockItems)
// -> ["Cold brew", "Latte"]

We can do all kinds of things from here! For instance, we could filter out multiple arrays at once by unioning them together:

const validOrders = difference(orders, union(outOfStockItems, itemsOutForDelivery))

...or figure out which items we should include using a SQL-inspired innerJoin:

// basically, filter our menuItems based on which ones were ordered
const itemsOrdered = innerJoin((item, order) => item.name === order, menuItems, validOrders)

Boolean operations like these are certainly not a unique concept. Still, I'm glad Ramda includes all of them with a nice REPL playground to boot. If it's your first time seeing boolean operations, I highly recommend this interactive tutorial 🔥

Formatting in bulk with `evolve`

Okay, this helper really blew my socks off. I'm sure you've run into this sort of pattern before when you try to transform one object into another one:

const orders = [{
  name: "Macchiatto",
  options: {
		roomForCream: true,
    cream: {
      quantity: "1tbsp"
    }
  }
}...]
// now, we want to loop over all of these and convert that "quantity" to an int.
orders.map(order => ({
  // make sure the name sticks around
	...order,
  options: {
    // and roomForCream
		...order.options,
    cream: {
      // ...and finally, parse quantity to an int
      quantity: parseInt(order.options.cream.quantity)
    }
  }
}))

Not bad, but all that dot chaining is making my head spin. We also have to remember all of the keys at each level so they don't disappear on us. The spread operator cleaned up this process for us, but it's still easy to forget (especially if you don't have type checking!). If only we could just modify the keys we care about, without all the nested dots.

This is exactly with evolve does! 🎉

orders.map(
	evolve({
  	// ignore the properties we *don't* want to change, like the name
    options: {
      // ignore roomForCream too
      cream: {
        // and just put a reference to the parseInt function as-is. Don't even call it!
        quantity: parseInt
      }
    }
	})
)

There's some serious benefits to this approach. Not only can we omit keys we don't want to change, but we can modify deeply nested fields without much trouble! You'll also notice we can just pass evolve into our map directly, without passing in the order like we're used to doing (i.e. map(order => evolve(order))). This is because all Ramda functions are curried, which you can learn a bit more about from this Stack Overflow answer 😁 Spoiler: it's an awesome feature.

And that's a wrap!

I know 2020 hit a lot of people hard this year. If you're struggling with family, dealing with kids at home, finding a new job, losing your mind indoors... well, at least you made it through to today 🙂

If you have anything else that made your life better as a developer or as a person, please drop them in the comments on the DEV version of this post. Would love to hear some fresh perspectives as we all take a fresh start for 2021!

NextJS, Contentful CMS, GraphQL, oh my!

Wed, 04 Nov 2020 22:42:55 GMT

We built the new Hack4Impact.org in a month-long sprint once we had designs in hand. To move this fast, we needed to make sure that we used tools that played to our strengths, while setting us up for success when designers and product managers want to update our copy. As the title excitedly alludes to, NextJS + Contentful + GraphQL was the match for us!

No, this post won't help you answer what tools should I use to build our site's landing page? But it should get your gears turning on:

How to access Contentful's GraphQL endpoints (yes, they're free-to-use now!) 📝
How to talk to GraphQL server + debug with GraphiQL 📶
How we can roll query results into a static NextJS site with getStaticProps 🗞
Going further with rich text 🚀

Onwards!

Wait, why use these tools?

Some readers might be scoping whether to adopt these tools at all. As a TLDR:

NextJS was a great match for our frontend stack, since we were already comfortable with a React-based workflow and wanted to play to our strengths. What's more, NextJS is flexible enough to build some parts of your website statically, and other parts dynamically (i.e. with serverside rendering). This is pretty promising as our landing site expands, where we might add experiences that vary by user going forward (admin portals, nonprofit dashboards, etc).
Contentful is one of the more popular "headless CMSs" right now, and it's easy to see why. Content types are more than flexible enough for our use cases, and the UI is friendly enough for designers and product managers to navigate confidently. It thrives with "structured content" in particular which is great for static sites like ours! Still, if you're looking for a simplified, key-value store for your copy, there are some shiny alternatives to consider.
GraphQL is the perfect pairing for a CMS in our opinion. You simply define the "shape" of the content you want (with necessary filtering and sorting), and the CMS responds with the associated values. We'll dive into some code samples soon, but it's much simpler than a traditional REST endpoint.

Note: There's roughly 10 billion ways to build a static site these days (citation needed), with another 10 billion blog posts on how to tackle the problem. So don't take these reasons as prescriptive for all teams!

Setting up our Contentful environment

Let's open up Contentful first. If you're 100% new to the platform, Contentful documents a lot of core concepts over here to get up to speed on "entries" and "content models."

When you're feeling comfortable, whip up a new workspace and create a new content model of your choosing. We'll use our "Executive Board Member" model as an example here.

Once you've saved this model, go and make some content entries in the "Content" panel. We'll be pulling these down with GraphQL later, so I recommend making more than 1 entry to demo sorting and filtering! You can filter by your content type for a sanity check:

Before moving on, let's get some API keys for our website to use. Just head to "Settings > API keys" and choose "Add API key" in the top right. This should allow you to find two important variables: a Space ID and a Content Delivery API access token. You'll need these for some important environment variables in your local repo.

Whipping up a basic NextJS site

If you already have a Next project to work off of, great! Go cd into that thing now. Otherwise, it's super easy to make a NextJS project from scratch using their npx command:

npx create-next-app dope-contentful-example

💡 Note: You can optionally include the --use-npm flag if you want to ditch Yarn. By default, Next will set up your project with Yarn if you have it installed globally. It's your prerogative though!

You may have found a "NextJS + Contentful" example in the Next docs as well. Don't install that one! We'll be using GraphQL for this demo, which has a slightly different setup.

Now, just cd into your new NextJS project and create a .env file with the following info:

NEXT_PUBLIC_CONTENTFUL_SPACE_ID=[Your Space ID from Contentful]
NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN=[Your Content Delivery API access token from Contentful]

Just fill these in with your API keys and you're good to go! Yes, the NEXT_PUBLIC prefix is necessary for these to work. It's a little verbose, but it allows Next to pick up your keys without the hassle of setting up, say, dotenv.

Fetching some GraphQL data

Alright, so we've set the stage. Now let's fetch our data!

We'll be using GraphiQL to view our "schemas" with a nice GUI. You can install this tool here, using either homebrew on MacOS or the Linux Subsystem on Windows. Otherwise, if you want to follow along as a curl or Postman warrior, be my guest!

Opening the app for the first time, you should see a screen like this:

Let's point GraphiQL to our Contentful server. You can start by entering the following URL, filling in [Space ID] with your API key from the previous section:

https://graphql.contentful.com/content/v1/spaces/[Space ID]

If you try to hit the play button ▶️ after this step, you should get an authorizaton error. That's because we haven't passed an access token with our query!

To fix this, click Edit HTTP Headers and create a new header entry like so, filling in [Contentful access token] with the value from your API keys:

After saving, you should see some info appear in your "Documentation Explorer." If you click on the query: Query link, you'll see an overview of all your Content models from Contentful.

Neat! From here, you should see all of the content models you created in your Contentful space. You'll notice there's a distinction between individual entries and a "collection" (i.e. executiveBoardMember vs. executiveBoardMemberCollection). This is because each represents a different query you can perform in your API call. If this terminology confuses you, here's a quick breakdown:

items highlighted in blue represent queries you can perform. These are similar to REST endpoints, as they accept parameters and return a structured response. The main difference is being able to nest queries within other queries to retrieve nested content. We'll explore this concept through example.
items highlighted in purple represent parameters you can pass for a given query. As shown in the screenshot above, you can query for an individual ExecutiveBoardMember based on id or locale (we'll ignore the preview param for this tutorial), or query for a collection / list of members (ExecutiveBoardMemberCollection) filtering by locale, amount of entries (limit), sort order, and a number of other properties.
items highlighted in yellow represent the shape of the response you receive from a given query. This allows you to pull out the exact keys of a given content entry that you want, with type checking built-in. Each of these are hyperlinks, so click on them to inspect the nested queries and response types!

Getting our hands dirty

Let's jump into an example. First, let's just get the list of names and emails for all "Executive Board Member" entries. If you're following along with your own Contentful space, just pick a few text-based keys you want to retrieve from your content model. Since we're looking for multiple entries, we'll use the executiveBoardMemberCollection query for this.

Clicking into the yellow ExecutiveBoardMemberCollection link (following the colon : at the end of the query), we should see a few options we're free to retrieve: total, skip, limit, and items. You'll see these 4 queries on every collection you create, where items represents the actual list of items you're hoping to retrieve. Let's click into the response type for items to see the shape of our content:

This looks really similar to the content model we wrote in Contentful! As you can see, we can query for any of these fields to retrieve a response (most of them being strings in this example).

Writing your first query

Alright, we've walked through the docs and found the queries we want... so how do we get that data?

Well, the recap, here's the basic skeleton of info we need to retrieve:

executiveBoardMemberCollection -> query for a collection of entries
  items -> retrieve the list items
    name -> retrieve the name for each list item
    email -> and the email

We can convert this skeleton to the JSON-y syntax GraphQL expects:

{
  executiveBoardMemberCollection {
    items {
      name
      email
    }
  }
}

... and enter this into GraphiQL's textbox and hit play ▶️

Boom! There's all the data we entered into Contentful, formatted as a nice JSON response. If you typed your query into GraphiQL by hand, you may have noticed some nifty autocomplete as you went. This is the beauty of GraphQL: since we know the shape of any possible response, it can autofill your query as you go! 🚀

Applying filters

You may have noticed some purple items in parenthesis while exploring the docs. These are parameters we can pass to Contentful to further refine our results.

Let's use some of the collection filters as an example; say we only want to retrieve board members that have a LinkedIn profile. We can apply this filter using the where parameter:

As you can see, where accepts an object as a value, where we can apply a set of pre-determined filters from Contentful. As we type, we're greated with a number of comparison options that might remind you of SQL, including the exists operator for nullable values. You can find the complete list of supported filters in the docs off to the right, but autocomplete will usually take you to the filter you want 💪

In our case, our query should look something like this:

executiveBoardMemberCollection(where: {linkedIn_exists: true}) { ... }

...and our result should filter out members without a LinkedIn entry.

Pulling our data into NextJS

Alright, we figured out how to retrieve our data. All we need is an API call on our NextJS site and we're off to the races 🏎

Let's pop open a random page component in our /pages directory and add a call to getStaticProps():

// pages/about
export async function getStaticProps() {
  return {
    props: {
      // our beautiful Contentful content
    }
  }
}

If you're unfamiliar with Next, this function allows you to pull in data while your app is getting built, so you access that data in your component's props at runtime. This means you don't have to call Contentful when your component mounts! The data is just... there, ready for you to use 👍

💡 Note: There's a distinction between getting these props "on every page request" versus retrieval "at build time." For a full rundown of the difference, check out the NextJS docs.

Inside this function, we'll make a simple call to Contentful using fetch (but feel free to use axios if that's more your speed):

export async function getStaticProps() {
  // first, grab our Contentful keys from the .env file
  const space = process.env.NEXT_PUBLIC_CONTENTFUL_SPACE_ID;
	const accessToken = process.env.NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN;
  
  // then, send a request to Contentful (using the same URL from GraphiQL)
  const res = await fetch(
      `https://graphql.contentful.com/content/v1/spaces/${space}`,
      {
        method: 'POST', // GraphQL *always* uses POST requests!
        headers: {
          'content-type': 'application/json',
          authorization: `Bearer ${accessToken}`, // add our access token header
        },
        // send the query we wrote in GraphiQL as a string
        body: JSON.stringify({
          // all requests start with "query: ", so we'll stringify that for convenience
          query: `
          {
            executiveBoardMemberCollection {
              items {
                name
                email
              }
            }
          }
				`,
        },
      },
    );
	// grab the data from our response
	const { data } = await res.json()
  ...
}

Woah, that's a lot going on! In the end, we're just re-writing the logic that GraphiQL does under the hood. Some key takeaways:

We need to grab our API keys for the URL and authorization header. This should look super familiar after our GraphiQL setup!
Every GraphQL query should be a POST request. This is because we're sending a body field to Contentful, containing the "shape" of the content we want to receive.
Our query should start with the JSON key { "query": "string" }. To make this easier to type, we create a JavaScript object starting with "query" and convert this to a string.

🏁 As a checkpoint, add a console.log statement to see what our data object looks like. If all goes well, you should get a collection of contentful entries!

Now, we just need to return the data we want as props (in this case, the items in our executiveBoardMemberCollection):

export async function getStaticProps() {
	...
  return {
    props: {
    	execBoardMembers: data.executiveBoardMemberCollection.items,
    },
  }
}

...and do something with those props in our page component:

function AboutPage({ execBoardMembers }) {
  return (
    <div>
    	{execBoardMembers.map(execBoardMember => (
      	<div className="exec-member-profile">
        	<h2>{execBoardMember.name}</h2>
          <p>{execBoardMember.email}</p>
        </div>
      ))}
    </div>
  )
}

export default AboutPage;

Hopefully, you'll see your own Contentful entries pop onto the page 🎉

Writing a reusable helper functions

This all works great, but it gets pretty repetitive generating this API call on every page. That's why we wrote a little helper function on our project to streamline the process.

In short, we're gonna move all our API call logic into a utility function, accepting the actual "body" of our query as a parameter. Here's how that could look:

// utils/contentful
const space = process.env.NEXT_PUBLIC_CONTENTFUL_SPACE_ID;
const accessToken = process.env.NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN;

export async function fetchContent(query) {
  // add a try / catch loop for nicer error handling
  try {
    const res = await fetch(
      `https://graphql.contentful.com/content/v1/spaces/${space}`,
      {
        method: 'POST',
        headers: {
          'content-type': 'application/json',
          authorization: `Bearer ${accessToken}`,
        },
        // throw our query (a string) into the body directly
        body: JSON.stringify({ query }),
      },
    );
    const { data } = await res.json();
    return data;
  } catch (error) {
    // add a descriptive error message first,
    // so we know which GraphQL query caused the issue
    console.error(`There was a problem retrieving entries with the query ${query}`);
    console.error(error);
  }
}

Aside from our little catch statement for errors, this is the same fetch call we were making before. Now, we can refactor our getStaticProps function to something like this:

import { fetchContent } from '@utils/contentful'

export async function getStaticProps() {
  const response = await fetchContent(`
		{
			executiveBoardMemberCollection {
				items {
    			name
    			email
    		}
    	  }
      }
  `);
  return {
    props: {
      execBoardMembers: response.executiveBoardMemberCollection.items,
    }
  }
}

...and we're ready to make Contentful queries across the site ✨

Aside: use the "@" as a shortcut to directories

You may have noticed that import statement in the above example, accessing fetchContent from @utils/contentful. This is using a slick webpack shortcut under the hood, which you can set up too! Just create a next.config.json that looks like this:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@utils/*": ["utils/*"],
      "@components/*": ["components/*"]
    },
  }
}

Now, you can reference anything inside /utils using this decorator. For convenience, we added an entry for @components as well, since NextJS projects tend to pull from that directory a lot 👍

Using a special Contentful package to format rich text

Chances are, you'll probably set up some rich text fields in Contentful to handle hyperlinks, headers, and the like. By default, Contentful will return a big JSON blob representing your formatted content:

...which isn't super useful on its own. To convert this into some nice HTML, you'll need a special package from Contentful:

npm i --save-dev @contentful/rich-text-html-renderer

This will take in the JSON object and (safely) render HTML for your component:

import { documentToHtmlString } from '@contentful/rich-text-html-renderer';

function AboutPage(execBoardMember) {
  return (
    <div
    dangerouslySetInnerHTML={{
    __html: documentToHtmlString(execBoardMember.description.json),
    }}></div>
  )
}

Yes, using dangerouslySetInnerHTML is pretty tedious. We'd suggest making a RichText component to render your HTML.

Check out our project to see how we put it together 🚀

If you're interested, we deployed our entire project to a CodeSandbox for you to explore!

Head over here to see how we retrieve our executive board members on our about page. Also, check out the utils/contentful directory to see how we defined our schemas using TypeScript.

Our repo is 100% open as well, so give it a ⭐️ if this article helped you!

Understanding the spectrum of CSS frameworks

Wed, 21 Oct 2020 22:44:21 GMT

I saw a short think piece by @urielbitton recently on why people should "stop using CSS frameworks." It was meant to start developer discussion more than anything, since there are definitely merits to rolling your own design system from scratch. Still, with a title like that, it sparked... quite the uproar in the comments 😆

I posted my own response on some of the nuances to explore before writing off frameworks for good. A kind commenter suggested it be its own post (thanks for the support y'all!), so without further ado...

Here's my clap back 👏

Understanding the spectrum of CSS frameworks

First, I'd want to draw a distinction between

Pre-styled, prescriptive, all-in-one frameworks like Material UI and Bootstrap
Hands-off, unopinionated, utility frameworks like Reach UI and Tailwind CSS

I'd consider both camps to be "CSS frameworks," but for different audiences and different use cases.

1. The case for all-in-one frameworks

⭐️ This category is all about developer guidance, giving you the building blocks you need for powerful web apps (even if you don't have the domain knowledge). Above all, these are important for developers that need to focus on the business logic and product vision, but don't need hyper-bespoke CSS to get there.

Accessible by default

The training wheels enforced by these frameworks ensure accessibility guidelines are met without as much research on the developer's part. You may not think about it, but hacking together dropdowns and tab sliders that look good won't always work well for all people. I recently wrote a longform post on building an accessible navbar for this very reason; there's so many little things to consider that Material UI et al. will consider ahead-of-time!

Given how mature popular CSS frameworks have become, they have a component for basically every accessibility concern you can think of. This is a huge win for teams without the resources to audit and fix a11y issues.

Inoffensive visual identity

These sorts of frameworks also enforce a visual identity out of the box. Yes, this does cause websites built on Material UI, Bootstrap, etc. to feel a bit cookie-cutter. Still, these are sensible defaults to build from, especially for a) developer teams lacking a design department and b) internal tools that don't need the customization effort.

Plus, there are gray areas in frameworks like Bootstrap that do allow you to build a visual identity on top of their tools. Heck, I just worked on a project in this camp! We just used Bootstrap for the 12 column grid (which my team was most comfortable with using), and themed the default styles into oblivion.

That said, I do agree with a point raised by Uriel on this front:

"Having custom styles is complicated (overriding issues) and will require multiple CSS files to be loaded."

For full-on component libraries like Material UI, it is pretty difficult to customize beyond colors and fonts. You can quickly fall into the weeds of excessive prop passing, mismatched styling across your site, and the infamous !important bonanza 😞

This is why I'd suggest solutions like Material UI only if your "visual identity" won't diverge from the defaults too much. If you find yourself outgrowing the walled garden though, there's always camp #2...

2. The case for utility frameworks

⭐️ This category is all about developer expediency, providing helpful abstractions for common use cases without prescribing a look and feel to work from. These systems offer a lot more freedom by being, well, a lot smaller out of the box!

"Utility" is a very generic label that could apply to anything in UI-land. For simplicity, I'll just explore 2 major movements I've seen emerging: class-driven frameworks, and functionality-first frameworks.

CSS class utilities - Tailwind and Bulma

Frameworks like Tailwind are really shaking things up. It's the first framework I've seen to go all-in on class-based styling. In other words, why can't every CSS property be its own class in your HTML?

At first, this sounds like a recipe for disaster. But it offers some pretty interesting benefits:

Media queries are standardized right out the gate. Instead of loosely defining breakpoints like max-width: 860px, you can simply append "small / medium / large" to the front of your HTML classes. For example, here's how you could dynamically change an element's size between mobile and tablet: class="h-16 w-16 md:w-24 md:h-24"
Shorthands can speed up experienced teams, without abstracting the CSS away too much. Since every class is a 1-1 with a CSS property (or small set of properties), you are still translating to core CSS concepts every time. This dispells the fear of using all-in-one frameworks like Material UI, where the CSS is completely hidden from developers most of the time.

This framework has a laundry list of pros and cons that deserves its own article. Luckily, @swyx wrote an amazing evaluation for his own needs that's worth reading 😁

I also want to mention Bulma in this section, in case the breadth of Tailwind is too intimidating for you. I'd consider it a "Tailwind-lite" with a lot of the same philosophies.

Bare-bones UI libraries - Reach UI

Reach UI is my favorite example in the "functionality-first" camp. In short, Reach UI gives you a set of React components with prebuilt aria labels, state management, and some lightweight CSS styles sprinkled on top (mostly for changing display properties). The goal here isn't to enforce a visual identity; it's to provide the least amount of code possible to create usable, accessible UI elements ✨

In the end, you're free to add your own layer of styling and JS logic on top. The documentation actually guides you through overriding the defaults! I'm a CSS warrior myself, so I lean on this type of CSS framework to get things done (as long as I'm using React of course).

I'd consider this sort of framework to be a master-class on inversion of control, and I hope more frameworks pick up on this pattern.

Wrapping up

Overall, I think writing off CSS frameworks is a bit of a hand-wavy statement to make given the huge landscape of tools out there right now. There will always be a place for prebuilt solutions like Material UI; if anything, I see them as one step removed from powerhouses like SquareSpace or Wordpress (closer to the code, but with a lot of details abstracted away). And for teams that don't want to be tied down, solutions like Tailwind and Reach UI should fit the bill for adding handrails without losing visual identity.

Still, keep hacking away Uriel! We all have opinions, so just use what works best for you and your team 😁

Building a sexy, mobile-ready navbar in any web framework

Tue, 06 Oct 2020 22:44:09 GMT

I've been building a lot more static sites recently, and every one of them needs the same thing:

A nice and responsive navigation bar with logo on the left, links on the right 💪
For mobile screens, collapse those links on the right into a hamburger menu with a dropdown 🍔
Hit all the marks for accessibility: semantic HTML, keyboard navigation, and more ♿️
Add some polished animations for that sleek, modern feel ✨

Oh, and implement it using whatever framework the team is using. This may sound daunting... but after bouncing between React, Svelte, and plain-ole JS, and I think I've found a solid solution you can take with you wherever you go.

Onwards!

First, what's the end goal?

Here's a screen-grab from my most recent project: redesigning the Hack4Impact nonprofit site.

Ignore the cats. We needed some purrfect placeholders while we waited on content 😼

This has some fancy bells and whistles like that background blur effect, but it covers the general "formula" we're after!

##Lay down some HTML

Let's define the general structure of our navbar first.

<nav>
	<a class="logo" href="/">
    <img src="dope-logo.svg" alt="Our professional logo (ideally an svg!)" />
  </a>
  <button class="mobile-dropdown-toggle" aria-hidden="true">
    <!-- Cool hamburger icon -->
  </button>
  <div class="dropdown-link-container">
    <a href="/about">About Us</a>
    <a href="/work">Our Work</a>
    ...
  </div>
</nav>

A few things to note here:

We're not using an unordered list (ul) for our links here. You might see this recommendations floating around the web, and it's certainly a valid one! However, this nuanced for / against piece from Chris Coyier really solidified things for me. In short: lists aren't required for a11y concerns (the problem is minimal at best), so we can ditch them if we have a fair reason to do so. In our case, we actually need to ditch the list so we can add our dropdown-link-container without writing invalid HTML. To understand what I mean, I clarified the issue to a kind commenter here!
You'll notice our dropdown-link-container element, which wraps around all our links except the logo. This div won't do anything fancy for desktop users. But once we hit our mobile breakpoint, we'll hide these elements in a big dropdown triggered by our mobile-dropdown-toggle button.
We're slapping an aria-hidden attribute on our dropdown toggle. For a simple nav like this, there's no reason for a screenreader to pick up on this button; it can always pick up on all our links even when they're "visually hidden", so there's no toggling going on 🤷‍♀️ Still, if you really want to mimic the "toggle" effect for these users (which you should for super busy navbars), you can look into adding aria-expanded to your markup. This is getting a bit in the weeds for this article though, so you can use my easy-out for now.

For those following along at home, you should have something like this:

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

Now, some CSS

Before worrying about all that mobile functionality, let's spiff up the widescreen experience.

Our base styles

To start, we'll set up the alignment and width for our navbar.

nav {
  max-width: 1200px; /* should match the width of your website content */
  display: flex;
  align-items: center; /* center each of our links vertically */
  margin: auto; /* center all our content horizontally when we exceed that max-width */
}

.logo {
  margin-right: auto; /* push all our links to the right side, leaving the logo on the left */
}

.dropdown-link-container > a {
  margin-left: 20px; /* space out all our links */
}

.mobile-dropdown-toggle {
  display: none; /* hide our hamburger button until we're on mobile */
}

The max-width property is an important piece here. Without it, our nav links will get pushed wayyyy to the right (and our logo wayyyy to the left) for larger screens. Here's a little before-and-after to show you what I mean.

**Before: ** Our nav elements stick to the edges of the screen. This doesn't match up with our page content very well, and makes navigation awkward on larger devices.

**After: ** Everything is beautifully aligned, making our website a lot more "scan-able."

Of course, you can add padding, margins, and background colors to-taste 👨‍🍳 But as long as you have a max-width and margin: auto for centering the nav on the page, you're 90% done already! Here's another pen to see it in action:

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

Adding the dropdown

Alright, now let's tackle our dropdown experience. First, we'll just focus on re-styling our links into a vertical column that takes up the height of the page:

@media (max-width: 768px) { /* arbitrary breakpoint, around the size of a tablet */
  .dropdown-link-container {
    /* first, make our dropdown cover the screen */
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    height: 100vh;
    /* fix nav height on mobile safari, where 100vh is a little off */
    height: -webkit-fill-available;
    
    /* then, arrange our links top to bottom */
    display: flex;
    flex-direction: column;
    /* center links vertically, push to the right horizontally.
       this means our links will line up with the rightward hamburger button */
    justify-content: center;
    align-items: flex-end;

    /* add margins and padding to taste */
    margin: 0;
    padding-left: 7vw;
    padding-right: 7vw;

    background: lightblue;
  }
}

This is pretty standard for the most part. Just a few things of note here:

First, we use position: fixed to align our dropdown to the top of our viewport. This is distinct from position: absolute, which would shift the nav's position depending on our scroll position 😬

Then, we use the -webkit-fill-available property to fix our nav height in mobile Safari. I'm sure you're thinking "what, how is 100vh not 100% of the user's screen size? What did Apple do this time?" Well, the problem comes from the iOS' disappearing URL bar. When you scroll, a bunch of UI elements slide out of the way to give you more screen real estate. That's great and all, but it means anything that used to take up 100% of the screen now needs to be resized! We have this problem on our Bits of Good nonprofit homepage:

Notice the links aren't quite vertically centered until we swipe away all the Safari buttons. If you have a bunch of links, this could lead to cut-off text and images too!

In the end, all you need is the override height: -webkit-fill-available to specifically target this issue. Yes, feature flags like -webkit are usually frowned upon. But since this issue only pops up in mobile Safari (a webkit browser), there really isn't a problem with this approach in my opinion 🤷‍♀️ Worst case, the browser falls back to 100vh, which is still a totally usable experience.

Finally, let's make sure our logo and dropdown buttons actually appear on top of our dropdown. Because of position:fixed, the dropdown will naturally hide everything underneath it until we add some z-indexing:

@media (max-width: 768px) {
  .logo, .mobile-dropdown-toggle {
    z-index: 1;
  }
  
  .mobile-dropdown-toggle {
    display: initial; /* override that display: none attribute from before */
  }
  
  .dropdown-link-container {
    ...
    z-index: 0; /* we're gonna avoid using -1 here, since it could position our navbar below other content on the page as well! */
  }
}

Squoosh this CodePen to our breakpoint size to see these styles at work:

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

Let's animate that dropdown

Alright, we have most of our markup and styles finished up. Now, let's make that hamburger button do something!

We'll start with handling the menu button clicks. To show you how simple this setup is, I'll just use vanilla JS:

// get a ref to our navbar (assuming it has this id)
const navElement = document.getElementById("main-nav");

document.addEventListener("click", (event) => {
  if (event.target.classList.contains("mobile-dropdown-toggle")) {
    // when we click our button, toggle a CSS class!
    navElement.classList.toggle("dropdown-opened");
  }
});

Now, we'll animate our dropdown into view whenever that dropdown-opened class gets applied:

/* inside the same media query from before */
@media (max-width: 768px) {
  ...
  .dropdown-link-container {
    ...
    /* our initial state */
    opacity: 0; /* fade out */
    transform: translateY(-100%); /* move out of view */
    transition: transform 0.2s, opacity 0.2s; /* transition these smoothly */
  }
  
  nav.dropdown-opened > .dropdown-link-container {
    opacity: 1; /* fade in */
    transform: translateY(0); /* move into view */
  }
}

Nice! With just a few lines of CSS, we just defined a little fade + slide in effect whenever we click our dropdown. You can mess around with it here. Modify the transitions however you wish!

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

Adapting for big boy components

Alright, I know some of you want to slide this in your framework of choice at this point. Well, it shouldn't be too difficult! You can keep all the CSS the same, but here's a component snippet you can plop into React:

export const BigBoyNav = () => {
	const [mobileNavOpened, setMobileNavOpened] = useState(false);
	const toggleMobileNav = () => setMobileNavOpened(!mobileNavOpened);

  return (
    <nav className={mobileNavOpened ? 'dropdown-opened' : ''}>
      ...
      <button class="mobile-dropdown-toggle" onClick={toggleMobileNav} aria-hidden="true">
    </nav>
	)
}

And one for Svelte:

<!-- ...might've included this to show how simple Svelte is :) -->
<script>
	let mobileNavOpened = false
  const toggleMobileNav = () => mobileNavOpened = !mobileNavOpened;
</script>

<nav className:mobileNavOpened="dropdown-opened">
	...
  <button class="mobile-dropdown-toggle" on:click={toggleMobileNav} aria-hidden="true">
</nav>

...You get the point. It's a toggle :laughing:

The little things

We have a pretty neat MVP at this point! I just left a couple accessiblity pieces for the end to get you to the finish line 🏁

Collapse that dropdown when you click a link

Note: You can skip this if you're using a vanilla solution like Jekyll, Hugo or some plain HTML. In those cases, the entire page will reload when you click a link, so there's no need to hide the dropdown!

If we're gonna cover the users entire screen, we should probably hide that dropdown again once they choose the link they want. We could just any click events in our dropdown like so:

document.addEventListener('click', event => {
  // if we clicked on something inside our dropdown...
  if (ourDropdownElement.contains(event.target)) {
    navElement.classList.remove('dropdown-opened')
  }
})

...but this wouldn't be super accessible :sweat:. Sure, it handles mouse clicks, but how will it fare against keyboard navigation with the "tab" key? In that case, the user will tab to the link they want, hit "enter," and stay stuck in dropdown-opened without any feedback!

Luckily, there's a more "declarative" way to get around this problem. Instead of listening for user clicks, we can just listen for whenever the route changes! This way, we don't need to consider how the user navigates through our dropdown links; Just listen for the result.

Of course, this solution varies depending on your router of choice. Let's see how NextJS handles this problem:

export const BigBoyNav = () => {
  const router = useRouter(); // grab the current route with a React hook
  const activeRoute = router.pathname;

  ...
  // whenever "activeRoute" changes, hide our dropdown
  useEffect(() => {
    setMobileNavOpened(false);
  }, [activeRoute]);
}

Vanilla React Router should handle this problem the same way. Regardless of your framework, just make sure you trigger your state change whenever the active route changes :thumbsup:

Handle the "escape" key

For even better keyboard accessiblity, we should also toggle the dropdown whenever the "escape" key is pressed. This is bound to a very specific user interaction, so we're free to add an event listener for this one:

// vanilla JS
const escapeKeyListener = (event: KeyboardEvent) =>
	event.key === 'Escape' && navElement.classList.remove('dropdown-opened')

document.addEventListener('keypress', escapeKeyListener);

...and for component frameworks, make sure you remove that event listener whenever the component is destroyed:

// React
useEffect(() => {
  const escapeKeyListener = (event: KeyboardEvent) =>
  event.key === 'Escape' && setMobileNavOpened(false);

  // add the listener "on mount"
  document.addEventListener('keypress', escapeKeyListener);
  // remove the listener "on destroy"
  return () => document.removeEventListener('keypress', escapeKeyListener);
}, []);

See a fully-functional React example 🚀

If you're curious how this could all fit together in a React app, our entire Hack4Impact website is accessible on CodeSandbox!

To check out the Nav component, head over here.

And thanks to James Wang for nudging me to write this article. Might have sparked a whole mini-series on how we built our splash page

Writing a state machine in one line with TypeScript

Wed, 02 Sep 2020 15:35:45 GMT

Ah yes, state machines. That thing David K Piano keeps tweeting about, or that CS concept that pops up in college once a semester (and seemingly never returns...). As the frontend world gets more and more disatisfied with Redux, state machines are one of many concepts devs are talking about these days.

But unlike Redux et al., state machines don't have to be a library you install into your project! Once you understand them conceptually, they become their own way of thinking about problems.

In short, this article should help you...

Identify when boolean flags and state variables are getting too complex
Write your own scrappy state machine with no libraries
Learn a bit more about state machines as a concept, and when XState might be a good idea

Onwards!

⚠️ Note: we'll be using React for the following examples. Still, the core learning concepts transfer to any frontend framework

First, a scenario

If we're talking UI complexity, form management is the easiest place to look. Let's say we have a simple sign-up screen we need to implement with a username and password. To make things a little interesting, let's say we're reviving the incredible childhood memory that is Club Penguin!

Try not the cringe. At least it's not built on Flash 😬

We also want to consider some scenarios as the user fills out the form. Namely, we should support a) password validation before you submit and b) disabling the submit button while we're sending to the API. Here's what that flow might look like:

A common approach: brute-force booleans

First, let's cover the approach a lot of devs might take (especially coming from a Redux background). Based on the interactions we want, we should probably have some flags for

When the password is invalid
When we're submitting to the API
Whether we've submitted successfully (maybe to move to the next screen)

I won't bore you with the HTML + colorful CSS we need (check this CodeSandbox for such goodies!), so let's just look at the pieces we care about:

const ClubPenguinSignup = () => {
  const [invalid, setInvalid] = React.useState(false);
  const [submitting, setSubmitting] = React.useState(false);
  const [submitted, setSubmitted] = React.useState(false);
  ...
  // state vars for username and password, markup, etc.
}

For the submitting / submitted flags, we can use a nice callback function for whenever our form submits:

const onSubmit = async (event: React.FormEvent) => {
  event.preventDefault();
  setSubmitting(true); // we're now submitting
  const addedUser = await arcticAuthService({ username, password });
  if (addedUser?.success) { // if signup call worked...
    setSubmitting(false); // we're no longer submitting
  	setSubmitted(true); // we've submitted
	}
};

Finally, we can make a super basic callback to validate our password as the user types it in. In this case, we'll listen for whenever the input's value changes (i.e. using a controlled input), and run the value through an insecure phrase checker:

const onChangePassword = (event: React.FormEvent<HTMLInputElement>) => {
  setPassword(event.currentTarget.value);
  checkPasswordSecurity(event.currentTarget.value);
};

const checkPasswordSecurity = (changedPassword: string) => {
  let insecure = false; // we first assume the value is secure (excuse the double negative)
  ["club", "penguin", "puffle"].forEach((badWord) => {
    if (changedPassword.includes(badWord)) {
      insecure = true;
    }
  });
  setInvalid(insecure);
};

Where it starts to get hairy

Great! This doesn't seem too bad... but we're not done yet. If you check that mockup again, you'll notice that our button has 3 different indicators to display (normal, loading, and finished). Since we're using separate boolean flags for each of these, we'll need some mappers to set the button backgrounds + flavor text:

const getButtonLabel = (): string => {
  if (submitting) {
    return "•••";
  } else if (submitted) {
    return "Time to play!";
  } else {
    return "Let's get sliding!";
  }
};

const getButtonClass = (): string => {
  if (submitting) {
    return "submitting";
  } else if (submitted) {
    return "submitted";
  } else if (invalid) {
    return "invalid";
  } else {
    return "";
  }
};

return (
	...
  <button type="submit" className={getButtonClass()}>
    {getButtonLabel()}
  </button>
)

Since we only need mappers for a single element, this doesn't seem that terrible. Still, this could easily start ballooning out of control as we add more UI and more state variables...

const [usenameTaken, setUsernameTaken] = React.useState(false);
const [apiError, setApiError] = React.useState(false);
const [serverAtMaxCapacity, setServerAtMaxCapacity] = React.useState(false);
const [invalid, setInvalid] = React.useState(false);
const [submitting, setSubmitting] = React.useState(false);
const [submitted, setSubmitted] = React.useState(false);

const getButtonClass = (): string => {
  // 100 lines of ifs
};

We're also allowing for a lot of states that shouldn't be possible. For example, we should never be "submitting" and "submitted" at the same time, and neither of these should be true when the password is invalid. Considering the crazy state explosion above, we'll end up restling all these variables to prevent such invalid states.

// api responds that servers are at max capacity, so no sign ups allowed
setServerAtMaxCapacity(true)
setSubmitting(false)
setSubmitted(false)
setApiError(true)
...

If anything, we just want to have a boolean with more than 2 values so we're not switching flags all over the place. Luckily, TypeScript gives us such superpowers 💪

Our new approach: the poor man's state machine

As you may have guessed, we can solve this boolean bonanza with a simple state machine. I've heard this approach called the "poor man's state machine" which is a super apt title as well!

All we need is ~~the XState library~~ a one-liner to model our state variables as a single type:

type FormState = 'idle' | 'invalid' | 'submitting' | 'submitted'

You could certainly use an enum for this as well. I just prefer string literals since they're a bit shorter + more readable (I also wrote a short article on the subject if you're still an enum stan).

With our type defined, we can condense all our state variables into one:

const [formState, setFormState] = React.useState<FormState>("idle");

Refactoring our password and submit callback is pretty easy from here.

const checkIfPasswordIsSecure = (changedPassword: string) => {
    setFormState("idle"); // not invalid yet
    ["club", "penguin", "puffle"].forEach((badWord) => {
      if (changedPassword.includes(badWord)) {
        setFormState("invalid"); // oops! Looks like it's invalid after all
      }
    });
  };

const onSubmit = async (event: React.FormEvent) => {
  event.preventDefault();
  if (formState === "invalid") return; // don't submit if our password is invalid
  setFormState("submitting");
  const addedUser = await arcticAuthService({ username, password });
  if (addedUser?.id) {
  	setFormState("submitted"); // no need to set submitting to false, since we don't have 2 states to consider anymore!
	}
};

And remember those button classNames we needed to map? Well, since our state is represented as a string, we can just pass these directly to our CSS ✨

return (
	<button type="submit" className={formState /* our state is our CSS */}>
		...
  </button>
)

This approach is super handy for keeping our CSS in check; instead of constantly adding and removing classes, we can just switch out which class gets applied.

Here's a working CodeSandbox using our new approach ✨

Going further 🚀

Of course, this is a pretty simple example that may not quite fit your use case. For example, you may want to be in multiple states at a given time, or guard against "invalid transitions" (for example, it shouldn't be possible to go from idle to submitted without passing through submitting first).

The former could just require multiple state variables, so consider creating multiple FormState types to see how it feels. Still, you may have enough complexity that a state management library makes a lot of sense. Check out XState if this sounds like you!

To get your feet wet, I found a couple high quality demos around the Internet worth checking out:

This one on building a more complex ReactJS form. It's long, but worth your time!
This one on creating a Vanilla JS drag-and-drop interaction. This is more CSS-intensive and speaks to the className trick I showed above.
This one on modeling UI with state machines across frameworks. Best conference talk on the subject hands down.

Before building your next static site with React, consider this

Tue, 07 Jul 2020 13:48:25 GMT

⚠️ Warning: Potentially controversial opinions ahead! Turn back now if Gatsby is your lord and savior, and you serve to protect the React dogma.

So I just finished building my shiny new personal site ✨ I thought about using fancy, component-driven frameworks like Gatsby to stay on the bleeding edge of web development, but after some reflection, I thought to myself...

do I really need all this tooling to write some static HTML?

This ended up being a huge learning experience on how to build a statically generated SPA from scratch (check out the README if you're curious how I approached it!). But it also taught me some valuable lessons on how far you can go while ditching the component libraries we all know and love.

A little background: going from dynamic to static sites

Okay, let's be real for a moment: component-level thinking rules modern web development. Even as new frontend libraries and Ruby-esque frameworks hit the scene, they still rely on the same basic formula: write your markup and JS logic inside a bite-sized component, and compose those components with imports and exports. Whether those components are class-based, functional, or even at the DOM level (hello web components 👋), they're all focused on these ideas of logic isolation and code reusability.

Popular libraries like React and Vue have become such a one-size-fits-all solution that we don't even question them anymore. New to building literally anything on the Internet? Just run npx create-react-app and get going!

...right?

I used to agree. But over the past couple years of Gatsby and JAMStack preaching, I've also come to realize that damn, we're making some fat JS bundles. With all these JS-based components, we're shipping entire rendering libraries to the browser, even for a company's plane ole' static splash page!

Before getting cynical, it's worth remembering why these libraries were made in the first place. React wasn't created because Facebook should be a better static site; it was created because Facebook is a super dynamic, ultra complex web app with logins, trackers, home feeds, settings menus, etc etc etc. That involves a ton of data / state management, which means, well, a whole lot of JavaScript to construct the web page. For this use case, it makes perfect sense to build and use a UI rendering library that's state driven, rather than markup driven.

This is why Gatsby (a popular static site generator) came years after, say Redux state management. Devs were mostly fascinated with building dynamic, JS-driven experiences that state, props, and data objects could solve. It wasn't until later that devs started wondering how they could bend these JS-heavy libaries to their will for static site creation.

If you ask me, it's pretty ironic that it takes a 500 MB directory called node_modules to generate a website with... as little JavaScript as possible.

Still, I can't say I'm surprised either. When you're taking a library like React, which needs JavaScript to render anything to the page, you'll obviously need even more JavaScript to process all that rendering logic to begin with. Fire really does fight fire.

So... why use React on a static site?

At first, it kinda feels like using a chainsaw to slice a loaf of bread. Why use a rendering library like React when you have zero-to-little rerendering to worry about?

In short, hydration.

If you don't get this reference, go culture yourself

For those unfamiliar, hydration basically lets us write a dynamic, state-driven webpage, but also render as much of the page ahead-of-time as possible using static HTML. The Gatsby blog does a great job explaining this process, but here's a quick step-by-step:

Your app exists as a big bundle of components, much like a create-react-app.
The static site generator comes along and renders out this bundle at build time. Now, instead of shipping a blank HTML file to the user, you can send the entire page's markup for a speedy page load.
Now, we want to do some stateful component magic alongside the static HTML we just built. To pull this off, we can look at the HTML page that's already been generated and compare it against our tree of components. When we find a component that does some state management craziness, we'll slot it into our existing HTML without rerendering the entire page. In other words, we hydrate our markup with some stateful components.

Seems slick! This comes in handy when you have some JS you want to use (say, a crazy animation library for added spice) that only apply to small areas of your otherwise-static site. But as you might have guessed, we'll need to ship the entire component library to the client in order to compare against the HTML. So it's still a fat bundle... but at least the user sees something on the first page load 🤷‍♀️

And what if you don't need state management?

Now, React doesn't make as much sense. If we just need to handle some button clicks, we should probably just write a couple lines of vanilla JS instead of, you know, shipping the entire React library 😬

For some perspective, here's some common dev requests when building a static site:

We want to break down our static site into reuseable UI components that can accept some JS objects as parameters (aka "props"). This lets us, say, turn a list of blog post links into a bunch of clickable cards on our homepage.
We need to fetch some information at build time to slap into our production site. For example, we can go get some Twitter posts at build time to slide into our site's homepage, without shipping any API calls or exposing secret keys.
We need to generate a bunch of URL routes from either a directory of files or a fat JSON object of content. For instance, we have a folder of markdown files that we want to turn into a personal blog, making each file its own URL on the interwebs.

These are all great reasons to use static site generators. But looking at this list, only the first requirement actually involves a component library. And even then, we may not need to worry about rerenders or componentized state management; it's mostly done at build time! If only there was a way to make our markup reuseable and template-able, without shipping a bunch of unused JS...

(Re)enter: Pug

That's right, good ole' Pug (formerly Jade). You know, that cute little templating library you used on your last CodePen, or maybe the weird looking HTML you found on an Express server template. It's a mighty little library from a pre-React era, before component-driven state management was even a thing.

It also uses a simplified syntax for HTML that makes it a bit easier to type / look at, which I'm personally a fan of 😁

So why am I bringing up this jaded (pun intended) templating library? Well, let's run through some of Pug's defining features to see what it can do. I'm hungry so we'll use a donut shop for examples 🍩:

1. You can take in some JavaScript data and turn it into HTML elements

This opens the door for all kinds of craziness, like looping, conditional "if" blocks, defining text content... you name it:

main.krispy-kreme-menu
	if menuItems.length === 0
	    p.alert Sorry! Sold out of gooey deliciousness :(
	else
         dl
         each item in menuItems
             dt #{item.name}
             dd #{item.price}

And at the JavaScript level:

const stringOfRenderedHTML = pug.render('/filename.pug', { menuItems: [...donuts] })
// spit out this string of HTML into a .html file at build time

2. You can compose multiple HTML files (now `.pug` files) into a single page layout

For example, you can create a navigation bar in one file...

// nav.pug
nav.krispy-kreme-navigation
	a(href="/") Home
	a(href="/donuts") Buy some donuts
	a(href="/contact") Somehow complain about your donuts

... and import into another file:

// index.pug
html
    body
        include nav.pug
        main.donut-content
            ul.list-of-tastiness
	       ...

We can go even deeper by passing parameters / "props" between these files. Check out this mixin syntax:

// nav-mixins.pug
mixin NavBar(links)
	each link in links
		a(href=link.href) link.text

// index.pug
include nav-mixins.pug
html
	body
		+NavBar(donutLinksPassedDownByJS)
		main.donut-content
			ul.list-of-tastiness

Here, we can consider each mixin an export statement from nav-mixins.pug. Then, when we include this file somewhere else, those mixins become usable via the + decorator (aka our "import" statement).

So in summary...

✅ We can turn JSON objects into static HTML with a one-line script (pug.render(filename, someJSON))

✅ We can break up our layout into multiple files using imports

✅ We can define component-like "mixins" for reusability and data passing

...in other words, we get to make our UIs with components, but without sending a bunch of libraries to the client!

But wait, this idea is nothing new!

I know! Backend servers have been doing this for decades.

Let's consider the server-driven model you would use for, say, an ExpressJS app. Everytime you hit an API endpoint, the server may go look up some info from a database, roll that data into an HTML template (probably using Pug), and send it back to the user. Same goes for PHP, C#, GoLang, or whatever exotic server you've seen before.

But guess what? A static site generator does the exact same thing! The only difference is that now, instead of doing all the data fetching + templating in an API endpoint, we're doing it in a build script that we call when the website actually gets deployed. For those familiar, this is that fancy script you tell Netlify to run when you first deploy your site.

Servers used this templating model long before we were making crazy, ultra-dynamic web apps. So my question is this: when your website just has some static landing pages, a few lines of JS, and maybe a blog to generate... why throw away this idea of templating for component libraries?

Call to action 👉 check out 11ty

I just found out about 11ty (pronounced "eleven-tee"), a static site generator built with this exact philosophy in mind. You can choose the HTML templating language of your choice (Markdown, Haml, Pug, Nunjucks, and a bunch more), and let the framework handle all the complicated routing and page generation for you. If you're trying to build a portfolio site with a blog, a promotional splash page for a company, or anything super static-y, this is honestly the best solution I can think of.

That said, I'm definitely not suggesting you give up your beautiful Gatsby site! There are some serious benefits to their hydration model in case you want any state management stuff. Plus, if your super comfortable in React-land and don't have time to pick up new tools, it's a pretty convenient choice with a huge community of support. Same goes for Gridsome, a Vue-based static site generator that works in a similar way.

Anyhow, whatever you end up using, I hope this article got you thinking a bit more about what static site generators really do. With that, I'll leave you with this cute pug photo to stick in your mind 🐶

Use flexbox? Here's when CSS Grid is better

Tue, 26 May 2020 16:34:01 GMT

This blog post introduces several new terms you may be unfamiliar with: griddazzle, gridify, getting "griddy" with it, etc. I recommend using context clues for these definitions.

I'll be honest, I was a flexbox diehard myself a while after CSS Grid took hold of page layouts. Even after taking Wes Bos' CSS Grid course (still the best resource hands-down if you're new to Grid!), I just didn't see the need to change my ways. Sure, flexbox sometimes needs an extra <div> or two to get layouts working... but hey, if it ain't broke, why fix it?

Still, I slowly forced myself to implement CSS Grid in some choice areas of my websites. Now, after a year of experimenting and getting increasingly Griddy with it, I've found some neat corners of CSS where flexbox struggles by comparison.

Posts comparing flexbox to Grid sometimes use simplified examples that don't get to the heart of flexbox's flaws. So, to convince all you flexers out there to join the dark side, here's some concrete examples of when CSS Grid really is alot simpler in my own experience.

1. When layouts have some reordering to do

Let's consider a common scenario: you have a 2 column layout for desktop / laptop users, and you want it to wrap nicely to a single column for narrow screens.

Taking a quick glance at your team's mockups, you fly into your usual flex rhythm and end up here:

<div class="outer-container">
    <div>...column 1 content</div>
    <div>...column 2 content</div>
</div>

<style>
    .outer-container {
        /* create flexbox with a single row */
        display: flex;
        justify-content: space-between;
    }

    @media (max-width: 800px) {
        .outer-container {
            /* wrap columns on top of each other for mobile */
            flex-direction: column;
          
          	/* alternatively, you can remove the flexbox entirely
          	and let the columns wrap naturally */
          	display: block;
        }
    }
</style>

Easy peasy! For a lot of use cases, this should work just fine.

But sometimes, your design team my have other ideas. Let's consider the layout below, with both a desktop and mobile mockup to implement:

Well, that's a lot less fun. Not only should we reverse the ordering of our header and image, but we also need to move the final element of the first column (the "find us in person" address) to the end of our second column. This is definitely a nail in our flexbox coffin 😕

Time to gridazzle

Fear not! CSS grid has an elegant solution to the problem: [grid template areas](Grid template areas - CSS: Cascading Style Sheets | MDN) ✨

With this tool, we can assign each HTML element a unique "area" in our layout. then, we let our grid container decide where to slap each area into our final layout. It's a lot like paint-by-numbers, but gridified.

Here's a sample of how we could implement the above layout:

<!-- First, put all our elements on the page. -->
<!-- Notice we don't need wrapper <div>s for each column anymore! -->
<div class="outer-container">
    <h1>Contact Us</h1>
    <p class="tagline-text">Want to learn more...</p>
    <img src="/static/contact-us.jpg" alt="People flying around with laptops" />
    <div class="address-container">...</div>
    <form>...</form>
</div>


<style>
  .outer-container {
    display: grid;
    /* use template-areas to define the structure of our 2 column page */
    /*										  col 1 | col 2 														 */
    grid-template-areas:  "header   header" /* row 1 (just the header h1) */
                          "tagline  form" /* row 2 (tagline text, start of form) */
                          "image    form" /* row 3 (image, form continues) */
                          "address  form"; /* row 4 (address, end of form) */
  }
  /* assign each element to  a unique area on our grid */
  h1 {
		grid-area: header;
  }
  p.tagline-text {
    grid-area: tagline;
  }
  img {
    grid-area: image;
  }
  form {
    grid-area: form;
  }
  .address-container {
    grid-area: address;
  }
  
  @media (max-width: 800px) {
    .outer-container {
      /* rearrange our grid on mobile, now using a 1 column layout */
      grid-template-areas: "image"
                           "header"
                           "tagline"
                           "form"
                           "address";
    }
  }
</style>

Nice! Not only can we define the positioning of elements however we want, but we even have an expressive explanation of the layout in our CSS using area names.

Of course, we'll need a few finishing touches to get all the spacing right (height of each row in our 2 column grid, spacing between the columns, etc.). So, if you're curious how the entire mockup was accomplished, you can check out a production-ready implementation on our GitHub repo for bitsofgood.org 😁

Accessibility note: CSS grid changes the visual order of elements on the page, but not the actual order of elements in the DOM. So, when we wrap our address-container to the bottom on mobile, it still appears above the form element in the underlying HTML. This shouldn't be much of an issue in our case, but before you start reordering text boxes on our own site, make sure this won't confuse screen readers!

2. When you want things kind of centered

I've run into this a few times trying to make a nice container of "cards," dynamically wrapping to a new row depending on the screen width. This conundrum is awkward to explain with words, so let's understand the problem visually:

Okay, so our container of cards should always remain centered on the page (notice the white space on either side of our card grid). However, each row of our container should start at the leftmost side and continue to the right (aka flex-start). That means we can't simply use justify-content: center here! That would center the item in the last row relative to the other rows, which breaks our illusion of a "grid."

Oh, and we also want constant "gap" between each card, as well as a constant width for each card.

If you've attempted this layout before, you can probably predict the @media query adjustments we'll need. Here's a sample implementation, assuming we'll never need more than 3 columns. Click "edit on CodePen" if you wish to squoosh that browser window.

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

Why this implementation is bad

We need a @media query to adjust our container width for each change in column-count. This requires some wacky mental math based on a) the width of each card, and b) the margin between elements. Adjusting the width of a card by even 1px, we'll need to run all these calculations again! And no, we can't use calc() in a media query 😑
This doesn't consider screen sizes below the width of a single card. We could add yet another @media query to change this, but as we'll see soon, CSS Grid can remove this need entirely!

Time to gridificate

Now, let's see a sample implementation of the same layout with CSS grid:

.container-of-cards {
  display: grid;
  /* set our column widths with wrapping in place */
  grid-template-columns: repeat(auto-fill, 340px);
  gap: 60px;
  /* center our columns relative to the container */
  justify-content: center;
  /* add a max-width to prevent more than 3 columns */
  max-width: 1200px;
  margin: auto;
}

.card {
  height: 120px;
  /* no need to specify the width or margins! CSS grid does it all for us. */
}

Some big takeaways here...

grid-template-columns lets us create as many columns as we can fit in a given container. In our case, we want to create columns 340px wide, and auto-fill our container with however many cards we have (wrapping to a new row as necessary).
justify-content works a bit differently in Grid land. Rather than changing the alignment within each row a-la Flexbox, it actually adjusts the alignment of the entire Grid container relative to the page; exactly what we wanted! As an FYI, Grid uses a separate property called justify-items to align items within a row.
Grid can assign the gap between items in our container, essentially applying margins between each element. This is an absolute godsend that's worth explaining in its own section!

Considering screen widths below `340px`

As mentioned previously, flexbox usually needs an extra @media query to shrink our layout for smaller screen sizes. Thankfully, CSS offers yet another magical operator for this: minmax ✨

.container-of-cards {
  grid-template-columns: repeat(auto-fill, minmax(max-content, 340px));
  ...
}

Breaking this down: the first parameter represents the minimum width each grid item can have, and the second represents the maximum width we should try to reach. In our case, we want cards to be 340px wide if possible, but shrink to 100% the width of the screen for layouts < 340px wide. In Grid land, we use max-content to represent this minimum.

2.5 When you want that "gap"

This is a frustrating one: we want to apply a constant margin between each element in a row, but not a margin at the start and end of the row.

Here's an example of the problem, taken from the Bits of Good projects page:

With our old-guild flex knowledge, we might end up with this rough layout:

<div class="outer-container">
  <div class="card">...card 1 content</div>
  <div class="card">...card 2 content</div>
  ...
</div>

<style>
  .card {
    width: 340px;
    /* add margins to either side of each card, totalling to a 60px "gap" */
    margin: 30px;
  }
  ...
</style>

This almost gets us where we want, but we end up with this awkward margin on either side of the flexbox. With a header in place, our layout gets a little out-of-wack.

If there are other sections on our page following the max-width: 1200px rule, this margin issue will get even more obvious!

We have a few options to remedy this...

Swallow up that offset with some negative margins on either side of our outer-container. This is an okay band-aid to our issue, but it's not a super readable solution. For example, what if we want a margin around our grid of cards for mobile layouts, and no margin for wider layouts? We could write this as margin: -30px -> margin: 0, but that's not super readable / doesn't spark joy in some devs' opinions.
Scrap the margin and use margin-right: 60px on every card. This requires some nth-child acrobatics to remove the margin on the last item in each row, which only gets worse as the number of columns changes 💀

...Or, we can just use Grid! As we saw in our last solution, Grid allows you to define the gap between elements from the parent container. You can even define a separate gap between rows and columns.

.container-of-cards {
  display: grid;
  /* gap between rows */
  row-gap: 60px;
  /* gap between columns in a row */
  column-gap: 120px;
  /* same card setup as our last example */
  grid-template-columns: repeat(auto-fill, minmax(max-content, 340px));
}

3. When you want that collage effect

This is a hallmark CSS Grid feature you've probably seen by now, but it's definitely worth repeating.

Say you're making a photo gallery of some kind. Instead of making rows of cards with uniform widths and heights, you want to add some snazzy dynamics to emphasize your favorite pics 📸

Here's one of my favorite examples of this end goal:

I could attempt this layout with flexbox... but I don't think 1000 lines of div adjustments and @media queries is very productive. In any case, you'd probably shoot down your designer's dreams entirely in a pre-Grid society.

You can see the completed Pen to absorb all the Griddy goodness. The biggest takeaway I want to pull out here is Grid's concept of "span:"

.container {
  /* make a gridified container with 4 columns,
  each 25% of the container width (denoted by fr / fractional units) */
  grid-template-columns: repeat(4, 1fr);
  /* don't specify how many rows (let everything auto-wrap) */
}

img.thicc {
  /* let this image span 2 columns (wider than it is tall),
  starting at the first column */
  grid-column: 1 / span 2;
  grid-row: 1;
}

img.tall {
  grid-column: 2;
  /* let this image span 2 rows (taller than it is wide),
  starting at the third row */
  grid-row: 3 / span 2;
}

Some big takeaways here...

Grid lets you specify column widths using "factional units," or frs. These are basically identify to flex units, except the container is charge of specifying them. This saves a lot of trouble when you want every element to obey a common unit.
You can allow each element on the grid to follow the specified rows and columns with no modification (each will span 1 column, 1 row by default), or...
You can add some span styling for spicy dynamics 🌶. This gives us a neat collage effect.

There are countless examples of Grid-heavy layouts to expand your realm of stylesheet possibilities. This collection of Pens is a great place to start!

Thanks for reading!

I hope this post got your gears turning on applying Grid to your own applications. I will confess, adopting Grid tends to break layouts on IE 11, so make an informed decision before applying this to production applications!

Also, expect some more posts from me over the next few months. I finally graduated college, which I have... mixed feelings about to say the least. Now, I'm trying to pump out quarantine-ridden content before I start my first adult job.

More to come soon.

How you can (sort of) write SASS @mixins in plain CSS

Fri, 08 May 2020 22:13:48 GMT

Trigger warning: I may use SASS and SCSS interchangeably throughout this post. You've been warned 😈

You probably clicked on this post thinking "wait, you can't write mixins in plain CSS. What kind of clickbait is this?"

Let me admit something right off the bat: this post does not show a one-to-one solution to replicate everything amazing about mixins. It's not like there's some magical corner of CSS to ENGAGE SASS MODE.

So yes, the pattern I'm about to detail isn't a direct translation of SASS / Stylus / LESS mixins. Still, it will help you overcome a problem that makes you reach for mixins in the first place:

You have some CSS you want to reuse in a bunch of places
You want to pass some parameters to that reusable CSS to adjust its behavior

Alright, expectations lowered. What do ya got?

Well, it all starts with our friend, CSS variables.

If you haven't used them before, CSS variables are a lot like SASS variables; you can store anything you want in them, and you can use them in any ruleset you define. However, these variables are extra powerful. Rather than being a value you define once and use everywhere, CSS variables can be reassigned at any level of the cascade. SASS details this distinction on their own documentation.

That kind of power let's you pull off something like this:

<div style="--theme-color: red">
  <p>I'm a red paragraph!</p>
</div>
<div style="--theme-color: blue">
  <p>I'm a blue paragraph!</p>
</div>

p {
  color: var(--theme-color);
}

Now, each paragraph will have a different color, depending on the variable value assigned by the parent div. Nice!

A concrete example

Say you have some social links on your site. You want all of these links to have a uniform layout, but you want to adjust the coloring to match the site you're linking to. In this case, we have two links to consider:

There's a bit more to this example than meets the eye. Notice each link has a different color in not one, but four places:

The text color
The SVG icon's fill
The link border
The background-color when you hover

Without variables, this would be extremely annoying / not-DRY. We'd have to write four rulesets (including nested styling for the icon) for every new color we add 💀

If you're cool enough to use a preprocessor, you could truncate your styles using a handy mixin. It goes a little something like this:

@mixin color-link($color) {
  color: $color;
  border: 1px solid $color;
  
  /* color the nested icon */
  svg {
    fill: $color;
  }
  
  /* change the background color on hover */
  &:hover {
    background-color: $color;
  }
}

Now, if we ever have a new link color to add, we can write a nice one-liner in a new selector:

.twitter-link {
  @include color-link(#1fa0f2);
}

Here's a Pen to show this solution in action:

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

Alright, but plain CSS can't do that...

That's where you're wrong! Though CSS lacks our nifty @include syntax, we can still pass variables to a color-link ruleset in a similar way.

Let's start with a raw example, no variables applied:

/* change our mixin to a CSS class */
a.color-link {
  /* replace each $color reference with a hardcoded val for now */
  color: #1fa0f2;
  border: 1px solid #1fa0f2;
}

/* CSS can't do nested rulesets, so we gotta separate these out */
a.color-link > svg {
  fill: #1fa0f2;
}

a.color-link:hover {
  background-color: #1fa0f2;
  color: white;
}

a.color-link:hover > svg {
  fill: white;
}

We did a couple things here:

We turned our color-link mixin into a plain ole' CSS class
We got rid of our nesting syntax since CSS still can't do that (but it could be coming soon!)

Now, we're ready to introduce some variable magic. ✨

a.color-link {
  /* replace our hardcoded vals with a variable reference */
  color: var(--color);
  border: 1px solid var(--color);
}

a.color-link > svg {
  fill: var(--color);
}

a.color-link:hover {
  background-color: var(--color);
  color: white;
}

a.color-link:hover > svg {
  fill: white;
}

And finally, we'll rewrite our twitter and github classes from before:

.twitter-link {
  --color: #1fa0f2;
}

.github-link {
  --color: #24292D;
}

Boom. With CSS variables, we can just assign a value to our color variable in whatever CSS selector we choose. As long as we apply either of these guys alongside our color-link class...

<a class="color-link twitter-link">...</a>

Our color-link "mixin" will apply the appropriate colors where we need them!

Here's another CodePen to see this working:

See the Pen by Benjamin Holmes (@bholmesdev) on CodePen.

Yes, there are still limitations

This definitely makes your plain CSS stylesheets more DRY, but it fails to address some funkier use cases.

For example, SASS can pull off conditionals and looping inside its mixins. This can let you, say, pass true / false booleans as parameters to switch between styles.

/* arbitrary example, applying different layout mixins depending on browser support */
@mixin grid-if-supported($grid) {
    @if $grid {
        @include crazy-grid-layout;
    } @else {
        @include crazier-flexbox-layout;
    }
}

Inspired by a rundown of magical mixin features found here

We also have to modify our HTML by applying more classes. Depending on who you ask, this defeats part of a mixin's sexiness. Mixins can be dropped into any existing ruleset you already have, without needing to create new classes or rulesets.

I agree with this somewhat, but this post should at least show off how powerful CSS variables really are. They can even store complicated styles with spacing and commas, like --crazy-padding: 12px 12px 0 0 or --dope-box-shadow: 1px 2px 3px #abcabc. The same can't be said for SASS mixin parameters!

Thanks for reading!

This post is part of my hard-headed goal to ditch CSS preprocessors. I definitely miss nested styles... but the power of CSS variables, combined with literal microseconds of build time whenever I save, make me happy enough with raw CSS these days 😁

In case you're interested, I have another post taking a deeper dive into CSS variables, exploring how you can down on JS style manipulation. Check it out here!

Also, expect some more posts over the next few months. I finally graduated college, which I have... mixed feelings about to say the least. This month should be nothing but pumping out quarantine-ridden content before I start my first adult job.

More to come soon.

The power of SvelteJS: building an animated image carousel in <30 lines of code ✨

Tue, 07 Apr 2020 20:01:36 GMT

Ah image carousels... the classic web dev conundrum. Back in the dark ages (so like 5 years ago), you'd be reaching for bootstrap faster than you could spell "bower." But now, with all the crazy component-based frameworks at our disposal, we might as well build one with our bare hands.

I've build carousels in a couple settings (React, Angular 1.x, vanilla ES6) with varying degrees of simplicity, but nothing compares to a neat trick I found using Svelte. I'll start by walking through a solution you can use in any framework you choose, then cover the super slick solution I found. This article should help whether you're already using Svelte, or you're considering it for your next web project. Since some Svelte newbies might find themselves here, I'll try to explain any Svelte-isms that pop up. Onwards!

What we'll be building

Let's see what kind of carousel we're talking here.

The behavior we want to see

A simple "next" button should show us the next image. We should also wrap around to the beginning when we reach the end of our carousel.
Images should fade between each other. This means we can't just change the image's src everytime we hit "Next." There's a short in-between state where two images are showing, one fading out while the other fades in.
The animation shouldn't break when we click really fast!

TLDR

I get it. You're excited and what to copy / paste some working code into your project. Well, head over here to see a sandbox of the solution running with a nice browser preview!

You can also skip down to Using a Svelte-y approach to understand how this works.

Note: the images may load somewhat slowly. I'm using picsum.photos to generate random images, but they should load faster if you're using static assets in your own project!

🚀 Check out the finished REPL

The framework-agnostic approach: flip-flop between image elements

Before jumping into the real Svelte magic, let's see how we'd approach a carousel traditionally. I include this example since it's framework agnostic (easily made with vanilla JavaScript too!), and similar to carousel tutorials you may have seen before. Still, we'll implement the algorithm using Svelte as a demo 🕺

In short, we need to take care of that annoying "in-between" state where two images are showing during the fade animation. Naturally, we should probably add two images to our markup:

<img src="/static/image_1.jpg" />
<img src="/static/image_2.jpg" />

Let's also assume we're keeping track of our image carousel URLs in a big JavaScript array. That may look something like this:

const carouselImages = [
  '/static/image_1.jpg',
  '/static/image_2.jpg',
  '/static/image_3.jpg'
];

Now, we need to figure out the logic to set the image sources correctly every time "Next" is clicked. This can get a little hairy, so let's walk through how our little algorithm will work:

The first image element is showing the first image in our array. The second image is hidden.
When we click "next," we set the source of the second image to the next image in our array (so image 2). Then, we animate that image into view while the other animates out of view.
The second image element is showing the second image in our array. The first image is hidden.
When we click "next," we change the first image source from the first image in the array (index 0) to the third image in the array (index 2) so that it shows the next image in the sequence. In other words, we bump up the index by 2. Then, we animate the first image element into view while the other animates out of view.

... continue the pattern, bumping up the index of the hidden image by 2 every time it gets displayed.

Here's a visual demonstration of how all that works!

The code

If you've worked with component-based frameworks before, you've probably identified the state variables we need to keep track of:

firstIndex The array index for the first image src
secondIndex The array index for the second image src
showFirst A boolean for which image is currently displaying. In this case, true means we should show the first image, and false for the second

Since this article's all about Svelte, I'll be using that framework to create and update these guys. But don't worry! This should be a pretty easy transition from your current framework of choice.

Initial setup

<script>
	const carouselPhotos = [
		'https://picsum.photos/300/200?random=1',
		'https://picsum.photos/300/200?random=2',
		'https://picsum.photos/300/200?random=3',
		'https://picsum.photos/300/200?random=4'
	]
	
  // state variables (yes, just regular ole "let" variables!)
	let firstIndex = 0
	let secondIndex = carouselPhotos.length - 1
	let showFirst = true
  
  const next = () => {
		// logic goes here!
	}
</script>

<img src={carouselPhotos[firstIndex]} />
<img src={carouselPhotos[secondIndex]} />
<button on:click={next}>Next!</button>

To start, we've created our state variables, carousel src URLs, all the markup we'll need, and a simple button click handler to jump to the next image.

Also, notice that secondIndex starts at the end of the array. This is because we want our second index to start one image behind our first, so when bump up its index by 2, it becomes the next image in our array. Since we'll be allowing our indices to wrap to the beginning, we'll consider the last image to be the one before our first.

Show and hide images on click

Now, let's write our handy algorithm using code:

<script>
  ...
  const next = () => {
    if (showFirst) {
      // if the first image is showing, make sure
      // the second image shows the next array element
      secondIndex = (secondIndex + 2) % carouselPhotos.length
    } else {
      // vice versa if the second image is showing
      firstIndex = (firstIndex + 2) % carouselPhotos.length	
    }
    // flip-flop!
    showFirst = !showFirst
  }
</script>

That wasn't too bad! Notice how Svelte just lets you manipulate state variables directly without any fancy hooks of "data" objects. Just modify regular ole JS variables, and the UI will react ✨

Here's how we can use our variables in the markup:

...
<style>
  img {
    opacity: 0;
    transition: opacity 0.5s;
  }
  .visible {
		opacity: 1;
	}
</style>

<img class={showFirst ? 'visible' : ''} src={carouselPhotos[firstIndex]} />
<img class={!showFirst ? 'visible' : ''} src={carouselPhotos[secondIndex]} />

All we need is a dynamically applied CSS class depending on our showFirst variable, and a couple styles to modify the opacity for a nice fade in and out.

Demos

🚀 See the full solution running at this REPL

😎 See the solution using vanilla JS with few modifications!

Cool solution! Is it the best one though?

So in the end, this code is ready-to-use in your project no problem. I have a few complaints with it though:

We have to write out two image elements in our markup, which feels a little repetitive. This will get more noticeable as we add more classes, attributes, and inevitable container <div>s around each of them.
We're using three state variables for one piece of functionality. This may not sound like a lot, but it hurts the readability of our solution a bit. I bet if you stumbled across this code in someone's repository and didn't have shiny GIFs to understand the algorithm, it would be pretty confusing on first sight.

Using a Svelte-y approach

Now, let's start using some Svelte-specific magic. There's two approaches that I find cleaner than the image flip-flop: one that's pretty readable but a little longer, and another that's super sleek with a little added magic.

Simple array mapping

So you're probably familiar with how to render a list of content to the page, whether that means a .map, an *ngRepeat, a v-for... you name it. You're also probably familiar with conditionally rendering elements with an if statement ({condition && ...}, *ngIf, v-if, etc.). So what can we do with these powers combined?

Well, make an image carousel of course! Let's check out this little chunk of code:

<script>
  ...
  let currentCarouselIndex = 0
  
  const next = () =>
  	currentCarouselIndex = (currentCarouselIndex + 1) % carouselPhotos.length
</script>

{#each carouselPhotos as photo, index}
	{#if index == currentCarouselIndex}
		<img src={photo} />
	{/if}
{/each}
<button on:click={next}>Next!</button>

Bam! Now we're iterating over all the photos in the carousel, then only showing the photo matching our current index. This means we only need one state variable total: currentCarouselIndex. Thankfully, I don't think I need to explain how Svelte handles for loops and if statements here. It's very readable on its own 😁

But wait, what about our in-between state? In most frameworks, the "if" statement doesn't just change the opacity of a given element. Rather, it decides whether that element gets thrown on the page at all. So in this case, we'd obliterate the previous image in our carousel before it even has time to fade away! Hm...

Transitions to the rescue

Luckily, Svelte has a solution for this already included in the library: transition directives ✨

At a basic level, here's how they work:

When an element first gets thrown onto the page (based on some conditional if statement), it triggers a tiny JavaScript function that animates that element into view.
When that element gets removed from the page (based on the same conditional), it triggers another tiny JavaScript function to animate that element out of view. Then, only once this animation finishes, the element gets removed from the document entirely.

This lets us support the in-between state only when we need it! Here's a transition directive in action:

<script>
	import { fade } from 'svelte/transition'
  ...
</script>

{#each carouselPhotos as photo, index}
	{#if index == currentCarouselIndex}
		<img transition:fade src={photo} />
	{/if}
{/each}

That's it! All we have to do is import the transition we want to use and apply it to our image. Then, let Svelte handle the JavaScript for us to add and remove elements at the appropriate time.

Here's a new visualization of what's going on:

And yes, you can customize the transition to your heart's content. Svelte has a great tutorial series on everything you can do with transitions. It's a little tricky to master, but you'll see that it's just as powerful as CSS transitions and keyframes!

In the end, this is my favorite solution. But I bet we can do it with even fewer lines of code...

Modification: The array key trick

Note: kudos to the incredible Rishov Sarkar for finding this trick!

Yes, our solution is nice and readable, but it feels kinda silly to iterate over all the photos in our carousel just to pick out 1 image to render. Ideally, we want to tell Svelte that each image is unique, and we should animate between them whenever the src changes.

Luckily, there is such a way to uniquely identify each image: keys

We now know that transitions will trigger based on a conditional. But according to the Svelte docs: "An animation is (also) triggered when the contents of a keyed each block are re-ordered." This is meant to help with, say, simple todo applications, where you might want to animate-in newly added list elements. As long as you apply a "key" to each element in the list (similar to the key prop in React), Svelte will know which elements are "new" between renders.

So how can we apply this to our carousel? Let me throw the solution at you:

... everything from the last solution

{#each [carouselPhotos[currentCarouselIndex]] as photo (currentCarouselIndex)}
		<img transition:fade src={photo} />
{/each}

Woah! What did we just change?

Most importantly / weirdly, we're now iterating over an array with only one element. In this case, we're creating an array containing just the photo at our current index.
We add (currentCarouselIndex) to the end of our #each statement to assign a "key" to each item in our array. We know that the index is a unique identifier for items in our array of photos, so we can use it as the key for our image element. Since there's only one element in the array total, we can use our state variable as the unique indentifier.
We remove our conditional statement, since Svelte already knows the image is unique based on our key!

This feels a little strange on the surface, but it's actually quite simple. At the start, we have an array of one element: the first photo with a "key" of 0 (our current index). When we hit "next," we transition from showing [carouselPhotos[0] (key 0)] to [carouselPhotos[1] (key 1)]. To us, it looks like we created an entirely new array. But from Svelte's perspective, it looks like we removed the first photo from our array (key 0) and added the second photo at the same time (key 1). So, it applies a fade out for what we "removed" and a fade in for what we "added."

So, we took our already short-and-sweet solution and made it even shorter / sweeter 🚀

Demo

Feel free to edit the sandbox code to try out both solutions. Also take a peak at the "JS output" tab in the preview window, which shows you exactly what get code is running on the page. In under 200 lines, all of this magic is possible without any hidden libraries or imports 🔥

🚀 See the full solution running at this REPL

That's it!

In the end, all solutions presented here should be good enough for a production-ready site. But I hope this post taught you some neat tricks that Svelte offers out-of-the-box to create some pretty complex UIs in just a few lines. In the end, our "key trick" solution comes in at under 30 lines of HTML, CSS, and JS combined!

We also applied this solution in the real world with great success. Check out the homepage for the Bits of Good organization, partnering Georgia Tech students with nonprofits to build seriously-useful web apps.

You can check out the source code for this component here. The markup may be a little hard to read since we're nesting images in a big SVG vector, but you'll notice the "key trick" getting used the same way we just learned 😁

Before you go: thanks for staying strong

I'm writing this post in the thick of COVID-19 social distancing. You may be a student grieving over missed opportunities or graduations, a mother or father spending too much time with your kids, or a recently unemployed household trying to make ends meet.

This is definitely a difficult time for all of us, but if there's any silver lining, it's all of these online learning opportunities at our disposal. So I'm glad you took the time to give this a read! If you've never used Svelte before, I hope it inspires you to pick it up 😁

The web dev tools that helped me get s*** done in 2019

Fri, 03 Jan 2020 20:13:06 GMT

Now that we're turning over a new year (a new decade even!), I wanted to take a minute to remember all the tools that made my life easier in 2019. "Best of" lists for web dev tend to summarize the technologies in general terms. So for this, I want to focus more on the projects I worked on this year, and how these technologies helped me do them. Onwards!

Netlify

I'm probably not alone in absolutely gushing over Netlify all year. It's just so freaking easy to get from zero to deployed! In brief, Netlify is for deploying a website frontend, along with a ton of extra goodies: continuous deployment, support for hooks, custom domains with automatic SSL certificates... all wrapped in a gorgeous dashboard that's easy to navigate.

I deployed two pretty big projects over there: my portfolio website at https://bholmes.dev, and the landing page for our Bits of Good organization over on https://bitsofgood.org. I hadn't managed custom domains in my life before this, but Netlify walked me through every step of copying DNS configs and other network-y things. I also highly recommend allowing Netlify to manage your domain over your domain provider, since they make setting up subdomains and SSL certificates so much easier 😁

Rapid testing on mobile Safari

Bet you've heard this one before: the website looks great on the "mobile view" in Chrome dev tools, but the layout completely breaks on the actual phone 🤦‍♂️

Well, Netlify actually has a solution for this: manual deployment from the command line. Instead of pushing up a new git commit every time you want to move that margin 5 pixels to the right, you can just push up your build directory at a URL of your choosing! This is perfect for testing a frontend before making a PR, and Netlify will make sure all your serverless functions, API proxies, and extra production setup get deployed as well.

This was pivotal for our Bits of Good homepage, where we had some magical CSS to reorganize our swooping vector graphics on mobile views. Also helped us catch a screen sizing issue well before pushing a PR!

Using Netlify Forms

I just dipped my toes into this, but Netlify forms proved a super quick and easy solution to storing HTML form responses without a backend. This came in clutch for our new Bits of Good "Contact Us" page. Originally, we planned to make an API request once the form's submitted to POST to a serverless function, which could then forward messages to our email. Not terrible, but sounds like a good 6-7 hours of work (we're bad at backends, so hold the I-could-do-this-in-negative-3-hours 😆).

Now with Netlify, here's all we have to do (for free mind you!)

Add data-netlify to our form element
Make sure each element in the form as a name attribute (which it already should for accessibility reasons!)
Add a name attribute to the form itself so we can see which form gets piped into Netlify
Profit 💰

Boom! All form responses now get stored on Netlify, complete with pretty solid spam detection. We can also deploy our serverless function for email forwarding directly to Netlify, which already has hooks for detecting form submissions. Nice!

Svelte v3

I stumbled across this library at the end of last year, when it was the #1 write-in for the State of JS 2018 survey. It was running on v2 at the time, but I was still blown away by it's mission statement: the magical disappearing framework ✨

Now, I've built more projects with it than I can count! Here's the gist of why it's so awesome:

It's a library that gets out of your way at runtime. Instead of having some "virtual DOM" to manage the page or a needless JQuery dependency, it just slaps the code you wrote onto the browser with zero added dependencies! It'll generate helper functions as needed of course, but the difference in production bundle size is staggering.
You manage state without even realizing it. Instead of having a setState function or something similar, you just change your JS variables directly... and Svelte knows how to update the page. There's some extra tooling to handle edge cases, but this is definitely the biggest time saver for me!
The templating is super minimal. All you need to know is how to write a for loop for lists of elements and how to insert JS variable values. There's a bunch of added goodies for binding and event handlers once you find the need.

For a quick rundown on how easy Svelte is to learn and use, check out my blog post exploring the tool from a teacher's perspective!

Svelte for quick projects

Svelte has become my new go-to for getting small projects up and running fast. I've been to a few hackathons at my university (go Yellow Jackets!), and I use this Svelte template to start working on a web UI. I started reaching for Svelte over, say, React because of how easy it is to make new components. Each component is basically "sandboxed" in its own file, where you write vanilla HTML, CSS, and JS while having all your styles and scripts scoped to that component alone. It's almost like whipping up a CodePen, if you could compose CodePens to create a mega-Pen for your entire website 😁

One of my favorite highlights was for a hardware hackathon called BuildGT. The premise: play a frame of bowling with a Roomba as the ball! The end product is something that never should have existed, but it was super fun to get everything talking to each other. We handled communication between the Roomba and the Kinect sensor (for fallen pin detection) via web sockets, but the icing on the cake was the instructional UI built on Svelte in a matter of hours.

The hack

■■■■■▣□□□□ 59% #100DaysOfCode

Joined a team for the 12 hour hardware+software hackathon #BuildGT. 41 projects total... And we managed to take 1st 🏆 ! Here's a demo of our hack in action: Roomba bowling feat. a raspberry pi, Kinect sensor, a web UI, and web sockets 🔥 pic.twitter.com/XIvsz3D2pN
— Ben Holmes (@BHolmesDev) March 3, 2019

The UI

■■■■■▣□□□□ 59% #100DaysOfCode (part 2)

Spent a lot of my time on the web UI. Kept it super simple with raw HTML and CSS, and used @sveltejs v3 to build it super quickly and change state based on web socket messages. Also grabbed those classic bowling alley anims 😆 pic.twitter.com/fA8gpNxgzk
— Ben Holmes (@BHolmesDev) March 3, 2019

Svelte for static sites

Aside from getting out ideas quickly, Svelte has some tricks up its sleeve for static site generation too. We use this for our Bits of Good org website (full repo here), built on Svelte and the Contentful CMS. To help with routing and prerendering the actual static site, we're using the magical Sapper framework to manage it all for us. This acts a lot like NextJS, but offers some really nice benefits:

Management of server-side rendering to make that initial page load fast. Similar to NextJS, you can specify all the API calls you want to fire before the page loads like so.
Management of routing behind the scenes. It even lets you use a regular old a tag to link to other routes on the site, rather than importing some special Link component.

Sapper also uses a build tool you can actually understand: Rollup!

If you're wondering what a CMS is, it's an external tool for storing all the text and images used by your website. This comes in handy working with non-techy team members who want to edit the content of the site, but don't know how to code. Instead of asking a developer, they can just open a web portal and edit the content themselves! Headless Wordpress is one of the most popular examples of this.

This lightweight build tool came in handy for managing our Contentful CMS setup. Rather than wrestling with webpack for days on end, Rollup was easy enough that we could set up a plugin from scratch! The docs walked us through every step of the process and led us to a pretty slick solution. All we do is import our text and image content from the CMS with an API call, convert markdown to HTML as necessary, and slap everything in a fat JSON at build time.

Now, whenever a component needs to include some content from the CMS, we can just import by that content's ID. For example, here's how we would fetch all of our nonprofit projects for our project highlights page:

import projects from '@contentful-entries/project'

Bam! Now projects is an array of JavaScript objects with all the text and image URLs we need. As you can see, Rollup also helped us add an alias called @contentful-entries to make content retrieval a little easier. For those curious about the nitty-gritty details, here's our final RollupJS plugin ✨

CSS variables / custom properties

This was a big win for CSS when it hit browsers in 2018. In 2019, the feature's matured a ton and scored some pretty great browser adoption. Yes, IE is still the problem child... but there's some good polyfills at this point if you need them 🙃

Source: caniuse.com as of January 3, 2020

I've started using these across the board to finally ditch SCSS for managing colors, font sizes, margins, etc. These are also much more versatile than the variables you'll find in SCSS preprocessors. Here's the main benefit: instead of creating static variables at the global level, you can now create variables that only apply to the element getting styled. In other words, these variables can exist at any level of the cascade, and dynamically update with the power of JS or CSS keyframes!

This was super useful when I moved some complex style calculations from JavaScript over to CSS with calc() magic. Crucially, CSS variables let me make JavaScript variables visible in CSS using inline styles.

To see CSS variables in action, check out my blog post on a practical application!

Contraste

Disclaimer: This is an app only available for Macs at the moment

This is more of a "design" tool than a pure "web dev" tool, but I use it so often that I can't help but mention it here.

Contraste is a dead simple tool for one thing only: checking the text contrast on a page to get an accessibility rating. This is measured by "ADA compliance," which applies a score of A, AA, or AAA depending on your site's accessibility to the visually impaired. This all comes down to text contrast, which isn't as easy to eyeball as I thought!

I freaking love this tool just for how simple it is, and the fact that it's a global tool rather than a browser extension. It's actually exposed some accessibility concerns when going from designer mockup to live website, where colors on the web don't quite match the beautiful colors in the mockup tool.

Before I go, thanks for all the support this year 😁

I started this blog back in March with a quick little post: Why I'm using Surge and not GitHub pages. I threw it out there not really knowing what I was doing (even managed to write some technical inaccuracies on a 3 minute read 😆), and expected maybe a couple likes by the morning.

Then, I opened my profile to find over 100 followers and close to 1000 views. Excuse me!? For this?

To be honest, it was a major stroke of luck from sending the right tweet at the right time (thanks for the like Emma Bostian!). If you're stuck trying to find readers on your own blog, all I can say is this: never stop writing. Never stop advertising yourself. And please, never stop learning.

So, after this freak accident and many posts later, I want to thank everyone so much for supporting me. It really gave me the motivation to see my blog through and genuinely love teaching others about web development. I'm apparently ending the year as one of the Top 500 authors on dev.to which is... a ridiculous milestone I'll never understand.

So, here's to many more posts and learning opportunities in 2020! Cheers 🥂

HTML5 tags - how do they work, and which ones should I use?

Mon, 02 Dec 2019 23:01:19 GMT

Let's get down to the fundamentals. Whether you've seen HTML or not, it may feel unclear when to use each element, or even what elements are available these days. The following should be a helpful cheatsheet for web dev beginners and markup professionals alike!

This article is a snippet from Bits of Good's web dev bootcamp. If you like what you see, head over here to view the full course (with written resources, video walkthroughs, and project activities) for free!

Starting with definitions

HTML, or Hypertext Markup Language, is a language used to define the "skeleton" of a webpage. It isn't meant to include any bells and whistles, and it definitely won't look pretty on its own! It's simply meant to define what gets shown on the page, from images to text and everything in between.

All modern browsers support the latest HTML standard: HTML5. This adds a whole host of features to improve the structuring of webpages. Namely, it adds special elements to denote the "layout" of the page, like where the navigation bar is, where the footer is, and so on. This is super useful for visually impaired individuals that rely on screen readers to browse the Internet, since it's now easier than ever to explain all the landmarks on the page right from the HTML!

Getting into syntax

When writing HTML, you will be working with something known as a tag. Basically, this is used to define some block of content you want to display on your website. There are many different tags you can use for different types of content, like blocks of text, images, headings, and so on.

For example, we can use the paragraph tag <p> to display a block of text like so:

<p>
  Hard work and no play makes Jack a dull paragraph.
</p>

Note that we need to right the tag twice: once to define where its content starts and again to define where it ends. In this case, it starts before our block of text (<p>) and ends just after our text block (</p>). Note you need an added / to denote a closing tag versus an opening tag. This whole block start to finish is called an element.

Attributes

Along with declaring a tag, you can also add a set of attributes to that tag for extra information. These are written using the format attribute="value" inside the opening tag.

The class and id attributes are the most common, which will be explained better once we start using CSS. Another example is declaring the language used by your page with lang as shown below.

The main wrapper

<html lang="en-US">
  <body>
    <!-- More to come in here! -->
  </body>
</html>

This is a basic wrapper you would always want to put around your HTML file. First, we create the base html element and specify our page's language using lang="en-US". Since anyone from Canada to Singapore may access the websites you build, it's best to specify the language so translation tools know what to expect!

Next, we add our body for all of our website's content to live. This is denoted by the body element. Also notice the  inside. This is how comments work in HTML, so whatever's inside those brackets won't be shown on the page.

Note: If you use CodePen, each Pen automatically adds these html and body wrappers for you around whatever code you put inside the "HTML" box, complete with the language specification. So, no need to use it on every CodePen you create, but know it's an important concept when building website outside of this tool!

Important tags

There are many HTML tags worth knowing. You can find the full list here, but these are some highlights you should know for getting started 🏃‍♂️

Tags for content

<p> A paragraph block; the most general block when you want some text on the page
<h1> ... <h6> A header block, with h1 being the highest level header, h2 being the second highest, and so on. A newspaper article is a solid example of this, where the article title would be an h1, each section heading would be an h2, and each subheading would be an h3
ul / ol A block for creating a list of content. Use a ul when you want a bulleted (u nordered) list and an ol for a numbered (o rdered) list
- li, or l ist i tem, for each element inside of the list
dl A block for creating a more complex list of content. This works a lot like a ul / ol, but now each item can have a title and a description as two separate blocks. Perfect for lists that have a header / body structure
- dt The "definition title," or the title of a list item
- dd The "definition description," or the content of that list item Note: No need for a wrapper around these two elements. Just place the dd element below its associated title dt, and the list item should look right! If you absolutely need to, it's safe to wrap these in a div for styling purposes.
<span> A wrapper around text within a paragraph or header. This is great for targeting certain lines or words in a text block for custom styling
<a href="https://penguin.club"> A weblink to some other website or a page within your own website. The link is specified by the href attribute
Note: You can force links to open in a new tab instead of the current page by including the attribute target='_blank'
<img src="https://cute_cat.gif" alt="gif of a cat eating ice cream" /> An image, with the actual image file coming from the src link and the alt describing the image. You can read the alt when hovering over an image or when using a screen reader
<button> A button you can click. You'll use JavaScript to get buttons to actually do something, but we'll leave that as a mystery for now 😁

Tags for the layout of that content

<header> A page header, often with the site banner and navigation bar
<footer> A page footer, often with important links that couldn't go anywhere else
<main> The main content area of a page. Helpful to separate from the header and footer
<nav> The navigation bar of a webpage (aka that ribbon at the top with all the links to other pages on the site). Usually within the <header>
<section> A sub-portion of the main content. Good for dividing up, well, sections of the page. Yes, nesting sections within sections works as well!
<div> A general way to define a container. You'll end up reaching for these when working on page layouts, trying to position content in certain places on the page

`<div>` versus `<section>`

Generally, you'll use a <section> to group elements under common themes, like in a book report outline you'd write in high school. A <div>, meanwhile, is not used to convey this sort of separation. Take a news article as an example. We may say the article's content and the comments are two separate <section> elements. However, each comment, along with the container for like and dislike buttons, are just <div>s.

Try these elements yourself!

Hop over to codepen.io and make a new Pen. Start pasting some of the tags above into the HTML section to see what they display in the preview box!

See these tags in action

Now, let's take a look at a completed website to see how the HTML is structured. We'll be using your browser's "inspector" for this, and you can follow along by visiting the live site at https://gsg.surge.sh. I encourage you to open this tool on some of your favorite website as well to see how they structure their own markup.

Found this helpful?

Great! This article is part of a huge suite of resources used by the Bits of Good organization to teach newbies the ropes. If you want to...

💅 learn how to write better CSS with your bare hands
⚙️ get the hang of array functions in JS
📶 figure out how to talk to APIs
👩‍💻 build feature-rich frontends and backends using JS frameworks
🏃‍♂️ and most anything else in the world of web dev,

Check out the Bits of Good bootcamp. All activities, written resources, and projects are free for you to explore and share with others 😁

👉 You can access the curriculum here!

If you have any feedback, criticisms, or content suggestions, message us at hello@bitsofgood.org.

What I learned planning and building an MVP as a frontend dev at Peloton

Tue, 03 Sep 2019 14:57:01 GMT

Writing this, I just finished my summer internship at Peloton Interactive 🥳 As I hang up my biker gang helmet, I wanted to talk about my biggest learning experience: working on a large-scale ReactJS project from concept to MVP presentation. I'll walk through the process of planning and building the project from start to finish, discussing the lessons I learned along the way.

Before you click away hearing the word "internship," note this is a 100% real project that is deployed to production right now!

Note: This post touches both on the product planning process and some of my learnings with git and design. Since I don't know my audience's background writing this, I hope you find some takeaways on any front that speak to you!

So, what was the project?

Simply put, to fix... this.

It's nice to see a lot of open positions. Well, unless you get lost trying to find the right section header 😕 There is also a major problem with company presentation. I don't know about you, but a big list of jobs alone doesn't get me excited about the company I'm applying to!

So, my team was tasked with ripping out our infinite list of open positions and putting something much friendlier in its place. We also needed to communicate the company's story better to get people to smash that apply button!

Lesson 1: Competitive analysis is important!

Like any starry-eyed CS student, I expect to start hacking on the frontend right away while the design mockups poured in. But slow down there! There was a lot of research we needed to do first. Otherwise, we might end up with another bottomless list of poor usability.

At Peloton, analysis of existing solutions (other career sites in this case) is done by the UX designers. Though I didn't play a part in the end experience from a UI perspective, I needed to weight in on options for implementation. In other words, how can we load all of our job listings as fast as possible without too much technical overhead?

For some background, Peloton's existing careers page uses the Greenhouse API to retrieve job postings and display by department header. This is done through a single, extra-large API call to get all the job listings with all of the departments and all of the job descriptions attached. With hundreds of listings and thorough job descriptions on each, that call gets... chunky.

If we try to get that on a poor cell connection, it can take up to 10 seconds before we can start scrolling!

What are some better options?

With this in mind, I started checking the network activity for existing career pages using Greenhouse. From dev tools alone, I could already piece together some smarter approaches to try:

Paginated loading using a custom endpoint. Since the Greenhouse API doesn't offer pagination, I'd need to add an endpoint to Peloton's backend to divvy up the Greenhouse response into pages. This would turn our page into a full-stack endeavor, though it wouldn't be too difficult.
Using PHP with Greenhouse's API plugin. Though this adds some helper methods for each endpoint, it adds little functionality over just making the calls myself. Plus, I'd have to learn PHP 😬
Building a 100% static site. In other words, no network calls at runtime for instant loading. However, popping a static site generator like Gatsby into the repo was almost out of the question due to technical overhead. So, I'd need a custom solution to poll Greenhouse at build-time and keep that list of jobs up to date, which is also fairly complex.
A hybrid of pagination and static content. Spotify Jobs uses this to show the first page of listings instantly and poll the API for additional content. Though slick, this has similar overhead as building a 100% static page.
Loading just the departments on the homepage for a much smaller API call. When choosing a department, I could retrieve the listings for that department alone.

I noticed another easy win looking closer at the API: each job listing includes a URL linking to the job description and application form. This means we can avoid loading the job descriptions entirely and link to the applications directly, saving a ton on response size.

How did this inform the design?

After researching the Greenhouse API and weighing out these options, I had enough info to come back to product and design. With design observing the UX of existing solutions and myself observing the tech behind them, we converged on a solid approach:

Just display a list of departments on the homepage, along with the number of openings for each. This cuts down on API response size while making the homepage more inviting.
Create landing pages for each department. Each should include their respective job listings and a location filter.
Add some extra sections on company mission for some added 🌶️. For the MVP, this meant using the existing company perks section and adding a video on company culture.

This obviously isn't the perfect solution in the end. What if a user wants to browse all job listings by location? How will someone interested in a retail role browse compared to an engineer scoping out the HQ?

These questions are worth asking as the team fleshes out the best experience going forward. However, we couldn't lose scope of the problem at hand: making the existing experience snappier and more inviting. If our MVP succeeds in that, it's still a great starting point!

Lesson 2: Epics are super helpful for task breakdown

After researching ideas and deciding on a solution, we needed to start building actionable tasks. I've done my fair share of semi-thought-out GitHub issues, but this added a whole world of product terminology to the fold.

The first was the "KPI," or a key performance indicator. To put it less fancily, we needed to measure the value a feature would have for the project and the company as a whole. This guided the MVP design process to see what the minimum set of features would be to make a kicka** careers page. By extension, this guided the user stories our tasks would focus on.

...Which brings me to user stories. Though this was covered in my college curriculum, I had little perspective on how useful they were in project planning. For those unfamiliar, the format goes a little something like this:

As a [stakeholder], I want to do [something] so that [reasons].

Based on this, we can figure out all the tasks necessary to make that goal happen. This often leads to an "epic" each actionable task branches off of. I'd think of the epic as an overarching feature we're developing to address a specific user story. From this, we can work out the major tasks the developers and designers should work on.

For us, this started with a few user stories:

As a visitor, I want to find the career I'm looking for easily so I can apply.
As a visitor, I want to view all the jobs available for my preferred location so I can view my opportunities there.
As a visitor, I want to learn more about the company so I can decide if it's a good fit for me.

From these, we worked out some actionable epics:

Display job listings by department
Allow filtering of job listings
Showcase a video about Peloton company mission

With these MVP goals mapped out and mockups in place, it was time to start developing!

Lesson 3: Smart subtasks lead to manageable PRs

This was a hard lesson to learn as the king of adding unrelated fixes to my branches 🙃 Though I improved working on team projects in college, I rarely had to plan out a month of tasks myself so PRs could smartly build off of each other. This was difficult at times without getting my hands dirty first, since I may not know the technical challenges of features before starting on them. Even so, instead of diving in head first per usual, I had to sit down and plan a semi-realistic roadmap.

In the end, I worked with the project manager to get a list of steps I'd complete:

Get the careers page displaying at the new URL (we were using [onepeloton.com/careers](http://onepeloton.com/careers) instead of the old /company/careers for better discoverability)
Port over the existing "Perks" section to the new page
Get the list of departments pulled in from greenhouse, properly formatted for frontend use
Display the list of departments on the page
Add a banner image with a "call to action" that will scroll to the list of departments
Add independent department pages that can be linked to by name (ex. the "Apparel" department can be reached at onepeloton.com/careers/apparel)
Pull in job listings from Greenhouse to display on each department page
Add a location filter
Add a department filter that redirects to the different department pages

Making this holistic overview was really help in judging the scale of each feature. It also helped me figure out which tasks were dependent on others, like setting up URL routing before building out the visuals.

So how did you make sure each PR was "manageable?"

Though this task list guided our issue board, some issues were easily large enough for multiple PRs.

Filing down the task list into PR-able subtasks led to some hiccups along the way. For example, I noticed both the department page and landing page needed access to our API dispatch functions, so I restructured these layouts to use a shared wrapper component. An extra PR needed to pop up for these situations to keep the purpose of each push hyper-focused. Though this meant more PRs overall that the team needed to review, the scope of them was much clearer! I learned this pointer from a fellow dev who made sure PRs touched about six files or less, excluding one-line edits for imports and the like.

Test-driven development also helped gauge the size of each PR. This was a lesson best learned the hard way... by putting out an absolute unit of a PR no one had time to review.

This happened when taking on a task and judging its scale at a surface level. Here, I was setting up URL slugs for each department, so each could have their own link-able landing pages. At first, this seemed like a simple mapping from the names of each department to a slug and setting up routing to display the right page. This had some minor caveats, like waiting for the departments to come in from Greenhouse before generating the slugs, but this easily built on the code I already had. So, I made a new git branch, started hacking it out, got the pages working...

and realized I wasn't handling redirects for bad slugs.

This check for redirects ended up being a little more than met the eye. A coworker showed me a much simpler way to handle redirects using Redux state management, but it took over a week for him to get around to reviewing my code!

This is a classic example of how thinking in terms of tests could have shown me all cases I needed to consider, making it easier to break everything down. In my experience, the size of the test file often reflects the size of the final PR. So, if those unit tests are easy to predict, try writing them out early to understand the scope of a feature. If getting 100% test coverage isn't possible, try writing down all the possible use cases for the feature before diving in 😁

Lesson 4: Designer communication is key

I will confess, this wasn't my first time working with designers on a project. However, they were usually less experienced or working on smaller scale projects with a lot of flexibility around the end product's design. Working with trained UX... xperts on a new project was a new experience, but an exciting one!

First off, getting regular feedback from designers was very helpful for hacking out the CSS. This meant UAT reviews, or giving feedback on a test version of the site, and desk-side checks for more visual PRs. At Peloton, designers work on a pretty strict desktop - tablet - mobile mockup system with specific pixel breakpoints for each. This led to some detailed feedback on all of the layouts I created, down to the smallest 10px padding adjustment.

As you may expect from such detailed guidelines, Peloton has a comprehensive design system to manage the scalability of elements. In fact, they have a small team of "UI engineers" communicating closely with designers to keep their system up to date. This means using Storybook to keep track of all the buttons, headings, banners, etc. for both designers and developers to reference. This made my job a lot easier working out sizing and spacing for text and navigational components, with just a handful of custom layouts left to style by hand. Just paying attention to the breakpoints and using flexbox was all it took to handle these effectively!

The final landing page for careers. All buttons, headers, and image sizing are from Storybook components, while the arrow icons and 2-column layout use custom CSS.

There was also close communication on imagery used for each page of the MVP. Namely, we needed to work out breakpoints for where the image would need to be cropped. For example, if a figure at the right side of the image on desktop needed to appear in the center on mobile, two differently cropped versions of that image would be necessary. I could use some positioning magic to crop using pure CSS, but since our project used Cloudinary to serve differently sized images based on screen width, there was no reason to get that hacky!

Wrapping up

My time at Peloton this summer was an amazing and rewarding experience. It's rare that a lowly intern can be the main developer on a project team, given the same responsibilities and expectations as a regular employee. It's even rarer that an intern gets to present that feature to company stakeholders, and have that project get deployed to production unchanged! If you're interested, you can view my slide deck from the MVP presentation (yes, it's using mdx-deck!).

And to check out the finished product, go here!

Overall, I am extremely grateful for my time at the company, and I'm excited to see how the careers project progresses. I hope these lessons I learned along the way help you on your MVP development journey! 🚀

Using Typescript string enums? Consider string literals!

Mon, 29 Jul 2019 14:39:03 GMT

If you've been using TypeScript for any amount of time, you've probably wondered this at least once:

Can I use string values instead of numbers on TypeScript enums?

This often comes up when you want a variable to have a select few string values. For example, say you're creating a banner for a website that's either yellow for warnings or red for emergencies. You want to make something reusable, so you add a enum for which type of banner it is:

enum BannerType = {
    Warning = "warning",
    Danger = "danger"
}

This gives you a lot of flexibility of how you can use that enum's value. A common use might be defining a class name for styling your banner:

{/* Yes, this is written a JSX-y fashion for you React users */}
<div className={BannerType.Danger}>Uh oh!</div>

This is much easier than writing weird helper functions and ternaries to figure out what class name to use. There are many more use cases for enum string values, like object keys, CMS content identifiers, paragraph text, error logs, etc etc etc.

When string enums fall flat

There's a few annoyances you might find with enums + string initializers:

They're a little verbose
They require lookups and tooltips to see what the actual string value is
They're limited in the special characters the enum can use

This last point was a huge point of friction for my web development team. To explain, we were looking to generate keys for content coming from the Contentful CMS. In Contentful, a key can be any string you could dream up. This means you can, say, include dots to indicate a subcategory (ex. "labels.danger") or dashes to mirror URL slugs (ex. "checkout-promo-code").

Clarification: A "CMS" is an external service to host all of the content for your website. In our case, we are using Contentful to store all of the header text, body text, images, and videos we display. In order to retrieve this content, we make an API call to fetch by specific keys.

This poses a problem for our enum solution. We need to use the keys in order to retrieve the site's content, and mapping each Contentful key to an enum means tossing out all the dots and dashes! Needless to say, this could lead to some nasty collisions between keys that are unique in Contentful but not unique on our hacky enums.

String literals to the rescue!

Luckily, TypeScript has a cleaner solution when you need those string values. You can provide a finite list of strings a variable can be assigned. Otherwise, it should throw a type error.

This will also prevent you from assigning a traditional "string" type to the string literal. So, when declaring your types, you'll need to export the string literal type and use it the same way you would use an enum.

You can see from the informative gif above that autocomplete works as well!

Limitations

String literals aren't the silver bullet for every situation. Notably, using string literals doesn't improve on the verbose nature of enums. In fact, it'll often provide more information than necessary when assigning the literal type.

It's also more visually unclear what all possible values are when assigning 'random string' instead of SpecificTypes.Enum. This requires team communication to decide if string literals work best for smooth PR reviewing and text editor / IDE support.

How to revert your git commits without panicking

Thu, 13 Jun 2019 02:23:26 GMT

Step 1: Take deep breaths

The best way to overcome your escalating fear that your codebase / world is collapsing around you is deep breathing. Before frantically flying to the keyboard, just go in through the nose... and out through the mouth.

Step 2: Look over the commit log

Before doing anything you might regret, it's best to look through all recent commits to pinpoint where you're reverting to. The cleanest way to do so is using:

git log --oneline

This will show all of the commit history for your branch, starting with the most recent. It also shows branch points to see the history of everything that got merged.

Also notice the alphanumeric strings to the left of each commit. These are hashes which uniquely identify a given commit. Once you find the inflection point for your code explosion, copy the hash for that commit and move on to the next step.

Note: You can exit this log by hitting the "q" key. This is very vim so I don't blame you if you got stuck here 😛

Step 3: Diff against the most recent commit

Checking for differences against your revert point is a great way to verify what changes you're about to make. To do so, use the copied hash and run the following command:

git diff HEAD COPIED_HASH^

Let's break this output down. First, we see a log of all binary files changed, with paths listed as a/file_path and b/file_path. These files are often editor / build specific files (as in .vscode or .circleci directories) and image files. In this case, the the resolution of a few images were updated.

Next, we see a line-by-line breakdown of lines added and removed from each modified file. Note this is from the perspective of changing from our most recent commit to the commit we're reverting to. So, everything in green is what will be added after reverting, and everything in red will be removed.

Also note the ^ at the end there. This makes sure we diff down to the ancestor of that commit hash. Otherwise, the diff will stop one commit early.

If you scroll through this and everything looks good, it's time to obliterate those commits!

Step 4 Option 1: Run a commit revert (recommended)

The first option is the most obvious one: run the revert command onto the commit hash we're reverting to. This is very straightforward:

git revert COPIED_COMMIT_HASH..

Note that doing so will create a new commit meant to revert all changes made down to the commit specified. This works well since you should be able to push your changes and have a clean change log as intended.

Worth warning that this will open a confirmation file in vi (assuming you're using the default git editor) for each commit being reverted. If everything looks as expected, type ":wq" to confirm the reverts.

You can also add the --no-commit flag to stage each revert without actually creating a revert commit. This is useful when reverting several commits deep since it allows you to submit one large revert commit at the end. Otherwise, you would end up submitting a revert commit for each one individually.

Still, you might want to change your commit history entirely so it appears those nasty commits were never there. For that, there is a second option...

Option 2: Rebase and drop commits

Note: Read the disclaimer at the end of this section before going with this option.

Rather than making a revert commit, you can modify the commit history directly using a rebase. To start the process, type the following:

git rebase -i COPIED_COMMIT_HASH^

Notice the -i flag here. This is a shorthand for --interactive, which allows you to edit each commit individually from the head to our specified commit hash.

It's simple from here to drop all of our commits. The instructions are actually visible right there in the comments, but as a TLDR: Replace every "pick" with a "drop" for all commits listed.

...If you're stuck wondering why your delete key isn't working, that's because git uses vi as the default editor. You can go here to change over to your favorite editor for this process, but if you're fine sticking with vi, it shouldn't be too difficult.

To start editing, hit the "i" key and use the arrow keys to move your cursor around
Move your cursor over to each "pick" statement, delete, and replace it with "drop"
Once all the picks are replaced, hit "esc"
To confirm the rebase, type ":wq". This will save the rebase file you just edited

If you want to abort at any time, delete all the lines listed above the commented section (those starting with "#") to force the rebase to error out. If you're using vi, just mash "d" repeatedly until the lines are gone 🙃

If your terminal window closes or something else happens, the rebase will hang uncompleted. To abort the rebase and start over, enter the command git rebase --abort.

If all goes well, you will have officially changed history!

Disclaimer

Modifying git history can be a problem if you have already pushed now reverted commits to the remote branch. After reverting, it will appear your branch is behind the remote, so you cannot push directly anymore. In this case, you will have to run git push --force-with-lease. This flag will force your history onto the remote by removing those dropped commits. with-lease acts as an error check to ensure the rest of your commits are in line with the remote's.

You may have heard using --force on a push isn't best practice since it involves rewriting commit history on the remote. This can be a problem for others working off of the same branch, since their history will no longer line up with the remote's. There are ways to fix this, but make sure others are aware of your force push before they run into trouble!

Wrapping up

Hopefully by the end of this you've gotten your branch back on track! Mainly, always make super sure of what commands you're about to run when modifying commits, especially when editing git history directly. This can be a very daunting task for beginners and experts alike, so making sure of the diff and viewing the commit log are a must!

I actually wrote this article after having to go through the same process for my job, wanting to give my hastily written notes some clarity. Hope this helps others stuck in the same boat 😊

How using CSS variables helped me cut down on JavaScript

Fri, 31 May 2019 03:37:13 GMT

Note: My post is inspired by this article from the brilliant Chris Coyier about the power of CSS calc(). Definitely worth a read!

If you’ve been keeping up with web development since 2018, you’ve probably come across CSS custom properties / variables. They’ve become the new hotness in applications even beyond just using raw CSS, as they offer scoping and cascading that even new CSS-in-JS solutions like Styled Components don’t directly replicate.

I hadn’t given CSS custom properties much of a fair shake when I first learned about them since I’ve become such a prop slinging, CSS-in-JS devotee (please hold your criticism 😛), but my recent project required me to go back to traditional stylesheets due to using the exotic framework, SvelteJS.

At first, simply declaring styles as necessary without any form of variables seemed manageable; whenever something custom needed to happen based on code, I could just whip up a string of inline CSS and tack it onto my element without worrying too much about optimization. However, while the website still seemed snappy, my codebase was growing less and less readable. Enter: CSS variables!

Sidenote: There was a time people would shout from the rooftops "they're not called variables; they're custom properties!" Thankfully, relevant MDN documentation and general lingo has caught up to just calling them variables. So either works, but "variables" is a little clearer in my opinion 😊

So how do CSS variables work?

To those unfamiliar, you can declare a variables within any element you choose, or within the :root selector to make it globally accessible. Just use --[property-name] syntax so CSS will pick it up as a variable…

:root {
    --global-var: 50px;
}
.some-class {
    --scoped-var: 4%;
}

… and then use those variables in sub-elements (or any element for global properties) using var(--[property-name]).

.child-of .some-class {
    margin: var(--scoped-var);
}

This is similar to how CSS attributes work, except CSS variables can take on any unit of measure you choose, then be used to define any CSS property. This means you get the same kind of flexibility that variables in pre-processors have been offering for years now, though with an admittedly clunkier syntax (hey, that’s CSS3 for you 🤷‍♀).

What’s not as well known is how CSS variables can be unitless. This doesn’t seem like a huge deal at first, but it offers a big advantage: combined with calc(), CSS variables can be used to scale properties by a set amount. This was invaluable in refactoring own code, since it meant I could rewrite my CSS string construction in JavaScript with just a couple lines of CSS calculation.

Let’s see an example

To show custom properties in action, I’ll take a logic snippet from a portfolio concept I built out.

The goal was simple: I wanted an accent bar to cycle through a set of gradients on a loop, shifting from one gradient to the next. This would be possible with a single animation keyframe, though I had a caveat: a looping interval was being used on other elements of the page with logic CSS couldn’t replicate, and I wanted to use the same interval in my accent bar for consistency's sake. This interval was, of course, defined in JavaScript using setInterval(...). Whenever the callback function was hit, some CSS needed to change. This interval was set in a parent component and accessed within my accent bar component (yes, I'm using a component-based framework).

Before diving into the example, note that this project was built on Svelte. This shouldn't affect the readability of the code too badly; just accept that the lesser details involve some magic ✨

The end goal

My old way of doing it

Originally, I cycled through the gradient by creating a wide background image with hidden overflow, then shifting the background position on each tick of the interval. This gave the illusion of the background shifting colors, though it was essentially moving through one large gradient. However, this background position required a fair amount of calculation.

To keep all the interval tracking simple across several components, I was keeping track of a gradientIndex variable passed as a prop. This index corresponds to a list of gradient colors I am cycling through called GRADIENTS.

However, this means some extra logic is necessary to update the CSS: whenever the gradientIndex is changed, a new CSS string needed to be constructed to be applied as an inline style. Thus, we need to dig out a lifecycle method to construct our strings when the gradientIndex prop changes. In Svelte, this is accomplished using the afterUpdate callback function:

...
afterUpdate(() => {
  backgroundPosition = `${(100 / (GRADIENTS.length - 1)) * gradientIndex}%`;
});

We also need to figure out the background size for our overflow by getting a percentage from GRADIENTS.length:

const backgroundSize = `${GRADIENTS.length * 200}% 100%`;

Finally, we throw this into our inline style alongside our constructed linear gradient background:

<span
  class="bar"
  style="background-image: {backgroundImage};
  background-position: {backgroundPosition};
  background-size: {backgroundSize}"
></span>

So yes, the end result functions pretty well without any performance problems... on my overpowered MacBook anyways 😛 However, we've added a fair amount of complexity that will only get worse as we scale. We've added a lifecycle method to handle our inline CSS construction, and we're littering our JavaScript with variables that would ideally be kept within the styles where they belong. If only there was a way to calculate this using just CSS!

A new, more readable solution

So how can we tackle this problem using CSS variables? Well, looking at the string for background position constructed in JS, we see the calculation requires knowing how many gradients there are (GRADIENTS.length) and the current index to figure out position (gradientIndex). So, why not just make each of these CSS variables?

Thankfully, CSS variables are settable using inline styles like any other CSS property (the same can’t be said for variables in SASS!). So, let’s say both our aforementioned variables are part of the component state. We can make them visible to CSS using the following inline style:

<span
  class="bar"
  style="background-image: {backgroundImage};
  --index: {gradientIndex};
  --length: {gradientLength}"
></span>

Now, we can determine our background size and position within CSS just by using calc():

.bar {
  --index: 0;
  --length: 0;
  background-size: calc(var(--length) * 200%) 100%;
  background-position: calc((100 / (var(--length) - 1)) * var(
  --index) * 1%);
}

There are a couple things to unpack here. First, we set each variable to some initial value for the sake of completeness. This isn’t necessary since the inline style should always be applied, though initializing CSS variables is a good habit to get into. Next, we set our background position similar to our JS, with one notable difference: we multiply the --index by a percentage, rather than write the percent sign directly after the variable. This is because calc() treats the variable like a constant in mathematics, so it has to be multiplied by some value for a unit of measure to be applied.

Oh, and here’s our new JS snippet: …wait, there isn’t one anymore! 🎉

Can we go even deeper?

Something this example doesn't take advantage of is variable cascading. This is super useful for component-based development, since you can consolidate a lot of wacky CSS calculation into the parent component. Then, child components can just access the CSS variables from higher up in the cascade. In our example, we could make gradientIndex a CSS variable in the parent wrapping around our color bar and avoid passing it as a prop entirely!

Of course, this can start to have a negative impact on readability, with variables several levels up cascading down without the developer realizing it. This exposes the age-old conflict between cascade thinking and component-based thinking, so use this technique sparingly.

Wrapping up

With that, it should be clear that custom properties can be pretty powerful to take your JavaScript logic over to the stylesheet. Additionally, now that CSS variables are compatible with most all modern browsers (except IE of course 😢), they should be pretty safe to experiment with even in production code. So go forth and get to styling!

Git + GitHub Best Practices for Teams (Opinionated)

Thu, 16 May 2019 19:50:13 GMT

Disclaimer: This was adapted from a guide written internally for our Bits of Good organization to help newbies get their footing when joining a project team. You can learn more about the organization here if you're interested. Yes, we are reworking the website these next few months :)

There are P L E N T Y of articles out there with a new spin on how to best use Git. Given how versatile and free-form the tool can be, it's easy to find a new system that works for someone. As such, there really isn't a catch-all gold standard that everyone must follow. So don't take the contents of this article as the law! This is merely an opinion piece with suggestions our Bits of Good organization has found to work well.

Note that Bits of Good is a college-level organization, so my opinions are based on experiences with smaller teams rather than working at large companies. So, issues like backlogs, ticketing, and user feedback are not covered here given my limited exposure.

Creating and Organizing Issues

Before jumping into modifying the codebase, let's talk about organizing what needs to be done first. A nifty GitHub feature is the option to create "issues" to break down tasks into assignable chunks. This is helpful in a team setting to decide on deadlines and priorities to keep everyone on track.

What a good issue should say

Let's start with an example of a bad issue:

Not only is it unclear how the final result should look, but it's nowhere near enough direction to keep a newbie's head from exploding. Do everyone a favor and break issues down!

GitHub themselves are nice enough to include example headers whenever you create a new issue. These are super nice for getting started, but may prove to be a little too much for the issues you create. At a minimum, try to include:

If it's a feature: A description of the feature being added to the project
If it's a bug: A description of what the bug is and how to replicate it
A breakdown of action items. This should be a list (with checkboxes preferably) of bite-sized tasks to complete in order to finish the feature / resolve the bug
General notes for the feature / bug or improvements that may be needed down the road
Discussion points if the team still needs to decide on certain details

The action items should be the bulk of the issue. You can get as granular or technical as you want, so long as it makes someone's life easier trying to read the issue. Good ideas are to include hyperlinks to potential solutions and supporting images like mockups as a guide.

Optional: Break down the action items like a tutorial, walking the reader through one potential method of coding out the issue. This is great for new team members so they don't feel lost navigating an unfamiliar codebase.

Here's an example of how to beef up that confusing one-liner issue from earlier:

Leveraging milestones

If your team happens to use Agile development or another form of rapid release cycles, you should probably avoid chucking issues around without any reference for completion timeframes. GitHub allows you to get a focused view of what you're working on for each dev cycle / sprint using "milestones." This is little more than a subset of issues in the repo at a given time.

To view these, look for the "milestones" button within the "Issues" tab. From here, you can create a new milestone with a useful title, description, and deadline. You may tack an issue onto a given milestone using the sidebar when creating a new issue. In general, make sure you don't have too many issues in a given milestone. It may take some time to feel out how long certain tasks will take, so stay optimistic in the beginning and pull back depending on the workload.

A look at our team's past milestones working on an Agile development schedule. We found emojis can help focus milestone objectives 😛

Branch flow using Gitflow

It's easy to jump into a new project and immediately think "screw the formalities, I'm gonna jump into some code!" Well, it's easy to forget an important detail when blinded by excitement: you should always branch off of a development branch first!

This approach is often lost on beginner Git projects, branching off of master alone and merging in whenever code gets the thumbs up. This approach works well on small-scale projects that are only seen by developers most of the time. However, When users get involved that may access the live project at any time, pushing to a "production" branch like master for every change may not always be a good idea. For example, say the you're on a team building a notification dashboard, with two developers splitting up the UI and a third working on API endpoints. Instead of pushing to master or working off of some awkward middle-way branch, wouldn't it be nice to push to a develop branch to merge everyone's changes gracefully?

This process is known as Gitflow, using a develop branch for building out features and a master branch for the user-facing code. Other flows include further branching stages such as a staging branch, used for testing and validating code before it is merged into the master branch.

Setting up this flow is extremely easy in Git. Just leave the default master branch, treating it as the production branch, and checkout a new develop branch off of master to branch from going forward. Also make sure all pull requests made to the project are targeted at this branch instead of master! The only PR to master should be from the develop branch itself most of the time.

Branching best practices

If you've been through a workshop or basic Git tutorial before, you've probably made branch names like Ben-Holmes, bug-fix, or homepage-57. Please don't do this!

As a general rule, try to title branches like an overarching todo task for yourself. So, it should be descriptive enough that you know exactly what you're working on, but kept to 5-7 words or less so it's not impossible for teammates to type. In addition, the scope of a branch should be more focused than broad so all your commits are working on a common issue. This has an added bonus of avoiding little "side quests" while you're coding. If you see a little spelling mistake on the splash page that has nothing to do with what you're working on, don't make the fix in your current branch!

Formatting

You can use whatever works best for the team of course, but a solid practice is to:

Start the branch name with either your name or your Git(hub, lab, whatever) username. This makes it easier to come back and find your branches later.
Include the issue number your branch resolves. If your building something without an issue attached (don't do this too often!), use a short tag on what your branch is trying to resolve. This could be feature, bug, poc, etc.
Add a 4-5 word title on what your branch does. You can use dashes, underscores or camel case to separate the words.
Use a consistent character to separate all of these 👆 like a dot or a dash. You can also uses slashes, but this can have some unintended git-y consequences!

Let's see an example

Say you’re working on an issue titled "#154: Add profile picture editing to the 'My Account' page." As the title implies, you are adding an option to the user's account management page to edit their profile picture, say, when they click on the image. Here's a decent branch name for the issue:

git checkout -b pr0H@ck3r.154.my_account_edit_profile_pic

Yes, this is a pretty rigid structure for a simple branch name. However, it really improves scan-ability when there are tens or even hundreds of branches open at a given time!

Committing best practices

It's the end of the day. You've exhausted your third cup of coffee and finally squashed an Internet Explorer bug that took hours to track down. Now you're ready to push up your changes and finally shut your computer. So, what's the best way to communicate all the pain and suffering you worked through with the team?

git commit -m "fixes"

😓☕️ Well... it's definitely not this. The commit message isn't some throw-away blob of text that no one will ever look at. This is the developer's chance to explain what their code is meant to accomplish, so when a peer combs through the log of changes you made, they will be able to step through the commits and track which changes are worth adding. This is invaluable for the occasional rollback, when changes made beyond a certain commit should get scrapped.

Writing a good commit message

So, how can you make the most of a commit message? First, it's best to start with some verb to describe what adding the commit to the project will accomplish. This is often a present tense phrase like "add," "fix," or "include."

Following this, include a brief phrase to describe the commit's purpose, usually in 50 characters or less. If you use VS Code, the built-in commit menu (the third button down in the sidebar) will do this check for you. This limit should be a check for yourself on how focused the content of the commit actually is. For example, if you were committing a bug fix for an out-of-place profile picture in Internet Explorer, a solid message might be:

git commit -m "fix profile picture position on homepage IE"

Spacing out your commits

Yes, that was a pretty easy example to contrive. Commits can easily span many more files and many more features. Always try to fit within the character limit as well as you can, but if there's too much to explain, it might be worth breaking up the commits into smaller chunks.

This can sounding daunting at first, but Git offers a handy tool for this when you're staging everything for a commit: git add -p. Rather than staging all your changes at once, this allows you to walk through each change to the codebase you've made file by file, giving you options to stage at each step. Here's a sample output staging some ESLint configuration files:

Here, we see a script added to the file package.json, along with a number of ways to respond for staging. If you're unsure about what all those random letters mean, just type the "?".

This can be a tedious process for larger commits, but is super helpful when just starting out with Git. It's also safest to commit like a madman so your changes are easy to summarize, and you won't have to do this walk(through) of shame as often.

Extended reading: Much of this section comes from experience and various Stack Overflow sources, but this is a great long-form read on quality commit messages.

Pull request best practices

Everything about Git we've talked about so far has been pretty standard fare: you read through an issue, you make a branch, you commit code to it, you push it up. It's easy at this point to push everything to the development branch and call it a day... but hang on a minute! If you're working on a team, it's probably best to have someone else review the changes you've made before merging them in.

The first best practice for pull requests are to... just do them 🤷 Whenever an issue is resolved by the branch you've created and your changes are pushed up, whip up a PR.

There admittedly isn't a great way to do this from the terminal, so it's likely easiest from GitHub directly. Note that the purpose of a PR is to allow others to review your changes before merging into another branch (most always the development branch), so be sure you have already rebased the remote master / develop branch onto yours to make reviewing changes a bit easier.

Note: If you are unfamiliar with rebasing, it is essentially merging but with an adjustment to the commit history. With rebasing, all commits in the remote will be placed before your own commits, making it seem like your branch is building off of the new remote. This article has a nice visual aid for showing how that works.

Once the pull request is made, add people for review so they will get notified. It's usually best to reach for people who did not work on the change with you so they can review your approach with a fresh set of eyes. However, if you are a fan of pair programming, it's possible to bypass the review process after having a solid back-and-forth with your partner.

Here's an example of what I'd consider a good pull request. First, note that the team's lead was requested for review (shown by the checkmark in the "reviewers" section). Also note that the comment box offers a detailed breakdown of what changes were made in the branch. This can be structured however you choose, but it's best to at least:

Include the issue number so the reader can reference what is being resolved
Write a bulleted / numbered breakdown of each feature added, or changes made to resolve a bug

Below this, there is a log of each commit made in the branch requested for merging. This shows how important quality commit messages are!

Let CSS frameworks empower you, not control you

Mon, 29 Apr 2019 14:54:27 GMT

Many articles tackling the issue of CSS frameworks either argue whether or not they should be used in a project at all, or dig deep on the pitfalls of each potential option. From my experience, there's a bit more nuance to it than that. CSS frameworks have a clear place to take care of all the hefty CSS logic that grows hard to maintain, like accessibility concerns, modal / pop-up visiblity, desktop vs. mobile nav bars, and so on.

But where do you draw the line on what should be framework-infused and what should be custom? More to the point, how do you stop feeling so controlled by the framework that nothing you make has that special touch?

My philosophy

I had to encounter this issue recently when joining a project team in the Bits of Good organization at my university, Georgia Tech (go yellow jackets! 🐝). I inherited a project a semester in progress that needed some serious wind in its sails to hit the finish line, but there was one little hitch: the site was thoroughly entrenched in Bootstrap.

I personally love whipping up small design systems for new projects, so switching to a CSS framework felt like a bit of a chore at first. However, I found some clear utility in it: it was now much easier to, say, include popover modals with background fade, or use decent buttons and dropdowns without worrying about tab focus. With this, I found the best way to reconcile my world of customize-all-the-things with my team's lego-bricking approach was to treat frameworks as a utility.

CSS frameworks shouldn't be the driving force behind how elements look and feel, nor should they govern the flexibility of the site at different screen sizes. Rather, they should be a place to grab those little bits and pieces when custom solutions stop making sense. I understand that this philosophy is hard for some to justify when they need that homepage done by yesterday; still, I think this can work at any level with a little adjustment of where the custom stops and where the framework utility begins. With that, here are the main points I want to expand on.

Don't rely on cookie-cutter layouts.

This is a pretty major problem I've seen, as fairly simple layouts get overly complicated by the constraints of framework layout styling. Though recent efforts like Semantic UI have done a better job of adding flexibility to the fold, there are still some severe rough edges that can make writing markup take longer than necessary.

I saw an example of this recently when a teammate was working on a pretty straightforward screen for our app: an applicant info view. This was just meant to be a list of headers and paragraphs to describe someone's name, email, address, personal bio, and so on. However, the curse of Bootstrap caused the document to become... this.

<Container>
  <Row>
    <Col>
      <Heading>{`${applicant.bio.first_name} ${applicant.bio.last_name}`}</Heading>
    </Col>
  </Row>
  <Row>
    <Col>
      <h5>
        <Label for="email">Email</Label>
      </h5>
      <p className="content">{applicant.bio.email}</p>
    </Col>
    <Col>
      <h5>
        <Label for="phoneNumber">Phone Number</Label>
      </h5>
      <p className="content">{applicant.bio.phone_number}</p>
    </Col>
    <Col>
      <h5>
        <Label for="birthDate">Birth Date</Label>
      </h5>
      <p className="content">{applicant.bio.date_of_birth}</p>
    </Col>
  </Row>
... a lot more row / columns

This is what I refer to as "spreadsheet hell," where seemingly everything on the page feels like it has to be a row or column in some grand table defining the site. Thankfully, this is using the popular component framework React, so I can spare you the more laborous <div class="col xs-4-72-57-sqrt(pi)"> on every tag 😉

Yes, crafting containers from scratch can be tough. But once you start using Flexbox or CSS grid more often, getting your HTML chunks to appear where you want can start to feel much quicker just writing the CSS directly.

In sum, to reduce overhead and make layouts work well, take a stab at some custom styling before letting the framework do it for you.

Tweak that border radius if it feels right

Another issue with CSS frameworks is how they encourage "window shopping," where you start to design your website around the default components. This works for getting up and running fast, but I'm sure you've visited countless sites that feel a bit too... bootstrap-y.

This is a more difficult hurdle that can be framework-specific. Most offer theming options for color and font overrides, but decidedly little beyond that. So, I find it helps to start picking which components of the site can have a more unique feel, and which can stay in framework-land. This is a fairly arbitrary choice I say is best left to your design preferences and what you can build with your CSS skills. However, changing something small like adding a textured background or a call-to-action button with a dramatic drop-shadow can do a lot to make a site feel like your own.

Here's a simple example from our own site. We had just added content search functionality to the applicant viewer, wiring up all the frontend and backend logic to get it working how we wanted. However, presenting it to our client, we found an issue: it was unclear how to change what you are searching by. This is because we were using a default bootstrap button for the dropdown icon, so it wasn't clear how it was associated with the searchbox. So, we broke out some custom CSS to change the button's background color and push it closer to the input box, complete with a unifying border radius. The end result felt much cleaner!

Don't let frameworks decide your functionality

This is the biggest point to drive home, since it's rare that a CSS framework will cover every possible element you can have on your site.

Our team ran into this pretty early on when building out our administrator dashboard. In short, we were designing an applicant viewer where an admin could quickly switch between volunteer applications to view applicant info and change their approval status. After some discussion, we decided that something similar to an email panel might work best, with an overview of applicants and their statuses along the left, and a space for each full application on the right.

We certainly could have gone window-shopping through the sea of bootstrap components to find inspiration. However, this probably would have steered us towards some sub-optional pull-out menu or tab view that didn't quite hit the mark. This goes back to my point that frameworks are really a utility at the end of the day; if they can't help you out, don't reach for them!

Here's our final administrator dashboard, complete with charmingly repetitive dummy data!

To sum up

Building websites is hard. That shouldn't surprise anyone. It can be easy to see CSS frameworks as a catch-all to build a site from scratch with no experience required, but they all come with their own sets of gotchas and limiations that can hamper the quality of your site. When working on a new page, I'd say just consider the following:

What do you want this to do?
What navigation, layout, buttons, etc. could best help you do that?
Is there any overlap between that and the CSS framework you are using?
If so, does the styling best suit your needs, or could it use a 🌶 switch-up?

A neat DIY solution to animating on scroll (for any framework)

Tue, 09 Apr 2019 15:46:47 GMT

Update 4.10.19 A recent comment below blew my mind name dropping the Intersection Observer API. This was essentially built for exactly what this article's about, allowing you to fire a callback whenever an element is in a certain position on the screen! The latter parts of the article about centralizing logic with a store are still totally applicable to this, but intersection observers clean up things a great deal over requestAnimationFrame while also being more performant. However, note there is no IE support and Safari support only just recently. Alrighty, enjoy the rest of this post 😊

Looking around the world wide web for inspiration, I've found that many sites I love incorporate fun little "reveal" animations whenever I scroll to certain elements. Though subtle, these extra touches make the page feel much less static and more responsive. The question is though... what's the best way to implement this?

Just scrolling through CodePen examples, I have found time and time again that people are reaching for catch-all libraries that can handle it for them. There are countless options out there for animating on scroll, the most prevalent being the aptly named AOS. I myself was hoping to 🌶 up my site with some scroll animations, so I naturally thought to turn to AOS library for this. However, as my implementation grew more and more specialized (ex. how to I avoid loading this iFrame until I scroll to it?) I began to wonder...

Can't I just build this myself?

Maybe. Let's see how

Just starting with basic, vanilla JS and no frameworks, the approach is actually pretty simple. All we need is an onScroll handler and whatever elements we actually want to animate. Starting with the basics, say we have an element of a specific ID we want to trigger an animation for. As you might imagine, we can reach for the DOM window's onScroll event to figure out where our element is on screen whenever you, well, scroll:

window.onScroll = ({target}) => {
    const element = document.getElementById('animate-me')
    const elementTop = element.getBoundingClientRect().top
    if (elementTop < document.body.clientHeight) {
        element.classList.add('scrolled-to')
    }
}

There are a few nested object attributes we need to grab for this. First, we need to get the pixel value for where the top of the element is on screen. There are a few valid ways of finding this, but through a quick internet search it seems getBoundingClientRect() is the most reliable way of doing so across browsers.

With this, we should compare against the fixed height of the document. This is basically just the height of your browser window, being the clientHeight. If the top of our element is less than this height, then some part of it must be on screen. Now, we just add our keyframe to our CSS on .animate-me.scrolled-to and we're good to go 👍

Okay great, we basically recreated a MDN help page example...

With that out of the way, let's actually make this useable in the real world. Firstly, if you got curious and threw a console.log statement in there, you likely got this whenever you twitched your scroll wheel.

This reflects how expensive analyzing every scroll event actually is. We're executing a function for every pixel we scroll, and as we start making this function more robust, that can start causing lags and stutters.

One way to resolve this is using a requestAnimationFrame to decide when our callback gets fired. This is another window-level function where you may queue up callbacks for the browser to call. When it feels it is ready to execute those functions without un-buttery-smoothing your scrolling experience, it will fire them off. Thankfully, this approach has seen relatively high browser adoption. All we need is a wrapper around our onScroll handler to requestAnimationFrame, along with a boolean flag to let us know whether or not our previous callback is done executing:

let waitingOnAnimRequest = false

const animChecker = (target) => {
    // Our old handler
    const element = document.getElementById('animate-me')
    const elementTop = element.getBoundingClientRect().top
    if (elementTop < document.body.clientHeight) {
        element.classList.add('scrolled-to')
    }
}

window.onScroll = ({target}) => {
    if (!waitingOnAnimRequest) {
        window.requestAnimationFrame(() => {
            animChecker(target)
            waitingOnAnimRequest = false
        })
        waitingOnAnimRequest = true
    }
}

Great! Now our calls should be a bit more efficient. But let's address a more pressing issue: how do we get this working for any element in the document we may want to animate on scroll?

It certainly wouldn't make sense to keep adding callbacks for each possible ID or className we would need, so why not just create a centralized array we can append all of our element selectors to?

Time for some loops

This addition is fairly straightforward leveraging querySelectorAll. Just create a global array with all selectors that should animate (either IDs or classes) and loop over them like so:

let animationSelectors = ['#ID-to-animate', '.class-to-animate']

const animChecker = (target) => {
    // Loop over our selectors
    animationSelectors.forEach(selector => {
        // Loop over all matching DOM elements for that selector
        target.querySelectorAll(selector).forEach(element => {
            const elementTop = element.getBoundingClientRect().top
            if (elementTop < bodyHeight) {
                 element.classList.add('scrolled-to')
            }
        })
    })
}
...

Now our scroll animation checker should be able to handle any element we throw at it!

Neat! But I use X framework...

...and I don't think I could use this because of Y 🤷‍♀️

Now hold it right there. I understand everyone's tooling has its own set of quirks, so let's try to address some of them.

I use a component system, so how do I centralize this logic?

Though it would be nice to have a succinct list of classes and IDs we would want to animate, components, especially with scoped CSS solutions, make it difficult to keep this list readable and expandable.

Thankfully, this solution just needs a single array of strings to get working, so we can use a global store each component can update with the DOM selectors they want to animate. I used this in a recent project built on SvelteJS, which uses a subscription-based global store. To update animationSelectors, I just created it as a store...

export const animationTriggers = writable({})

... and added the class name from whichever component when it gets created.

import { animationTriggers } from '../stores'

onMount(() => {
    animationTriggers.set([
      ...$animationTriggers,
      '.wackily-animated-class',
      '#section-id',
    ])
  })

This works just as well for common global state solutions like Redux and React Context as well. Redux implementations widely vary by middleware so I'll spare the multi-file example here, but here's an option using React Context (which works in vanilla React):

// store.js
...
const AnimationTriggerContext = React.createContext()

class StoreWrapper extends React.Component {
    constructor() {
        super()
        this.state = {
            selectors: []
        }
    }
    render() {
        return (
            // create a provider to wrap our components in at the parent level
            <AnimationTriggerContext.Provider value={{
                // make our array of selectors accessible from all children
                selectors: this.state.selectors,
                // add a helper function to update our array
                addSelector: (selector) => {
                    this.setState({
                        selectors: [...this.state.selectors, selector],
                    })
                }
            }}>
                {this.props.children}
            </AnimationTriggerContext.Provider>
        )
    }
}

//childManyLayersDeep.js
...
class Child extends React.Component {
    componentDidMount() {
        this.context.addSelector('special-class')
    }
    render() {
        return <div className="special-class"></div>
    }
}

//wrap the child with a 'withContext' so it can be accessed
export default withContext(Child)

Naturally, this method is extendable to VueJS, RxJS observables, and basically everywhere else you might use a global store.

Okay that's pretty nifty... but I can't use basic CSS selectors. These are components!

Okay fair point; this can complicate things in most component-based frameworks. The simplest compromise is to pass a reference to the element itself in our "add" function instead of the class name so we can avoid DOM querying. Overall, the humble ref attribute in React or Vue, rather than a class or an ID selector, should do the trick for this.

Also, I'm using CSS-in-JS and would rather not check for class names to start animating. What are my options?

This is a fairly common pattern these days and tends to rely more on prop passing that on class name switching. Thankfully, we have pretty much all of the logic in place to figure out these props based on our store. All we need is an extra object attribute on the selector we pass in, say a scrolledTo flag, which can be set "true" or "false".

For this, we would modify what we add to our store to go from just a string (or ref) to an object...

{
    selector: 'class-name',
    scrolledTo: false,
}

...and update its flag when scrolled to.

const animChecker = (target) => {
    ...
        if (elementTop < bodyHeight) {
            animationTriggers[currentIndex].scrolledTo = true
        }
    ...
}

Now we can subscribe to our array of animationTriggers (or grab the context, depending on your implementation) and pass our scrolledTo flag as a prop to the component's styles.

In Summary

So before you protest that you could have gotten your favorite animate-on-scroll library working in the time it took to read this article... I get it. But I would say taking this feature as a fun little challenge to build out yourself is super helpful for understanding how to make sleek, efficient DOM listeners. It also means you will have one less dependency to worry about in your package, so no breaking changes and a lot of flexibility for adding new features!

To see this solution in action, it is used all over the place on our Georgia Tech club's homepage: Golden Swarm Games. Visit the site or the repo to see how our scroll animations work under the hood.

Why SvelteJS may be the best framework for new web devs

Tue, 19 Mar 2019 22:03:49 GMT

Any web dev who's been at it for a few years has likely heard this question every other day.

I'm really interested in learning about web development, but I don't know how to start. Any suggestions?

A decade ago, this would have been an easy answer. Just make an index.html, throw some tags in there, make that header turn red with CSS, and reach for JQuery (or plane ole JavaScript, depending on who you ask) to handle those mouse clicks!

...Oh, how things have changed. Now we're running around with build tools, client side routing, special frameworks with fancy runtime scripts, binding "this" everywhere, template literals, CSS-in-JS... how do we choose what matters most? 🤷‍♀️ We can't start teaching how React uses a virtual DOM if someone doesn't even know what the DOM is!

This has led to countless avenues to start with with varying degrees of "just type this now, and I'll explain later." Some encourage beginners to just learn React or Vue right away to get started with modern practices, while others scream from the mountaintops that beginners should always start with the fundamentals. Truthfully, there are merits to both approaches. The former can get newbies excited with hot reloading and components, running the risk of leaving too much to the unknown, while the latter gets beginners understanding how DOM manipulation works under the hood, while possibly steering people away with the complexities of JS we've since abstracted away.

What we need, then, is a middle ground. A way to get started with the fundamentals while soaking up modern concepts like component-driven development, scoped vs. cascading CSS, templating, declarative functions, etc etc etc.

##Enter: Svelte

SvelteJS is a pretty new kid on the block just starting to get some attention. Some may know it as the most popular write-in for the State of JavaScript 2018. For the abridged explanation, Svelte is meant to be the framework that isn't really a framework; it's basically a tool to compile components down at the build step, allowing you to load a single bundle.js on your page to render your app. This means no virtual DOM, no frameworks on top of frameworks, and no framework to load at runtime.

These are pretty big selling points for more experienced developers, but most beginners probably couldn't read that last paragraph without their head exploding. Luckily, it's not this compilation sorcery that makes Svelte so beginner-friendly. It's actually the syntax.

If you've never seen a Svelte component before, here's a really basic example:

<p class="pretty">Here's some markup <strong>written by {name}!</strong></p>

<style>
    /* here's some scoped CSS */
    .pretty {
        color: red;
    }
</style>

<script>
    /* ...and a variable we can access in the markup */
    let name = "Ben";
</script>

Let's unpack this a little. So first off, it's worth noting that all of this can live inside a regular .html file, or a .svelte file if your heart desires. Also, we see some familiar tags reminiscent of framework-less development: <style> and <script>. Sadly, writing styles and JS in these tags is necessary for properly building scoped components, but it allows syntax highlighting to work without extra text editor extensions like CSS-in-JS solutions. Plus, Svelte's build step is smart enough to scope any component-specific styles by default, so you won't have styles bleeding between components.

You'll also see some magic happening with that JavaScript variable called name. This is a shiny new concept for Svelte v3, where any variable in your component's script is accessible from markup. Thus, there's no framework specific syntax to learn for state management, so no Angular $scope, no React this.state, and no Vue data. Instead, we can just use lets everywhere to get assignable state values, cuing re-renders whenever these values change.

This freedom from this jargon means making a component can almost feel like whipping up a CodePen, but without wondering how to connect that declarative JS function you learned to some DOM query selector. Don't worry too much though: Svelte won't mess with callback functions or window listeners, so those fundamentals remain.

The other nice thing about these components is that they're just as import-able as a traditional component. Just import the .html and Svelte knows how to unwrap it 😊

<div>
    <Wizardry />
</div>
<script>
    import Wizardry from './wizardry.html'
</script>

Neat, but hang on a minute...

Some readers may find this concept as mind-blowing as I do, but others probably have their pitchforks ready at the thought of throwing this at beginners. Won't this confuse them about how DOM manipulation really works?

The answer is... maybe. But when someone's just starting out (at least from personal experience), it's okay to accept a little abstraction for the sake of making cool things more quickly.

Also, just as languages like Java and JS have abstracted away pointer management with garbage collection, it feels like most every modern web development tool has abstracted away DOM manipulation, save for more advanced edge cases beginners likely won't need to face. Btw, if you are scratching your head at what pointer management is, I think that kind of proves my point 😛 Thus, rather than forcing beginners to manipulate the DOM or grasping framework-specific state wrappers, why not just let them access variables directly from markup? Now they can learn the basic principles of component state without getting caught in the weeds.

Okay, but how much "special syntax" is there?

There's some templating to pick up here admittedly, but it's a lot less than you might think! One Svelte-y syntax is for looping and conditionals for displaying DOM elements. This works a lot like the JSX way of returning elements from a map, but without all the nested brackets beginners (and myself) can easily get lost in. Here's a basic one that generates a list of a elements from an array:

<ul>
    {#each profiles as profile}
    <li>{profile.name}: {profile.role}</li>
    {/each}
</ul>

<script>
    const profiles = [
        {name: 'Wes Bos', role: 'React extraordinaire'},
        {name: 'Chris Coyier', role: 'Father of CodePen'},
        {name: 'Cassidy Williams', role: 'Letting you know it's pi time'}
    ]
</script>

Again, I understand any criticisms about the syntax, but what I love is how easily understood it is. Instead of nesting JavaScript in our HTML, we just say hey, lemme loop over this array and create an element for each one.

There's another Svelte oddity worth mentioning that I'm admittedly not as thrilled about: passing props to components. Yes, it is fully functional and easy to learn, but the syntax is a bit too magical for some people's tastes. To handle props, we simply pass the prop to the component wherever it's imported...

<!-- somewhere.html -->
<Profile coolGuy="Scott Tolinski" />

...and get that variable as an exported "let"

<!-- profile.html -->
<p>{coolGuy}</p>
<script>
    export let coolGuy = '';
</script>

I totally understand if some are turned off by abusing "export" like this, but it does at least follow the way beginners should conceptualize modules: we export what we should access outside of the component, and import what we want to show in our component.

What about the build process though?

Another criticism about getting beginners started with frameworks is the need to use a package manager. Which means... gasp using the terminal!

Look, I get it, popping that thing open can be intimidating, with its monospace font and that spooky "cd" to jump directories. But to be fair, it's really not a huge hurdle when you only need a single command to get running. Additionally, the integrated terminal within VS Code makes it dead simple to get started with; it even plops you down in your current project directory!

Svelte actually offers a downloadable starting point that's nice outside of the box, but I made my own starter template that just uses the build tool Rollup for live reloading. In fact, the config file is under 30 lines long! For a basic Svelte project, these is all the directories and files you need:

/public
    index.html
/src
   index.html
app.js
rollup.config.js
package.json

Just add a command to run the build step in the package.json and you're all set! You could certainly say that all the extra modules and files other frameworks need aren't a problem if beginners don't touch them, but in my eyes, the less extra stuff for newbies to wonder about, the better.

But is it a stable framework?

This is a very relevant question for a framework as young as Svelte. All examples I have shown use the syntax of Svelte version 3, which ~~is still in beta as of the time of this writing~~ has a relatively small following compared to framework behemoths like ReactJS and VueJS. So as exciting as it is, I would wait another few months before rushing to teach code workshops with it. Still, Svelte offers a really concise page for documentation for version 3 that can ease beginners into the framework without getting overwhelmed by subpage after subpage of explanation.

So let's go over some of the main selling points for learning web development with Svelte:

It's a component-based framework with 0 extra plugins
It handles state management without all the usual cruft
It uses scoped styling without needing CSS-in-JS (so no editor extensions or wacky syntax)
It only needs a dead simple build script to get going
Hardly any files are needed in a base project

Of course, it's totally fine if I haven't convinced you with this post; all good posts stoke a little controversy! But I hope it at least showed you how freaking cool and simple Svelte can be to learn.

Why I'm using Surge and not GitHub Pages

Wed, 06 Mar 2019 22:40:16 GMT

Update: I've noticed that Surge hasn't seen many updates to its repo recently. It seems safe to use for now (I haven't seen any vulnerability warnings), but if the project ends dying off, Netlify and Zeit Now are great alternatives that offer similar benefits over GitHub Pages

Hm, so what's a "surge" exactly? 🤔

GitHub Pages is so prolific at this point it likely needs no introduction. Surge, on the other hand, is a much lower profile project. It accomplishes the same goal as GitHub Pages, allowing one to publish their static site on an accessible URL of whatever name they choose complete with an "https." Where surge differs is in how that website gets put on the world wide web.

Surge lets you get from 0 to published in the command line without any extra setup. Once you install the package, you can use their CLI in your project directory to whip up an account...

👉 surge

    Welcome to surge!
    Please login or create an account by entering email and password:

    email: jamesKPolk@napoleonofthestump.gov
    password:

enter your domain to deploy to...

    domain: forgottenpresidents.club

and boom 💥! You're up and running. Note I'm using a custom URL extension here as well. You can of course specify this if you have the rights to that domain, but you can omit the extension to use the totally free surge.sh.

Looks easy, but where are my git hooks?

The beauty of GitHub Pages is it will simply track your master branch and rebuild / publish your site whenever it gets updated. Thankfully, surge offers the option to hook into pushes and commits with a little addition to your package.json. This snippet will do the trick for redeploying on push:

"devDependencies": { "surge": "latest", "git-scripts": "0.2.1" },
    "git": { 
        "scripts": { "pre-push": "surge --project ./ 
        --domain forgottenpresidents.surge.sh" }
       }

Neat. But what are the benefits exactly?

Surge offers a few niceties that GitHub Pages won't out of the box. For one, you obviously don't need to use GitHub to manage your version control, so you can use any custom solution you desire and still deploy with the same surge command.

Another is an advantage that Zeit Now also fails to address: client side routing fallbacks.

Extending our James K. Polk example, say we deployed a simple project folder with a few html files:

    ./build
      - index.html
      - what_i_stand_for.html
      - donate_now.html
      - 200.html

Notice our 200.html added at the bottom. This acts as a fallback to serve up whenever a given route is invalid. Assuming these are all the html files in our build, we know someone visiting, say, forgottenpresidents.club/sendfanmail would get a 404 since that file doesn't exist. However, since we have a 200.html, Surge knows to just serve up this page instead since it's a fallback. This is more flexible than the traditional 404.html to catch errors since we sometimes don't want certain paths to result in a 404, like a dynamic username in the URL that gets handled in JavaScript but should always route to the same base page. This makes routing a bit cleaner whether you're using a library like React router or just tapping into the browser's history API on your own, since we don't have to deal with redirects anymore 🎉

The last major benefit is one shared by Zeit Now: deploying whenever you want in a matter of seconds. Rather than dirtying up your commit history, you can just deploy your changes instantly and see how they look. This was super useful recently when testing out a mobile layout for a site I was developing, where mobile Safari was being a bit more finicky than my mobile viewer in Chrome. I could just deploy my changes to whatever URL I chose and see my edits as soon as I refreshed the page!

Okay I'm starting to see it. What are the limitations?

So Surge was built to be really good at doing a very specific task. If you have anything more than a static site or client side application, there's sadly not much you can do with this tool. Any fancy backend you have would need to be deployed separately, or you can use the aforementioned Zeit Now to deploy everything in one place. Now is a much more flexible tool that's quickly gaining traction, but I've stayed loyal to Surge because of the routing niceties and lack of any necessary config files.

Of course you should use whatever tool that works best in your workflow. But the next time you're building v175 of your portfolio site, consider giving Surge a try 😊

The BHolmesDev Blog

Build a Self-Updating LLM Knowledge Base

Step 1: one directory of raw markdown

Step 2: the /enrich-note skill

Step 3: the wiki skill

Step 4: automations

Local Automations with Codex

Cloud Automations

Step 5: visualizations

Go write things down!

Hubble Note

What is it?

Why Hubble?

Why me?

When can I try it?

Response to DHH on the gift of open source

Open source is a gift exchange

What gift giving means

The consequence of selfish gift giving

My time at Astro

Conclusions

The python environment setup cheatsheet

Setup

Editor tooling

Building serverless applications with Fauna + GraphQL

Key terms

Why serverless?

Why GraphQL?

How GraphQL turns menus into buffets

Why serverless + GraphQL?

When is serverless + GraphQL a bad choice?

Flaws with serverless

Flaws with GraphQL

Let’s build a simple app with GraphQL, Netlify serverless, Astro, and FaunaDB

Clone the starter code on your machine

Overview of the project

Spin up your function locally with the Netlify CLI

Write a simple GraphQL resolver using Apollo lambda

Query this serverless endpoint from your Astro frontend

Generate routes for each galaxy

Persist these galaxies in a database with Fauna

Load mockGalaxies into your database

Query this data from your GraphQL resolver

Can you use Fauna’a GraphQL resolvers instead?

Deploy this serverless function for production use

Deploy your frontend for production use

Conclusion

Understanding single page apps & client-side routing

🤔 First off, how do non- SPAs work?

Wait, is that wasteful?

1. HTML is super cheap to load and render

2. Shared resources don't need to get re-loaded

3. The next page only appears when it's ready

💁 Now, let's talk single page apps

Key benefits to this approach

🍔 A juicy visual comparison

Wrapping up: so which should I choose?

Grabbing subsets of JS object properties with... GraphQL?

What we want

📈 Enter: GraphQL

📖 Applying GraphQL to reading JSON objects

Traversing our query

Handling nested objects

Cleaning this up a little

Handling arrays

🚀 The finished product

Usage example

Sexy, accessible show-hide animations in any web framework

Starting with a naive solution

⌨️ Let's accommodate keyboard users

👁 Let's accommodate screen readers

Communicating toggle states with aria-expanded

Focusing our dropdown on expanded

⚙️ Applying this to your favorite framework

A simple React solution

Svelte example

Want CSS variables in media query declarations? Try this!

Why var() can't work in a @media declaration

For SASS and SCSS users: use SASS variables for media queries

For everyone else: use the incoming CSS environment variables spec

Load `mockGalaxies` into your database

Communicating toggle states with `aria-expanded`

🌅 Fixing format + size problems with the `picture` element

The `sizes` attribute

`gimme` ✊

`yoink` 🎣

Clarification on using `stash` vs `stash push`

`woosh` 💨

`boop` 👇

Going from `forEach` to `reduce`

So wait, why do I even need `reduce`?