seanmcp.com

Defaults 2026

Sean McPherson — Wed, 28 Jan 2026 13:48:00 GMT

Mail Client
- Gmail app and Zoho app
Mail Server
- Gmail for personal email
- Zoho for professional email: I've tried other providers for @seanmcp.com but keep coming back to Zoho. It's cheap, customizable, and provides all the features that I want.
Notes
- A private repo with shell scripts. Mobile notes are written in Google Keep and manually backed up.
To-Do
- Todoist: I don't use most of the features, but I love the keyboard shortcut on Mac to quickly add a TODO.
Phone Photo Shooting:
- Default Android app
Photo Management
- Google Photos (though I'm sad they removed the free tier for photo storage)
Calendar
- Google Calendar: My wife and I have personal calendars and then a shared family calendar.
Cloud File Storage
- Google Drive and Git
RSS
- Feedbin: I could probably get by on the free tier of another service, but Feedbin is so nice and simple. I don't have to think about it when reading, and I'm not being upsold at every opportunity.
Contacts
- Google Contacts: It recently added a new feature to add birthdays to the calendar and give you a notification ahead of time. I almost built an app that would do the same, and I'm glad it's now a feature.
Browser
- Microsoft Edge: Chromium-based with vertical tabs and the ability to remove most features.
Chat
- Text or WhatsApp
Bookmarks
- A private repo with shell scripts. I migrated from Raindrop last Fall, and it has been smooth enough.
Read It Later:
- I leave things unread in Feedbin
Word Processing
- Google Docs and VS Code
Spreadsheets
- Google Sheets
Presentations
- Google Slides: I've tried code-based solutions, but it generally leads to more tinkering and less preparation. I use all the default layouts and then tweak the design once I'm finished.
Shopping Lists
- Google Keep: A note for groceries and another for shopping that are shared with my wife
Meal Planning
- Google Keep (though this is mostly handled by my wife)
Budgeting and Personal Finance
- A Google Sheet that is updated 1-2 times per year.
News
- National: AllSides, the Atlantic
- Local: Pittsburgh Post-Gazette, PublicSource, and Spotlight PA
Music
- YouTube Music: It's included with a YouTube Premium subscription and has access to the all the music I want.
Podcasts
- Pocket Casts: I like that it is focused on being a podcast player. I've tried other all-in-one options and keep going back to Pocket Casts. I've listened to 94 days and 22 hours since 2016.
Password Management
- Bitwarden
Code
- VS Code: I've tried Zed and Cursor as potential replacements, but neither of them provide the right features with the right form.
Terminal
- Terminal (Ubuntu): Not bad enough to look for alternatives
- iTerm2 (Mac): I like that it isn't trying to be anything other than a terminal. I used Warp for a while but it became clear that their product roadmap was not in the terminal space.
Search
- DuckDuckGo: I'm skeptical of AI summaries, and DDG is the only provider I've found that allows you to disable them. That said: the results aren't great. If you have an alternative, please let me know.

AI use case: Asking questions of large files

Sean McPherson — Wed, 07 Jan 2026 12:50:00 GMT

Khan Academy uses GraphQL to handle all request to query and mutate data. Each service in the system contributes to the GraphQL schema, and everything is ultimately combined into a single file. If a developer wants to know what our API can do, the answer is in that file.

The problem is that it's over 80,000 lines long.

Most of the time you can get by searching the file for keywords. If you're interested in the user or classrooms or a specific feature, you can find breadcrumbs that lead you to the answer. But sometimes you're dealing with unfamiliar terms or features old enough to have been renamed over the past decade. File search alone won't always get the job done.

Yesterday I was in this situation and turned to Copilot in VS Code. I switched it to "Ask" mode and entered my query: "How can I determine if a user is in a given district?" The model interpreted by question, read the file in chunks, and then returned an answer.

Of the options provided, only one included the exact terms that I had in my query. After inspecting the response, I found that the best option used an old term that we don't use anymore and I've never heard. I would not have found that by searching the file by myself. Uncovering the answer was only possible with an LLM.

I'm generally skeptical of using AI to write production code that matters. But as a search tool, I'm increasingly convinced that they are a powerful addition to a developer's toolbox. When file search can't surface the answer, the ability to ask questions of large files with an LLM is a valuable resource.

Install curl with apt (and not snap)

Sean McPherson — Mon, 25 Aug 2025 11:50:00 GMT

After switching my desktop to Linux from Windows^[1], I ran into an issue installing Node. The official directions recommend using nvm, but the nvm install 24 command was failing with a lack of permissions:

Downloading and installing node v24.6.0...
Downloading https://nodejs.org/dist/v24.6.0/node-v24.6.0-linux-x64.tar.xz...
Warning: Failed to open the file /home/seanmcp/.nvm/.cache/bin/node-v24.6.0-linux-x64/node-v24.6.0-linux-x64.tar.xz: Permission denied
curl: (23) client returned ERROR on write of 1360 bytes

download from https://nodejs.org/dist/v24.6.0/node-v24.6.0-linux-x64.tar.xz failed
grep: /home/seanmcp/.nvm/.cache/bin/node-v24.6.0-linux-x64/node-v24.6.0-linux-x64.tar.xz: No such file or directory
Provided file to checksum does not exist.
Binary download failed, trying source.
Downloading https://nodejs.org/dist/v24.6.0/node-v24.6.0.tar.xz...

Warning: Failed to open the file /home/seanmcp/.nvm/.cache/src/node-v24.6.0/node-v24.6.0.tar.xz: Permission denied
curl: (23) client returned ERROR on write of 1360 bytes

download from https://nodejs.org/dist/v24.6.0/node-v24.6.0.tar.xz failed
grep: /home/seanmcp/.nvm/.cache/src/node-v24.6.0/node-v24.6.0.tar.xz: No such file or directory
Provided file to checksum does not exist.

The permissions in the .nvm/.cache/ directory looked fine, sudo didn't work, and Claude Sonnet 4 wasn't helpful. I went searching online and found a question and answer from three years ago that recommended:

Uninstalling curl with snap: sudo snap remove curl
Reinstalling curl with apt: sudo apt install curl
Running the nvm/Node install commands again

Doing that fixed the issue for me.

I would have never considered curl as possible source of my issues. So I'm thankful that questions/answers like that exist on the internet.

I think I need to learn about the differences between apt and snap, and why you would choose one versus the other. If you have a good resources for that, please let me know.

My build was incompatible and Windows 11, and I didn't want to upgrade to use an operating system that I am ambivalent about. ↩︎

Four perspectives on AI

Sean McPherson — Wed, 20 Aug 2025 10:24:00 GMT

Maxi Ferreira writes in Fear and Curiosity and AI about the two stages of AI adoption among developers:

A Stage 1 reaction looks something like this: “Ha! Look at this dumb mistake the AI made. It thought I was using Tailwind when I’m actually using Style Components. More like Artificial Unintelligence, am I right? Good luck taking my job, bots.”

A Stage 2 reaction looks more like this: “Hmm, I wonder why the AI got confused there. Maybe some of my classes in this component look like Tailwind classes. How can I prevent this from happening in the future? Let me add a Cursor Rule to tell it I’m actually using Styled Components in this project.”

The naming suggestions a progression. Developers start at the defensive/fearful Stage 1 but are able to progress to Stage 2 with a "curiosity mindset".

I agree with Ferreira about the two reactions. I feel like I've heard them both near verbatim while talking about AI with colleagues. And I agree that curiosity and a growth mindset are invaluable in our field and life broadly. But the framing of "Stage 1/Stage 2" and the motivation behind them is uncharitable (at best) and unhelpful (at worst).^[1]

The difference between the two reactions depends not on time and mindset but on an individual's belief of AI's transformative potential and positive impact.

The Skeptical see AI's capabilities and limitations. They question the imminent advent of AGI and whether future frontier models will have a significant impact on the world in the long-term. They don't see the technological developments of AI as a net positive. They'll use phrases like "over-hyped" and "flash in the pan". They are unlikely to experiment with AI tools. When they see the output of any-given model, they tend to have Reaction 1 because criticism illustrates their beliefs.

The Wary also see AI's capabilities and limitations but believe that developments in the field will result in dramatic changes to our work and lives. They are concerned that the advancement of this technology will come at severe cost to other aspects of our world. They'll have a "p(doom)" number, raise concerns about safety, and cite environmental or societal detriments of AI. They may have Reaction 1 but are more likely to avoid AI entirely and encourage others to do the same.

The Pragmatic aren't swayed by arguments for or projections of AGI. They see AI as a tool to help them with tasks today. They'll experiment with prompts and models but will quickly move on when it isn't working. They'll mention "usefulness", "utility", and "productivity". They spend little time thinking about AI beyond a specific problem and solution. They may have Reaction 2, though there will be a reasonable time box for how long they explore.

The Optimistic see the potential in AI's capabilities and trust that the limitations will eventually be overcome. They believe that future models will radically transform our world for the better citing problems to be solved in medicine and the environment. They'll encourage others to learn how to use AI so that they "don't get left behind". They tend to have Reaction 2 and will push the boundaries of what is capable with the current state of AI.

I've grouped these four perspectives, but everything here is a spectrum. Depending on the context or day, you might find yourself at any point on the graph. And I've attempted to describe each perspectively generously, because I don't believe that any are inherently good or bad. I find myself switching between perspectives throughout the day as I implement features, use tools, and read articles. A good team is probably made of members from all perspectives.

Which perspective resonates with you today? Do you also find yourself moving around the graph? I would love to hear your thoughts, as I'm sure mine will continue to develop over time.

Despite my disagreement with Ferreira, I still recommend his newsletter. It has helpful insights and interesting links that I'm happy to see in my inbox. ↩︎

Axe DevTools doesn't flag multiple h1 elements on a page

Sean McPherson — Wed, 16 Jul 2025 18:40:00 GMT

The axe DevTools extension is valuable for testing the quality of your work. I use it multiple times per day when working on frontend tasks. So I was surprised today when I learned that axe does not consider multiple h1 elements on a page an issue.

It turns out that this is intentional. There is no rule stating that pages cannot have more than one h1–even if it is widely considered best practice^[1]. The A11y Project has a nice write up on the topic.

Even though axe doesn't consider it an issue, I still want to avoid rendering more than one h1 on a page. I previously wrote a little script to print all of a webpage's headings to the console, and I wanted to make that as easy to use as axe. Thankfully we can do that with Chromium's snippets API^[2].

Open the browser devtools
Select the "Sources" panel
In the left-hand panel, select the "Snippets" tab (it might be hidden in the caret menu)
Select "New snippet"
Name it something like "Print headings"

Paste the code from my gist:

document
  .querySelectorAll("h1,h2,h3,h4,h5,h6,[role=heading][aria-level]")
  .forEach((node) => {
    let level = node.getAttribute("aria-level") || node.tagName[1];
    let prefix = " ".repeat(parseInt(level) - 1);
    console.log(`${prefix}${level}: ${node.textContent}`);
  });

Save the snippet

You can run snippets from the Sources panel, but the faster way is to use the keyboard shortcut:

In the browser devtools, press ctrl/cmd+o to open the command menu
Type "!" to bring up the list of snippets
Select your snippet from the list
Press enter/return to run it

The snippet will execute and print all of the headings on the page to the console.

You could do more in your version of the snippet like validating the existence of a single h1 or the heading order. For me, having it print the headings is good enough to spot check my work.

Axe's has a "Best Practices" option, but that doesn't flag it either. ↩︎
I couldn't find an equivalent for Firefox (and didn't check Safari). If I've missed it, let me know and I'll update this article to include information for other browsers. ↩︎

Writing code was never the bottleneck in software engineering

Sean McPherson — Wed, 09 Jul 2025 11:05:00 GMT

Writing Code Was Never the Bottleneck by Pedro Tavares makes an important observation about using LLMs when writing software. The problem as stated by the solution is that writing code is primarily the bottleneck in development. "If only we could write code faster, then we'd be able to ship more features."

Tavares challenges that presupposition:

The actual bottlenecks were, and still are, code reviews, knowledge transfer through mentoring and pairing, testing, debugging, and the human overhead of coordination and communication. All of this wrapped inside the labyrinth of tickets, planning meetings, and agile rituals.

These processes, meant to drive quality, often slow us down more than the act of writing code itself because they require thought, shared understanding, and sound judgment.

...

The marginal cost of adding new software is approaching zero, especially with LLMs. But what is the price of understanding, testing, and trusting that code? Higher than ever.

When engineering software for an organization, writing code is rarely the hard part. It's everything that precedes and follows writing code that slows you down: gathering requirements, exploring existing patterns, reviewing pull requests, testing solutions, sharing knowledge. LLMs can supercharge the generation of code, but they make the rest of the process slower.

Judicious use can result in modest productivity improvements. But stray too far and suddenly you're spending more time to assure quality or waving it away with "vibes".

Tavares' observation also explains why using LLMs in greenfield or prototype environments feels so different. In those situations, writing code is the bottleneck and generating code with an LLM blows it wide open. The tech debt created by using LLM code takes time to be noticed and may never come up (e.g. sacrificial prototypes).

But in a software-development environment, the equation changes. Requirements, understanding, reviews, and testing take priority. In that world, generating huge swaths of code with LLMs only exacerbates the true bottlenecks of software engineering. The craft becomes learning how to use them well without creating more problems for your team down the road.

Hat tip to Rendezvous with Cassidoo for sharing the article.

Colocate functionally-related code

Sean McPherson — Mon, 30 Jun 2025 18:30:00 GMT

I read Colocation by Kent C. Dodds back in 2019 before I had an opinion on the topic. Six years later, I've come to a similar conclusion. Generally speaking, we should keep related code as close together as possible.

Common related code in my work are components, styles, tests, and stories. My preference is to keep all of these files together in the same directory:

components/
    ├── my-component.tsx
    ├── my-component.css
    ├── my-component.test.tsx
    └── my-component.stories.tsx

A change to one will often require a change to one or more others. By keeping the code together in your file system, you both remind yourself of that fact and make it easier to find the other files that need to change.

The major alternative pattern I see are dedicated directories for each "concern": __tests__, __stories__, etc. By one definition of related, this is a method of colocating related code. Everything in those directories is related to the same domain and has some things in common.

But rarely do I need to update "all test files." And when I do the filename pattern is sufficient to find them. In contrast, every day I need to update functionally-related code. So I want my organization system to prioritize the work that occurs most frequently.

Colocate all of your functionally-related code.

Maccy is a great clipboard manager for Mac

Sean McPherson — Fri, 27 Jun 2025 13:02:00 GMT

I don't where I saw a recommendation for Maccy, but I owe them a big thank you. It's a simple clipboard manager for Mac that takes the headache out of copying and pasting.

Once it's installed, use copy and paste like normal. But when you want to dig into your clipboard history, you can open Maccy with the keyboard shortcut. Mine is:

cmd + shift + c

A pop up shows you a searchable list of items that you've copied in reverse-chronological order. Selecting an item adds it back to your clipboard.

Maccy also remembers images, which is useful when taking screenshots of your work. Snap a few pictures and then retrieve them from Maccy when filling out your pull request or Slack message. It's handy when managing multiple git branches too. I can quickly retrieve a branch from memory when pulling, merging, or rebasing.

It looks like macOS 26 will add clipboard history to Spotlight^[1], but we'll see if the implementation works as well as Maccy.

Hopefully it doesn't become another case of sherlocking from Cuppertino. ↩︎

My on-again-off-again relationship with AI assistants

Sean McPherson — Mon, 31 Mar 2025 10:18:00 GMT

For the past few years, I have been paying on and off for ChatGPT and Claude. I will read an interesting story about how someone transformed their work with AI, then sign up for a premium plan for one month. I spend a few days actively engaging with the AI and then quickly fall off. I go weeks without chatting with the assistant and then cancel before the month is up.

There is a lot of smoke in the work-productivity AI space. I believe there is (probably) fire there somewhere. But I haven't been able to find it.

Beyond one-off questions that require more nuance than a search on StackOverflow or quick chats about naming things^[1], I struggle to find many use cases for an AI assistant. I don't know if that is a result of how I think and work or a limitation of the product. But it's not working for me.

GitHub Copilot is a little different. It continues to churn in the background while I code, and I frequently utilize its autocompletions. Sometimes the refactors are usable, but others they are way off. I have been experimenting with the more "agentic" features, but I'm finding that reviewing the generated code takes a comparable amount of time to writing it myself. And writing code is more fun than reviewing.

I find AI assistants useful, just less so than other folks online. I'm glad to have them as an option^[2] but am still on the lookout for a reason to pay $20/month for a premium plan. If that all resonants and you have some suggestions, please reach out. I can be convinced!

A famously hard problem ↩︎
I am especially thankful for the free access to GitHub Copilot that I am granted every month. I don't know what I did to qualify for this program and at this point am afraid to ask! ↩︎

Introducing Speed Catan

Sean McPherson — Sat, 18 Jan 2025 18:30:00 GMT

For the record: I like Settlers of Catan. But as I age, I have less interest in games that can be unbalanced or take a long time. A decade ago my friends and I came up with Sanders of Catan to improve balance and increase speed, and it is still my favorite way to play Catan.

But then I had kids and needed to increase speed while also decreasing the amount of time spent setting up and cleaning up the game.^[1] So we came up with Speed Catan, a faster and simpler way to play Catan.

The main change is that instead of setting out the circular number tokens (or chits) and using them to determine what resources to draw, you set the resource and development cards in an ordered list on the table. Whenever you roll the dice, you draw the resource based on it's index in the list.

It also introduces a time-based win scenario where the player with the most victory points after x minutes wins (I recommend 15 minutes). And finally it removes the robber because who wants to play with crying kids? You can read more and see examples here.

With these changes we are able to complete a full game with young children and no conflict!

If you have an old version of Catan on the shelf, I recommend dusting it off and playing some Speed Catan with the kids or adults in your life. Then let me know what you think.

It is common in our house to spend a long time setting up a game only to have the kid lose interest half-way through. ↩︎

Zed still isn't ready

Sean McPherson — Thu, 16 Jan 2025 24:30:00 GMT

VS Code started acting up after a recent update, so I took the opportunity to try Zed again. It has improved since my last attempt and was a perfectly workable editor for small stuff.

The cracks started to show when I used it with a large codebase. The search was incredibly slow—much slower than VS Code. And since it doesn't preserve filter settings between queries, every subsequent search was slow too.

I liked some of the code actions like autofix imports, but I never felt confident that Zed would select the right file. At work we have some duplicate file names and exports, so it is important to be able to choose which View component to import.

The biggest issue I encountered was around memory and possible leaks. Zed (for some reason) supports looking up all references for primatives like false, which would crash my M2 Mac by scouring the whole codebase for every instance of false. Today it crashed when I searched for a term with too many matches.

I couldn't get AI completions working correctly (despite installing and registering with GitHub Copilot) nor the unit test runner.

Zed is promising, and I think they nail a lot of the intangibles that make a product desirable. But it still isn't ready for full-time development work.

Rewriting in Eleventy (again)

Sean McPherson — Tue, 14 Jan 2025 10:50:00 GMT

After growing disillusioned with Astro in 2024, I rewrote this site in Eleventy. Again.

I want a library with features that are laser-focused on my project's needs. Astro is an awesome framework for building complex content sites, but I no longer believe that it is the right tool for a static site like this.

Eleventy is focused on crawling through a directory and converting markdown files into a HTML. And it has stayed the course over many years of regular updates from its maintainer.

That gives me the freedom to reorganize my site based on what works for me (and not what the collections API wants). As a result, some pages have moved and others disappeared. That used to bother me, but I can't be on the hook for preserving all content forever. The grass withers and the flowers fade.

Last time I built this site with Eleventy, I got bogged down with tons of filters, shortcodes, and partials that made working on pages difficult. This time around, I wanted to take care to avoid unnecessary complexity.

For templating, I tried WebC but it felt too niche. I wanted to choose boring technology for this site, and the uncommon errors with limited online resources were not going to be helpful. I opted for Liquid because it has support for all of Eleventy's internal features and the best documentation/support resources.

This time I have five filters: two for debugging, one for formatting dates, and two for handling RSS-ONLY and DRAFT articles. I have two partials: one for a list of articles, and one for a list item. These are used in the articles, home, and search pages to make sure that everything renders consistently. I have no shortcodes.

A few articles had interactive components that were written in Svelte or used Astro components. I rewrote those with web components, which I should have done in the first place. It feels right to mix custom elements in markdown with script tags to load the JavaScript.

The biggest tradeoff is the developer experience. Astro invests heavily in that area. and it shows. Eleventy errors can be confusing and the documentation hard to parse. And I miss the inline documentation in my editor that comes from a fully-typed library^[1]. I think those tradeoffs are worth the simplicity of Eleventy.

Going forward, I want to think less about maintaining this site. It exists as a collection of resources for myself and others. And when I have something new that I want to write or add, I have a place for that.

Here's to a few happy years before another rewrite.

JSDoc comment syntax can help a lot, but I struggle to get it working correctly ↩︎

Sorry if I broke your feed

Sean McPherson — Tue, 14 Jan 2025 10:40:00 GMT

I'm in the process of completing a rewrite of this site in Eleventy, and have moved a bunch of content around. Last year I made the foolish decision to make everything an article and therefore part of the RSS feed. That was a mistake and so a lot of articles have been removed.

Feedbin at least is able to reconcile the changes without too many issues, but I apologize in advance if your RSS-reader-of-choice does not handle the changes well.

Mc-Pher-son

Sean McPherson — Tue, 26 Nov 2024 13:43:00 GMT

This morning my son asked me "If our last name is McPherson, why do people always call us McPhearson?"

"I don't know," I replied. Besides the "Mc" there are no tricks; the pronunciation follows the standard English reading rules.

I know that text on a page is not the best medium for a pronunciation guide (at least until we all learn IPA), so here's a read aloud:

Related: How to pronounce my name

Balance bikes are just better

Sean McPherson — Sat, 23 Nov 2024 18:28:00 GMT

I learned to ride a bike with training wheels. So when it was time for our oldest son to learn, we tried training wheels. A year passed with no noticeable progress. Maybe he just wasn't a bike rider?

Our friends suggested a balance bike instead. After two weeks of practice, he was riding a normal bike independently. It was like magic.

Not wanting to be left behind, our four-year-old wanted to learn how to ride too. So we got a balance bike, he practiced for two weeks, and then he learned to ride a bike too.

Training wheels help you practice pedaling and steering, which most kids have mastered on a tricycle or big-wheel. Training wheels don't help with the most important skill for riding a bike: balancing. By focusing on that, balance bikes help kids learn to ride faster than with training wheels.

The are a bunch of brands that sell balance bikes, and since kids only need them for a short time there is a healthy second-hand market for them. We got ours for free from a Buy Nothing group.

But if that isn't available, you can convert a normal bike into a balance bike by removing the pedals and lowering the seat. Once the kids has learned how to balance as they roll, add the pedals, raise the seat, and watch them go.

For learning how to ride, balance bikes are just better.

Deleting my GPTs

Sean McPherson — Tue, 12 Nov 2024 24:38:00 GMT

Today I deleted all of my public and private GPTs. I thought I would feel sad: they were the feature that convinced me to start paying for OpenAI last year. But instead it feels like an anticlimactic end to an experiment.

When custom GPTs were initially launched, I was interested in an official playground for prompt engineering with the potential of a marketplace. I spun up a few and even wrote some articles about it. But the feature fizzled and the market hasn't panned out.

Beyond a questionably-accurate conversation count, OpenAI doesn't provide even basic usage data. Critical measures like recent sessions, average conversation length, and bounce rate are all missing. Maybe you could overlook that if your GPTs made a few bucks a month, but there is no market and no clear road to one.

That was enough to convince me, but paying for the privilege of keeping these GPTs online wore me down too. I don't like being tied down with subscription services, and GPTs were the only thing keeping me in the OpenAI ecosystem. So I deleted them.

Without the GPTs, I'm free to switch to Claude (which all my cool prompt-engineer friends say is better) or nothing at all. $20 a month goes pretty far at a food bank or international charity.

If you were a faithful user of my GPTs, then I apologize for the change. But dozens of users are not enough to justify the expense or the lock-in. Send me an email, and I will share everything you need to make your own.

Smile and wave

Sean McPherson — Fri, 18 Oct 2024 17:54:00 GMT

I live on a neighborhood street that runs parallel to a larger road connecting multiple communities. As a result, our street gets extra traffic from folks who try to cut a corner and shorten their commute. Some of these drivers slow down on their way through the neighborhood, but others do not.

I have two young children who like to play outside in the yard and ride their bikes on the street. We have worked with them to recognize when a car is approaching and what to do. But they're kids. Sometimes they don't hear a car coming and sometimes they forget what to do. So speeding cars make me nervous.

Most people try to discourage speeding cars through shame. They frown and shake their head or gesture with their arms. Maybe they mouth the words "Slow down!" I don't know if this is effective; shame seems to be a pretty poor motivator in my society. But I understand the instinct. A speeding car is dangerous and negatively impacts me, my family, and my neighbors. It is legitimate to want to communicate that.

However, there is a different danger to the shame approach: it destroys the relationship^[1] between you and the driver. It turns you into a judge looking down on and condemning the defendant. And because you have seized this seat of authority, and the driver might reasonably rebel against it. They'll get mad. Maybe they'll drive faster. You will both leave the interaction filling angry and self-righteous.

I don't like what shaming does to me or the driver. Is there a way to discourage speeding that doesn't destroy relationships?

I think there is, and it's simple: instead of shaming just smile and wave. I do this to every driver I see on my street. Drivers in cars, trucks, vans, work vehicles, delivery trucks, and everything in between get a smile and a wave—whether they are speeding or not. I think this is better for three reasons.

First, it's good for me. Frequently in life we are provided with opportunities to elevate ourselves above others. To judge. To condemn. By choosing to to smile and wave, I am consciously defying that urge and replacing it with kindness. It helps put me in the right head space for this and future reactions.

Second, it's good for the driver. No one wants to have their actions judged, especially by a random person on the street. Smiling and waving humanizes pedestrians without introducing a power dynamic. Your smile will linger on their mind for a long time, shading future thoughts and actions.

Third, it works. The drivers of speeding cars slow down when they see people smile and wave. This is especially true when our kids do it. The natural reaction for the driver is to slow down, and then return the smile and wave. The next time they drive down your street they will remember "there are friendly people who live here."

Smiling and waving is a radically egalitarian response to the problem of speeding, but I think it's the right solution. It helps you, helps your neighbor, and results in a safer and healthier environment for everyone.

So next time you see a speeding driver, try smiling and waving. I think you'll be surprised. And look for other opportunities to extend kindness and grace to those who may be misbehaving. It just might be the right solution then too.

I'm using relationship in the general sense of a connection between two people. I do not know most of the speeding drivers personally. ↩︎

Pittsburgh TechFest 2024

Sean McPherson — Sat, 28 Sep 2024 10:31:00 GMT

Yesterday I went to Pittsburgh TechFest 2024 at the Commonwealth Charter Academy building on the Waterfront. The venue was nice, the food was good, and both keynotes were interesting—though I definitely did not know enough about SNL to fully appreciate the closing.

My favorite talk was by Dominika Blach of the Greater Pittsburgh Community Food Bank about how they're using low-code solutions for an organization that needs technology solutions but can't afford developers. I knew nothing about low code but can imagine a lot of organizations with similar constraints who need professionals who can navigate that world for them.

I gave a talk title Thinking Outside the Bots: A human-centric approach to model interactions and discussed some of my thoughts about how we build features using AI^[1]. I got to share some of the cool things that I've been working on at Khan Academy and felt validated by the responses. The talk was well received, sparking interesting conversations afterwards and a couple invitations to give the talk again to other groups.

For the first time, I enjoyed the networking side of the event more than the talks. I had the chance to reconnect with some former colleagues at Niche, met some of the folks from Carnegie Learning, talked with friends, and saw a lot of familiar faces from last year. I handed out some business cards (vintage 2017) and made some good connections.

It's hard to feel connected to the local tech scene when you work remotely for a company based 2,200 miles away. So I think it's important for workers like me to invest time in events like this. Looking forward to next year!

tl;dr I think that chatbots are a bad UI for most use cases and that we should focus our design efforts on user needs and defined outcomes ↩︎

Seventy7 Ventures feigns credibility with fake "Best of British Business" award

Sean McPherson — Sat, 03 Aug 2024 18:08:00 GMT

Seventy7 Ventures, the new majority shareholder of Inverness Caledonian Thistle FC, state on their website that they have "been awarded Best of British Business by The Independent."

This claim has been repeated by other outlets and Scottish soccer fans.

A biography of Seventy7 Ventures Director Ketan Makwana includes a similar and more specific claim: “Seventy7 Ventures was awarded the Best of British Business 2023 by The Independent for its impact on British Businesses.”

Jimmy Nguyen, Executive Board member of Seventy7 Ventures, stated that “Seventy7 Ventures awarded Best of British Business 2023 by @BiznessReporter for The @Independent”.

However, the Independent does not administer the "Best of British Business" awards. It is, according to the Independent, a “campaign” run by the Business Reporter. A marketing campaign.

Business Reporter creates “high-quality video, imagery and articles” to showcase their client’s business, i.e. sponsored content. Business Reporter has contracts with larger and more reputable organizations that allow them to publish the sponsored content on those platforms. Their two biggest contracts are with Bloomberg and the Independent.

Seventy7 Ventures paid Business Reporter to create sponsored content marketing their business. That article is clearly marked “Sponsored by Seventy7 Ventures” and tagged “Best of Business”.

The sponsored article was then cross posted to the Independent with the “sponsored” indicator replaced with an opaque notice: “Seventy7 Ventures is a Business Reporter client". That cross post is dated May 31, 2023, the same year that Seventy7 Ventures claims to have received the “award”.

The “Best of British Business awards” is a marketing campaign for companies who pay Business Reported for sponsored content. The content, as part of the paid package with Business Reporter, is cross posted to the Independent. But stating that the “award” is “by the Independent” or “for [Seventy7 Ventures’] impact on British Business” is false.

By linking the “award” to the Independent, Seventy7 Ventures is either unintentionally misrepresenting the truth or deliberately deceiving the public to give their business credibility.

Seventy7 Ventures and Business Reporter were reached for comment but did not respond.

Big changes ahead

Sean McPherson — Thu, 25 Jul 2024 10:46:00 GMT

Hey RSS Club! Long time no see. I've gotten out of the habit of writing to you this year, but I wanted to give a heads up about upcoming changes to the site.

I'm going to be merging gardens and notes into articles to create a single content type. As a result, there will be a bunch of new entries into the RSS feed that may affect you, dear reader. I apologize for any inconvenience, but I think this is the right move for the health of this site going forward.

I have really enjoyed creating gardens this year with the explicit permission to edit/change content as the page grew. So while the "Garden" content type is going away, the ethos is carrying on into articles. Rather than a resource that is set in stone when published, I'm going to treat articles as living documents that will change over time.

To summarize the changes: Soon everything will be an article, and articles will be more like gardens.

Bypass "Error: There are no prompts" in promptfoo

Sean McPherson — Sun, 30 Jun 2024 01:21:00 GMT

While evaluating different language models with promptfoo, I started running into the following error message:

/Users/seanmcp/project-dir/node_modules/.pnpm/promptfoo@0.67.0_@aws-sdk+client-bedrock-runtime@3.606.0_@azure+identity@4.3.0_@azure+openai-_c7fwzdecwpaax3yh5ny536i2qu/node_modules/promptfoo/dist/src/prompts/index.js:136
            throw new Error(`There are no prompts in ${JSON.stringify(prompt.raw)}`);
                  ^

Error: There are no prompts in "TEXT_OF_THE_PROMPT_THAT_I_TRIED_TO_EVALUATE"
    at readPrompts (/Users/seanmcp/project-dir/node_modules/.pnpm/promptfoo@0.67.0_@aws-sdk+client-bedrock-runtime@3.606.0_@azure+identity@4.3.0_@azure+openai-_c7fwzdecwpaax3yh5ny536i2qu/node_modules/promptfoo/dist/src/prompts/index.js:136:19)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async resolveConfigs (/Users/seanmcp/project-dir/node_modules/.pnpm/promptfoo@0.67.0_@aws-sdk+client-bedrock-runtime@3.606.0_@azure+identity@4.3.0_@azure+openai-_c7fwzdecwpaax3yh5ny536i2qu/node_modules/promptfoo/dist/src/main.js:129:27)
    at async runEvaluation (/Users/seanmcp/project-dir/node_modules/.pnpm/promptfoo@0.67.0_@aws-sdk+client-bedrock-runtime@3.606.0_@azure+identity@4.3.0_@azure+openai-_c7fwzdecwpaax3yh5ny536i2qu/node_modules/promptfoo/dist/src/main.js:545:48)
    at async Command.<anonymous> (/Users/seanmcp/project-dir/node_modules/.pnpm/promptfoo@0.67.0_@aws-sdk+client-bedrock-runtime@3.606.0_@azure+identity@4.3.0_@azure+openai-_c7fwzdecwpaax3yh5ny536i2qu/node_modules/promptfoo/dist/src/main.js:704:9)

It didn't occur for a long time, but then started occurring every time I added a new prompt to the config. Clearing the cache did not help.

The only solution I found was to add a space to the end of the prompt text:

prompts:
  - "TEXT_OF_THE_PROMPT_THAT_I_TRIED_TO_EVALUATE "

This enabled promptfoo to run as expected. Definitely not ideal, but hopefully this unblocks you if you run into the same issue.

I will update this article if I find a better solution. If you have one, please send me an email.

Use state callbacks in React

Sean McPherson — Fri, 28 Jun 2024 01:17:00 GMT

When you want to update state in React, you have two options: pass the next value, or pass a callback function that returns the next value.

const [state, setState] = useState(0);

// Next value
const reset = () => setState(0);
// Callback function
const increment = () => setState((prev) => prev + 1);

To choose correctly, you need to ask if the next state depends on the previous. If so, choose the callback function. Otherwise, you can pass the next value.

The reason for this is that React does not update state until the next render. So if you have multiple references to state in the callstack, all but the first will be stale. Here's a contrived example:

// ⚠ Buggy code
function loginSuccess(username) {
  setState({ ...state, username });
  // ...
  setState({ ...state, showLoginModal: false });
}

When the loginSuccess function is called, it first sets the username property while referencing the current state. No issues so fare.

But although setState has executed, state will not change until the next render. So when the second setState is called, it references the stale state value which does not include the updated username.

The final state is not what we want:

{
    username: undefined, // We wanted this to be updated
    showLoginModal: false
}

You can try to avoid this by avoiding multiple setState calls in the same stack. But as your application grows, you will inevitably run into this issue. And in my experience it's not an easy bug to track down.

The better solution is to use the callback function every time you need to reference the previous state:

// ❌ setState(count + 1)
setState((count) => count + 1);

// ❌ setState(items.filter((item) => item.id !== id))
setState((items) => items.filter((item) => item.id !== id));

// ❌ setState(!isEnabled)
setState((isEnabled) => !isEnabled);

// ❌ setState({ ...user, username: "seanmcp" })
setState((user) => ({ ...user, username: "seanmcp" }));

This will ensure that every setState call references the latest state, regardless of where it is in the callstack.

VIVO sit/stand desk

Sean McPherson — Thu, 27 Jun 2024 18:09:00 GMT

In 2021 I purchased a 43" VIVO sit/stand desk from Amazon. It has served me well for the last few years, but I have encountered a few issues and solutions that I want to log here.

Desktop rocks back and forth

When the allen bolts that hold the desktop to the frame are too loose, then the desktop will rock back and forth with normal use. This is particularly noticeable when you are leaning on the desk, but also when writing or typing.

To fix this, I've found that tightening the bolts with an allen wrench prevents the rocking. However, over-tightening results in the paint chipping around the bolt holes and slight deformations of the metal. Be careful and only tighten as much as necessary.

Desktop squeaks under pressure

This one was maddening: whenever I applied the slightest pressure on the desktop it would squeak. Some days it was so bad that every keystroke prompted a small squeak.

Loosening the allen bolts that hold the desktop to the frame fixed this issue but caused the rocking issue mentioned above.

To fix this, I purchased nylon washers from the hardware store and placed them in-between the frame and the brackets holding the desktop^[1]. With those in place the the allen bolts tightened, the squeaking has stopped.

Modifications

Added an IKEA Signum cable organizer to the bottom of the desktop
Added a generic clear acrylic headphone hanger to the bottom of the desktop

Don't be like me: make sure to clear the desktop before you do this ↩︎

Simplify event delegation with the Element.closest method

Sean McPherson — Wed, 12 Jun 2024 01:31:00 GMT

Let's say you have a list of buttons and want to perform an action when one is selected. A solution is to add an event listener to each button with a reference from querying or creating the button.

let buttons = document.querySelectorAll("button");
buttons.forEach((button) => {
  button.addEventListener("click", (e) => {
    console.log("Clicked:", button);
  });
});

For a small number of buttons, this is fine. But as the number of buttons grows or if they are added and removed dynamically, then this solution grows inefficient and fiddly^[1].

Another option is to delegate the event handling to a parent element. Since most events bubble in JavaScript, an event that is fired on the button child will trigger the listener callback for the parent.

Here's an example of a delegated event listener in a counter where a parent contains buttons that increment by different amounts:

let parent = document.querySelector("#increment-buttons");
parent.addEventListener("click", (e) => {
  count += parseInt(e.target.dataset.increment);
});

I like this pattern because it enables you to add buttons declaratively in HTML instead of imperatively in JavaScript. That said, the code above is brittle. If you add additional markup to the buttons, like an svg icon or a span, then the e.target will refer to that element instead of the button.

To resolve this, we can use the Element.closest method to walk up the DOM tree to find the nearest element that matches a selector. Element.closest checks the element first before moving to the parent, so we can use it in our event listener to find the button:

let parent = document.querySelector("#increment-buttons");
parent.addEventListener("click", (e) => {
  let button = e.target.closest("button[data-increment]");
  if (button) {
    count += parseInt(button.dataset.increment);
    // Other rendering logic...
  }
});

Now we are free to add children elements to our buttons without breaking our event listener.

Event delegation is a useful pattern to simplify situations like this where you have many descendant elements that need similar event listeners. But if you tried to route all of your events through a single parent like the document, it would grow inefficient and unwieldy too^[2].

Reach for the best tool for the job, and when you choose event delegation: remember Element.closest.

You have more event listeners in memory and need to manage them all manually. ↩︎
You need to call Element.closest and add conditional logic for every event interaction. ↩︎

Align content in Markdown tables

Sean McPherson — Fri, 07 Jun 2024 10:47:00 GMT

You can set the align attribute on a table column in Markdown by using a colon in the header row separator.

A typical table looks like this:

| A   | B   | C   |
| --- | --- | --- |
|     |     |     |

To align the content, add colons to the separator row--:- for left, :-: for center, and -: for right:

| A    |   B    |     C |
| :--- | :----: | ----: |
| Left | Center | Right |

That Markdown will render a table with the align attribute set on the header and body cells:

A	B	C
Left	Center	Right

Solo-playing Adventure Games with AI

Sean McPherson — Wed, 29 May 2024 23:09:00 GMT

Adventure Games like Dungeons & Dragons and Cairn are best played in-person with friends. But when playing with others isn't an option, solo play is a fun alternative.

Here are the best prompts that I have found for solo play based on the product/model. As with all AI: your experiences will vary.

ChatGPT 4o

You are a game master for Cairn RPG. Run a play by post adventure with me. Keep everything brief, the goal is to get through an adventure quickly.

+ Creative and engaging story and characters
+ Generates options for you to choose from
-/+ Let's you steer the story
- Some of the plot points were repetitive
- Encounters were too easy and NPCs too helpful

CSS nesting is (almost) ready

Sean McPherson — Tue, 28 May 2024 24:50:00 GMT

I've been hearing a lot about CSS nesting, but I figured that it was still years away from being ready for use even on a site like this.

But a quick check of Can I Use shows that it is ready in all major browsers. Even more if you make sure to use the & nesting selector.

Try it out for yourself:

View this interactive on seanmcp.com

So should you start using CSS nesting today? Probably not. But it is almost ready, and that's exciting. Variables and nesting are the two features that would still draw me to a preprocessor like Sass or Less. We've had native custom properties for years, and now we are so close to being able to use nesting.

Exciting times!

Looking over the fence at Eleventy

Sean McPherson — Mon, 27 May 2024 18:43:00 GMT

First of all: I'm happy with Astro. It's an exciting project that provides the tools necessary to build websites in the way I want to build them. The future is bright for Astro.

But... I still find myself looking at alternatives. I've written previously about Astro's relentless releases, and it continues to be a source of stress for me.^[1] Every other week it's a fresh release and reminder that I am behind. Are there alternatives that provide me some of the same features without the release cadence?

Thanks to the recent "International Symposium On Making Web Sites Real Good" conference and its positive reviews, Eleventy has caught my eye again. Robin Rendle's recent experience returning to Eleventy was insightful. Once upon a time this site was previously built with Eleventy, and I liked it too... until I didn't.

Eleventy was fast and focused, but the lack of opinions meant that you could easily architect yourself into a corner. I was so bogged down with Nunjucks templates, filters, and shortcodes in the end that I gave up and rebuilt in Astro.

That said, I still admire what Zach Leatherman is doing with Eleventy. and the community that he is building. I like the ethos, and that gives me confidence in where the project will be in 3-5 years. Can I say the same for Astro?^[2]

I'm not going to re-write this site. But I think I'm going to reach for Eleventy the next time I'm building a simple or long-lived website. If all I need is a way to generate a bunch of HTML with linked CSS and JavaScript, Eleventy seems like the better option of the two.

At the time of writing, I am five minor releases behind and counting. ↩︎
I think the answer is no. They have received venture capital and need to find some way to make a return on that investment. Since I'm not a paying customer, I don't have great confidence that the project will grow in the direction that meets my needs. ↩︎

ChatGPT 4o isn't a good researcher yet

Sean McPherson — Sat, 18 May 2024 01:51:00 GMT

I asked ChatGPT 4o for general recommendations for software release frequency, and it spouted out some information that seemed generally plausible. I asked it to cite its sources, and after an internet search it provided three links. I checked all three, and none of them contained the information that ChatGPT initially provided.

I replied with "None of those articles had the guidelines that you cited" and it responded back with more information and more links. I checked a few of them, but it was the same as before. They were on the same topic, but the information that ChatGPT provided was not sourced from those articles.

I don't know what I expected, but it's clear that ChatGPT 4o isn't a reliable research assistant yet. It can provide you some common ~~misconceptions~~ information, but it isn't going to point you to a true source consistently. You're going to need to research for yourself.

Use with caution.

Astro and release velocity

Sean McPherson — Sat, 18 May 2024 01:12:00 GMT

This website is built with Astro, and overall I've been happy with my choice. The framework model makes sense to me, and I really enjoy using their templating language for building UI. If I were to start over today, I would still choose Astro.

But I've had an unsettled feeling about Astro and this site, and I think I've finally put my finger on it: Astro is moving too quickly. It feels like every few weeks they're putting out a new version with new features and new patterns to build new websites.

And as exciting as that is (I'm sure the maintainers are thrilled to be able to ship new things so quickly), it's overwhelming for me as a user. I feel like I'm always behind because I am. I updated the Astro dependencies on this site two months ago, and I'm already four minor versions behind. That's two minor versions per month!

Now full credit should go to the Astro team for working to make updates relatively painless. I haven't encountered any particularly difficult breaking changes, and they have tooling that helps make the process simpler. But a simple process is still a process, and it's one that users have to do a lot to keep their Astro sites up to date.

I know that no one is forcing me keep my dependencies on latest; that pressure is internal. But it's real, and it impacts how I feel about working with Astro.

Given two identical frameworks, my preference would be for one that updated regularly but less frequently. Quarterly or even twice-yearly updates would be perfect (patches excluded). Enough to keep you thinking about updating dependencies but not so often that you're always behind.

Sadly for me, that isn't the reality with Astro. Is that enough to drive me to choose a different framework? No. But release velocity was not something I considered when choosing Astro. Now with a little more experience it is something that I will think about in the future.

Render and effect call order in React

Sean McPherson — Sat, 18 May 2024 24:43:00 GMT

Setup: Let's say I have a React tree like this:

function Parent() {
  console.log("Parent render");
  useEffect(() => {
    console.log("Parent effect");
  }, []);
  useLayoutEffect(() => {
    console.log("Parent layout effect");
  }, []);

  return <Child />;
}

function Child() {
  console.log("Child render");
  useEffect(() => {
    console.log("Child effect");
  }, []);
  useLayoutEffect(() => {
    console.log("Child layout effect");
  }, []);

  return null;
}

ReactDOM.createRoot(/* ... */).render(<Parent />);

What order would you expect the logs to fire in? If you were like me, you'd probably have some mental model of how React works and be able to make an educated guess. But I was wrong.

Then I asked this question to a handful of seasoned React developers, and they all got it wrong.

Because the real answer is unexpected:

Parent render
Child render
Child layout effect
Parent layout effect
Child effect
Parent effect

Try it yourself: Here's a StackBlitz in case you don't believe me.

Attempting an explanation: When rendering a tree, React calls the components from the top of the tree downward. So because Parent is at the top of the tree, its render log is called before Child. So far, so good.

Effects are a different story. React effectively queues effects from the bottom of the tree upward, so Child's effects are called before Parent's. Plus there is the additional layer that useLayoutEffect is called before useEffect (which, to be fair, does make sense but is one more thing to think about).

I ran into this issue at work when a child had code running on render that was occurring before the parent's useLayoutEffect ran. There were several layers of components between the two, and finding the cause was not fun.

Takeaway: I don't expect you or me or anyone else to remember this order. But if you can remember that the order is unexpected, then that will put you on the right path.

Tweaking garden details

Sean McPherson — Fri, 17 May 2024 17:58:00 GMT

I like the idea of digital gardens, but I haven't been happy with how I implemented them on my site. This afternoon as I was thinking about it, inspiration struck and I redesigned how I illustrate a historical record of tended dates.

Instead of a verbose list of "Planted on...", "Tended X times", and "Last tended...", it is now two dates and a visualization representing the number of intermediary dates. You can see how this looks for gardens in different states on /gardens.

Check it out and let me know what you think.

Manage your photo archive

Sean McPherson — Thu, 09 May 2024 10:36:00 GMT

A coworker at Khan Academy shared some advice (apparently secondhand from the New York Times) for managing your ever-growing photo archive:

Every day open your photos app
Search for the day's date
Review your old photos from that day
Delete ones you don't need anymore

My first thought was "That's brilliant!" It's a low lift but once the habit is established it ensures that you address every day of the year.

The first day I tried it, I found this photo from 2017 when I was still teaching:

I have no memory of this day or what I was expecting the students to do, so I deleted it. One less photo in the archive!

With strategies like this, we can reduce the amount of junk data that we all have hanging around on someone else's server.

Site update May 2024

Sean McPherson — Sat, 04 May 2024 18:29:00 GMT

I just landed a PR that made some changes to this site. It started as an experiment to move from Netlify to Cloudflare, but then turned into Spring cleaning. Here is a summary of all the changes:

Removed dark mode: I'm sorry if dark mode was your preference (it was mine too), but I didn't like the ongoing cost of maintaining multiple themes. Now it's just light mode, but that will change in the future.
Removed /contact: No one used it, and my email address is in the footer of every page.
Removed likes: It was an interesting experiment, but a) it wasn't valuable to me and b) it locked me in to specific platform features.
Removed analytics: I hadn't checked the analytics in months, and even when I did it never had an impact on my decisions.
Removed Netlify: This included Netlify CMS and an /admin route I never used, Netlify CLI, Netlify edge functions, and a single Netlify form.
Replaced /fn/random with /articles/random: A feature for random articles is fun, and this iteration handles everything with client-side JavaScript.

Now that the work is done, I don't actually have plans to move off Netlify. I didn't see the performance improvements that others have reported, so inertia will keep me here for now^[1]. But I like the idea that I could move quickly if/when the need arises.

Hopefully I don't live to regret that decision. ↩︎

Measuring and cutting

Sean McPherson — Wed, 24 Apr 2024 17:24:00 GMT

I learned “measure twice, cut once” while working with my dad. He probably learned it from his dad and him from his dad. It’s good advice, but in an issue of Frontend at Scale Maxi Ferreira suggests that it might not apply neatly to software engineering:

[S]oftware is different, and trying to apply this piece of advice to planning, designing, and writing applications can sometimes do more harm than good.

Measuring twice (i.e. considering all possible options and coming up with the perfect design or architecture before writing a single line of code) is not the most effective way to build software. That’s the waterfall approach, and we know it doesn’t work.

Instead, we can use the flexibility of software to our advantage and flip the woodworker’s advice on its head. We can measure once, decide quickly, and cut as many times as needed.

When your materials are (close to) free, you don’t need to spend the extra time up front getting all of measurements perfect. Instead, get ship something and spend that time iterating.

He expands on the idea more in the article. Give it a read and let me know what you think.

A Few Things #12

Sean McPherson — Sun, 07 Apr 2024 01:05:00 GMT

Here are a few things that I found interesting this week:

Machine by XKCD

Machine is a collaborative interactive where you help build a machine that moves colored balls from point A to point B. Once you have completed your task, you can take a look at the machines that others have built. It's really neat and an interesting change of pace for XKCD.

Africa by Toto but its played on instruments in Majora's Mask by bigfatfrown

I really like YouTube, but sometimes I get nostalgic for the simpler, amateur past. This video is only two years old, but it feels like one from an earlier era of YouTube.

Truncate: A word-based strategy game

This one took some time to understand, but it's a fun little combat-style word game. It's a challenging and refreshing alternative to more traditional word games.

Canabalt

I have a soft spot for all Flash games, and I have fond memories of playing this one on Flashplayer.com (RIP). It's a simple infinite runner game, but the artistic style and the feel set it apart. See if you can beat 2000 meters.

A Few Things #11

Sean McPherson — Sun, 31 Mar 2024 24:59:00 GMT

Here are a few things that I found interesting this week:

Why I am a Christian by James J. Choi

Choi, a professor of Finance at Yale, shares his reasons for being a Christian. The whole article is worth reading, but I wanted to highlight the sections surrounding Jesus' death and resurrection:

Christianity is falsifiable
MANY RELIGIOUS CLAIMS ARE NOT VERIFIABLE OR FALSIFIABLE
Claim: Religious Figure X received a divine revelation
On what basis would you confirm or deny that claim?

CHRISTIANITY IS DIFFERENT
It makes a claim that an event happened in space and time: Jesus Christ died and then was raised from the dead. And it says, if this didn’t happen, you should dismiss the entire religion.

There is credible evidence for Jesus’ death and resurrection
Non-Christian philosopher of religion Antony Flew: “The evidence for the resurrection is better than for claimed miracles in any other religion. It’s outstandingly different in quality and quantity.”

The world is awful. The world is much better. The world can be much better. by Max Roser (Our World in Data)

The world is awful. The world is much better. The world can be much better. All three statements are true at the same time.

This article unpacks some of the challenge that we face when trying to understand our deeply complex world. The reality is that there are terrible things happening. And that the world has improved significantly for many people. And there is more that we can do to make the world a better place.

Scotland's Forgotten Rainforest by Aidin Robbins

This video takes an interesting look into the history of forests in Scotland. I was impressed with the quality of the video and the detailed descriptions with links to dive further into the topic. More creators should do that.

Music Map

Finding new music is hard. Even when I try to learn into algorithmic recommendations, I still find myself gravitating to the old bands and sounds that I'm used to. Websites like Music Map can help by suggesting artists that are similar to your favorite bands. I've used it to discover new music and re-discover bands that I'd forgotten.

A Few Things #10

Sean McPherson — Sat, 23 Mar 2024 10:55:00 GMT

Here are a few things that I found interesting this week:

Lake Retba: The Pink Lake of Senegal

Lake Retba is one of many pink lakes in the world, that are colored by bacteria or algae. The lake is a source of salt production for the surrounding communities in addition to being a tourist attraction.

More photos: https://africageographic.com/stories/pink-lake-retba-senegal/

How Farmers Reshaped a Region and Solved Drought by Andrew Millison

This is the second video that I've shared from Andrew Millison (see A few things #6). In this video, he learns about a community in northern India that used permaculture to transform environment for the better over the course of 45 years.

I was struck by the long-term commitment to collective action for the benefit of all. That's the stuff that it feels like we can only dream of here in the United States.

Did Idaho Get Its Name As A Result Of A Hoax? (hoaxes.org)

The US state of Idaho may have been named a man making up a Native-American word. He initially proposed "Idaho" as a name for Colorado which was rejected. But his made-up word that meant "gem of the mountains" was planted in the minds of many, and eventually became the name of a different state.

This is, if Idaho even exists at all: http://www.fantasymaps.com/stuff/idaho.html

Create a custom search for a static site

Sean McPherson — Fri, 22 Mar 2024 19:08:00 GMT

There are out-of-the-box solutions for searching on a static site. I previously used Pagefind for this site which remains a great option. But if you want fully control of the behavior and appearance of your search feature, then you might have to build your own.

After thinking through how I wanted to use a search feature, I came up with these acceptance criteria:

Query and filter by type, year, and tag: I want to be able to view all Articles from 2023 tagged JavaScript with the text “class”.
Fuzzy search: Before Pagefind I had a search that used strict string matching, but the experience was poor.
URL-powered: I want to use it as a custom search engine in the browser and be able to link directly to filtered search results.

With those criteria established, I could move on to designing and building the solution.

Solution

Without going into too many details about how I accomplished this in Astro, here are the high-level steps I followed to build a custom search:

Gather all of my content into a normalized array: As I’ve written previously, normalizing data is a good idea.
Expose the data to client-side JavaScript:
1. Astro has a helpful define:vars directive for this, but your static-site generator has some kind of solution for hand off data with a script tag.
2. The important part for me was to avoid network requests for the content data; I wanted this to be available at build time.
In JS sync HTML with URL: Read the search parameters and then update the in-page form elements with the data. For this solution, the URL is the source of truth.
Create a function to search and render: I wanted the results to render on load and whenever there was a change to the search form. By encapsulating that logic in a function, I was able to call it whenever I wanted.
Use Fuse.js to search through content: This is the first time I’ve used Fuse and it was awesome. I added it from a CDN with a script tag, and it worked without any issues.
Render: Take the results from Fuse and add some markup to an output element.
Add event listeners for change, input, and submit: These were all added to the form element to a) sync URL with form state, and b) render updated results.

You can view the finished product at seanmcp.com/search.

Lessons learned

Pushing search parameters to the URL without reloading is easier than I thought. I really like the idea of using the URL as the state for a feature like this.
The default select[multiple] UI is difficult to design around. I ended up limiting the filters to a single selection because I couldn’t find a layout that I liked with multiple.
Fuse.js was a delight, and I look forward to more opportunities to use it.
I thought that I would need to debounce changes from the form, but in my testing it handled individual keypresses without any issue.
Astro will scope styles for you, but you can only reference elements that are currently in the file. This is a problem when you will be building a UI with client JavaScript. Thankfully Astro works with templates, so you can style a sample response element and style it without resorting to :global() calls.

Fix missing Astro files on GitHub pages

Sean McPherson — Wed, 20 Mar 2024 01:12:00 GMT

I'm in the middle of a long project to migrate my projects from Netlify to GitHub pages. I was working on the GitHub actions for an Astro project and noticed that most of the CSS files were missing from the assets directory.

When I built the project locally, I saw the following:

_book_.95a15f93.css
_book_.ef58a27b.css
_chapter_.02b05af9.css
index.3e3ecbbf.css

The index.3e3ecbbf.css file was the only CSS one that was successfully deployed. That led me to think that there was something about the underscore prefix that was causing the other files to be ignored.

GitHub Pages uses Jekyll behind the scenes, even if your site doesn't use it. And Jekyll ignores files and directories that start with an underscore. So the solution is to tell GitHub to skip Jekyll processing of your build directory with a .nojekyll file.

In the GitHub Action for the Astro project, I added the following line to the build step:

touch dist/.nojekyll

Once that was added, all of the generated CSS files were successfully deployed to GitHub Pages.

There is also an official action for Astro projects that probably handles that for you.

Create a useIsOnline React hook

Sean McPherson — Tue, 19 Mar 2024 19:35:00 GMT

There are two browser features that enable you to detect an internet connection with JavaScript:

The Navigator interface's onLine property for the current state
The online and offline events for state changes

By combining these, we can create a custom React hook that tells us if the browser is currently online.

import * as React from "react";

// Check if window is available
const maybeWindow = typeof window === "undefined" ? null : window;

export default function useIsOnline() {
  const [isOnline, setIsOnline] = React.useState(
    // Read onLine value from navigator if available, otherwise fallback to true
    maybeWindow?.navigator.onLine ?? true
  );

  useEffect(() => {
    // Add event listeners on mount
    maybeWindow?.addEventListener("online", () => setIsOnline(true));
    maybeWindow?.addEventListener("offline", () => setIsOnline(false));

    // Remove event listeners on unmount
    return () => {
      maybeWindow?.removeEventListener("online", () => setIsOnline(true));
      maybeWindow?.removeEventListener("offline", () => setIsOnline(false));
    };
  }, []);

  // Return the online status
  return isOnline;
}

We can use this hook to display a banner when the user is running our app and then goes offline:

function App() {
    const isOnline = useIsOnline();
    return (
        <>
            {!isOnline && (
                <div role="alert">
                    You are offline. Changes will be synced when you reconnect.
                </div>
            )}
            {/* ... */}
        <>
    )
}

In newer versions of React you can use a hook like useOnline which depends on useSyncExternalStore.

Fix static file endpoints after Astro v4 upgrade

Sean McPherson — Tue, 19 Mar 2024 10:03:00 GMT

Yesterday I upgraded to Astro v4 without any issues, but this morning I noticed that my RSS feed was broken.

I have two static file endpoints that generate a file at build time, one for RSS and the other for a webfinger. Both of these had two issues highlighted after the upgrade:

The files did not export a GET function
The files did not return a Response or Promise<Response>

The first issue was resolved by capitalizing the previously-valid get function to GET.

The second issue required an update to the @astrojs/rss dependency which now returns a Promise<Response>. The webfinger endpoint is custom, but all I needed to do was wrap my return value with a Response object:

// Before
return { body: JSON.stringify(data, null, 2) };

// After
return new Response(JSON.stringify(data, null, 2));

The webfinger issue is easy to miss (and nonconsequential), but I should have verified that the RSS feed was working before shipping the upgrade. Lessons learned!

Upgrading from Astro v2 to v4

Sean McPherson — Tue, 19 Mar 2024 01:44:00 GMT

Update March 19, 2024: I missed some issues with static file endpoints that I needed to fix after the upgrade.

In a recent episode of the ShopTalk podcast, Chris Coyier and Dave Rupert interviewed Fred K. Schott about new features in Astro. That reminded me that I need to upgrade this site from 2.6.1 to 4.5.6.

Here is a log of the process:

pnpm install astro@latest
Peer dependency issues
1. pnpm install typescript@latest
2. pnpm install @astrojs/mdx@latest
3. pnpm install @astrojs/svelte@latest
4. pnpm install svelte@latest
Tried pnpm run build
Build error on articles: localStorage is not defined
1. Found a reference to localStorage in a Svelte component in the last page generated by Astro
2. Remove all direct references to localStorage
3. That fixed it
4. Read client:only documentation
5. Realized that is what I wanted
6. Reverted changes to Svelte component
7. Added client:only to MDX files that referenced the component
8. That fixed it
Tried pnpm run build again
It worked

Netlify build failed:

9:32:21 PM: Node.js v18.12.1 is not supported by Astro!
9:32:21 PM: Please upgrade Node.js to a supported version: ">=18.14.1"

Updated NODE_VERSION environment variable to LTS 20.11.1
That fixed it

Done

I get a little nervous reading about the complexity of Astro--especially because I'm using it to build this simple site. But in my experience, all of the upgrades have gone smoothly. (Edit: they even have an upgrade tool)

The Astro team deserves a lot of credit for engineering a tool that is feature-rich while managing the complexity for the developer. I hope they can continue that as they grow.

A Few Things #9

Sean McPherson — Sun, 17 Mar 2024 24:10:00 GMT

Here are a few things that I found interesting this week:

When can you hear yourself think? by Greg Gilbert

Gilbert reflects on the modern (maybe?) impulse to continuously consume media. News, audiobooks, podcasts, music: "we fool ourselves into thinking we are doing something meaningful and productive." But the reality more often is cluttered minds and unorganized thoughts.

The antidote is quite time in our own mind. "We need to hear ourselves think on a regular basis. The easiest way to do that is to unplug from 'knowledgetainement' when we perform mundane tasks like emptying the dishwasher."

I think that washing the dishes can be a great time to catch up on podcasts or YouTube videos. But too frequently I feel myself reaching for media just to fill the void. Gilbert's article gives me something to thinking about.

h/t Evan Travers

Making A Medieval Book by Four Keys Book Arts

This video compresses 60 hours of expert bookmaking into 24 minutes. I haven't thought much about how books are made before, but I really appreciated the care and attention to detail. Making books is an art.

For a more accessible look at bookmaking, checkout Adam Savage on Tested.

Semantic Satiation (Wikipedia)

This week I wrote about the term "blog", and it didn't take long before the word felt weird in the mouth and sounded strange to my eat. That phenomenon has a name: semantic satiation.

Matthew Wolff Design

I really like soccer, and I really like logo design. I was pleasantly surprised to learn that almost all of my favorite American soccer logos were designed by the same guy: Matthew Wolf.

On articles and blogs

Sean McPherson — Sat, 09 Mar 2024 19:07:00 GMT

My first memory of the word “blog” was my four-years-older brother complaining that he didn’t like the term. “It’s a web log,” he insisted, “not a buh-lawg!” I don’t know why he felt so passionately, but as a dutiful little brother I adopted his position without question.

So from my earliest days online I have avoided the word blog. Occasionally I used “web log” or just “log”, but even when I was writing on Blogger I didn’t refer to my site or my writing as a “blog”.

After college, I spent some time as an amateur soccer journalist covering the lower leagues in my area. I have fond memories of interviewing players and staff and writing about their experiences (though most of what I wrote were less-memorable match reports).

In journalism, you write the news. You write articles. The word feels more dignified. An article is professional. An article is something worth writing—worth reading.

When I begin writing as a software engineer, I continued with that term. That’s what I used on this site, both as a label and URL.

But as time passes, I’m starting to reevaluate my position. I don’t actually have a problem with the word blog (though my brother still might!). And calling what I write here “articles” is a stretch. “Blog” is the common term, and a blog is what I have.

I’m not going to change my site based on this realization. After all, cool URLs don’t change. But I am going to describe this site differently. Instead of telling people “I write articles on my website”, I’m going to try “I write posts on my blog.”

It's more accurate and more helpful, so I'm going with it (sorry bro!).

Thanks for reading my blog!

A Few Things #8

Sean McPherson — Sat, 09 Mar 2024 10:40:00 GMT

I'm trying something different with the formatting this week. Let me know what you think.

Here are a few things that I found interesting this week:

Leaf letters: fan email for Melbourne's trees pours in from around the world by Monica Tan (The Guardian)

Melbourne Australia registered email address for trees so that people could report damages. Instead people sent kind messages:

Hello, dear Tree. I read about this wonderful project and suppose to write you from another side of Earth - Russia. I hope you have a good care and don’t sick. One day we will meet, may be.

I hope the same for you, dear reader.

Where did all the roaches go? by Radio Atlantic via Search Engine

I wouldn't have thought that I would be recommending media about cockroaches, but that's long-form narrative podcasting for you! Although it is billed as the third part of a series on animals from the Search Engine podcast (which I recommend), it's really an episode from Radio Atlantic (which I hadn't heard of).

I'm too young to remember the cockroach days, but I remember lots of references from my youth that didn't match reality. Pixar's Wall-E is a good example of the lasting legacy of roaches in popular media.

One Year to Make a Game - Or Be a Janitor Forever - Devlog 0 by Wyrmyr Games

I'm a fan of the "Game Dev Log" genre on YouTube, and subscribe to a few different channels. I don't have a passion for game development, but I appreciate documenting the building process.

This particular video is a small creator who is trying to get into game development while also working full-time as a cleaner. His fish-feeding simulator idea is intriguing, and I hope that he is able to meet his goals.

Why Microsoft Edge?

Sean McPherson — Wed, 06 Mar 2024 17:59:00 GMT

I like trying out new browsers and try to avoid being tethered to one for too long. But ever since its switch to Chromium, I find myself coming back to Microsoft Edge.

Powered by Chromium: I have issues with recent releases of Chrome, but now that Edge is powered by the same underlying technology I don't need to choose.
Size conscientious: Screen real estate is precious, and Edge is the only cross-platform browser that cares about conserving it. The combination of vertical tabs and minimal UI makes it the clear winner for smaller screens.
Customizable UI: Chrome has started adding buttons to the toolbar that you can't remove. Edge allows you to decide what icons make sense for you.
Unobtrusive AI: I don't use Copilot features often, but it's there when I need it and out-of-the-way when I don't.
DevTools improvements: I like the vertical activity bar and the built-in accessibility checks.

If you haven't tried the new Edge, I recommend giving it a look.

Switching from Ubuntu to Linux Mint

Sean McPherson — Wed, 06 Mar 2024 17:24:00 GMT

Ubuntu was running slow on my old personal laptop. Previously I had turned to Lubuntu, but I read online that Linux Mint has slighly better performance on low-powered devices. So with a free morning I decided to give that a go.

Setup steps:

Customized the colors and wallpaper
Switched trackpad scroll from "Reversed" to normal (i.e. down goes down)
Installed some key programs with Software Manager
Removed some bundled software that I won't need
Set up a custom search engine in the browser
Installed git with apt
Installed Node with nvm
Set up SSH for GitHub
Cloned this repo and started writing

First impressions:

It seems to run faster than Ubuntu
It generally looks good (though I'm not sold on the "LM" icon)
The window management is nice

Issues:

I first installed VS Code with Software Manager, but 1) the terminal was not loading the correct shell, and 2) the icon was non standard. I downloaded the .deb directly from VS Code and installed to fix those problems.

Open questions:

How can I get an emoji picker?
How do I configure the panel clock to use 12-hour time?

Notes on improving the process for me:

I haven't setup settings sync for VS Code, and getting everything running from scratch isn't fun. Figure out how to do that for the future.

A Few Things #7

Sean McPherson — Sat, 02 Mar 2024 20:40:00 GMT

In #6 I shared Trivia Pig, the Wordle-inspired trivia game. After playing it for a week I can confidently say that I am not good at trivia. But my wife and I have been playing every night before bed, and it's been fun to share our successes (but mostly failures) together.

Here are a few things that I found interesting this week:

Open Syllabus: Explorer
Recently I was looking to find a popular textbook for a given topic. That search led me to Open Syllabus, a database of over 7 million college syllabi from across the world. You can find the most commonly assigned for a given area of study. Pretty niche, but it's great to have in your pocket for later.
Best Trash Bag? Let’s Find Out! by Project Farm
This YouTube channel has videos of comprehensive tests for competing consumer products. In this video they test trash bags to see which are the best based on their metrics. I love that they do what I think of doing when I'm at the store but know that I don't have time for. It's an interesting watch, but click here for the results.
Living for Plants by shawcat
Play as a skeleton caring for their plants. I had plans to build a very similar game, but this is 10 times better than anything I would have created!
Obvious Plant Store
My wife showed me this store, and we both shared a good laugh. You will either think these are funny or you won't. Which I now realize is true of all things but particularly these.

A Few Things #6

Sean McPherson — Sat, 24 Feb 2024 20:40:00 GMT

Here are a few things that I found interesting this week:

Design Patterns that Encourage Junk Data by Michelle Barker
I don't think the thought has occurred to me before, but our digital footprints are huge and ever expanding. And all of that data, from old forum accounts to Google Docs from high school to random photos on various platforms needs to live somewhere.

Personally, I like being able to access all of that. I like that data feels permanent. But maybe that's because I don't bear the cost of that availability. And maybe I should think about more and more deeply. Good food for thought.
How the UN is Holding Back the Sahara by Andrew Millison
The UN is working with local communities in the African Sahel to build a "Great Green Wall" to 1) reclaim low-quality soil, 2) increase local agriculture, and 3) prevent the southward spread of the Sahara. For more information, checkout thegreatgreenwall.org.
The Book of Kells Collection at Trinity College Dublin
After last week's article about text illuminations, I wanted to track down the most famous illuminated text: The Book of Kells. The detail of the illustrations is stunning, and the colors are beautiful. Take a few minutes and explore the pages of this 1200-year-old book.
Trivia Pig
A fun Wordle-style game with daily trivia questions in 8 different categories. I don't see it being a runaway success, but it's good for a quick diversion.

Running Ollama without a GPU

Sean McPherson — Sat, 24 Feb 2024 10:48:00 GMT

tl;dr You can run Ollama on an older device, but the response will be slow and/or low quality.

I have successfully run Ollama with a new Macbook M2 and a mid-range gaming PC, but I wanted to experiment using an older computer. My personal laptop is a 2017 Lenovo Yoga with Ubuntu and no graphics card. Here are some specs:

CPU: Intel i5-7200U CPU @ 2.50GHz
RAM: 4GB
Memory: 128GB SSD

Following the setup instructions for Linux, Ollama installed fine but printed the following:

WARNING: No NVIDIA GPU detected. Ollama will run in CPU-only mode.

This was foreshadowing for everything to follow.

I decided to run mistrel and sent the model a prompt by the terminal. The response was streaming in at about one character every four seconds, and my computer was obviously struggling with the task. I held on for around three minutes but then had to quit when the response was less than on sentence.

That seemed conclusive enough, but I decided to try with a smaller model. I ran tinyllama and was able to stream responses at a normal rate. However, the quality of the responses was terrible. I don't have experience with this model on a more powerful machine, so I can't blame the model. But the responses were so bad that I wouldn't use it for anything on this device.

These results were disappointing, but the reality is that running LLMs is resource intensive. So if you want to try running LLMs locally with Ollama, make sure you have a modern CPU or a dedicated GPU.

Use Ollama with the official Python library

Sean McPherson — Wed, 21 Feb 2024 17:06:00 GMT

Ollama is a great way to get started with AI by using open-source and publically available large-language models locally on your computer. I wrote previously about how to get started with the experimental OpenAI API, but Ollama has a dedicated Python library that is even simpler.

Install the library: pip3 install ollama
Create a new python file: touch completion.py

Add the following code to completion.py:

import ollama

def get_completion(prompt, model):
    response = ollama.chat(model, messages=[{
        'role': 'user',
        'content': prompt,
    }])

    return response['message']['content']

prompt = "What is the chief end of man?"

print(get_completion(prompt, "mistral"))

Run the file: python3 completion.py

There is more information available in the library repo on GitHub, including examples for streaming responses and a custom client. For even more documentation on Ollama, check out the /docs directory in the main repo.

A Few Things #5

Sean McPherson — Sat, 17 Feb 2024 10:55:00 GMT

Here are a few things that I found interesting this week:

Handwriting but not typewriting leads to widespread brain connectivity by Van der Weel et al.
Researchers at the Norwegian University of Science and Technology studied how handwriting and typewriting affected brain activity:

"When writing by hand, brain connectivity patterns were far more elaborate than when typewriting on a keyboard, [which existing research shows] are crucial for memory formation and for encoding new information... Our findings suggest that [handwriting contributes] extensively to the brain’s connectivity patterns that promote learning."

I remember hearing of similar research I was in college, and it was the main reason that I took notes by hand instead of on a laptop. I'm glad to see that there's more research on the topic and that those hand cramps were not in vain.
The mystery of the medieval fighting snails by Zaria Gorvett (BBC)
Gorvett looks into the history of medieval illuminations, decorative illustrations that were added to the borders of a text. The subject of the illuminations did not need to match the text, and "for a brief period in the late 13th Century, illuminators... across Europe embraced a new obsession: fighting snails.". Gorvett explores the possible reasons for the trend--none of which consider the possibility that there were megafauna snails in the medieval period.
Liz Climo Cartoons
I saw one of these cartoons on r/wholesomememes and wanted to track down the creator. All of Climo's comics feature cute animals in relatable situations. Very wholesome.
Banana Prices by XKCD
When a student asks their Math teacher "Why do I need to learn this?", they should be shown this.

Get started prompt engineering with local LLMs

Sean McPherson — Fri, 16 Feb 2024 18:59:00 GMT

Ollama is an application for running large-language models locally on your computer. It gives you access to open-source LLMs that you can prompt directly with the command line or an endpoint.

To getting started with local LLMs:

Download and install Ollama: https://ollama.com/download
When prompted, install the ollama CLI
Download and run your first LLM: ollama run llama2
Send your first prompt: “What is the chief end of man?”

The response will be printed to the console.

Using the CLI is nice, but a better option is to create and send prompts with a scripting language. I'm going to use Python and OpenAI's chat completion API, since that a popular combination. For an example with JavaScript, see this documentation.

Create a new python file: touch completions.py
Install the openai package: pip3 install openai

Set up your OpenAI client:

# completions.py
from openai import OpenAI

client = OpenAI(
     base_url="http://localhost:11434", # ll43a looks like llama
     api_key="ollama" # Unused but required
)

Create your first completion:

# This function is not required, but it's nice to have
def get_completion(prompt, model="llama2", temperature=0.0):
     messages = [{"role": "user", "content": prompt}]
     response = client.chat.completions.create(
         model=model,
         messages=messages,
         temperature=temperature,
     )
     return response.choices[0].message.content

response = get_completion("What is the chief end of man?")
print(response)

Run your script: python3 completions.py

That’s all it takes! For a good introduction to prompt writing, I recommend DeepLearning.AI’s ChatGPT Prompt Engineering for Developers course.

Adding a components page

Sean McPherson — Fri, 16 Feb 2024 15:24:00 GMT

In episode 696 of Syntax, hosts Scott Tolinski and Wes Bos discussed testing components when building websites and where fully-featured solutions like Storybook struggle:

Tolinski: People often feel like if I wanna test these things or look at them in isolation, I now have to bring in some other dependency. And that's the whole thing with Storybook: it's its own process. It’s a whole entire app that runs within your app.

They instead proposed a simple page where you dump all of the components that you’ve created. You can create individual scenarios for components that need it without the complexity of another dependency.

Bos: You can see them all at once, and you you're not playing whack-a-mole where you change one thing and you go, “Oh, shoot. That that broke it on this instance.”

Their components page is public, which has inspired me to create one of my own: seanmcp.com/internal/components

It’s fun to see all of the components that I’ve created for this site on a single page. And the pages combines nicely with a dev-only mock article to form a two-step testing process for making changes to this site.

I think /components pattern is a great solution for most sites, and I’m excited to use it the next time I redesign or rebuild.

Making a video game with my kids

Sean McPherson — Fri, 16 Feb 2024 14:05:00 GMT

Last Saturday, my five-year-old son asked me "Can we make our own video game?" He asks a lot of "Can we make out own…" questions, and the practical answer is usually no. But I felt uniquely qualified to help with this one, so I said "Sure!"

I turned to Kaboom.js, "a Javascript game programming library that helps you make games fast and fun." I had some previous experience playing around with it in 2019 and knew that it would be a good option for what he wanted to build. Between the Kaboom playground and the Kaboom template on Replit, it was really easy to get started building the game.

That said, we quickly outgrew online dev environments and wanted to move local. I created a new directory, npm inited, and then installed kaboom. I imported the library from an .html file, opened it with Live Server, and we were off to the races. With this setup, we worked on the game Saturday and after work a few days this week.

The big takeaway from one week of development is that making games is hard! Even a Mario-clone is a complex application with a lot of conditions to manage and interactions to handle. Kaboom makes it easy, but it still takes a lot of time to build. I wish there were more examples in the Kaboom documentation; I’ve found a lot of detailed but outdated tutorials online and it’s hard to sift through what still works and what depends on old APIs.

But more importantly, building the game has meant a lot of quality time with my kids. Although the project started with my older son and me, we where quickly joined by my three-year-old son. Both boys really enjoy working on the game together, even though most of the time is spent with me reading the documentation and debugging issues. But doing it with them on my lap is a wonderful experience. I’m looking forward to building more with them as they grow.

If you are interested in making a game with your kids or nieces/nephews or students, here are some recommendations:

Involve your kids as much as possible in designing the game: Let their imagination run wild, and then figure out how to make it a reality later. If they’re stuck, guide them through the brainstorming process, and have paper and pencils handy for their designs.
Make small, incremental, and visible changes: It can be really tempting when you’re working in a new library to refactor old code when you learn new things. But for the sake of the kids, make sure to have something different about the game that they can see after each session. And give them lots of chances to play the game during and after coding.
Use Kaboom’s types when you’re developing: Kaboom adds a ton of global functions, and it is challenging to learn what they are and how to use them. Thankfully, the library includes type definitions that help with this. A bundler like Vite would probably bring in those types automatically, but if you (like me) want to keep things simple you can import the types with a JSDoc @typedef comment like this:
```
/** @typedef { import("./node_modules/kaboom/dist/global") } */
import kaboom from "./node_modules/kaboom/dist/kaboom.mjs";
```

When the game is in a more finished state, I’ll be happy to share it. But in the meantime, I’m just going to enjoy the opportunity to use my talents to spend extra time with my sons.

A Few Things #4

Sean McPherson — Sat, 10 Feb 2024 10:55:00 GMT

Here are a few things that I found interesting this week:

What's inside this crater in Madagascar? by Vox
Vox teams up with local reporters to find out who is living inside a remote volcanic crater in a rural part of Madagascar. An interesting story that is well told.
Parkinson's Law (Wikipedia)
This week I was reminded of Parkinson's Law, which states that "work expands so as to fill the time available for its completion." The Wikipedia article has some interesting information, including corollaries and a formula. For a more practical explanation, checkout: What is Parkinson's Law?
FutureMe: Write a Letter to your Future Self
Multiple commenters on HackerNews mentioned using the service every year on their birthday. That seems like an interesting practice (especially since my birthday is coming up soon).
Shark Tracker by OCEARCH
In a similar vein to the lightning tracker from #2, here is a live world map of tagged sharks tagged by researchers. This will be fascinating or terrifying depending on your feelings about sharks.

A Few Things #3

Sean McPherson — Fri, 02 Feb 2024 20:02:00 GMT

Here are a few things that I found interesting this week:

Kintsugi – Art of Repair by Traditional Kyoto
I've been reading Art + Faith by Makoto Fujimura and learned about Kintsugi, the Japanese art of repairing broken ceramics with gold. The beauty for me, beyond the stunning contrast between earth and metal, is that the restored object is greater than the original.
Taste.io
There are other services that provide movie and TV recommendations, but Taste appears to be above average. The basic service is free, but they charge to view more recommendations.
drawing.garden by Ben Moren
Tend a small garden with emojis and pleasant tones. A relaxing... game? App? Experience? I'm not sure.
Elephants swimming by Katey B
My son asked me this week if elephants can swim. We both learned something that day.

Adobe has the worst captcha

Sean McPherson — Thu, 01 Feb 2024 16:45:00 GMT

I signed up for a Behance account today and needed to complete the worst captcha^[1] that I have ever experienced:

Adobe presents you with the image of a number and a picture of a pile of dice. You are required to find sum the dice and then compare it to the number. That is painful enough, but not out of bounds for captchas.

The worst part is that you are presented with 12 pictures of dice and you need to find the sum of every one. Doing that once would be annoying, but you are required to complete the task 10 times.

So in order verify that you are a human, Adobe requires that you find the sum of up to 120 pictures of dice. 120! Absurd.

(The audio captcha was similarly bad, but I didn't have the patience to work through all of the audio clips required for one step of the task. So save that review for later.)

I understand the need for captchas, but this is exceptionally bad. We need to find a better balance between security and user experience. Whatever the solution is, this is definitely not it.

Wikipedia uses CAPTCHA because it is an acronym, but I don't want to shout. ↩︎

A Few Things #2

Sean McPherson — Sat, 27 Jan 2024 02:30:00 GMT

Here are a few things that I found interesting this week:

Craft vs. Content: Resisting Mediocrity in a Dual-Existence Age by Brett and Kate McKay
The pressure to constantly share is powerful, and it has particularly impacted makers. "The modern writer, artist, or entrepreneur is not only tasked with promoting the final product of their efforts, but sharing inside looks of their art in progress, and even offering tips on how the average viewer at home can improve their own craft". Is there room for those who want to focus on their art and not the content around it?
How the NFL got so rich by Search Party
The NFL is one sport among many watched primarily in a country with many other popular sports. So why is it far and away the most profitable league in the world with the most valuable teams? In this video, Search Party answers this question by going back in time and comparing its development to European soccer leagues.
Lightning & Thunderstorms World Map by Blitzortung.org
Lightning is fascinating--beautify and deadly. This map shows lightning strikes and thunderstorms in real-time, and it is mesmerizing. As I write this, there are lightning storms in the Gulf of Mexico, the Middle East, and off the eastern coast of Australia.
The Presidential Ham by Bijijoo
Oil paintings of every US President holding ham. Very surreal. Not at all kosher. I'm looking forward to Biden's portrait.

Receiving cold-emails from GitHub stars

Sean McPherson — Fri, 26 Jan 2024 10:44:00 GMT

I’ve noticed a new trend where I receive cold-emails from maintainers after starring a repository on GitHub. All of the emails are explicit about it, following a pattern like this:

Hey Sean,

I hope you don’t mind I got your email when looking at your GitHub profile.

I noticed that you starred the PROJECT_NAME repo…

I like that GitHub stars are public; I’ve benefited a lot from being able to browse other users’ stars. And if someone notices that I starred their repo and wants to reach out, I don’t necessarily have a problem with that. But the emails I’ve received are marketing from maintainers of huge projects, and that feels fundamentally different.

GitHub stars are a mutually beneficial system. Individuals have a way to keep track of noteworthy projects and browser other lists for inspiration. Project maintainers get an indicator of popularity. And GitHub drives engagement on their platform. It’s a win-win-win.

The problem arises when one of the parties, the maintainers, try to gain an additional benefit at the expense of another, the individuals. At some level, it’s reasonable for maintainers to monitor their stargazers and reach out personally to notable users. But when projects with thousands of stars are using an automated system to watch and feed user details into a CRM, we’ve crossed a line. The “social contract” has been broken.

I don’t blame GitHub for this breech. I like that they provide an API with useful data. I blame the SaaS companies that are exploiting this system for profit, and the maintainers who subscribe to their service.

Open source is a mess, and funding projects a constant concern for many maintainers. I believe that the desire to engage with stargazers comes from a good place, either to build community or to market. But this is not the right way to do it.

A star is a bookmark; it's not a commitment. I haven’t even tried most of the projects that I star. By making assumptions about stars, maintainers run the risk of alienating potential users of your project. I for one will think twice before using the library that triggered the email above. And no one benefits from that.

So to prevent these emails in the future, I need to choose between 1) avoid using GitHub stars, or 2) remove the public email address from my profile. Of those options, I choose the latter (anyone who is really interested in reaching me can find my email address elsewhere). It’s sad that I have to do it, but that is the tragedy of the commons.

A Few Things #1

Sean McPherson — Fri, 19 Jan 2024 18:06:00 GMT

Here are a few things that I found interesting this week:

From-To by Franz Labs
From-To is an app that helps you understand a city that you're visiting by comparing it to a city that you already know. Later this year, my wife and I are planning a trip to Colorado Springs, but we've never been to Colorado before. Using From-To, I can compare Springs to our hometown of Pittsburgh to see what neighborhoods are similar. Definitely worth bookmarking for your next trip. (h/t Chris Coyier)
GovDocs to the Rescue! Debunking an Immigration Myth by Rosemary Meszaros and Katherine Pennavaria
Here in the United States, it is very common to hear that a family's name was changed at Ellis Island. But researchers Meszaros and Pennavaria have dispelled the myth by comparing government records before and after visiting Ellis Island. They found that these records "demonstrate conclusively that immigrants left Ellis Island with the same surnames they had arrived with." (h/t Morning Brew)
The glassmith tactic by Greg Gilbert
AI and Large Language Models will change content creation forever. Instead of competing with the machine, Gilbert suggests looking to artisans for inspiration. "The [glassblowers] didn't merely sell you a vase. No, they sold you a vase and a story."
Starcatcher by Escada Games
Starcatcher is a little browser based game where you play as an astronaut trying to collect stars on chunks of space debris. The trick is that gravity changes based on where you character is facing, which makes it a challenging and mind-bending experience.

Did OpenAI's Web Browser GPT leak its prompt?

Sean McPherson — Thu, 18 Jan 2024 18:25:00 GMT

I'm not an expert in LLMs or GPTs, but something about the interaction above feels wrong.

When prompted with a simple getting started question, OpenAI's official Web Browser GPT seems to have leaked some version of its prompt.

Here is the conversation transcribed:

Me: How do I get started?

Web Browser GPT: As a "Web Browser" GPT, your role is to assist users by leveraging web browsing capabilities to find and provide current, specific, or detailed information that isn't included in your pre-existing knowledge base. Here's how you can get started:

Understanding User Queries: Listen to the user's request carefully. Your users might ask for information on recent events, details about a specific topic, or even assistance in research that requires up-to-date or specialized information.

Using the Browser Tool: Utilize your browser tool to search the internet. This can be done by issuing search queries based on the user's question. You can view search results and select a number of relevant pages to read in detail.

Selecting Sources: Choose a diverse range of sources to ensure a balanced view. Prioritize trustworthy and reputable sources to maintain accuracy.

Extracting and Conveying Information: After reading through the selected pages, synthesize the information in a way that is easy to understand. Be sure to cite the sources of your information.

Staying Within Scope: Remember that your primary function is to browse the web for information. Avoid providing personal opinions or advice.

Privacy and Ethics: Always respect user privacy and avoid accessing or sharing sensitive, personal, or confidential information.

Continuous Learning: Although you don't learn from individual interactions, each query is an opportunity to refine your skills in searching, selecting, and summarizing information.

If a user asks a question, you should first determine if the answer lies within your existing knowledge. If it does, provide an answer as usual. If not, or if the question requires updated information, use your browsing tool to find and present the answer. Remember, your goal is to assist users by effectively finding and relaying information from the web.

Migrating from Google Domains to Porkbun was...

Sean McPherson — Thu, 18 Jan 2024 12:41:00 GMT

Painless. They charged a fee of around $11.00 US to transfer the domain and then handled the rest seamlessly.

I was hesitant to make the switch off of Google/Squarespace because I didn’t know how involved the process would be. I only had two domains on Google, but there was never a good time to encounter and address downtime issues during a transfer.

Thankfully, there weren’t any. I transferred a low-stakes domain first, and from start to finish it took around 15 minutes. It went so smoothly that I repeated the process with seanmcp.com with the same results.

Thank you Google Domains for providing a good service and for facilitating an easy transition. And thank you Porkbun for being a fun alternative. I look forward to many years of service from a dedicated registrar. 🐷

Normalizing data is a good idea

Sean McPherson — Wed, 20 Dec 2023 13:47:00 GMT

On this site I have a few different types of content: articles, notes, gardens, and now art. There are subtle differences in the data structure for each content type which come to a head whenever I try to combine them into a single list.

Previously, I merged all of the content into a single array and then had a bunch of conditions when rendering for each type:

[...articles, ...notes, ...gardens, ...art].map((item) => {
  return (
    <article>
      <h2>
        <a
          href={`/${item.collection}${
            item.collection === "art" ? `#${item.data.title}` : `/${item.slug}`
          }`}
        >
          {item.data.title || `Note #${item.slug}`}
        </a>
      </h2>
      <time>{item.data.pubDate || item.data.tendedDates[0]}</time>
      {item.data.description && <p>{item.data.description}</p>}
    </article>
  );
});

This works--the complexity needs to live somewhere. But adding new content types with this setup requires additional conditions that increase the cognitive load to work with this code.

An alternative to this is to normalize the data structure so that each content type can be handled in a similar way. Each type has its own normalization function, which helps reduce the complexity by addressing one content type at a time:

function normalizeNotes(notes) {
  return notes.map((note) => ({
    description: note.data.description,
    href: `/notes/${note.slug}`,
    title: `Note #${note.slug}`,
    pubData: note.data.pubDate,
  }));
}

Once all of the content is normalized, rendering is simpler:

[...normalArticles, ...normalNotes, ...normalGarden, ...normalArt].map(
  (item) => {
    return (
      <article>
        <h2>
          <a href={item.href}>{item.title}</a>
        </h2>
        <time>{item.pubDate}</time>
        {item.description && <p>{item.description}</p>}
      </article>
    );
  }
);

The next time I need to add a content type, all I do is write a normalization function and then slot it in alongside the existing content. That's scalability!

This is a personal example, but I think it illustrates the benefits of normalizing data.

Normalization functions contain all of the logic to transform data into a consistent structure. You can focus on one data type at a time, and convert it into whatever structure makes sense for the current problem.

Once normalized, you can work with your data in a regular way without worrying about conditional logic for each type. And down the road, it will be easier to troubleshoot and develop further when everything is consistent and logic is isolated.

Normalization is a good way to make your code more scalable and maintainable while also reducing cognitive load. So anytime you're working with multiple incoming data types, take the time to normalize them first.

How I'm using AI in November 2023

Sean McPherson — Mon, 11 Dec 2023 10:42:00 GMT

AI products/services that I used regularly (multiple times per week):

GitHub Copilot ⭐: Copilot continues to be a valuable resource when coding.
Chat GPT: I signed up for the paid version and spent a lot of time working with custom GPTs. Not sure that the service is worth the price, especially with rate limits, but I'm viewing it as professional development.
Khanmigo 📈: I now work on a AI-product that is powered by Khanmigo daily.

AI Products/services that I used occasionally (once per week or less):

Dall-E 📈: I played around with image generation in the context of custom GPTs.
Warp: I probably use this feature once a week to help with a command that I know exists but can’t remember.

AI products/services that I have access to but did not use:

Bard
Bing
Claude
Cursor 📉
MDN
Notion

Sli.dev review

Sean McPherson — Mon, 27 Nov 2023 13:55:00 GMT

I used sli.dev to create my slides for my recent talk at Pittsburgh TechFest 2023. I've previously used Google Slides--which is a great option--but I've been interested in finding a good tool for creating slides from Markdown.

There were two main motivations for this:

I want the content of the slides to be easier to edit and share.
I want to spend less time fiddling with the design of the slides and more time on the content.

The main reason to move away from Google Slides is productivity. I find it incredibly easy to sink tons of prep time into designing slides. It provides a perfect opportunity to procrastinate when I really need to be working on the content of the talk.

Pros

Design: The default designs are high-quality enough that I didn't feel the need to customize them to make it look nice.
Presenter mode: I think this worked better than Google Slides. The ability to edit content and comments from presenter mode was really useful when prepping.
Markdown: It was really nice to be able to "markup" my slides and comments with Markdown like bold, italics, and code blocks. That feels like that is pre-requisite for any dev slides now.
VS Code extension: I didn't use it much, but it was a nice option to have.

Cons

Formatting: I couldn't figure out how to get the VS Code formatter working correctly. If I accidentally hit the format shortcut (which is a reflex of mine), it broke all of the slides with frontmatter.
Slide images: Slidev has nice options for decorative images with layouts, but I couldn't figure out how to position content images correctly. A single centered image was fine, but if you wanted to have an image beside text then it was more difficult.

Conclusion

Overall I was happy with Slidev, and I think I will use it again for future slide decks.

I forgot about #divtober

Sean McPherson — Tue, 21 Nov 2023 10:36:00 GMT

On October 10th, I boldly claimed that completing #divtober was "my goal for this month." In the words of Maury, that was a lie.

I thought about whipping something up just for this article, but I'm not going to do that either. So here is an RSS Club article to let you, dear reader, down easy.

Maybe next year! (But don't quote me on that.)

Is it better to have one large file or multiple small files with GPTs?

Sean McPherson — Wed, 15 Nov 2023 14:46:00 GMT

tl;dr: Using a single file seems to reduce the likelihood of a knowledge-base loading and improve response times overall.

Introduction: Custom GPTs allow you to upload files that it will reference when answering questions. In my experience, the response time with these knowledge-base GPTs is really slow. That lead me to the question:

Is there a way to improve the response time by altering the number/length of files in the knowledge base?

I expected that the single large file would result in a faster response time than many smaller files, because loading an additional file will take longer than reading the same additional content from an already opened file.

Materials and methods: I uploaded the maximum number of files with dummy text to a GPT. One file contained a secret: the secret is: banana bread (file 6 of 10). I then asked the GPT “what is the secret?” and timed the response with a stopwatch. In between runs, I removed all of the files and added them back. I ran it again with single file of approximately equal length that contained the same secret text.

Results:

Many files (seconds)
1. 25.24†
2. 7.82
3. 33.81†
4. 5.96
5. 23.79†
6. 7.73
7. 14.19†
8. 7.76
9. 5.92
10. 8.75
Single file (seconds)
1. 6.92
2. 6.53
3. 7.10
4. 9.62
5. 11.78

† Indicates runs where the GPT indicated knowledge-base loading

Mean (seconds):

Many files (with loading): 14.97
Many files (without loading): 7.32
Single file: 8.39

Discussion: This experiment was pretty hacky! Using a stopwatch was not ideal, and it was difficult to decide when to stop with a streaming message. Response times may have varied significantly due to network connections or traffic on OpenAI’s servers. We shouldn’t take away any specifics from this experiment, but we might be able to draw some general insight.

Conclusion: When the GPT loads from its knowledge base, the response times were significantly slower. But when it didn’t, or at least didn’t indicated that it did, the results were similar between multiple files and single files. Based on this, my hypothesis was wrong. Generally, the response times did not vary significantly for multiple files vs a single file.

However, the data seem to show that using multiple files is more likely to trigger knowledge-base loading. And since that takes a long time, it is preferable to use fewer files to improve response time.

What is the file limit for GTPs?

Sean McPherson — Wed, 15 Nov 2023 13:23:00 GMT

As of 11/15/2023, the limit is 10 files.

Although you wouldn't know it if you tried to upload more. The UI lets you upload more than 10 files, but you get an unhelpful "draft failed to save" message.

If you inspect the network requests, you'll see a 🔴 400 to https://chat.openai.com/backend-api/gizmos with the following response:

{"detail":"Cannot upload more than 10 files"}

Hopefully OpenAI surfaces that error message in the UI soon. In the meantime: keep your file count to 10 or fewer.

How I'm using AI in October 2023

Sean McPherson — Tue, 14 Nov 2023 10:42:00 GMT

This feels like the breakthrough month. I moved to a new project at Khan Academy working on AI, and I found myself reaching for AI-powered tools more frequently throughout October. I can see a future where I use some of these daily.

AI products/services that I used regularly (multiple times per week):

GitHub Copilot ⭐: Copilot continues to be a valuable resource when coding.
Chat GPT 📈: I don’t know if the quality of the answers changed or I just had better questions to ask, but I found myself using it regularly this month.

AI Products/services that I used occasionally (once per week or less):

Cursor: A VS-Code-like editor with ChatGPT built in. I used it once while pairing with a coworker and it was neat.
Warp: Same as last update, I probably use this feature once a week to help with a command that I know exists but can’t remember.

AI products/services that I have access to but did not use:

Bard
Bing
Claude
Khanmigo
Dall-E
MDN
Notion

GPTs read text files better than markdown

Sean McPherson — Tue, 14 Nov 2023 10:23:00 GMT

tl;dr: Use text files instead of markdown with OpenAI’s custom GPTs

I conducted an experiment to see if the file type of uploaded content had an impact on how GPTs could read the information.

I created two files with the following content:

secret.md: the secret is: bananas foster
secret.txt: the secret is: banana split

Then I uploaded one file to a GPT and then asked the question: “What is the secret?”

With the markdown file, the GPT consistently had no clue what I was asking for and refused to or hallucinated an answer. I tried to help by providing some instructions to look at the uploaded file for the answer. My goal was to provide a kind of “table of contents” for the GPT to reference.

Here are some of the iterations:

"the secret" is in secret.md
"the secret" is in secret.md. Read that file before answering.
"the secret" is in secret.md. Load the contents of that file.
With other permutations

The only success with the markdown file was after selecting “Code interpreter”, where the GPT wrote (and ran?) a Python script to read and print the contents of secret.md. Pretty cool, but definitely not ideal.

With the text file, it just worked. I uploaded the file and with no instructions the GPT was able to supply the new secret.

Based on these results, it is better to use text files with custom GPTs as opposed to markdown.

Thoughts on Web Speech API

Sean McPherson — Thu, 09 Nov 2023 24:52:00 GMT

Last week I spent time working with the Web Speech API for a hackathon at Khan Academy. Here are some quick lessons learned from my experience:

Web Speech is a weird partnership between browser and OS. There are similarities across browsers on a single operating system, and across operating systems with a single browser. Make sure to test as many browser/OS combinations as you can.

Voice has a big impact on how text is read. I was experimenting a lot with math expressions, and I found some voices would read with correct math terminology while others would not. For example, on macOS the default voice (Samantha) reads 3x × 5 as “three times ex five” while Gordon reads it as “three ex times five”.

The default voice on Ubuntu was really bad. Most of the voices on ChromeOS, macOS, and Windows were fine, but Ubuntu was almost unintelligible. I didn’t play around with other voice options, but it might be a showstopper if you have a significant number of Linux users.

Sometimes speechSynthesis.getVoices() returns an empty array. I couldn’t find any official documentation about this, but some articles online suggest that the browser populates that list well after the initial page load. If you are trying to populate a select field with voice options, make the request for voices as late as possible.

speechSynthesis.speak() and speechSynthesis.cancel are unpredictably asynchronous. I think this goes back to the weird partnership between browser and OS, but calling speak() doesn’t happen immediately and cancel() can “swallow” subsequent speak() calls. I needed to use timeouts with a 100ms delay in a few areas to ensure that the utterance would speak when expected.

The Web Speech API is neat, but it has a lot of rough edges. It’s unlikely that a major user-facing feature would use it alone, especially with the rapid developments in AI text-to-speech. That said, Web Speech provides a solid foundation to progressively enhance with more power TTS solutions.

Declarative code and cognitive load

Sean McPherson — Wed, 25 Oct 2023 15:03:00 GMT

If you had asked me ten years ago about my ability to handle cognitive load, I would have said that I was above average. Today? I would say that I am pretty bad at holding multiple things in my head at once. Whether that is due to aging, fatherhood, multiple-bouts of COVID, humility, or any combination of those, I can’t say.

What I do know is that I am now very interested in reducing cognitive load so that I can do my best work.

In a recent issue of Frontend At Scale, Maxi Ferreira wrote about how declarative code can reduce cognitive load. Giving an example service for file uploading with user permissions, Ferreira proposes a simple list of maps for file extensions and permissions:

This [declarative code solution] doesn't simplify the relationship between our services in any way, but it does wonders for reducing cognitive load. We might still have some complicated logic between our different services, but now we don't need to concern ourselves with it. We can now declare our updated rules without having to load a bunch of information in our heads.

This feels like a significant insight and is a great solution to the example problem. You don’t need to know how the system works (at least, not at first), but you can quickly understand what the system does by looking at the validation rules.

Now I’m off to brainstorm about how declarative code could reduce some of the cognitive load in systems I’m working on at Khan Academy. Give the full article a look and let me know what you think.

Attempting #divtober 2023

Sean McPherson — Tue, 10 Oct 2023 13:17:00 GMT

In years past I have participated in Hacktoberfest. But I've found that the t-shirt recently it isn't worth the effort as a contributor (to speak nothing of the headache it is as a maintainer).

I'm used to doing something special in October, so my curiousity was piqued when I read about #divtober in Steph Eckles' Modern CSS newsletter. Instead of spamming a bunch of maintainers with trivial PRs, you get to spam a single div with a bunch of pseudo elements and box shadows. Neat!

So that's my goal for this month. Here is a some inspiration if you would like to join the party: https://a.singlediv.com

How I'm using AI in August & September 2023

Sean McPherson — Tue, 03 Oct 2023 21:22:00 GMT

Sorry for two months in one post, but I haven't been using AI much recently. I think the trend so far is that AI-powered products that are directly related to my work are more likely to stick around. All the others come and go more quickly.

AI products/services that I used regularly (multiple times per week):

GitHub Copilot ⭐: Copilot continues to be a valuable resource when coding.

AI Products/services that I used occasionally (once per week or less):

Warp 📈: I have used Warp's AI-powered command suggestion occasionally over the past two months. It's helpful when I'm looking for a git command or something similar but can't quite remember the flags or syntax.

AI products/services that I have access to but did not use:

Bard
Bing 📉
Khanmigo 📉
Dall-E
MDN 📉
Notion

See what object properties are accessed in JavaScript

Sean McPherson — Thu, 28 Sep 2023 10:30:00 GMT

At work I was mocking an object to be passed to a React context provider. I knew the type for the object, but I wanted to learn what properties were being accessed on the object from this point in the component tree.

Thankfully, JavaScript has a native way to "watch" an object and respond whenever any of its properties are accessed or reassigned: a Proxy.

First start with the object that you want to watch:

const user = {
  name: "",
  email: "",
  username: "",
  createdAt: "",
};

Then pass your object to the Proxy constructor along with a handler object that determines what you want to do you when a property is get or set:

const userProxy = new Proxy(user, {
  get(target, property) {
    console.log(`Getting ${property} on ${target}`);
    return target[property];
  },
  set(target, property, value) {
    console.log(`Setting ${property} on ${target} to ${value}`);
    target[property] = value;
    return true;
  },
});

Now you can use userProxy as if it were the original user object. I passed the proxy into the context provider and then watched then checked the console to see what properties for that object were accessed.

Nice and easy! Let me know if you have any other use cases for a proxy in JavaScript.

I'm not dead yet!

Sean McPherson — Mon, 25 Sep 2023 10:03:00 GMT

I found out at the end of August that I talk that I proposed for Pittsburgh TechFest 2023 had been accepted. This was excited, but there was a catch: I only had two weeks to prepare the presentation.

So I spent the first two weeks of September working on that talk to the detriment of everything else (sidebar: thank you wife Anne for accommodating that!). And thankfully the "two week deadline" for all presentation materials turned into three weeks, and I was able to get everything ready in time.

But that means that I am back and ready to start writing again. It felt fitting to return with an article for you, the RSS Club. I'm looking forward to sharing some of the details from my presentation and writing about other topics that I have been thinking about over the past few weeks.

See you soon!

Remove duplicates from an array in JavaScript

Sean McPherson — Fri, 25 Aug 2023 10:38:00 GMT

Removing duplicates, sometimes called de-duplicating or de-duping, is a common task in programming. There are many ways for removing duplicates from an array in JavaScript, and here I am going to share two scenarios and strategies.

Array of primitive values

In JavaScript, primitive values are the simplest form of data like strings and numbers. Let's say you have an array of strings:

const original = ["a", "b", "c", "b"];

We can de-duplicate this array by using it to create a set, a special object that only stores unique values. We'll pass it to the Set constructor, and then compare the two by looking at how many items they contain:

const original = ["a", "b", "c", "b"];
const set = new Set(original);

console.log(original.length + " vs " + set.size);
// "4 vs 3"

The final step is to convert this new set back into an array. We can do this with the Array.from method:

const original = ["a", "b", "c", "b"];
const set = new Set(original);
const deDuped = Array.from(set);

console.log(original); // ["a", "b", "c", "b"]
console.log(deDuped); // ["a", "b", "c"]

With that strategy, we could write a one-liner or create a helper function for reuse later:

const original = ["a", "b", "c", "b"];
const deDuped = Array.from(new Set(original));

const deDupePrimitiveArray = (arr) => Array.from(new Set(arr));
deDupePrimitiveArray(original); // ["a", "b", "c"]

I think this is a nice and modern solution to remove duplicates from simple arrays, but it will not work when you have an array of objects. For that, we'll need a different strategy.

Array of objects

In JavaScript, object-like values like objects and arrays need a different strategy for removing duplicates. Let's say you have an array of objects with a unique id property:

const original = [{ id: "a" }, { id: "b" }, { id: "c" }, { id: "b" }];

We can use this id to keep track of which objects we have already seen. There are multiple options to do this, but let's stick with sets since we used that in the last example. We'll create a new set to keep track of ids that we've already seen:

const original = [{ id: "a" }, { id: "b" }, { id: "c" }, { id: "b" }];
const seen = new Set();

Next, we filter the original array by checking if the current object's id is in the set. If it is, then we know that this object is a duplicate and can be filtered out:

const original = [{ id: "a" }, { id: "b" }, { id: "c" }, { id: "b" }];
const seen = new Set();

const deDuped = original.filter((current) => {
  if (seen.has(current.id)) {
    return false;
  }
  seen.add(current.id);
  return true;
});
// [{ id: "a" }, { id: "b" }, { id: "c" }]

We can't write a one-liner for this, but we can create a helper function. In addition to the array, we'll need to accept a function that maps an item in the array to the unique property that we'll use for comparison:

const original = [{ id: "a" }, { id: "b" }, { id: "c" }, { id: "b" }];

const deDupeObjectArray = (arr, mapper) => {
  const seen = new Set();

  return arr.filter((current) => {
    const key = mapper(current);
    if (seen.has(key)) {
      return false;
    }
    seen.add(key);
    return true;
  });
};

deDupeObjectArray(original, (item) => item.id);
// [{ id: "a" }, { id: "b" }, { id: "c" }]

Now that we have a mapper function, we can combine this with the previous strategy to create a single function that can de-dupe both primitive and object arrays.

Bringing it all together

To create a function that will remove duplicates from an array of primitive or object-like values, we can take the solution for object arrays and modify it slightly with a default mapper function:

const deDupe = (arr, mapper = (item) => item) => {
  const seen = new Set();

  return arr.filter((current) => {
    const key = mapper(current);
    if (seen.has(key)) {
      return false;
    }
    seen.add(key);
    return true;
  });
};

Now we can use this function to remove duplicates from primitive or object arrays:

console.log(deDupe(["a", "b", "c", "b"]));
// ["a", "b", "c"]
console.log(
  deDupe(
    [{ id: "a" }, { id: "b" }, { id: "c" }, { id: "b" }],
    (item) => item.id
  )
);
// [{ id: "a" }, { id: "b" }, { id: "c" }]

You can see all of the examples above in this REPL: https://replit.com/@SeanMcP/removing-duplicates-in-arrays#index.ts

Off to Kindergarten

Sean McPherson — Wed, 23 Aug 2023 10:59:00 GMT

Today is the first day of Kindergarten for my first-born son, Samuel. At 8:00pm this morning we'll drive him to school, and his 13+ year journey in education will begin.

I'm excited for this new chapter of his life, but I'm going to miss him a lot. Since the pandemic started in 2020 and I started working from home, I have had the privilege of seeing, talking to, and playing with Samuel almost every weekday.

I loved when he would stop by during the day and tell me a fact that he learned while reading, show me a picture that he drew, or share something he thought was funny. I loved eating lunch with him, getting random high-fives and hugs, and taking a tickle break during the day.

I'm thankful that my wife was able and willing to mother him full-time--we've both gotten to know him so well over the past 5 years. I'm thankful that I work from home and can be around for her and the kids throughout the day. I'm thankful that Samuel is off to a wonderful school that will both challenge and encourage him. I'm thankful for the one-on-one time that we will get with Ezra while his big brother is at school.

Life transitions like this can be hard for both parents and kids. I know I'm feeling the full range of emotions! So I'm going to try to hold them all gladly today: excited, nervous, proud, scared, optimistic, sad, hopeful.

Godspeed, Samuel. May the road rise to meet you. May the wind be ever at your back. May the sun shine warm on your face. May the rain fall gently on your fields. And until we meet again: may God hold you in the hollow of His hand.

1000 commits

Sean McPherson — Fri, 11 Aug 2023 10:50:00 GMT

Publishing this article will be the 1000th commit to my website repository. This makes it my most-active and side project by a large margin.

I created the repo in April of 2019 as the successor to a Gatsby site that was powered by Eleventy. That version continued until the fall of 2022 when I rewrote everything in Astro. Since then I’ve logged over a third of those 1000 commits; the pace of development is going strong.

Reflecting on the last four years of development, I can say that building this site has been a valuable use of my time. Working on this site has provided opportunities to:

practice skills
learn new techniques, and
explore new technologies.

Plus it’s rewarding to have created a valuable resource that helps thousands of visitors every month.

Here’s to the next 1000!

How I'm using AI in July 2023

Sean McPherson — Tue, 08 Aug 2023 10:47:00 GMT

AI products/services that I used regularly (multiple times per week):

GitHub Copilot ⭐: Copilot continues to be a valuable resource when coding. I was working on a script while offline, and I missed seeing it's suggestions.

AI Products/services that I used occasionally (once per week or less):

Bing Images & ChatGPT: I used these for a small project (creating a fantasy RPG to play with my kids), but it didn't end up going anywhere.
Khanmigo: Khan Academy has their own AI offering that I have access to through work. It's neat, but I'm not convinced how useful it is for the average user.
MDN: MDN launched a new AI-powered search feature that I tried a few times. The results weren't great: nothing for information that should have been easy to find, and some incorrect answers. But I can see potential in something like that.

AI products/services that I have access to but did not use:

Bard 📉
Bing 📉
Dall-E
Notion
Warp 📉

Timeboxing types

Sean McPherson — Wed, 02 Aug 2023 10:14:00 GMT

Two things that I currently believe:

There is a lot of value in statically typed code
Writing types is a potential time sink with diminishing returns

I don't feel like I need to justify the first belief. The trend in the front-end industry towards TypeScript illustrates that there is a growing consensus that types are a net positive.

That second belief probably needs more of a defense. I think there is a general maximum value for any given type, and the additional value derived from writing a type decrease over timer. Plotted on a chart, I think it looks something like this:

Despite this knowledge, my brain is still tempted to spend significant amounts of time writing the "perfect" type. I find myself giving away a lot of additional time while deriving little to no additional value. Chris Krycho, an engineer at LinkedIn, puts it this way:

Type systems very often do mash a puzzle-solving button in our brains. Figuring out how to get the types just right for a given design can lead an unwary developer (reader: I mean myself) into an hours-long maze. Getting out of one of those mazes with a good solution feels incredibly satisfying. But it is not always worth it.

The puzzle metaphor rings true for me. As with other puzzles, we want to spend the time to "solve" them. And as the types grow more complex, so too does the amount of time required for the "solution". I don't know if I can say exponentially, but that doesn't feel far off.

The reality is that a basic type written quickly will probably get you 90+% of the benefits of the "perfect" type. Chris continues:

A simpler type might be a little less precise, might catch a couple fewer errors, might make the system mildly less robust at runtime, might make it possible for there to be runtime bugs the system could in principle have ruled out entirely by clever use of the type system… and be 100% worth those tradeoffs given the context.

I think the solution to marry beliefs 1 and 2 is to timebox the amount of time that you spend writing any given type. Give yourself 5 minutes to write the best type that you can, and then move on.

If you can write the perfect type--"solve" that puzzle--then great! But if not, that's okay too. You surely have enough value in the type to justify the time you spent writing it.

This timeboxed writing should be in combination with an effort to master the type system you are using. As you grow in your understanding of the system, the quality of the types that you can write within your timebox will increase.

Is 5 minutes enough time? That depends. If you are new to the type system, you might need a little more time to write a valuable type. Or if you are dealing with a mission-critical type, it might be worthwhile to invest more time. If you are authoring a library that will be shared widely with the organization or world, then a more-perfect type will probably be worth the time (if only to save yourself future support work).

But for the average developer with some experience writing types, I think 5 minutes is a good starting point.

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

CSS columns are neat

Sean McPherson — Tue, 01 Aug 2023 11:18:00 GMT

I was looking for a solution to dynamically create two columns in a UI when I came across the columns CSS property. With a single property, you can tell the browser to split content evenly between n number of columns:

Two columns

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ornare augue placerat, malesuada nulla volutpat, pharetra arcu. Aenean consectetur diam in justo interdum, eu pharetra purus congue.

Sed cursus porta lorem, non posuere ex sagittis nec. Nam pulvinar rutrum condimentum. Proin sodales neque eget eros vulputate, vel hendrerit sem mollis. Sed quis faucibus quam.

Etiam at enim id quam posuere feugiat non posuere est. Donec dictum lacus posuere augue congue, ac tincidunt velit dignissim. Quisque hendrerit eros vel erat ornare porta.

Nunc viverra enim dui, sit amet dapibus lacus mollis vel. Donec vitae lorem sagittis, vulputate mauris a, posuere est. Nam nulla urna, laoreet in massa id, finibus tincidunt risus.

Aliquam quam massa, varius ac dolor ac, pharetra hendrerit eros. Suspendisse at facilisis leo, vel posuere dui. In hac habitasse platea dictumst. Proin congue euismod metus quis dictum.

Three columns

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ornare augue placerat, malesuada nulla volutpat, pharetra arcu. Aenean consectetur diam in justo interdum, eu pharetra purus congue.

Sed cursus porta lorem, non posuere ex sagittis nec. Nam pulvinar rutrum condimentum. Proin sodales neque eget eros vulputate, vel hendrerit sem mollis. Sed quis faucibus quam.

Etiam at enim id quam posuere feugiat non posuere est. Donec dictum lacus posuere augue congue, ac tincidunt velit dignissim. Quisque hendrerit eros vel erat ornare porta.

Nunc viverra enim dui, sit amet dapibus lacus mollis vel. Donec vitae lorem sagittis, vulputate mauris a, posuere est. Nam nulla urna, laoreet in massa id, finibus tincidunt risus.

Aliquam quam massa, varius ac dolor ac, pharetra hendrerit eros. Suspendisse at facilisis leo, vel posuere dui. In hac habitasse platea dictumst. Proin congue euismod metus quis dictum.

You can also set a certain width for the columns:

10ch width

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ornare augue placerat, malesuada nulla volutpat, pharetra arcu. Aenean consectetur diam in justo interdum, eu pharetra purus congue.

Sed cursus porta lorem, non posuere ex sagittis nec. Nam pulvinar rutrum condimentum. Proin sodales neque eget eros vulputate, vel hendrerit sem mollis. Sed quis faucibus quam.

Etiam at enim id quam posuere feugiat non posuere est. Donec dictum lacus posuere augue congue, ac tincidunt velit dignissim. Quisque hendrerit eros vel erat ornare porta.

Nunc viverra enim dui, sit amet dapibus lacus mollis vel. Donec vitae lorem sagittis, vulputate mauris a, posuere est. Nam nulla urna, laoreet in massa id, finibus tincidunt risus.

Aliquam quam massa, varius ac dolor ac, pharetra hendrerit eros. Suspendisse at facilisis leo, vel posuere dui. In hac habitasse platea dictumst. Proin congue euismod metus quis dictum.

I don't come across many use cases for this magazine-style layout, but it's nice to know that CSS has solution for it.

Quality requires iteration

Sean McPherson — Tue, 01 Aug 2023 10:57:00 GMT

You're not going to get it right the first time. You might not even get it right the second time. But if you iterate enough, you're going to find a good solution.

Too often I catch myself overanalyzing the first pass at a problem. I spend too much time thinking about how the whole system needs to work, or all of the edge cases that need to be addressed, and trying to plan the Perfect™ solution.

But it is never the case that plan A is the final solution. So why spend so much time agonizing over the first attempt?

Think about the problem that you need to solve, sure. Consider the edge cases that come to mind, definitely. Then move quickly on to building something.

Write a function once to figure out how it needs to work, and then write it again now that you know more.

Throw a bunch of messy components in a single file while you figure out what the UI requires and how you can compose them. Then refactor and move things into their own files (with individual stories and tests).

If you have time, iterate again... and maybe again. Each pass should get faster and more direct, because your knowledge of the problem is increasing the the picture of the solution is growing more clear.

Plan to make several attempts at the solution. Plan to delete what you've written. Plan for several rounds of code review. Plan to plan less up front and more as you go.

Quality in programming requires iterations. So lean into it.

A workable emoji picker on Ubuntu

Sean McPherson — Wed, 05 Jul 2023 11:25:00 GMT

I like to use emojis and have missed them since moving to Linux/Ubuntu. They render fine, but there isn’t a good way to input emojis into a field like on macOS and Windows.

Technically there is a native GNOME emoji picker, but it only works with “supported GTK 3 applications” and I don’t use any of those regularly. I tried installing a few third-party options, but none of them worked well.

I thought that I was resigned to not using emojis often on Linux, when one day I discovered suggested emojis in the Activities overview’s search results.

Here are the steps that work for me:

Press the super key (formerly Windows)
Type the name of the emoji: e.g. turtle
Select the emoji result from the Characters application to copy to clipboard

In addition to your mouse, you can use tab and the up/down arrow keys to navigate the options 🙌

Paste the emoji in your application

This process is not perfect: there are some emojis that are hard to find by name, and the lack of browsing makes discoverability a challenge. However, it’s definitely good enough for me for now.

It would be nice if all applications could use the GNOME emoji picker, but I’m too new here to know if that is even possible. A man can dream.

My first RSS Club oopsie

Sean McPherson — Tue, 04 Jul 2023 11:49:00 GMT

My latest article, Losing steam, was supposed to be an exclusive for the RSS Club. But I confused tags: RSS-ONLY with flags: RSS-ONLY in the frontmatter, and now it is published for the world to see: oops!

(Note to self: avoid data field names that rhyme)

I could fix it but that would break my feed, and I really like the idea of RSS as being the source of truth for my content. It is what it is!

So forgive my mistake, and enjoy the article. I look forward to hearing from anyone who has suggestions for writing prompts.

Losing steam

Sean McPherson — Tue, 04 Jul 2023 10:58:00 GMT

I set a goal earlier in the year to focus on writing more. And while I have already written 35 articles in 2023 (one fewer than all of 2022), I have found motivation waning in recent months.

Part of that is the regular ebb and flow of life, which is normal. I have other obligations outside of work/professional development that take my time and attention: parenting, home ownership, church responsibilities, and volunteer work. I don't want to be one-dimensional, so I'm happy to step away and work on other things.

But when I do set aside time to write, I have found recently that I don't have much to say. Some writers that I admire share their opinions on a current topic or trend in tech, and I value their contributions. But as time goes on, I find that my opinions are growing weaker not stronger. And I don't think that "A is neat, but B is also fine too" makes for a compelling read. So perhaps "columnist" is not in my future.

To help unblock myself, I created a new garden of writing prompts for programmers. These are cultivated for freewriting, an exercise where you write about a particular topic for a set amount of time. The goal isn't the output but rather the practice of getting started writing. It helps prime your brain for creative thinking, which I think is exactly what I need.

So the next time that I feel stuck or unmotivated to write, I'm going to try to sit down with one of those prompts for five minutes and see what happens.

Let me know what you think of the prompts, and be sure to email me any suggestions.

Reviewing "Go By Example"

Sean McPherson — Tue, 04 Jul 2023 10:51:00 GMT

I started Go By Example in April with the goal of learning the language for work. Khan Academy (and my old company Niche) use Go for their back-end services. And while I am focused on the front end, knowledge of the Go language is valuable for my work.

It took me 80 days from start to finish to complete the 79 examples. After a few starts and stops in the beginning, I settled into a routine of starting each day (barring Sunday) by working through an example. This felt like a good pace to learn the syntax and patterns slowly so that it sticks. And I think that it has, for the most part!

Overall, I enjoyed the exercises, and I would recommend Go By Example to anyone who is interested in learning the Go language. The examples were focused and clear, and the progression of concepts was logical. After completing the course, I feel confident reading and writing Go, and feel like I could contribute to an existing project.

One criticism of the course is that it does little to explain how Go projects work beyond simple scripts. I don’t have clear understanding of “packages” in Go which made it difficult to explore the language with side projects. There was an example on how to make a simple HTTP server but no details on how to deploy one.

To be fair, that wasn’t the point of the course. But if you’re looking for a more holistic introduction to Go, you might need to supplement Go By Example with something else.

So I’m looking for an additional resource to fill in some of those knowledge gaps. If you have any recommendations, please let me know. Otherwise, I’ll write again when I have found something that works well.

How I'm Using AI in June 2023

Sean McPherson — Fri, 23 Jun 2023 10:57:00 GMT

AI products/services that I used regularly (multiple times per week):

GitHub Copilot ⭐: Copilot continues to be a valuable resource when coding.

AI Products/services that I used occasionally (once per week or less):

Bard 📉: Although a rising star last month, I found that the quality of its answers seemed to decrease over the past month. That could be due to the types of questions I was asking (primarily Go coding questions) or changes under the hood.
Bing 📉: I use Edge as my daily browser and will occasionally send it a question, but it doesn’t play a big part in my workflow.
Warp 📉: Handy to look up a common command without leaving the terminal, but that isn’t something that I need to do regularly.

AI products/services that I have access to but did not use:

Bing Images
ChatGPT 📉
Dall-E
Notion

Looking for a new creative outlet

Sean McPherson — Mon, 05 Jun 2023 15:01:00 GMT

Since changing careers in 2017, programming has been by creative outlet. I enjoy coding in the early mornings before the rest of the family is awake, in the evenings when the kids are in bed, and on Saturdays when I have some downtime.

In general, I think this hobby interest in programming has been a help to my career as a software engineer. But occasionally my passion for it wanes, and it can have a negative impact on my drive at work. I don’t want my creative outlet and job to be too closely connected.

When I’m feeling disinterested in my creative outlet, my default is to go to consumption: watching YouTube videos and playing video games. And rarely do I feel good about my decisions after doing that for a long stretch of time.

So I’d like to find a new hobby for those times when programming is unappealing. Something simple that I can pick up and put down whenever. Preferably something offline and low tech. When I was a kid I was interested in drawing (my first career choice was an illustrator), so maybe that is a good option option to pursue. Plus it’s a good activity to do with little children.

I want to cultivate more opportunities to create as opposed to consume. Any suggestions?

A quick comparison of JavaScript and Go executables

Sean McPherson — Mon, 05 Jun 2023 11:34:00 GMT

Background: Bun and Deno, JavaScript runtimes, provide a native way to convert your JavaScript code into a single executable file.

Bun: bun build --compile my-script.js
Deno: deno compile my-script.js

To create these executables, Bun and Deno need to include their entire JS runtime in the executable file. That means all of Apple’s JavaScriptCore for Bun and Google’s V8 for Deno. But once that is compiles, the executables should work in any environment that those runtimes support.

I wanted to compare these new JavaScript options and Go to see if JS is a legitimate option for creating cross-environment executables.

Setup: I created a project for a simple command-line utility for reading package.json files from the terminal: github.com/seanmcp/rpj. Then I implemented the utility in all three environments: Bun, Deno, and Go. I have Bash scripts to create the executables and then compare the results by two metrics: file size and execution time.

The numbers:

File size

Bun: 97733752 bytes or 97.7 megabytes
Deno: 109968928 bytes or 110.0 megabytes
Go: 2607443 bytes or 2.6 megabytes

Go created the smallest executable (by a wide margin). I ran into issues with the Deno executable being rejected by GitHub for being too large, and Bun isn’t far behind.

Execution time

Bun: 0:00.04 real, 0.02 user, 0.01 sys
Deno: 0:00.04 real, 0.02 user, 0.01 sys
Go: 0:00.00 real, 0.00 user, 0.00 sys

The execution time was not a major factor in my example, and my hypothesis is that most of the difference is due to the startup cost of the JavaScript runtime. We would need more tests to determine how big the difference in execution time between these options.

Takeaway: Based on these results, Go is still the superior option for executables based on file size and execution time. However, Bun and Deno provided a great authoring experience for developers who are familiar with the JavaScript ecosystem. And the ability to use pre-existing tools and processes when creating executables might make Bun or Deno the best option for you and your team.

Personally, I’m excited to see how this feature of JavaScript runtimes develops over time.

Afterward: Node.js does have an experimental feature to create executables, but at the time of writing the steps were too involved. For open-source options for creating Node executables, checkout nexe and pkg.

I have never reviewed a podcast

Sean McPherson — Thu, 25 May 2023 11:27:00 GMT

I listen to podcasts a lot. When I’m working, cleaning, driving, or relaxing, there is a good chance that I have an earbud in and podcast playing.

PocketCasts is my app of choice, and according to their statistics I have listened for 61 days and 19 hours since 2016. I started listening to podcasts earlier than that, but that is two months worth of podcasts!

There are podcasts that I make sure to listen to every week. Multiple times a week. They cover my professional and personal interests, and a little bit of everything in between. When asked by a friend, I can usually come up with a good podcast recommendation.

Despite this, I have never reviewed a podcast. Not even once.

This might seem odd, since almost every podcast ends with the same plea:

Make sure to leave a review if you like the show

This is usually followed up with an explanation that reviews “really do help people discover the podcast.”

The problem is: I can’t review podcasts. Outside of work I don’t use Apple products (no reviews on iTunes/Apple Podcasts). I don’t listen on Spotify. PocketCasts doesn’t have a review system, and neither does Google Podcasts.

I love that podcasts are just RSS feeds. They're as decentralized as websites. But that creates a problem: there isn't a way to review an RSS feed. That responsibility lies with third-parties like Apple. But when you aren’t in the Apple-ecosystem, what are the alternatives?

The short answer is there aren't any--at least not any common ones. Some apps provide rating features, not not PocketCasts. There are some services for rating, discovering, and sharing podcasts, but they don’t seem particularly popular.

What can I do, then? I guess exactly what I have been doing. Listening regularly and sharing recommendations in real life. Complete interest surveys when they're advertised. But never leaving a review.

Compairing Objects, Maps, and WeakMaps for lookup tables in JavaScript

Sean McPherson — Mon, 22 May 2023 11:24:00 GMT

I use lookup tables/dictionaries/hashmaps/maps a lot when I’m coding. That’s a data structure that stores key and value pairs that are easily retrievable. Here is an example table for storing and looking up element names by their symbol written in Python that uses a dictionary:

periodic_table["H"] = "Hydrogen"

print(periodic_table["H"])
# Hydrogen

In JavaScript, we have three tools for this pattern—Objects, Maps, and WeakMaps—each with strengths and weaknesses.

Objects

Objects are the standard data type for dictionaries. They are so flexible that they are, in a way, the base prototype for all values in JavaScript. Entries are added and retrieved with dot or bracket notation, and then removed with the delete keyword:

// Declare
let periodicTable = {};

// Set
periodicTable.H = "Hydrogen"; // dot notation
periodicTable["He"] = "Helium"; // bracket notation

// Get
periodicTable.H; // "Hydrogen"
periodicTable["He"]; // "Helium"

// Delete
periodicTable.Li = "Lithium";
delete periodicTable.Li;

Object are not strictly iterable, but you can use for...in to access its keys or the global Object’s methods to get an iterable array: Object.keys(), Object.values(), and Object.entries().

for (let key in periodicTable) {
  console.log(key, periodicTable[key]);
}
// H Hydrogen
// He Helium

Object.keys(periodicTable); // ["H", "He"]
Object.values(periodicTable); // ["Hydrogen", "Helium"]
Object.entries(periodicTable); // [["H", "Hydrogen"], ["He", "Helium"]]

Objects will work as a data structure for every problem you encounter. So in some ways, it is the best of the three options for lookup tables. Some weaknesses of Objects are:

Prototype properties can conflict with keys in table
Key types limited to strings, numbers, and symbols
No guaranteed entry order

Maps

The Map object was added to JavaScript in ES2015 and provides a dedicated native solution for lookup tables. Entries are added, retrieved, and removed with dedicated methods:

// Declare
let periodicTable = new Map();

// Set
periodicTable.set("H", "Hydrogen");
periodicTable.set("He", "Helium");

// Get
periodicTable.get("H"); // "Hydrogen"
periodicTable.get("He"); // "Helium"

// Delete
periodicTable.set("Li", "Lithium");
periodicTable.delete("Li");

Maps are iterable so you can access all of the entries with a for...of loop (similar to Arrays). They also have a Map.forEach() method which provides the same data but (curiously) in the reverse order:

for (let entry of periodicTable) {
  console.log(entry);
}
// ["H", "Hydrogen"]
// ["He", "Helium"]

periodicTable.forEach((value, key) => {
  console.log(key, value);
});
// H Hydrogen
// He Helium

Maps also have Map.keys() and Map.values() methods that return iterators for keys and values, but the use cases for those might be rare. More common are the Map.has() method which returns a boolean of whether a key exists, and Map.size getter which returns the number of key/value pairs.

periodicTable.has("Li"); // false
periodicTable.size; // 2

Some other features that would take more time to illustrate:

Preserved entry order
More performant than objects for frequent additions and subtractions
Support any data structure for keys, including objects and functions (this makes them a good choice for implementing memoization)

It is for these methods/features that Maps really shine as data types of lookup tables. The main weaknesses for Maps are:

Not serializable

WeakMaps

WeakMaps were added to JavaScript along with Maps in ES2015. A noticeable difference between the two is that keys in WeakMaps must be objects. Entries are added, retrieved, and deleted with dedicated methods:

// Declare
let periodicTable = new WeakMap();

// Set
let H = { symbol: "H" };
periodicTable.set(H, "Hydrogen");

// Get
periodicTable.get(H); // "Hydrogen"

// Delete
let He = { symbol: "He" };
periodicTable.set(He, "Helium");
periodicTable.delete(He);

Note: There is nothing special about the { symbol: "" } syntax here. I’m just creating an object for each key that makes sense for the periodic-table example. You could use any object or object-like value for the key: {}, [], () => {}

Unlike Maps, WeakMaps are not iterable and there is no way to access its size. The only method provided is WeakMap.has() to receive a boolean of whether that key exists or not:

periodicTable.has("He"); // false

All of these differences are due to a shift in focus. WeakMaps are special in that they weakly reference the objects used as keys. This weak reference means that JavaScript can garbage collect those objects sooner, which will improve the memory performance of your application.

If you have a long-living lookup table, this memory-performance feature may be the perfect solution. Some weaknesses of WeakMaps are:

Limited key types
No iteration or access to keys/values list
Not serializable

Try it out

I created a REPL that includes all of the code examples above for you to explore: replit.com/@SeanMcP/JavaScript-lookup-tables

Conclusion

What is the best tool for implementing lookup tables in JavaScript? The answer will vary depending on your specific use case, but here are some general recommendations:

Map is (probably) the best: Between flexible key types, preserved order, easy iteration, and helpful methods, Maps have all of the features that you need for 90% of lookup tables that you will write in your code. Learning the syntax is a worthwhile investment over basic Objects.
Otherwise use an Object: That said, you could still implement every lookup table with an Object. One scenario where objects shine is for inline lookups:
```
function getElementName(symbol) {
  return {
    H: "Hydrogen",
    He: "Helium",
  }[symbol];
}
```
WeakMap for performance: If you are working in a situation where memory performance is important, then WeakMap’s weakly referenced keys will be helpful. There are other programming problems where WeakMaps shine, but we’re looking specifically for lookup tables.

Now that you know the different tools that JavaScript offers for dictionaries/hash maps/maps/lookup tables, you can choose the best solution in your context.

Web-browser Accessibility Tools

Sean McPherson — Fri, 19 May 2023 11:07:00 GMT

Khan Academy celebrates Global Accessibility Awareness Day with a whole week of activities. Yesterday on GAAD proper, we were encouraged to set aside our normal work and pick up some accessibility tasks from the backlog or do some a11y-focused professional development.

They also hosted four accessibility lightning talks, and I was happy to give one on a11y tools built into modern web browser. The talk consisted of quick tours through Chrome, Edge, Firefox, and Safari that highlighted some of their accessibility features.

I enjoy preparing presentations about the browser dev tools because it is a perfect excuse for me to learn more about the tools that I have at my disposal. Some of the cool new features that I learned about were:

Vision-deficiency emulators in Chrome (Rendering tab) and Firefox (Accessibility panel)
Interactive accessibility trees in Firefox (Accessibility panel) and Chrome (experimental - Inspect panel)
Targeted accessibility audits in Firefox (Accessibility panel) and Safari (Audit panel)
Visualized tab order in Firefox (Accessibility panel)
Automatic Axe scans in Edge (Issues tab)

The recording is private, but my outline for the talk is available at /talks/browser-a11y-tools/. I might re-record the talk for YouTube, so subscribe if you’re so inclined.

Overall, its encouraging to see all of the major browsers putting time and effort into creating tools to help developers built accessible applications. Now we all just need to use them!

Linux Update in 2023

Sean McPherson — Tue, 16 May 2023 12:49:00 GMT

Last year I experimented with using a Raspberry Pi as a home development environment. The device was ultimately too low powered, but my interest was piqued. Linux has improved a lot since my last experiments with it in the early 2010s.

Encouraged by that experience and a coworker who uses Linux at work and home or development, I decided to try again with a more powerful device. I considered buying a new laptop—Pinebook and System76 look promising—but I opted instead for a Lenovo Yoga from 2017 that we had lying around. It has an Intel i5, 128GB SSD, and 4GB of RAM which felt sufficient. Plus, it feels good to give new life to an old device.

After some internal debate, I ended up installing Ubuntu. There are probably distros that would have been better for an older device with simpler specs, but bog standard should be good enough for me. I didn’t have any issues with drivers this time (🙌), and the only feature that I lost was the fingerprint reader. Overall, the experience of installing Linux on the laptop was great.

Outside of work, I’ve been using this Linux laptop almost exclusively for the past month. It runs well, the battery life is decent (Power Mode helps a lot), and Ubuntu has been a great development environment. I work mostly in the JavaScript world, and the computer is able to handle some resource-intensive Node.js processes. I’ve also been learning Go, and all of that runs without the fan.

I’ve installed Microsoft Edge for browsing and VS Code for editing, but outside of that I’m trying to keep things lean. I know that 128GB will fill up fast, so I’m trying to limit installs to only the essentials. To date, that hasn’t been a limiting factor: turns out your don’t need much to write web apps and Go scripts!

In summary, I’m happy with my current set up. The experimenting with Linux in 2022 helped prepare me to use it as my daily driver in 2023.

Suffering from recipe-blog syndrome

Sean McPherson — Mon, 15 May 2023 10:50:00 GMT

Recipe blogs infamously include a lot of text before the recipe. This apparently helps with SEO, and search-engine traffic is critical for sites trying to make a profit online. But these long introductions are frustrating to the reader.

Average reader: (scrolling furiously) I don't need to know your life story with this recipe; I just want to know how to make blueberry muffins!

While I don't feel the need to overshare personal details when I'm writing, I do feel the pull to include long introductions to my articles. It's like I'm trying to justify to the reader why this article was worth writing.

But they don't care! Almost all of my traffic comes from search engines. My users obviously think the article was worth writing: they clicked on it! I don't need to waste their time and mine with a introduction explaining why this article should exist.

My advice to myself: don't qualify; just write.

How I'm using AI in May 2023

Sean McPherson — Sat, 13 May 2023 12:00:00 GMT

As of May 2023, I use the following AI-powered products on at least a weekly basis:

GitHub Copilot ⭐
Writing code: typically this is autocomplete to the end of the line, but occasionally it generates small blocks of code. Rarely I use it to generate a Regex for a particular pattern, saving me a search, copy, and paste from StackOverflow.
ChatGPT
Conversations: the best for prompt engineering, it runs with a persona that you give it. I’ve found rubber-duck sessions with a “helpful coworker who asks insightful questions” to be really helpful.
Generating structured code: creates a list of ten objects that match a given structure.
Document drafting: I needed to write a charter for a church building committee and had no clue where to start. A few prompts to ChatGPT, and I had an outline and draft to follow.
Bing
Internet searches: if I have a question that would typically require more than one search, then I’ll ask Bing. It does a good job of answering with citations.
Summarizing content: given a URL, Bing does a good job of summarizing content from a web page. You can even ask for comprehension questions if you’re reading to learn.
Bard 📈
Coding questions: Bard gives the right balance of length and depth for questions I have about programming. It usually includes helpful code snippets.
Warp
Command suggestions: saves a lot of time searching for those common commands that you can never seem to remember, e.g. “how to undo the last commit?”

As of May 2023, I have access to but no interest in the following products:

Midjourney/Dall·E/Bing Images: I’ve seen some of the things they generate, and while some of it is cool none of it feels useful to me.
Notion: I don’t need an AI to write content for me.

Declaring variables in Go

Sean McPherson — Fri, 12 May 2023 16:00:00 GMT

There are three ways to declare variables in Go: var, :=, and const.

The var keyword is the standard method for declaring a variable. It can be used anywhere in your program, with a value or without:

var s1 string = "Hello"

func main() {
	var s2 = "World"
	var s3 string
	s3 += "!"
}

Variable declarations without a value require a type (s3 above), but types are otherwise optional.

Declare a variable with with var when you need a variable at the top-level of your program or want to initialize it with no value.

The short-declaration operator, :=, works like the var keyword for declaring variables with three differences: a) it can only be used within the scope of a function, b) it cannot initialize an empty variable, and c) it does not accept a type. Of the var examples above, only one could be replaced with a :=:

// s1 := "Hello" // Outside of function scope

func main() {
	s2 := "World"
	// s3 := // No empty variables
}

These may sounds like significant limitations, but most of your program will be written inside a function’s scope and rarely do variables need to be declared without a value. So the benefit of using := comes from letting Go infer the type of your variable so that you can focus on the code.

Declare a variable with := when you are working within a function with initial values.

The const keyword tells the compiler that the variable is a constant -- it will not be changed or reassigned. Like var it can be used anywhere in your program but can only be used with some types: boolean, float64, int, and string.

const PI float64 = 3.14159

If you try to use const with other types like a slice, then you will get a compiler error: (value of type []string) is not constant compiler(InvalidConstInit)

Declare a variable with const when you know that it will not change throughout your program.

I am new to learning and writing in Go, but in practice I almost exclusively use the declaration operator, :=, for declaring variables. But it’s useful to know the reasons when and why you should reach for var or const.

What is nullish in JavaScript?

Sean McPherson — Thu, 11 May 2023 16:00:00 GMT

Nullish-coalescing operator (?? or double question mark) is a handy tool that returns the right-hand operand when the left-hand is nullish. In JavaScript, nullish is defined as null or undefined.

I enjoy using the nullish coalescing operator in my code, especially combined with optional chaining:

const name = response?.user?.name ?? "Anonymous";

This code will return the user's name if user and name exist on the response variable, or fallback to "Anonymous" if not.

However, I tend to get nullish confused with falsy in JavaScript. And while there is some overlap, it is important to know and remember the difference between the two.

Common falsy values are null, undefined, 0, "", false, and NaN.

Nullish values are a subset of that at just null and undefined.

If you try to use the nullish-coalescing operator with a falsy value, it will return the left-hand operand:

false ?? "fallback"; // false

To state it one more time, nullish in JavaScript is null or undefined. All other values, even if they are falsy, are excluded. So reach for nullish coalescing only when dealing with null or undefined. Otherwise use logical OR (||) or a ternary operator (? :).

QA questions for everyone to ask

Sean McPherson — Wed, 10 May 2023 18:04:00 GMT

My former colleague Michael Scotto recently wrote about quality assurance and asking questions:

Many use phrases like “QA Engineer” and “Tester” interchangeably. It’s convenient to do so, and generally innocuous — but this is narrow thinking. To think of Quality Assurance as “testing” is reductive; it puts a governor on the value-add of your QA team.

Testing is a skill, not a job. Instead, think of QA as the art of asking unasked questions. Testing is only one way to do this. It’s a coincidence that “QA” could also represent “Question Asker”, but it’s a meaningful coincidence.

He lists three types of questions to ask:

Verification: Does X do Y?
Discovery: What happens if…?
Criticism: Does this make sense?

I really like this breakdown, and he includes more examples in the article. It illustrates the reality that assuring quality transcends any functional team: everyone is responsible, because everyone can and should be asking these types of questions.

As an engineer, I should to be asking verification questions throughout the development process. I’ll probably codify those questions by writing unit and end-to-end tests. Answering these questions should be the baseline before handing the work off to another team member.

But I should also be asking discovery questions to surface edge cases that need to be addressed. Some of those are apparent when writing the code, “Oo, we aren’t handling this state case”, but other times it’s based on user interaction. I need to play around a bit and look for those pitfalls.

And all the while I should ask critical questions: does this implementation make sense? Will it meet the needs of our users? What about folks on low-powered devices or those with disabilities? If the answer to those questions are unsatisfactory, then I might need to work out a different solution.

Personally, I find asking verification and criticism questions easy; it’s discovery questions that I often overlook. This article was a good framework for thinking about quality assurance and reminder that I need to play my part in the process as well.

Learning Go

Sean McPherson — Tue, 09 May 2023 10:44:00 GMT

Niche and Khan Academy use Go for their backend services, so I've been "reading" Go since 2019. But as I progress in my career, I'm realizing that it would be useful to understand Go at a deeper level, and even write some Go code when the need arises.

For the past few weeks I've been going through Go by Example, a "hands-on introduction to Go using annotated example programs", and logging my progress here: seanmcp/go-by-example.

So far, I am enjoying the experience. Go by Example is well designed: the examples are clear and the concepts build upon each other well. And the development environment setup for Go is straightforward:

install Go,
write .go files in your editor of choice, and
run programs from the command line.

I've been using VS Code with the official Go extension, and it's been great -- even on an older laptop.

My favorite features so far:

The built-in formatter: it's nice to not have to think about how your code should be formatted.
Generating executables: I've played around with Deno's compiler for this, but Go's feels more mature.
Simple syntax: you don't need to remember a lot of syntax to write Go code.

My not-so-favorites:

Conventions are too terse: you can name things whatever you want, but reading through examples with 1-3 letter variables gets old. timer.C is not explicit.
The name Go: it's too common a word for a programming language, which makes searching online for challenging. Using "golang" tends to work, but even the title of this article might confuse people.

The negatives aside, I'm looking forward to continuing this journey. If you have any recommendations or resources, please let me know!

Set up Decap CMS

Sean McPherson — Wed, 19 Apr 2023 01:02:00 GMT

Decap CMS is the official successor to Netlify CMS and works well with the old tooling. Here are the steps to get up and running with Decap.

Step-by-step:

Add a new page route for /admin

For me, this was src/pages/admin.astro

Copy and paste the markup from the documentation
Add a config.yml file to your public directory
Run netlify-cms-proxy-server alongside your dev server:
```
npx netlify-cms-proxy-server
```
Access the content manager at localhost:XXXX/admin/

Issues: Decap CMS still hasn't fixed the jumping cursor issue when inserting within a textarea. It makes writing content incredibly frustrating. Thankfully, there is a fix that requires some additional CSS (of all things):

<!-- admin.html -->
<style>
  [data-slate-editor] {
    /* See https://github.com/netlify/netlify-cms/issues/5092 */
    -webkit-user-modify: read-write !important;
  }
</style>

With those style loaded, the issue is resolved.

Takeaways: Decap CMS is easy to set up and works well with all of Netlify CMS' old tooling. It's nice to hear that the project will live on with new maintainers, but it remains to be seen how invested they will be in development like fixing old bugs.

Zed is a rocket-powered skateboard

Sean McPherson — Sat, 01 Apr 2023 10:32:00 GMT

Zed is a new Rust-powered editor by the creator of Atom that focuses on speed but lacks a lot of features.

My experience: I downloaded Zed after hearing the creator talk about it on the Changelog podcast. And my first impression was that it just feels fast. Opening the application, navigating projects, and editing files are all zippy. The integrated terminal does the job without fanfare.

The numbers: Zed compares itself favorably to Sublime Text, VS Code, and CLion in three metrics on its homepage, but I found Sublime to have a significantly smaller install size:

Sublime Text – 126MB
Zed – 312MB
VS Code – 526MB

Trade-offs: Zed is missing a lot of features that I expect from a modern editor.

The editor is missing autocomplete, block moving shortcuts, and does silly things like matching quotation marks in comments.
The search is missing find and replace, filtering by path or filetype, and collapsing/removing results.

As a result, my rate of development was noticeably slower in Zed than in VS Code.

Takeaway: Zed is a fast editor in the same vein as Sublime Text and is a good option for a lightweight second editor. But for modern front-end development, Zed lacks the features to be your daily driver.

There are a number of interesting collaboration features that I haven’t tested. I didn’t want to ask a coworker to download Zed when I knew the editor was lacking.

Zed has a solid foundation that may enable it to outpace other editors in the future – but it’s not there yet.

Read more:

Changes to the RSS Club

Sean McPherson — Thu, 30 Mar 2023 20:31:00 GMT

Last month I created this RSS Club for special articles shared exclusively with my RSS subscribers. The idea came from Dave Rupert, but I differed from his pattern by omitting articles entirely from my website. I said at the time:

If you want to read that content, the only way to do so is with an RSS reader.

That decision was a mistake, so I’m going to make some changes. It remains true that the only way to find an article for the RSS Club is with an RSS reader, but I made some changes internally to create pages for them. That way you can bookmark an interesting article, and/or share it with someone else.

My current plan is to send articles to the RSS Club monthly. Will they all be RSS-related? That remains to be seen 😅, but stay tuned for more.

In the meantime, I’d love to hear from you: what is your RSS reader of choice and what do you like about it? Let me know by email: sean@seanmcp.com

If I get some interesting responses, I’ll include them in a future article.

Fix failed Fastify deploy on Render

Sean McPherson — Tue, 28 Mar 2023 21:01:00 GMT

To get a boilerplate Fastify app to deploy on Render.com, you need to read to listen on PORT environment variable.

Background: When trying to deploy a basic Fastify app to Render.com, I received a generic failure method: Deploy failed for COMMIT_HASH. The log indicated that the server started correctly, and there was no information indicating why the deploy failed.

The fix: I couldn’t find docs for running Fastify on Render.com, but there are example repos for other languages and libraries. The Render example for Express included a reference to process.env.PORT. By adding that to my Fastify app, I was able to successfully deploy.

Copy and paste:

const port = process.env.PORT || 8080;

const server = fastify();

server.listen({ port }, () => "Hello world!");

If you’re using TypeScript, you will have to convert the environment variable to a number:

// TypeScript
const port = process.env.PORT ? parseInt(process.env.PORT) : 8080;

Read more:

Find and replace with Regex groups

Sean McPherson — Tue, 14 Mar 2023 10:50:00 GMT

Create Regex groups with parentheses for powerful find/replace patterns.

Setup: I have a markdown file with a lot of shorthand links to GitHub PRs, e.g. user/repo#1, that I wanted to be replaced with full URLs: https://github.com/user/repo/issues/1.

These steps are for VS Code, but you can do a Regex find/replace in any environment.

Step by step:

Open the search panel in VS Code
Turn on Regex searches with the .* toggle
Search with the following Regex pattern: ([\w-]+)/(.+)#(\d+)

This looks for any text that matches the pattern of:
- ([\w-]+) a word containing one more alphanumeric or hyphen characters,
- / a forward slash,
- (.+) one or more of any character,
- # a pound sign, and
- (\d+) one or more digits
It creates three groups (identified by the parentheses)

Replace the matched text with the following pattern: https://github.com/$1/$2/issues/$3

Try it out:

https://regexr.com/7a3kb

Tradeoffs: The regex pattern above will only match for alphanumeric GitHub usernames with optional hyphens. I don’t know the official pattern used to validate usernames, so your data might include some that don’t match.

Fix SVG CSS animation issue in Safari

Sean McPherson — Fri, 10 Mar 2023 10:45:00 GMT

Safari 16 has trouble with CSS animations on SVG child elements, but you can resolve them by using a combined transform property.

Setup: You have an SVG that needs separate animations for its path and rect elements. Applying a single transform to the elements works, but combining multiple transforms results in nondeterministic animation bugs:

@keyframes worksInSafari {
  from {
    scale: 0;
  }
  to {
    scale: 1;
  }
}

@keyframes brokenInSafari {
  from {
    rotate: 0deg;
    scale: 0;
  }
  to {
    rotate: 20deg;
    scale: 1;
  }
}

The fix: You can fix this by combining your transformations into multiple functions on a single transform property:

@keyframes fixedInSafari {
  from {
    transform: rotate(0deg) scale(0);
  }
  to {
    transform: rotate(20deg) scale(1);
  }
}

Try it out:

See the Pen Safari CSS animation SVG bug by Sean McPherson (@SeanMcP) on CodePen.

Takeaway: Individual properties for CSS transforms are nice, but they can cause issues with SVG animations in Safari. The safer option seems to be sticking with a single transform property for now.

Read more:

Listen for class change in JavaScript

Sean McPherson — Thu, 09 Mar 2023 11:00:00 GMT

There isn’t an event for class list changes, but you can write a function that listens for class changes on an element with the MutationObserver API.

Copy & paste:

function onClassChange(node, callback) {
  let lastClassString = node.classList.toString();

  const mutationObserver = new MutationObserver((mutationList) => {
    for (const item of mutationList) {
      if (item.attributeName === "class") {
        const classString = node.classList.toString();
        if (classString !== lastClassString) {
          callback(mutationObserver);
          lastClassString = classString;
          break;
        }
      }
    }
  });

  mutationObserver.observe(node, { attributes: true });

  return mutationObserver;
}

Step by step:

The function accepts two parameters: a reference to a DOM node to watch and the callback to execute when the class has changed.
Within the function, we store a reference to the class list as a string that we will use for comparison later.
Create a new MutationObserver instance with a callback that listens for class changes.
1. Inside that callback, we loop through the mutation list and look for any changes to the class attribute.
2. If we find one, then we compare the current class list as a string to the reference declared above.
- This comparison is necessary to prevent false class change positives, e.g adding the same class twice.
1. If the class strings do not match, invoke the callback and update the class string reference.
2. Break out of the loop if we have detected a change.
Observe the passed node with the new mutation observer instance and configure it to fire on attribute changes.
Return the mutation observer for later clean up

Try it out:

See the Pen Function to listen for class change by Sean McPherson (@SeanMcP) on CodePen.

Takeaway: It would be nice if there was a standard method for listening to class changes, but it is nice to know that you can write your own with a MutationObserver.

Read more:

Reviewing my Netlify Analytics

Sean McPherson — Wed, 08 Mar 2023 10:53:00 GMT

Thanks to Netlify Analytics I know to focus on writing how-to articles, but it has less data than I hoped.

Some context: Netlify provides analytics information for $9 per month per site. They offer data from server requests including page views, unique visitors, top locations, and sources.

The data varies greatly from client-side options like Google Analytics

The numbers:

My site received 38,000 page views from 13,000 unique visitors in the last 30 days
The top location was the United States, followed distantly by Germany, France, and China
The most popular page was a tool for looking up words by consonant-vowel patterns
The most popular content were how-to articles

Trade-offs: Netlify Analytics was easy to set up with an existing project — just one click after adding payment information. But it lacks comprehensive data for informed decision making.

I want to know how all of my pages are performing, but Netlify’s dashboard limits you to 15 results.
The inclusion of bot traffic add uncertainty to the numbers.

Takeaway: People are visiting this site for guides on completing a particular task. These are broken down into two categories: tutorials and debugging.

In order to create value for my readers, I’m going to focus this area
I expect more for $9/month and probably won’t continue the subscription

Read more:

Create Axios-style articles with CSS

Sean McPherson — Mon, 06 Mar 2023 18:52:00 GMT

You can style heading elements to look like the axioms in Axios articles with CSS.

Step by step:

Start with the following HTML markup for this example:

<article>
  <p>Paragraph 1</p>
  <h2>Why it matters</h2>
  <p>Paragraph 2 should be inline with the heading</p>
</article>

Turning over to CSS, add stack styles the container element:
```
article * + * {
  margin-block-start: 1.5rem;
}
```
This positions all of our block elements within an article with a consistent gap.
Move the h2 and following p elements onto the same line:
```
article h2,
article h2 + p {
  display: inline-block;
}
```
This positions those element correctly, but creates a problem. The block start margin of the h2 element isn’t collapsing with the block end margin of the first paragraph.
Remove block end margins for everything within our article:
```
article * {
  margin-block-end: 0;
}
```
Add a colon using a pseudo-element:
```
article h2::after {
  content: ":";
}
```

With those styles in place, we have a semantic and accessible Axios article.

Try it out:

See the Pen Axios-style articles with h2 headings by Sean McPherson (@SeanMcP) on CodePen.

Takeaway: This solution is better than Axios’ markup because it uses the heading hierarchy. They use strong elements which aren’t navigable by screenreaders.

CSS :empty pseudo class

Sean McPherson — Thu, 02 Mar 2023 11:08:00 GMT

:empty allows you to apply styles to an element when it has no child nodes
This is useful for hiding empty elements to keep visual grids consistent
It is supported in all major browsers

When building a user interface, it is common to have a container element that conditionally contains content. A simple example is an element that displays error information when a form field is invalid. To accomplish this, you have two options:

Always render the container in the DOM and conditionally add children (e.g. text, other nodes)
Conditionally render the container when needed.

There are use cases for both approaches. When working with vanilla JavaScript, I typically reach for the former. If I were building the interface with a front-end library, then I use the later.

A problem that arises with option 1 is spacing in between elements. If you are using flex box or grid with a gap the empty element will be included in the layout and will result in a double space between visible elements.

See the Pen Removing extra flex/grid spacing with :empty by Sean McPherson (@SeanMcP) on CodePen.

The solution is to use the :empty pseudo class to select the empty element and hide it with display: none. Once the element is removed from the flex/grid, the gap between elements are consistent.

It is worth noting that the double spacing is not an issue with patterns like Every Layout’s stack, which uses the browser's collapsing margins. But if you are using flexbox or grid, then the problem will eventually arise.

Fix trailing whitespace in Astro components

Sean McPherson — Thu, 02 Mar 2023 10:59:00 GMT

A closed issue on GitHub appears to still be occurring
Forcing your code onto a single line is a workaround

When your Astro code is formatted onto multiple lines, the resulting markup from the Astro compiler includes a whitespace. This is noticeable when you have a list of links that are underlined:

<a> Link 1 </a> <a> Link 2 </a>

Result: Link 1 Link 2

But if the markup is on a single line, then the issue goes away:

<a>Link 1</a> <a>Link 2</a>

Result: Link 1 Link 2

I have faked the output for this article, but you can see a live reproduction of this behavior on StackBlitz.

To workaround this issue, you need force your markup onto a single line. Let’s look at a real-world example element with multiple attributes. Your code formatter will spread it over multiple lines:

{items.map(item => {
  return (
    <a
      aria-current={Astro.url.pathname === item.url ? "page" : null}
      href={item.url}
    >
      {item.label}
    </a>
  )
})

To force this code onto a single line, we need to refactor. Create variables to represent attributes and children with short names, and then pass them to the element:

{items.map(item => {
  const a = {
    'aria-current': Astro.url.pathname === item.url ? "page" : null,
    href: item.url
  }
  const c = item.label
  return <a {...a}>{c}</a>
})

This code is objectively worse (and might create a TypeScript warning that you need to ignore), but it will fix the whitespace issue. Hopefully the Astro team can fix the issue in the compiler and make this workaround unnecessary.

Farewell Create React App

Sean McPherson — Tue, 28 Feb 2023 15:03:00 GMT

The React team is looking to sunset “Create React App” as a project scaffold
They are leaning towards turning it into a “launcher” which would suggest a list of recommended frameworks
This is part of a greater shift away from client-side rendered applications

I learned React while attending a coding bootcamp in 2017. With the help of Create React App, I was able to learn the syntax and features of the library without needing to understand Webpack or Babel. It was a valuable tool for learning React, and I’m thankful that it existed.

Today I rarely spin up new React applications – even for pet projects. But if I did, I would use Vite instead of CRA. The ecosystem for front-end project scaffolds has changed significantly in the last six years, and CRA hasn’t kept up with the times. I think that it makes sense for the React team to move on from it and let the community solutions and frameworks pick up the slack.

The discussion also mentions that server-side rendering and static-site generation are two critical areas of front-end development going forward. The use cases for client-side rendered apps are limited, and the weaknesses are now well documented. Instead of the React team having one official approach (CRA) and a bunch of official ones (Next, Astro, Vite, etc.) for using the library, they want to be more agnostic. This is a good move for the health of the web.

Thank you for your service, Create React App. Enjoy retirement.

Starting an RSS Club

Sean McPherson — Tue, 28 Feb 2023 14:42:00 GMT

I added the ability to publish articles exclusively to the RSS feed. The idea for an RSS Club comes from Dave Rupert and friends.

To accomplish this, I added a new data field to the frontmatter of articles for flags. This is an enumerated array of special conditions for each entry. With Astro collections and Zod, the configuration looks like this:

flags: z.array(z.enum(["DRAFT", "RSS-ONLY"])).optional(),

I had previously built in logic to handle drafts with a boolean in the frontmatter, but I wasn’t interested in adding another z.boolean().optional() to the configuration. Flags gives me a pattern to quickly add additional conditions for instances like this.

To publish an article for the RSS Club, I just add this line to its frontmatter:

flags:
  - RSS-ONLY

Dave’s RSS Club creates pages for entries online – the links are just hidden from site navigation. My implementation differs in that the articles only exist within the rss.xml file. If you want to read that content, the only way to do so is with an RSS reader.

Join the club by subscribing to https://seanmcp.com/rss.xml

Hello RSS Club!

Sean McPherson — Tue, 28 Feb 2023 11:10:00 GMT

This article is only visible to those who have subscribed to my site via RSS. So if you are reading this, then you are a member of the RSS Club!

My favorite thing about RSS is the autonomy that it gives you as a reader. You have the freedom to subscribe to content that interests you. That could be textual, like this blog, or images or audio. You choose the content, and then you choose how to consume it with an RSS Reader. It bypasses the vendor buy in of content platforms and puts you in the driver's seat.

These days I've been enjoying FeedBin for reading RSS feeds. The best features for me (though not unique to FeedBin) is piping newsletters into the reader. I had built up a few subscriptions in my inbox, but that never felt like the right platform for reading content. If your RSS reader has the option, I recommend it.

On closings

Sean McPherson — Mon, 27 Feb 2023 18:56:00 GMT

Update: I misused the term “salutation” in this article. What I meant was apparently "valedictions" or "closings". I've updated the article below to reflect this, but the permalink will remain the same.

I have historically ended all of my articles with a closing like “Happy coding!” or “Happy debugging!”. Recently I tried a Lewis-inspired “Onward and upward!” and the controversial “Up the web!”.

I picked up the practice back when I was blogging my way through coding bootcamp. I’m not sure where I picked it up; probably something that I noticed other writers doing as I tried to find my own style.

But on further reflection, I’m don’t think that a closing is necessary online. And the amount of time I have spent thinking of the best gerund to follow “Happy” is not negligible. Instead, I could better use that time refining the conclusion.

Going forward, once I have made my point I will end the article.

How long should it take to write an article?

Sean McPherson — Mon, 27 Feb 2023 15:37:00 GMT

How much time should it take before your writing can provide value? I’ve been meditating on this idea. Here are three truths to keep in tension:

I want to write articles that are valuable
I don’t want to waste my reader’s time
I don’t want to waste my time

A goal then could be to write articles that contain valuable information as quickly as possible without sacrificing quality.

When I have a five minute break at work or in the morning/evening, I want to be able to use that productively. Is it reasonable to write a valuable article in five minutes?

I don’t know the answer. But I think that it is a question worth exploring. Set a timer, and start writing. If it is valuable when the timer chimes, then publish. If not not, then hold off for the next five-minute interval.

If an article is hanging around for a long time, consider scrapping the idea. There might be gold there, but maybe it isn’t worth your time to try and find it. Leave that for the next person to discover.

My writing process in February 2023

Sean McPherson — Mon, 27 Feb 2023 15:22:00 GMT

Today my process for writing an article looks like this:

Get an idea
Add it to a Kanban board on Notion
Write/edit the article in a card
Run a script in my website repo to create a markdown file
Copy the contents from Notion into the created file
Update frontmatter, including description and tags
Commit and push
Netlify builds automatically

I would like to be able to write drafts and publish from one interface on desktop and mobile. To date, I haven’t found a good CMS solution.

I had Netlify CMS configured, but a jumping cursor bug made it annoying to use. I’m interested to see if Static CMS or Decap CMS, both successors, can address this and other usability issues. In the meantime, my choices are to refine my current workflow or look for alternatives.

Update 1: I originally misspelled February in the title and URL. Both have been rectified (sorry permalink fans).

Update 2: I have added two Bash aliases to improve the process:

alias blog="node ~/seanmcp/seanmcp.com/src/draft-script.mjs"
alias publish="(cd ~/seanmcp/seanmcp.com && git add src/content/articles public/images && git commit -m 'publish article' && git push)"

Learning about Smart Brevity for writing

Sean McPherson — Mon, 27 Feb 2023 14:23:00 GMT

I was introduced to the idea of Axios’ Smart Brevity on the How I Built This podcast. Based on the reality that people don’t read much, the idea is writing that presents information as clearly and concisely as possible. Axios has pushed this model successfully with 200-400 word news stories that liberally use bulleted lists.

This was attractive to me, in part, because I find writing to be struggle. I want to be a good writer, but I think my voice pales in comparison to the writers that I admire. Rather than trying to match their wit or charm, perhaps I could provide value by being direct and informative.

I followed the podcast episode by watching Jim VandeHei’s TEDx talk on Smart Brevity. Here some some key points (loosely quoted):

On data to support this approach:
Nobody reads anything
Humans are built to keep up with so much information
More often than not, people who share stories haven’t read them
Tips for writing better:
Stop being selfish: Writing is self-indulgent. We don’t think about the purpose. What does the reader need to know?
Grab me: What is the most important thing? What is the reason that you’re writing? What is the one thing that I need to remember?
Keep it simple: Shorter. Simple, strong words.
Be human: Write like a human. We’re think we’re Walt Whitman; we try to show off with our writing. If you’re talking to someone at a bar, you’re not going to use SAT words or use acronyms.
Just stop: The best thing you can do in this cluttered world is give people their time back. Use as few words, in as few sentences, as humanly possible.
In your own mind you’ll find yourself start to think more clearly and speak more clearly.

Valid JavaScript variable names

Sean McPherson — Sat, 25 Feb 2023 11:15:00 GMT

I’ve been working on a little library to help build little JavaScript applications. Something to fill the gap for me between little scripts and reaching for a framework like Svelte.

While designing the API, I’ve found myself searching for obscure but technically valid JS variable names to distinguish my library from the standard HTML element properties. Is @id valid? What about $id? Can I use a :?

These questions are easy to answer by opening the console, but wouldn’t it be nice to have a little tool to validate JavaScript variable names? Thankfully it already exists: Mathias Bynen’s JavaScript variable name validator.

With it you can quickly validate a variable while maintaining your flow. And if you’re curious as to why, he has an article explaining the specifications. While writing this, I noticed that the main site has a bunch of other little tools for you to checkout. (Pardon the name 🙊)

Up the web!

Burrito emoji

Sean McPherson — Wed, 22 Feb 2023 11:04:00 GMT

The burrito emoji, aka 🌯 aka :burrito:, means thank you. Why a burrito? In the words of a former colleague:

Would you rather hear someone say “thanks”, or someone give you a burrito?

His logic was unassailable!

Examples:

Sarah: Here’s that doc you were looking for: https://example.com/doc

Raul: 🌯

Eleanor: @Wilson 🌯 for the help in that meeting

🌯 for reading!

Migrating to IndieWeb.social

Sean McPherson — Thu, 16 Feb 2023 14:38:00 GMT

Today I migrated from fosstodon.org to indieweb.social. You can find me @seanmcp@indieweb.social. In the process, I found this guide by Josh Justice to be really helpful.

Why migrate? I initially migrated to Fosstodon from Mastodon.social because I wanted an instance that was more focused on technology. I dabble in open-source maintenance, so the FOSS part of Fosstodon was intriguing.

What I did not realize at the time is that FOSS is its own thing. There was tons of discussion about Linux distros and desktop environments that went way over my head. I’m a general fan in free and open-source software but not big enough.

I’m more interested in the indie-web scene than FOSS, so I’m thinking that the new instance will be a better fit. But we’ll see! The grass is always greener 🌱

Following account were migrated and links here have been updated. Come say hi!

Publishing a Qwik component

Sean McPherson — Mon, 13 Feb 2023 11:25:00 GMT

After hearing creator Miško Hevery on every front-end podcast that I listen to, I decided to give his new Qwik library a look. My canonical approach to learning a new library is creating a *-emoji component that wraps emojis with the appropriate HTML attributes for accessibility.

Using npm create qwik@latest, I was able to scaffold a Qwik component library quickly. Then it was a matter of writing the component using Qwik’s component$ function and exporting things in the right places.

To speak nothing of Qwik’s other features, it was a breeze writing my first component. It looks and feels just like React (thanks JSX!), and I only needed to reference the documentation one time to confirm how props worked. The project setup was great, and helped me identify some Qwik-specific TypeScript issues before I published the library.

Overall, publishing a Qwik component was a smooth and painless process. Kudos to the Qwik team for making it a great developer experience.

You can checkout my Qwik emoji library on npm, or install it yourself with:

npm i qwik-emoji

Onward!

Fix Astro dev server hanging with new collections API

Sean McPherson — Sat, 11 Feb 2023 17:08:00 GMT

This week I was in the process of upgrading this site to Astro v2 and its new features. Upgrading to version 2 went smoothly, but I encountered a frustrating problem adopting the new content collections API.

I repeatedly hit an issue where the Astro dev server will hang after calling getCollection from astro:content. The hardest part is that there are no errors in the browser or console – just an endless spinner when you try to load the page.

I though that maybe a solution was to manually clear Vite’s cache before restarting the dev server, which was as sophisticated as rm -rf node_modules/.vite. This may have resolved the issue a few times, but everything was so intermittent that I can’t say for sure.

On the Astro Discord, I posed a question to see if anyone else had encountered a similar issue. One of the devs linked to this issue on GitHub which described a similar scenario. The problem there is a page and its layout calling the same collection.

Looking back to my code, I couldn’t see where that was happening, but I decided to remove all the layout prop from the entries in that collection. (I wanted to do this anyway, since moving to content collections made a separate layout unnecessary.)

After those changes, the hanging dev server issue resolved itself. I’m glad to have found a fix, thought it would probably be good for Astro to recommend not using layouts for content collections.

Onward!

Site improvements in 2023

Sean McPherson — Tue, 07 Feb 2023 24:06:00 GMT

In 2023 I want to making this site better. Here is an unordered list of tasks that I would like to complete by the end of the year:

Adopt Astro content collections: I have two different systems for articles and notes, and it would be great to standardize with the new API.
Redesign with emphasis on personality: This will involve selecting and serving a font, which I have avoided up to this point.
Astro-less callouts and embeds: I want the reusability of components without needing to use MDX.
RSS-only articles: Seem like a fun feature (🤫 RSS Club)
Fix the trailing whitespace in my header links: I don’t know what the cause is — maybe something with how the Astro code is formatted?
Mastodon posts in the homepage: Probably a little component to load recent toots on the client.
Explore CMSs: I have Netlify CMS configured, but between its bugs and the lack of support I would like to find a better option.
FART-less dark mode: I’ve read a few different strategies for this, but I want to find the best option for this site.
Optimizations: I’d like to find a good/cheap solution for serving responsive images, and reduce any unnecessary network requests.

I’ll probably convert this list into GitHub issues like a good developer at some point in time. Until then!

Back from time off

Sean McPherson — Wed, 01 Feb 2023 17:47:00 GMT

I took the month of January off from coding. It was a good opportunity to decompress after work hours, explore new hobbies, and reflect on the future.

Looking forward to the rest of 2023, I want to focus on:

This site. I want to work on writing daily and publishing regularly instead of in bursts. I’m also hoping to redesign this year to give it more personality.
Existing projects. I have a few that are moderately successful, and I want to spend the year iterating on those. I would like to release a new version of Popsicle Sticks this Summer.

In order to focus on those, I need to de-emphasize:

New projects. Small stuff is okay, but I don’t want to spend a lot of time this year working on “The Next Big Thing”.
Open source. It’s a time commitment, and if I’m not actively using the library then I want to de-prioritize the work as much as I can.

Outside of the regular schedule, I’ll try to get a conference talk or two accepted. I think that is a valuable skill set to nurture, even if it is a big time commitment.

Onward and upward!

Be careful parsing formatted numbers in JavaScript

Sean McPherson — Tue, 20 Dec 2022 14:14:00 GMT

I was working on a script recently and ran into an unexpected issue. The work involved parsing a number-range string into an array of numbers, e.g. "1-100" into [1,100].

My first instinct was to reach for parseInt with something like:

"1-100".split("-").map((string) => parseInt(string));
// [1, 100]

This worked nicely until I rant into formatted numbers in the dataset: "1,000-2,000". Instead of parsing the strings into the expected numbers, parseInt seems to treat the commas as decimals:

"1,000-2,000".split("-").map((string) => parseInt(string));
// [1, 2]

Unfortunately, parseFloat and the Number constructor similarly struggle with formatted numbers:

"1,000-2,000".split("-").map((string) => parseFloat(string));
// [1, 2]
"1,000-2,000".split("-").map((string) => Number(string));
// [NaN, NaN]

It's interesting to me that Number returns NaN, but MDN says you probably shouldn't be using it like this anyway.

The solution is to remove the commas before parsing. There are a few methods to do this, but String.replace will work nicely:

"1,000-2,000"
  .replace(",", "")
  .split("-")
  .map((string) => parseInt(string));

If you're curious, swapping the commas for underscores – the approved numeric separator – doesn't work either:

parseInt("1_000");
// 1

There might be an optimal solution that handles numbers formatted for different locales, e.g. "1.000,00" and "1,000.00", so please send me a message if you know of one.

Happy coding!

New command palette

Sean McPherson — Thu, 15 Dec 2022 11:17:00 GMT

Last month, I wrote about the new "command bars" UI pattern, and ever since the idea of adding one to this site has been kicking around my head. The design doesn't support lots of links in the header, so an "over UI" for navigating seemed like a decent choice.

Yesterday I added a new command/control k command palette to this site. You can activate it by typing the keyboard shortcut or clicking the magnifying-glass icon in the header. You can exit the palette by pressing "Escape" or tapping on the overlay.

The component is built using Astro and some styles and TypeScript, which should make it portable to other sites once I iron out all of the bugs. I still get a kick out of how easy it is to build UI with Astro components. Well done, Astro team!

Currently your query has to directly match the content available, but I'm planning to add fuzzy matching in the future. In the meantime, I'm hoping that it simplifies the process of surfacing content on my site.

Happy commanding!

Fix "package esbuild-linux-64 could not be found" error on Netlify

Sean McPherson — Wed, 14 Dec 2022 14:37:00 GMT

This morning my website's builds started failing on Netlify. Checking the deploy logs, I saw the following error:

10:29:09 AM: [astro:jsx] The package "esbuild-linux-64" could not be found, and is needed by esbuild.
10:29:09 AM: If you are installing esbuild with npm, make sure that you don't specify the
"--no-optional" flag. The "optionalDependencies" package.json feature is used
10:29:09 AM: by esbuild to install the correct binary executable for your current platform.

There is a closed issue about it in esbuild, but there wasn't a definite fix. Seems to be a problem related to dependencies built for different platforms.

I had recently encountered some merge conflicts in package-lock.json (RIP) and thought that might have been it. But generating the file again had no effect on the error, and neither did running npm audit fix.

The last thing I tried was to delete package-lock.json entirely and commit that. Without the lock file, Netlify was able to install the correct dependencies and deploy the site. So... solved?

That will work for me and my personal site, but if you are working on project with multiple developers in a more high-stakes environment, then you'll probably want to keep looking for a more permanent solution.

I'll make sure to update this article if the issue arises again.

Happy debugging!

Adding images to articles (again)

Sean McPherson — Tue, 13 Dec 2022 10:52:00 GMT

Back in 2020 I wrote about adding images to articles, but I broke all of that when I rewrote the site in September. At the time, I wasn't too upset about the regression, because images had become a bit of a painpoint for the site.

The reality is that I want to add images to my articles, but I was paralyzed by the process of optimizing images for the web. Between widths and aspect ratios and new image formats that aren't support by all browsers, to figure and img and picture elements and all their unique attributes... it is overwhelming.

But images are helpful. Beyond adding a little visual interest to articles, they can help explain things that are hard to put into words. For example, I have a few articles talking about features within the browser's dev tools. I can try and describe the toolbars of a panel's pane all I want, but a quick screenshot is much more helpful.

So once more into the breach.

Astro, like other site-building frameworks, has a package for adding optimized images to your site, but that seems designed for known images on your site like a hero image. What about arbitrary images within post content? I wasn't sold.

I wanted a solution that would work for all images, regardless of where they were used in the site. I wanted the process of resizing them to be automatic, with options to run in development or as part of the build process. That way I can add images locally or via a CMS and they will be automatically optimized for the site.

I started with a new Node script, that reads a directory of images and then runs them through sharp to resize. The script overwrites the original file (so that references within Markdown files are preserved), and stores the original for future reference. The changes are automatically committed (though that part is a little hit or miss).

With the code in place, I added a "prebuild" script to the package.json to run my script during a build. That way any images that were not resized when added will be handled before they go into production.

There are some additional feature that I baked in, including a --skip-git flag for running in CI/CD and an ability to regenerate all images when the width settings change. That's a little in the weeds for this article, but you can view the source code on GitHub if you're interested.

Hope that helps! With all of this in place, I'm looking forward to adding more images to my articles in the future. So stay tuned for more!

Portable custom search engines

Sean McPherson — Mon, 05 Dec 2022 15:49:00 GMT

Custom search engines (or site search) are a useful tool for improving your workflow in the browser. By configuring shortcuts and URLs, you're able to search sites or complete paths quickly and efficiently. Plus, it's totally customizable.

I have a few setup to query common documentation sites or complete common URLs. They save me time, clicks, and/or cognitive load and are an important part of my workflow.

Even though Chrome browsers and Firefox all support custom search engines, there isn't a good way to port your settings from one browser to the next. They're hidden away in a special settings location which doesn't get exported alongside history and bookmarks when you move.

As a front-end developer, I spend a lot of time hoping between browsers. And the inability to use my custom search engines everywhere has been a point of frustration. To solve this, I created a web-based solution that gives me the features I want from custom search engines without getting locked in to any particular browser.

Jean is a portable custom search engine that you control. Search engines are added to a simple file using a CSV-like syntax for labels, shortcuts, and URLs. Then load the page in your browser and get searching!

Jean was designed to work with GitHub Pages, but for a little more privacy you can load it directly from your computer – no HTTP server required! Just copy the whole path into your browser and bookmark it.

You can checkout a live version of Jean here.

For a little extra power, you can use Jean's query API to forward shortcuts through Jean. Just add a single custom search engine to your browser: - Label: "Jean" - Shortcut: "j" (or whatever you want) - URL: "/?q=%s"

Now you can search using any of your custom search engines by using Jean as a proxy:

j wk Search engines

After porting all of my custom search engines over to Jean, I was able to switch my Chrome work setup to Edge in about two minutes. Blazin'!

To create your own portable custom search engine, fork the Jean repository and add your favorites to engines.js. And that's it; you're read to start searching.

Let me know what you think, and file an issue if you find a bug.

Happy searching!

A first look at Static CMS with Astro

Sean McPherson — Wed, 30 Nov 2022 24:43:00 GMT

The first version of Static CMS, a community fork of Netlify CMS, is scheduled to drop today. As a Netlify user and a general fan of Netlify CMS, I am excited to see what the community can do iterate on a useful product.

While we wait for that initial release, I wanted to explore what it would take to switch this Astro site from Netlify CMS to Static CMS.

First, I created a new admin route within the public/ directory with index.html and config.yml files:

mkdir public/x-admin
touch public/x-admin/index.html public/x-admin/config.yml

I opted for the CDN hosting option (mostly because it was simpler), which involved pasting the following code block into index.html:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Content Manager</title>
  </head>
  <body>
    <!-- Include the script that builds the page and powers Static CMS -->
    <script src="https://unpkg.com/@staticcms/core@%5E1.0.0/dist/static-cms-core.js"></script>
    <script>
      window.CMS.init();
    </script>
  </body>
</html>

Loading the route, and I hit issues where window.CMS was undefined. I tried tweaking the version of the script from the snippet and eventually got it working:

<script src="https://unpkg.com/@staticcms/core@latest/dist/static-cms-core.js"></script>

With that updated, I moved on to configuration. I tried copying my Netlify CMS config.yml into the new admin directory, and it loaded right up! It's nice when things go smoothly.

I was able to view all of my articles and create a new draft (I'm using Static CMS to write this article right now). The only configuration that didn't obviously work was the "list" widget. I use this to set the tags for an article, but there was nothing rendered in the UI.

I tweaked the config a little for "list" and got something to render, though I'm not sure it would work correctly for me:

- label: "Tags"
  name: "tags"
  widget: "list"
  fields:
  - label: "Tag"
      name: "tag"
      widget: "string"

I tried to test what the resulting data would look like, but when I attempted to publish I got the following error:

Failed to persist entry: API_ERROR: "params.options.useWorkflow" is required

There isn't any reference to that in the documentation or GitHub issues, so I was feeling kind of stuck. But after a little digging, I found this comment in one of the example templates:

# Please run "npx static-cms-proxy-server" for local backend

I didn't see a reference to that in the documentation, so I ran that in the terminal and received the following:

$ npx static-cms-proxy-server
npm ERR! Cannot convert undefined or null to object

Turns out that package does not exist yet. There is a reason why they call it the "bleeding edge."

I could go on, but this felt like a fair enough attempt at getting it to work.

Conclusion

I'm excited to see what the maintainers of Static CMS can do to carry the torch of Netlify CMS. But at this stage, it still feels very raw. To illustrate that point, I started writing this article in Static CMS but am finishing it in Netlify CMS.

Maybe if you use one of the starter templates you will have more success. For now, I'm going to be watching the development from the sidelines.

Happy coding!

Astro components do not merge HTML attributes

Sean McPherson — Tue, 29 Nov 2022 14:36:00 GMT

Over the past month I have been enjoying working in the Astro ecosystem recently, and have been working on some simple community packages.

I've learned that Astro merges component props and element attributes differently, so I'm writing this short PSA to help myself and other Astro devs in the future.

First, some terminology:

Props are the data or properties that we pass to components
Attributes are the data that we pass directly to HTML elements

We might think of these interchangeably in most component-based frameworks, but as we will see here they are different in Astro components.

Props: left-to-right

For props, Astro merges from left-to-right. This means that a prop on the left-side of a component call will be overwritten by the prop with the same name on the right:

The resulting side prop within the Example component will be "right".

The above example is a little contrived, but you can imagine a scenario where you are creating a component that allows overriding default values:

Attributes: no merging

However, Astro does not merge attributes on HTML elements. So if you have two identical attributes passed to an element, that is what goes to the DOM. Browsers typically ignore any duplicate attributes, so the prevailing value is the first from left-to-right:

The resulting type attribute for input element will be "text".

If you want to create a component that allows overriding default attribute values, then you need to spread them on the left-side of the element:

This behavior might be the opposite of what you expect. For a counter example, React merges both props and attributes. But whatever the reason for the difference, it's important to remember.

tl;dr

In Astro you should spread props to components on the right, and elements on the left:

You can see this behavior in action live on StackBlitz.

That's all. Hope it was helpful to you, and memorable for me!

Happy coding!

Run Netlify CMS and your dev server in one command

Sean McPherson — Tue, 29 Nov 2022 10:54:00 GMT

If you're using Netlify CMS, there is a command that you can run to load it in development:

npx netlify-cms-proxy-server

This is useful, but it needs to be run in a separate terminal window to your development server. I use VS Code, which has easy split terminal windows, but it's still a little annoying to have to fire up two processes when you want to get to work.

# Window 1
npm run dev

# Window 2
npx netlify-cms-proxy-server

An ideal solution would be to run a single command that runs both scripts in parallel, so that you can focus on working as opposed to setting things up.

Thankfully for us, npm-run-all is the perfect solution for this. First we install it as a dev dependency:

npm i -D npm-run-all

Then add a new script to our package.json:

{
  "scripts": {
    "cms": "npx netlify-cms-proxy-server",
    "dev": "astro dev",
    "dev:cms": "npm-run-all --parallel cms dev"
  }
}

Now when you want to run Netlify CMS alongside your development server, you just need to a single command:

npm run dev:cms

Happy coding!

Fix Netlify Dev's 'Multiple possible start commands found' issue

Sean McPherson — Tue, 29 Nov 2022 10:40:00 GMT

Netlify Dev attempts to guess what framework your project is using and what commands it should run in development.

$ netlify dev

◈ Netlify Dev ◈
◈ Ignored general context env var: LANG (defined in process)
◈ Ignored general context env var: LC_ALL (defined in process)
? Multiple possible start commands found (Use arrow keys or type to search)
❯ [Astro] 'npm run dev'
  [Svelte] 'npm run dev'
  [Svelte] 'npm run build'

Reading the Netlify documentation, it seems like you should be able to resolve this by adding a [dev] section to your netlify.toml file.

<!-- This doesn't work -->
[dev]
    command = "npm run dev"

However, that alone does not work. There is a "closed" issued that describes the behavior, but essentially the Netlify CLI doesn't read the command even though you've set it.

Thankfully, someone contributed an actual solution that only requires a few more details:

[dev]
    command = "npm run dev"
    framework = "#custom"
    targetPort = 3000

framework needs to be set to "#custom" and you need to manually set the port that your dev server typically runs on. With Astro, that is port 3000.

With that configured, everything works as expected:

$ npx netlify dev

◈ Netlify Dev ◈
◈ Ignored general context env var: LANG (defined in process)
◈ Ignored general context env var: LC_ALL (defined in process)
◈ Setting up local development server

Happy coding!

Astro components for Netlify features

Sean McPherson — Fri, 25 Nov 2022 11:26:00 GMT

This morning, I released the first version of astro-netlify-components,a library of Astro components for Netlify. I was about to start dogfooding the functionality in my own site, and I figured I might as well share it with the world.

There are two exported component at launch:

<Form>: adds all the of the markup for Netlify Forms with types and validation
<CMS>: a full-page component to render the Netlify CMS admin interface

To add either component to your, add the package to your project:

npm i astro-netlify-components

Then, import the components and use in your Astro page:

---
import CMS from "astro-netlify-components/CMS.astro";
import Form from "astro-netlify-components/Form.astro";
---

CMS renders a full page, so import and invoke it on a page of its own:

---
// src/pages/admin.astro
import CMS from "astro-netlify-components/CMS.astro";
---

Form expects children, so you could set up a contact form on your site like this:

---
// src/pages/contact.astro
import Form from "astro-netlify-components/Form.astro";
---


  
    Name
    
  
  
    Email
    
  
  
    Message

If you want to give it a try, make sure to checkout the documentation and file any issues you encounter.

Happy coding!

Create a "Dave Rupert"-inspired activity graph

Sean McPherson — Wed, 23 Nov 2022 18:48:00 GMT

This article was written when seanmcp.com was powered by Astro. I have left the content in place, but the activity graph described no longer renders.

I noticed on Dave Rupert's website that he had a little activity graph to illustrate how many articles he has written per year over time.

That seemed like a nice little feature, so I decided to try to recreate it for my site. This is a little code walk through how I made it using in a custom Astro component.

First, I needed to grab all of the data to count. I have two main forms of content on this site, articles and notes. Using Astro's glob() method, I was able to get that data and pass it into a sorting function:

const articles = getSortedContent(
  await Astro.glob("../pages/articles/*.{md,mdx}")
);
const notes = getSortedContent(
  await Astro.glob("../../content/notes/*.{md,mdx}")
);

This code is all subject to change, so for the latest checkout the source on GitHub

Next, I knew that I needed to keep a record of some totals, so I created an object to track the totals for each content-type by the year:

const yearCount: Record<number, { articles: number; notes: number }> = {};

With that in place, I could loop through articles and notes and start counting:

articles.forEach((article) => {
  const year = new Date(article.frontmatter.pubDate).getFullYear();
  if (!yearCount[year]) yearCount[year] = { articles: 0, notes: 0 };
  yearCount[year].articles++;
});

notes.forEach((note) => {
  const year = new Date(note.frontmatter.pubDate).getFullYear();
  if (!yearCount[year]) yearCount[year] = { articles: 0, notes: 0 };
  yearCount[year].notes++;
});

This was far from DRY, but I didn't think it was worth refactoring at this point.

With the data ready, it was time to start rendering. I went with an ordered list, ol, with list items for each year. Within each li, I have a label, and two spans to represent articles and notes.

I tried to label things in a helpful manner, but I'm sure there are accessibility improvements to be made.

The last bit of magic was finding a decent height for the most prolific year, and then use that when calculating the individual span heights. And thanks to Math.max()'s API, this was pretty nice:

const highest = Math.max(
  ...Object.values(yearCount).map((record) => record.articles + record.notes)
);
// 16 * 4 or 64 is the maximum height for a year
const multiplier = (16 * 4) / highest;

With all that set up, all I needed to do was iterate:


  {
    Object.entries(yearCount).map(([year, { articles, notes }]) => {
      const articlesLabel = `${articles} articles`;
      const notesLabel = `${notes} notes`;
      return (
        
          {year}
          
            {articlesLabel}
          
          
            {notesLabel}
          
        
      );
    })
  }

There is certainly room for improvement, but I'm happy with how it turned out. Here it is in all its glory:

Happy coding!

Use your domain on Mastodon with Astro

Sean McPherson — Fri, 18 Nov 2022 13:29:00 GMT

Update: The solution in this article still works, but I think using a redirect as described here is probably a better option.

Maarten Balliauw shared a cool strategy for using your own custom domain as a reference to your Mastodon account. He explains it better than I can summarize, so take a look at his article first.

I wanted to try it out, but I'd prefer if the process was automated in my site's build process. Thankfully, Astro has an API for generating arbitrary files on build with endpoints.

In your Astro site, create a new file called src/pages/.well-known/webfinger.ts and paste the following code block

const INSTANCE = "indieweb.social";
const USERNAME = "seanmcp";

/**
 * This endpoint adds a webfinger JSON file to your site so that you can use
 * your domain as a reference to your Mastodon account.
 */
export async function get() {
  const response = await fetch(
    `https://${INSTANCE}/.well-known/webfinger?resource=acct:${USERNAME}@${INSTANCE}`
  );
  const data = await response.json();
  return { body: JSON.stringify(data, null, 2) };
}

Make sure to swap out the values for your Mastodon instance and username!

When you trigger a build, Astro will run the get() function which grabs the webfinger information from your Mastodon instance and outputs it in the correct /.well-known/webfinger location.

With that in place, you can now use your domain as a reference to your Mastodon account.

Enjoy!

Thoughts on Steve Job on consulting

Sean McPherson — Thu, 17 Nov 2022 13:43:00 GMT

My manager at Khan Academy sent me an old video of Steve Jobs talking about the idea of consulting:

https://www.youtube.com/watch?v=rp6_3UQLi2Y

Here are some of the key quotes:

Without owning something over an extended period of time–like a few years–where one has a chance to take responsibility for one’s recommendations, where one has to see one’s recommendations through all action stages and accumulate scar tissue for the mistakes, and pick oneself up off the ground and dust oneself off, one learns a fraction of what one can.

Coming in and making recommendations and not owning the results and not owning the implementation–I think–is a fraction of the value and a fraction of the opportunity to learn and get better.

You do get a broad cut at companies, but it’s very thin. … You might get a very accurate picture, but it’s only two dimensional. And without the experience of actually doing it, you never get three dimensional.

You’re also a variable expense, and in hard times you find yourself [expendable].

I don’t have much experience with consultants, but his thoughts seem to ring true.

It’s easy to stand at a distance and make recommendations. On the lay end of the spectrum, millions of people do this every week to the manager of their favorite sports team every week. And then there is a whole class of professional pundits who make suggestions and critique decisions in (and too often outside) their sphere of expertise.

The ideal situation would be a consultant who has a long track record of working in the weeds through difficult problems in different scenarios. They’ve seen what worked, what didn’t and why. With that experience, you could trust their opinions and confidently follow their recommendations.

That reminds me of the proverb:

Seek first to understand, then to be understood

Or updated for consultants:

Seek first to understand the problem, context, constraints, history, technology, and best practices over a long period of time, then to be understood

Unless you truly understand all of that, why should others bother listening? That is a humbling question for me as I move into the next stage of my career.

Food for thought!

Are command bars the future?

Sean McPherson — Thu, 17 Nov 2022 11:14:00 GMT

Maggie Appleton recently wrote about "Command K Bars", those command line bars that you pull up with a keyboard combination. In addition to giving a lot of cool product recommendations, she explained the pattern for designers:

Command bars are command-line bars that pop up in the middle of the screen when you hit a certain keyboard shortcut.They're also known as 'command palettes', 'command launchers', or 'omniboxes' Traditionally CMD + K, hence the moniker “Command K bars.” But CMD + E and CMD + / have also been strong shortcut contenders.

Bars like this let users search through all the available commands in an application. Rather than remembering which sub-sub-sub menu a function lives in, users need only remember its name.

They don't even have to remember its exact name. Fuzzy search can help them find it by simply typing in similar names or related keywords. For example, if I type “make” into a command bar, it's likely to show me any actions related to creating new items. Even if “make” isn't part of the action name.

Some notable examples of this in my line of work are:

Slack CMD + K
VS Code CMD + P
Chrome DevTools CMD + P
Notion CMD + K
GitHub CMD + K

I, for one, absolutely love this pattern. It's so nice to be able to quickly jump to a command without needing to remember where the button is in the UI or even the exact name for it. These command bars definitely improve my workflow.

However they feel like a very developer-focused pattern, extending to products for companies that work in tech. I'm skeptical at this point that the pattern is ready for mainstream products.

In a quick survey of popular information and social-media sites, I found no command K bars.

It's also worth noting that the command key is Mac-centric. In tech we can probably get away with that since it has large sections that are dominated by Mac users, but that isn't the case for products with broader audiences. Maybe swapping command for control is sufficient, or maybe switching to the meta key makes more sense. It might take time before a true standard emerges.

I think command bars are a great pattern, and I'm looking forward to using them in more ways and on more sites. But I wouldn't prioritize that feature work unless you are in an industry that caters to developers or the companies that employ them.

What do you think: are command bars the wave of the future? Let me know.

Happy interacting!

Node.js is great for scripting

Sean McPherson — Wed, 16 Nov 2022 14:21:00 GMT

This week I was working on a project that reads 6.4 MB of text files (the complete English Bible), does some processing and computation, and then outputs JSON data. You can see result of that work on GitHub.

In times past, I've felt pressure to reach for a "proper scripting language" like Python or a more performant one like Go. But I feel like we've reached the point where Node.js is a great choice for scripting.

JavaScript is everywhere. You can find tutorials and examples for every conceivable task for JS. And by and large, the code that works in the browser will work in Node.js too.
JavaScript is forgiving. When I'm writing a script, it's usually for a specific and personal use case. I don't want to spend a lot of time writing syntax or worrying about types. And thankfully, JavaScript doesn't care about that either.
The ecosystem is huge. There are over one million npm packages, so the chances are good that there is a solution available for whatever problem you have. And thanks to JS being everywhere, there are countless guides to adding dependencies to your project.
Node.js is readable. Thanks to JS' async/await and sync functions from Node.js' standard libraries, writing a script that reads multiple files/directories and then writes to others is pretty straightforward. No more chaining callbacks!
Node.js supports ESM. Node.js supports ES modules with either the type: module flag in package.json or the .mjs extension. Maybe this is a bigger deal for me personally, but the ability to import and export modules without needing to think about require() or module.exports is pretty nice.
Node.js is fast. That project I mentioned at the top? The Node.js script that I wrote (which was not optimized for performance) ran in less than a second. 6.4 MB in < 1 second! I'm not saying that Node.js is the fastest option, but for your typical scripting needs: it's more than fast enough.

I'm not arguing that everyone should be using Node.js for scripting, nor that it is the best solution for every problem in every environment. And if you prefer Rust or Go or Ruby or WhatEver, go for it!

But if you're a developer who is comfortable working in the JavaScript ecosystem, don't be hesitant to reach for Node.js. It's a great option for your next script.

Happy coding!

There is no multi-tasking on the Raspberry Pi

Sean McPherson — Thu, 03 Nov 2022 11:14:00 GMT

Maybe this isn't fair to file under the "Trying Linux 2022" series since it isn't commentary on the operating system writ large. However, it is a part of my journey trying Linux and worth documenting.

I have a Raspberry Pi 3 B+ (or something like that). I bought it about 4 years ago with the goal of using it as a RetroPie, and it did that pretty well. Now that I'm here in 2022 trying to use this as a developer compuer, however, I'm starting to see some of the strains.

With the Pi and Raspberry Pi OS, I can do approximately one tasks at the same time. I can use the browser (Firefox ESR), VS Code, or the Raspberry Pi package manager. If I try to use two of these things at the same time, however, the whole system grinds to a halt for minutes at a time. So I need to be really careful not to multitask while I'm working.

You hear some developers complain about how resource intensive modern development has become. Browsers with all their extensions are big and bloated. Electron-powered programs are slow and resource intensive. Running all of the services locally takes more cores from your processor than computers had 20 years ago. I've been largely sympathetic to those criticisms, but I haven't really felt the pain because I've always had a high-powered computer from my employer that can manage the workload.

Now that I'm on a Raspberry Pi and trying to run a "simple" Node process and view it in the browser... I feel it.

And maybe that is a good thing.

Finding a Linux distro and software that work

Sean McPherson — Wed, 02 Nov 2022 12:55:00 GMT

I wrote yesterday's article about giving Linux another try while things were still installing, i.e. too soon. Here is everything that I tried:

Ubuntu Mate 22.04: Installed but setup wouldn't complete (I probably tried 3-4 times).
Ubunutu 22.04: Installed and setup, but it was very slow and crashed multiple times.
Ubuntu Mate 22.04 (attempt 2): Installed and setup, but I was unable to open Firefox.
Lubuntu 20.04.5: Couldn't get it to install on the microSD card. Maybe because I renamed an .iso file to .img? (Following this recommendation)
Raspberry Pi OS: It worked! 🎉

With the OS up and running, I moved on to installing software. Git was included already, and I used apt to install nodejs and vim. Brew doesn't work with ARM devices, so I need to manage some software manually.

I decided that it would probably be a good idea to use pnpm instead of npm on a low-memory device. It required at least Node.js 14, but the latest version available from apt was 12.

After going through the usual journey of trying to update Node.js, I ended up installing NVM and going with the new 18 LTS. With that updated, I could install pnpm with: npm i -g pnpm

The included version of Chromium struggled to render emojis correctly, so I opted for Firefox instead. I used the Raspberry Pi's package manager to install firefox-esr and it worked great. I made sure to install uBlock Origin to hopefully help a bit with performance.

With all that in place, I now have a serviceable Linux machine for tinkering! It still struggles a bit running multiple processes at the same time, but it's definitely good enough for now.

Giving Linux another try

Sean McPherson — Wed, 02 Nov 2022 24:35:00 GMT

I felt inspired by an article by Hey Homepage and recent episode of The Changelog podcast to give Linux another try. This description just sounds so nice:

For over a year now, I use a Raspberry Pi 4 (with 8GB of RAM) as my daily desktop computer. I browse the internet, read and send e-mails, program software, edit photos, create images, watch Youtube videos and play games on it. Without any significant problems.

So tonight I'm dusting off the ol' Raspberry Pi and trying a fresh installation of Ubuntu Mate. Why Mate? Because it was recommended in the article above. The latest time I needed a low-powered Ubuntu flavor I used Lubuntu, but that is probably 10 years ago. Time flies!

I don't expect to completely change my computing habits; as a front-end focused developer I feel pretty compelled to stick with macOS. But I'm looking forward to peeking outside of the Apple ecosystem, even in a sandbox, to get a better picture of the world out there in 2022.

Please let me know if you have any suggestions, because I don't know what I'm doing. 😄

Awesome browser extensions

Sean McPherson — Mon, 31 Oct 2022 13:11:00 GMT

Extensions can slow down your browser, so I try to only add ones that are necessary or super helpful. Here is a list of the extensions that make the cut, grouped by category and listed alphabetically:

General use

Disable automatic gain control: I've written an article about this extension already; it prevents Chrome from automatically adjusting the gain for your audio input. I couldn't use Meet on Chrome without this extension!
uBlock Origin: Simple and effective ad blocking. Add this on every grandparent's computer!

Developers

axe DevTools: Adds an accessibility audit panel to the developer tools.
Markdown Editor for GitHub: Converts GitHub's default textarea into a full-featured Monaco editor. This means you can use your favorite VS-Code keyboard shortcuts when editing issue descriptions and PR comments.

This list will grow over time, so feel free to email suggestions and check back later. Happy extending!

Using dynamic routes to organize blog posts in Astro

Sean McPherson — Sat, 29 Oct 2022 17:21:00 GMT

If you create a new Astro project with the installer, it will organize blog posts as markdown files in a src/pages/blog/ directory. Each post will have some frontmatter, including a layout field to set the frame in which the content will render.

Astro will create a new page for every markdown file in the src/pages/ directory, so adding a new post is as simple as a creating a new markdown file in the blog/ subdirectory.

When you want to render blog content on another page, e.g. a homepage with the last three posts, then you need to rely on two Astro APIs: compiledContent and/or the Content component. These will give you the Astro-rendered content for a post that you can then add to another page.

There are two issues that I encountered using these APIs:

MDX does not support compiledContent, so you can either omit .mdx content or create your own workaround with rehype plugins.
The Content component for a post includes the markup for the layout, so "embedding" it in another page results in a strange iframe-esque page within a page.

If you just want to render the content of md/mdx files, there doesn't seem to be a workable solution with the current setup. But with a little refactor, you can have your cake and eat it too!

A new organization system

Rather than putting all of your content somewhere in the src/pages/, instead let's create another directory at the same level as src/ called content/. This is where we will put all of our blog posts, maybe in a blog/ subdirectory:

content/
    blog/
        first-post.md
        second-post.md
        third-post.md
src/
astro.config.mjs

Now we'll create a dynamic route for all blog posts in the src/pages/blog/ directory. This file will gather all of the posts from your new content/ directory create static paths for each:

---
// src/pages/blog/[slug].astro

export function getStaticPaths() {
  const content = Astro.fetchContent("../../../content/blog/*.{md,mdx}");
  return content.map((item) => ({
    params: { slug: item.url.split("/").pop() },
    props: {
      ...item,
      // Any additional props
    },
  }));
}
---

Astro will call the getStaticPaths function and create a page for each item in the returned array with the given params. We've added the item as props for the page, so we can access all of the data for each post.

Finally, we can remove the layout: frontmatter from all of our posts in content/blog/ and set the markup in our new dynamic route:

---
// src/pages/blog/[slug].astro

export function getStaticPaths() {
  const content = Astro.fetchContent("../../../content/blog/*.{md,mdx}");
  return content.map((item) => ({
    params: { slug: item.url.split("/").pop() },
    props: {
      ...item,
      // Any additional props
    },
  }));
}

const {
  Content,
  frontmatter: { title },
} = Astro.props;
---

{title}

Make sure to include post content in the <head> element too, and add encoding to ensure that it renders correctly.

With all of that in place, you are now able to render markdown or MDX blog post content anywhere on your site with Astro's Content component; we're doing it right here in our [slug].astro file!

In addition to resolving the issue above, I think I like this approach better because it keeps the content separated from the code, which feel like different concerns. As of publishing, I use it to organize notes, which are individuals bits of md/mdx content that are rendered on the notes page.

tl;dr

Astro's default setup for organizing blog posts works well for a one-to-one relationship between content and pages. But if you want to have a many-to-one relationship with markdown and MDX, a better aproach may be layout-less posts with a dynamic route.

I hope that helps! Happy blogging 🚀

Rebuilding with Astro

Sean McPherson — Thu, 13 Oct 2022 16:00:00 GMT

This article was written when seanmcp.com was powered by Astro. I have left the content in place, but the component described no longer renders.

After almost four years of Eleventy, I recently completed a rebuild of this site with Astro.

Why leave Eleventy?

I think that Eleventy is a really neat project and that Zach Leatherman is doing a great job with it. My main reason for wanting to move to a different solution was the inability to use components to build pages.

That may sound silly, but I've found components to be a helpful conceptual model for building user interfaces. When I look at a webpage now, I visualize components. When I think about building a webpage, I plan in components. And for my personal site, I want to be able to build in components.

To be fair to Eleventy, there is a plugin to "use Vue", but the missing features and de-prioritized development make it an unappealing option.

In 2022 and beyond, I don't want to be limited to templating languages and partials when building pages. I want to be able to use components big and small across the site to compose interfaces.

Why Astro?

I've been interested in Astro since it launched and am generally excited by the "framework to build modern websites" trend. Three things stood out the most to be when choosing Astro for this project:

Components-based layouts
Island architecture for interactive articles
Familiarity and complexity

Components!

I want to be able to build my user interfaces with components. It's as simple as that, and Astro enables you to use components from any of your favorite JavaScript libraries.

For this site, I stuck with Astro's own components, which feel like a combination of stateless React and Svelte. It was super easy to pick up and build all of the layouts and components I needed.

The only real issue that I encounted with Astro components was the scoped styles. Conceptually I love the idea, but in practice it applies styles using the :where() pseudo-class which has 0 specificity. As a result, I frequently encountered instances where my component styles were overridden by global styles.

For an example, the global selector body > main has a greater specificity than the scoped component selector main:where(.astro-S3KS4JBQ). I would expect component styles to override global styles.

If there is a setting to make Astro apply generated classes directly to the element, e.g. main.astro-S3KS4JBQ, please let me know!

This isn't an insurmountable issue, but I would love to find a workaround (and avoid changing my mental model!).

Islands

I previously tried to add interactive elements to my articles through the use of good ol' HTML, CSS, and JavaScript. And for the use cases that I had, this was usually sufficient. But authoring and maintenance were painful, and the lack of standardization made each interactive a bit of a headache.

What I really wanted was a way to write little self-contained "applets"^[1] that I could drop into any page/article. And that is exactly what Astro Islands are: "an interactive UI component on an otherwise static page of HTML."

The best part is: you can author these islands using whatever JavaScript library you want. I'm a big fan of Svelte, and I'm excited to be able to drop a Svelte component into any article that I'm writing.

This counter here? A Svelte component!

<Counter client:only="svelte" />

And with client directives, you have control over when the component are hydrated on the page. 🚰

Familiarity

The above features are great, but I don't think I would have used a new system if it was more complex than the status quo. That was my favorite part about Eleventy: it used a familiar language to take text files and generate a website.

Thankfully, Astro feels cut from the same cloth. Add a bunch of markdown files to the src/pages/ directory, create a few layouts, and the astro CLI will do the rest. In practice it feels simpler than Eleventy, but maybe that is just a symptom of being more opinionated.

After years working on a site with Eleventy, I found switching to Astro a very confortable transition. And thanks to the new features like components and MDX support, I enjoyed working on the site for the first time in a while.

Cons of Astro

In addition to some of the styling specificity issue mentioned above, there are two other features that I lost in the transtion from Eleventy to Astro:

Line highlights in code blocks. Eleventy provided easy access to the markdown parser and I was able to configure things to my liking with Markdown It. Astro uses remark to parse markdown, and I haven't found a good way to add line highlights to code blocks.
Detailed RSS feed. Astro does provide a plugin for generating an RSS feed, but the resulting output does not have much detail. I would like to include at least a snippet of the article's content, but that doesn't appear to be an option with the plugin.

Wrapping it up

Overall, I'm really happy with the rebuild. It was a good opportunity to evaluate the feature that my site needed and architect it in a way that would be easy to maintain.

Looking forward, I think Astro's island's architecture is going to help me create the content that I want to publish. And hopefully that's good new for everyone.

Happy reading!

Is it safe to reclaim that word from Java yet? ↩︎

Jest tips & tricks

Sean McPherson — Thu, 06 Oct 2022 15:58:00 GMT

Since 2017, I have only used Jest for JavaScript application testing. And while Vitest does look exciting, I think that it's safe to say that Jest will be around for a good while longer.

Here are some of tips and tricks that I've learned that make working with Jest a little better. The headings are organized alphabetically for ease of reference.

Aliases

Jest's global test method has an it alias that you might find useful. There is usually a standard in the codebase where I'm working, but I've found that tests can read a little more naturally with the alias:

test("When a user is logged in, ...", () => {});
it("Logs an event on interaction", () => {});

`expect`

There are a lot of matcher functions that are good to know, so I'll only list a few here.

One of the most useful matchers (and hardest to remember) is expect.objectContaining(). This allows you to assert that certain properties/values are present on the object without needing to mock all of them.

expect(mockFn).toHaveBeenCalledWith(
  expect.objectContaining({
    example: true,
  })
);

Another handy matcher is not(), which gives you a simple way to negate any matcher:

expect(sum).not.toBe(0);
expect(typeof readableTime).not.toBe("number");

I do recommend skimming the Jest docs for expect occasionally to pick up some new matcher that might help in your next test.

Flags

The Jest CLI has a number of flags that can be used to change the way that Jest runs. Here are some of the ones that I find most helpful:

--bail/-b: Exits the test suite after a given number of failures (default 1)
--changedSince: Only run tests related to files changed since a given point. I like to use this with the target branch as a quick check for regressions. - --findRelatedTests: Runs tests related to changed files. Works well in a pre-commit hook.
--watch: Run tests in watch mode. Great when running a small set of tests, but maybe omit if you're running the whole suite.

Selective runs

When working in a large test file, it's nice to run only the cases that you care about. Sometimes that means selecting a specific test or block, and other times that means skipping anything that isn't necessary at the moment.

To just run a specific test, you can use the only() method on the global describe/test methods. This will ensure that only that code is run:

test.only("This test will run", () => {});
test("This test will not", () => {});

To omit a test from the run, you can similarly use the skip() method:

test("This test will run", () => {});
test.skip("This test will not", () => {});

For a smaller change to skip tests, you can add an x to the front of for the same behavior:

test("This test will run", () => {});
xtest("This test will not", () => {});

If you're going to use this, I'd recommend a linter rule to prevent you from committing skipped tests.

I hope that helps! Let me know if you have any other tips and tricks that you have found helpful.

Happy testing!

Solid VS Code extensions

Sean McPherson — Tue, 06 Sep 2022 14:18:00 GMT

I use VS Code as my daily editor, and one of its best features is the wide selection of extensions. However, as with any other large marketplace, discoverability is a real issue.

In an attempt to resolve that issue, here is a curated list of some great VS Code extensions that you might not have tried before:

Code Spell Checker: This extension has saved me from committing embarrassing spelling mistakes on multiple occasions.
Copy GitHub URL: Adds commands to copy the URL for the current location on GitHub. Obviously more helpful if you use GitHub a lot.
es6-string-html: Adds syntax highlighting for ES6's multiline strings. Just add a comment /*html*/ and your backticked strings are more usable.
Format Comment: Adds a command to nicely format comments. Really nice if you prefer the // syntax to /** */ (which VS Code already formats nicely.
Live Server: Adds a button to the bottom status bar to launch a local development server in the current directory. Never Google "serve directory python" again!
Search node_modules: Adds a command to search the node_modules/ directory in your project. VS Code ignores those files by default, so having a method to go spelunking in your dependencies is really handy.

Happy extending!

How to use StackBlitz with Firefox

Sean McPherson — Tue, 23 Aug 2022 16:00:00 GMT

StackBlitz is a great tool for rapidly prototyping web applications. In recent weeks, I has been my go-to tool for testing out new web technologies (CodeSandbox's loss). However, when you try to use StackBlitz with Firefox, the preview window gives the following error message:

Enable Third-Party Cookies Looks like your browser is blocking our Service Worker. To see this web page, please allow third-party cookies for this site.

If you follow the link, it leads you to a guide for enabling the feature for Chrome – a great addition to the error message but not helpful for Firefox users.

To enable the StackBlitz preview pane in Firefox, select the shield icon in the URL bar and turn "Enhanced tracking protections" off for this site:

Once that setting is disabled, Firefox will prompt you to reload the page. Once you do that, you should see the shield icon with a line through it to indicate that Firefox is providing no additional protections:

But more excitingly, the preview pane is now working! With that setting configured, you should not be able to use StackBlitz's features in Firefox.

Happy blitzing!

How to replace Math.random with crypto in JavaScript

Sean McPherson — Mon, 18 Jul 2022 18:15:00 GMT

JavaScript has a method for generating random numbers from 0 to less than 1: Math.random(). If you've ever been working on an app that selects a random item from a list, chances are that you've done something like this:

const randomItem = list[Math.floor(Math.random() * list.length)];

This will probably work for 99% of the use cases of a random number. However, numbers generated from Math.random are not cryptographically secure. That means that the "random" values are guessable by a computer and therefore not suitable for use in cryptography.

Thankfully, we have other methods of generating random numbers in the browser: crypto. This global object has a getRandomValues method that we can use to recreate the functionality above. The method needs to be called with an typed array, so we'll create one with the Uint8Array constructor with a length of 1:

const typedArray = new Uint8Array(1);

Now we pass this to getRandomValues and select the first (and only) item from the returned array.

const typedArray = new Uint8Array(1);
const randomValue = crypto.getRandomValues(typedArray)[0];
// E.g. 122

Since we used an Uint8Array, all of the numbers generated will from 0 to 255. To convert that into the same float returned from Math.random, we need to divide the value by the total number of possible numbers: 256 or 2⁸.

const typedArray = new Uint8Array(1);
const randomValue = crypto.getRandomValues(typedArray)[0];
const randomFloat = randomValue / Math.pow(2, 8);
// E.g. 0.4765625

With these steps in place, we can create a function that is a drop-in replacement for Math.random called cryptoRandom.

function cryptoRandom() {
  const typedArray = new Uint8Array(1);
  const randomValue = crypto.getRandomValues(typedArray)[0];
  const randomFloat = randomValue / Math.pow(2, 8);
  return randomFloat;
}

A few things to note:

You'll (probably) never need this. Reach for Math.random unless you have a very specific reason for cryptographic security.
The floats from this method are shorter. Math.random pretty consistently returns floats that are 10+ decimal places long. If you are depending on a long tail of numbers, then consider switching to Uint32Array and dividing by Math.pow(2, 32).
I'm not a security expert. All of the information in this article was from a quick Google search; make sure to consult people who know what they're talking about before copying and pasting code from a random website.

I hope that helps and as always: let me know if you have any corrections to the article.

Happy randomizing!

Starring content

Sean McPherson — Wed, 13 Jul 2022 15:49:00 GMT

Stars were not migrated during the 2022 site rebuild. For a similar feature, check out bookmarks!

In June, I added a new feature to this site: stars. Now whenever you command or windows click anywhere on the site, a little star emoji ⭐️ is added. When you navigate to that page again, the star will be there waiting for you. If you ever want to remove a star, click it and it will vanish.

Try it out by adding a new star here 👉

My thought was that stars could mark specific portions of an article or page that were helpful so that you can quickly find that location again. This is similar to Medium's highlight feature, but the data is saved to localStorage instead of an external database. As a result, stars are for your eyes only.

To implement this feature, I added a new localStorage key called com.seanmcp.stars where I keep a map of pathnames and an array of star coordinates. Whenever you navigate on my site, stars.js looks to see if there are any stars for that pathname and renders them if present.

I added a new click event listener that handles the logic of adding and removing stars. To check to see if the command or windows key is pressed, you can reference the readonly metaKey property on the event. You can see all of the source code for this feature on GitHub.

It was fun to add a new feature, but I'm realistic about how popular it will be. The meta + click combination is not discoverable, so it will remain a fun surprise for readers who find it.

Let me know if you have any thoughts about the feature or how to improve it.

Happy starring!

Use multiple Chrome Profiles when debugging

Sean McPherson — Mon, 06 Jun 2022 16:00:00 GMT

Awhile back, I read about using separate Chrome profiles^[1] for debugging. The idea is to have specific environments that are specially configured to debug different kinds of issues.

While the article mentioned many different profiles for different users and scenarios, I’ve found myself settling on three: my main profile, the guest profile, and a DevTools profile.

The main profile is where I am signed into Google with my personal or work email address. If you use Google Chrome regularly and have a Google account, you probably have a profile setup already. This is where I do most of my development and debugging work. I have a selection of extensions installed and a few resources like bookmarks and snippets to help my workflow. The first step when debugging is to use my current setup – if I can get things reproducing here, great! But if I have to alter settings or clear data, then I reach for something else.

The next option is the default Guest profile in Chrome. When switching to a guest profile, you lose the session and any information stored in the browser. It's a clean slate. This is helpful when you want to reproduce the bug in a particular scenario but don’t want to logout or toggle feature flags on your main profile. Guest profiles have full access to the browser’s DevTools but do not support extensions. For that, I have a third option.

Finally, I have a profile specifically for DevTool extensions. Here I have the React DevTools installed, and any additional else that would be helpful when debugging. If I know that I am investigating a React issue, I will switch over to this profile and then explore the tree with the Components panel or run tests in the Profiler. Any created profile will save site data, so I make a point of frequently resetting everything to ensure a clean environment for reproducing bugs.

With these three profiles, I find that I'm better able to identify and fix issues that I encounter when developing. Give it a try and let me know how it works for you.

Happy debugging!

Read Vitaly Friedman’s DevTools Debugging Tips And Shortcuts ↩︎

When to use React's memo HOC

Sean McPherson — Thu, 28 Apr 2022 16:00:00 GMT

When React wants to render a component, it renders all of the components in the tree from that point. So if you have a parent component with two child components, a re-render (↻) of the parent will include re-rendering both children.

Parent ↻
├── ChildA ↻
└── ChildB ↻

Since data typically flows down the tree, this is the behavior that you probably want for the UI to reflect the current state of the application.

However, there may be instances when you do not want a component to re-render when its ancestor re-renders. Let's imagine a similar scenario with two children. One of the components is presentational while the other has a deep tree of its own.

Parent
├── BasicChild
└── ComplexChild
    ├── GrandChildA
    └── GrandChildB
        └── GreatGrandChild

Just like before, any changes (✴) to the parent will result in re-rendering all if its children – including the complex subtree. Depending on the depth of the tree or the complexity of the render, this could be a time-consuming render cycle.

Parent ✴↻
├── BasicChild ↻
└── ComplexChild ↻
    ├── GrandChildA ↻
    └── GrandChildB ↻
        └── GreatGrandChild ↻

We want to prevent ComplexChild from re-rendering unnecessarily to improve the performance of our application.

Thankfully, React has some features to accomplish this.

Class components

Class components have a shouldComponentUpdate lifecycle method that allow you to determine whether a component should re-render based on props and state.

class PreventRerender extends React.Component {
  shouldComponentUpdate(nextProps, nextState) {
    return this.props.value !== nextProps.value;
  }
}

PureComponent goes one step further by implementing shouldComponentUpdate with a shallow prop and state comparison. When you component extends PureComponent, it will only re-render if its props or state have changed.

class PreventRerender extends React.PureComponent {}

Function components

For modern function components with no lifecycle methods, we need a different solution. React exports a memo higher-order component (HOC) that takes a function component and returns a wrapped component that will only re-render if a shallow comparison of props indicates a change.

const PreventRerender = React.memo(function PreventRerender(props) {});

For more customization, you can pass an optional compare function to React.memo as a second argument that determines whether to render based on previous and next props.

Any of the strategies above to prevent unnecessary re-renders come at a small cost, so make sure to implement them only when necessary. You can use the React DevTools' Profiler panel to determine which areas of the React tree are good candidates for performance improvements.

In our example above, we could wrap our complex component with React.memo in order to prevent re-rendering when the props are unchanged:

export default React.memo(ComplexChild);

We would not need to do anything to the basic child component, as any memoization or lifecycle checks would probably be more expensive than the cost of re-rendering.

With that change in place, a change within the parent component would only result in re-renders for Parent and BasicChild – the expensive tree in ComplexChild would not change.

Parent ✴↻
├── BasicChild ↻
└── ComplexChild
    ├── GrandChildA
    └── GrandChildB
        └── GreatGrandChild

I hope that helps explain when and how to use React's memo HOC.

Happy memoizing!

Calculate the sum of everything up to a given number

Sean McPherson — Sat, 23 Apr 2022 16:00:00 GMT

My wife showed me a Tik Tok series where someone was decluttering their life by getting rid of an increasing amount of items every day for 30 days. That's kind of hard to type out, but the idea was getting rid of one thing on day 1, then two things on day 2, etc. until tossing thirty things on day 30.

It was late a night, and we both struggled with the math of determining how many items this person would give away by the end of the experiment^[1]. Being an engineer, I set out the next day to create a little tool to calculate that for you.

Type in the number of steps (in our case 30 for thirty days), and select "Calculate" to see the sum:

Try this interactive on seanmcp.com

I remember seeing something similar when I was in college and folks would try to raise support to go on a mission trip. They would have a board with every number from 1 to 100 (or so) and try to find people who are willing to donate that amount. With this calculator, you should be able to figure out how long your support board needs to be with some guess and check.

Hopefully this helps someone else.

Happy counting!

Spoiler: It's 465 items ↩︎

English words by consonant-vowel pattern

Sean McPherson — Thu, 03 Mar 2022 16:00:00 GMT

When teaching people (or computers) to read, it's useful to group similar words into categories. One such grouping is by consonant-vowel patterns, which represent words by the letters that they contain.

With consonant-vowel patterns, we can put words like "bun", "cat", and "dip" into one bucket as "cvc" words; they are all made up of a consonant, followed by a vowel, and ending in a consonant.

I put together a list of all English words sorted by their consonant-vowel pairs. However, that is a long list to search through and I thought it might be nice to have a tool to look up shorter words by their consonant-vowel pattern.

The word list isn't perfect, but hopefully it will give you all of the data that you need for your use case! Let me know if you have any suggestions or run into any issues.

Happy reading!

Music to code to

Sean McPherson — Tue, 15 Feb 2022 16:00:00 GMT

Whenever I need to put my head down and focus on a coding task, I have found that listening to music can help me focus and increase my productivity.

There are two main criteria that I have for music while I am programming: 1) it needs to be instrumental, and 2) it needs to have a decent beat/tempo. If a song can check both of those boxes, then it gets added to the rotation.

Here is a list of songs/artists that I enjoy listening to while I work, in alphabetical order:

As of writing, these artists are all in similar, but as the lists grows I plan on organizing things by genre.

Happy listening!

Add a custom emulated device in Chrome

Sean McPherson — Sat, 05 Feb 2022 16:00:00 GMT

Google Chrome provides a feature in the dev tools to emulate a device within the desktop browser. This is really helpful to get a quick preview of what a webpage will look like on different types and sizes of devices.

You can also add a custom emulated device that meets the specifications of your users. For example, if you work on a product that is primarily used by school students on Chromebooks, then it would be useful to have an emulated device that you could easily select.

To add a custom emulated device in Chrome, first open the dev tools with your favorite method.

Then select toggle the device toolbar by clicking the phone/tablet icon or using the shortcut ctrl/cmd + shift + m.

Open the dropdown to see all of the default devices available in Chrome. To add a new one, select "Edit" at the bottom of the list.

This should review a new dev-tools panel. Here you can select from a greater list of default devices. To add a new device, select "Add custom device...".

Next, input the dimensions for your custom device. I have two Chromebooks with two different window dimensions: 1366x649 and 1300x605. I'd rather test again the more extreme device, but you do whatever makes sense for you.

Make sure to select the correct user agent type! For a Chromebook, I'm going with "Desktop (touch)".

When you are done, select "Add".

With your custom emulated device added, you can now selected it from the responsive device dropdown menu back on the far left.

The screenshot below illustrates just how different the real estate is for a Chromebook user compared to someone on a full-sized laptop or desktop:

With custom emulated devices, we can test to make sure that our webpages and applications will work well for all of our users.

Happy customizing!

Upgrading an Eleventy site to 1.0.0

Sean McPherson — Tue, 18 Jan 2022 16:00:00 GMT

I initially published a note about how easy it was to upgrade to Eleventy 1.0.0, but I hit a snag which warrants a quick article. Here are the two steps that I needed to complete to update this website to the latest version of Eleventy.

First, update @11ty/eleventy with the following command:

npm i -D @11ty/eleventy@latest

After updating that, both the start and build scripts for the site worked as expected. There are breaking changes to be aware of, so your mileage may vary.

I took the time to update some other dependencies and pushed the changes to GitHub. I have the repo connected to Netlify for CI/CD, which usually works without a hitch. Today, however, I noticed that the build failed with the following log:

10:03:16 AM: $ eleventy
10:03:16 AM: Eleventy requires Node 12. You will need to upgrade Node to use Eleventy!
10:03:16 AM: 
10:03:16 AM: ────────────────────────────────────────────────────────────────
10:03:16 AM:   "build.command" failed
10:03:16 AM: ────────────────────────────────────────────────────────────────
10:03:16 AM: 
10:03:16 AM:   Error message
10:03:16 AM:   Command failed with exit code 1: eleventy

There weren't any build configurations in Netlify for Node.js version, but a quick search led me to this guide on managing build dependencies. Good documentation; another reason to use Netlify!

I added an environment variable for NODE_VERSION and set it to the current Node.js LTS (16.13.2 as of writing), and the build was successful.

Regardless of your setup, just make sure that you are using Node.js version 12 or later and you should be good to go. 🚀

Happy upgrading!

Make a web component

Sean McPherson — Fri, 14 Jan 2022 16:00:00 GMT

To make a web component, you need to create a new class. You can extend an existing component class if you want to preserve some semantic behavior, but we'll go with the default HTMLElement:

class HelloWorld extends HTMLElement {}

Next, we need to add a constructor method and call the super function to ensure that our component is initialized with all the necessary information:

class HelloWorld extends HTMLElement {
  constructor() {
    super();
  }
}

Now we need a DOM to build on. Web components use a shadow DOM, which we'll create by calling our class's attachShadow method:

class HelloWorld extends HTMLElement {
  constructor() {
    super();

    const shadow = this.attachShadow({ mode: "open" });
  }
}

With our shadow DOM declared, we can create a new element. Let's go with a span element with the content "Hello world!" and append it to our shadow:

class HelloWorld extends HTMLElement {
  constructor() {
    super();

    const shadow = this.attachShadow({ mode: "open" });

    const span = document.createElement("span");
    span.textContent = "Hello world!";

    shadow.appendChild(span);
  }
}

The last thing we need to do is define our custom web component with:

class HelloWorld extends HTMLElement {
  /* Collapsed for brevity */
}

customElements.define("hello-world", HelloWorld);

Finally, references your new element in the HTML:

<hello-world></hello-world>

Congratulations, you just made your first web component!

Happy coding!

Prevent Chrome from adjusting audio input levels on Mac

Sean McPherson — Tue, 11 Jan 2022 16:00:00 GMT

Starting Fall of 2021, I noticed that my bluetooth headphones would periodically mute me while I was speaking during video chats on Google Meet. I tried multiple sets of bluetooth headphones, and they all had the same issue.

I learned last week that macOS will automatically mute an audio input when the input level is set to zero. While in meetings, I kept an eye on the level in System Preferences > Sound > Input and noticed that it would decrease as I spoke. As soon as the level reached zero, my headset would notify me that it had been muted.

There are no settings in Google Chrome (on in my case, the new Microsoft Edge) nor Google Meet to disable those input level adjustments, and there is an unanswered help question) with a lot of folks experiencing the same issue.

One of the responders came up with a solution: a Chrome extension that prevents certain domains from changing the input levels.

After installing that from the Chrome Web Store, I navigated to Google Meet, activated the extension, and gave it permissions on that domain. The page refreshed, and the issue was resolved: no more adjusted input levels and no more unwanted muting.

It’s great that there are creative solutions like this available, h/t Joey Watts, but its frustrating that issues like this can go unresolved for so long on popular projects like Google Chrome.

Happy resolving!

My best Slack emojis

Sean McPherson — Tue, 04 Jan 2022 16:00:00 GMT

I like reaction emojis and have spent an embarrassing amount of time making new ones for myself and my coworkers. These are some of my creations that were popular or just my favorites:

Image	Name
	`:ack:`
	`:all-in-this-together:`
	`:all-seeing-eye:`
	`:avalanche:`
	`:awe:`
	`:do-it:`
	`:does-not-equal:`/`:dne:`
	`:eagle-eye:`
	`:frankensteins-monster:`
	`:good-point:`
	`:good-question:`
	`:interesting:`
	`:its-alive:`/`:frankenstein:`
	`:nail-biter:`
	`:nerves:`
	`:nice-catch:`
	`:not-crying:`
	`:ope:`
	`:save-your-money:`
	`:shakes-head:`
	`:shivers:`
	`:so-close:`
	`:team:`
	`:this:`
	`:this-week-i-learned:`/`:twil:`
	`:thumbs-down:`
	`:too-big:`
	`:very-interesting:`
	`:yuck:`
	`:yikes:`

Feel free to take inspiration or add to your workspace.

Happy reacting!

Helpful online tools for diagramming

Sean McPherson — Wed, 15 Dec 2021 16:00:00 GMT

A good diagram can make a big difference when communicating a message. I often turn to a diagramming tool when trying to explain a complex idea or organize my thoughts when brainstorming. Thankfully, there a bunch of online tools to help you make quality diagrams. Here are a few options for your to use:

Excalidraw

Excalidraw makes it easy to create quick diagrams that look sketchy. It saves your changes to local storage (which is super handy), and supports a backup option to download/upload an illustration. There is a live collaboration feature that I haven't tried, and some premium offerings with Excalidraw+.

TL Draw

TL Draw has a similar feature set to Excalidraw but diagrams look a little more neat and tidy. Depending on the style you are aiming for, this may be the better option for you. The biggest difference is that your changes are not saved to local storage; so make sure to backup your illustration!

Draw.io

Draw.io makes creating diagrams and flowcharts easy and painless. It supports a lot of different element options and seems to be a go-to option for diagramming complex microservice systems. It has a desktop application and backs up to the cloud. My only criticism is that the illustrations from Draw.io are not pretty; it's definitely function over form.

Google Drawings

One of the forgotten tools of Google Drive, Drawings is an adequate option for simple diagrams. If you or your organization are already using Google, it will be the easiest option if not the most inspired.

If you have any other suggestions to add to this list, please let me know.

Happy diagramming!

What is a build.gradle file?

Sean McPherson — Thu, 04 Nov 2021 16:00:00 GMT

When working on a React Native app, you will probably make some changes to the build.gradle file in your projects android/ directory. This file is the core component of your build process and has all of the instructions necessary to compile an Android app from source.

Your build.gradle file is read and executed by Gradle, an automation tool that is popular in Java development. Gradle's job is to resolve the dependency tree of your application and run everything through the Java compiler to generate code that can be run in the Java Virtual Machine (JVM). All of that work is divided in to tasks that can be mixed and matched as needed.

The nearest equivalent in the world of web development might be Gulp, a composable task runner,, or perhaps Webpack, a bundler. But build.gradle also manages dependencies, so mix a little bit of package.json in there too. Essentially, build.gradle is the main configuration file for your Android project.

When you look at a build.gradle file through the lens of a web developer, it looks like a bunch of nested objects with a few method calls. However, that is completely wrong!

build.gradle files are often written in Groovy, which is its own Java-based programming language. What looks like an object declaration in JavaScript is actually a function call in Groovy. Let's take a look at the following block:

repositories {
    google()
    maven { url 'https://www.jitpack.io' }
}

Here we are calling the repositories function and passing a closure, identified by the curly brackets {}. Within that closure, we are calling more functions: google with no parameters, and maven with another closure and another function url.

I'm still working to wrap my head around closures, but the takeaway here is that there is more going on that you might first assume.

The best part about using a programming language for a build configuration file is that you can add variables and functions as needed. Variables and functions can be defined with the def keyword customize the build process:

def version = "1.2.3"

def customFunction() {
    println "Building v${version}!"
}

customFunction()

The last bit of information you should know about build.gradle is that all of the tasks are executed via a wrapper. This is the executable gradlew (Linux/Mac) or gradlew.bat (Windows) file that is included in your project. By running everything through the wrapper, you remove the need to have Gradle installed on your computer.

To start the build task, run the following in your terminal:

./gradlew build

Hopefully that demystifies the build.gradle file in your Android/React-Native project a little bit. This is not yet my area of expertise, so please let me know if I need to make any corrections.

Happy building!

Three new games on Toollama

Sean McPherson — Wed, 27 Oct 2021 16:00:00 GMT

I don't think I've written about Toollama.com yet on this site, so here's a quick introduction. Toollama is a loose collection of education-focused productivity tools and games. For the past year, it has been the home of all of the little apps that I create for myself, teachers, or my kids.

Over the past three weeks, I have created two new games and one new activity to help children develop core computer skills:

🐢 Turtle Guide: Use the arrow keys to help a little turtle find his way home
🐷 Paint Pig: Use the arrow keys to help Pig paint a picture
🔦 Spotlight: Use the mouse/trackpad to reveal animals hidden in color nature scenes

From a technical perspective, these are all vanilla JS, CSS, and HTML served from GitHub Pages. I've found that solving problems with simple tools has been a relaxing change of pace from the complex environments of work. As always, the code is open source on GitHub: turtle-guide, paint-pig, and spotlight.

These additions bring the grand total on Toollama up to 13 apps! Check it out, if you haven't already.

Happy learning!

React Native Glossary

Sean McPherson — Thu, 07 Oct 2021 16:00:00 GMT

Building applications with React Native requires a high-level understanding of mobile development on Android and iOS devices in addition to React and React Native fundamentals. This glossary of terms will serve as a helpful reference when working across these environments.

AAB

Android App Bundles (AABs) are a new format for publishing applications on Android. AABs can contain multiple APKs. Since August 2021, Google Play requires AABs for new apps.

About Android App Bundles (Android)

APK

Android Package Kits (APKs) are an older format for publishing applications on Android.

`build.gradle`

A build.gradle file contains all of the information for Gradle to compile Android apps, including dependency resolutions and tasks to process the source.

What is a build.gradle file?

Gradle

Gradle is an automated build tool that is used to compile Android apps from source code. It is configured in build.gradle files and run through a wrapper: gradlew/gradlew.bat.

Hermes

Hermes is a mobile-optimized JavaScript engine that is included in React Native builds for Android and iOS.

`Info.plist`

The information property list or Info.plist is an XML file that contains all of the configuration data for your application. You can update these values directly or through the Xcode UI.

About Info.plist Keys and Values (Apple)

JavaScriptCore/JSCore

JavaScript Core or JSCore is a JavaScript engine that is included on iOS devices. It was included in Android builds to run JS code by React Native versions prior to 0.60. It has since been replaced with Hermes.

JavaScriptCore (Apple)

SDK

Software Development Kits (SDKs) are bundles of code to add to your application. Third parties will often have an SDK to integrate with their service.

What happened to @react-native-community packages?

Sean McPherson — Tue, 05 Oct 2021 16:00:00 GMT

When React Native was first released, it included extra modules that were helpful for mobile development like WebView, NetInfo, and AsyncStorage. Later in 2018, the RN team made the decision to deprecate those internal modules and hand them off to the community to maintain.

This spawned the @react-native-community organization on GitHub and a number of community-maintained packages like react-native-webview and react-native-netinfo. If you were working in React Native in the late 20-teens, you probably remember adding these dependencies and switching out imports.

In most cases, the community proved capable to maintain current packages and continue development. However, some packages were abandoned as requirements changes or maintainers moved on. Alternative options popped up and gained the support of the community, driven by individual developers or those at different organizations like Expo, Wix, Callstack, or Software Mansion.

Developers who were new to React Native might defer to @react-native-community packages, not because they were better than those alternatives but because they appeared to be "the approved solution" from the community. That wasn't ideal for developers, which might end up with unmaintained projects, nor for the greater React Native community that was driving things forward.

At the end of 2019, the @react-native-community decided to move modules out of the organization and into individual project organizations. In the words of one maintainer:

These modules aren't being maintained by fewer people, and aren't any less supported. But now perception can match the reality.

As a result, scoped packages like @react-native-community/async-storage moved to react-native-async-storage/async-storage. But besides the name, little to nothing else changed about how they were maintained.

By offloading packages, @react-native-community is free to focus on higher-level goals for the community, like tools to discover and maintain high-quality React Native packages. Two projects still owned by the community organization are upgrade-helper and React Native Directory, both exemplifying its new focus.

So while you won't be adding @react-native-community packages to your projects going forward, that is ultimately for the best. Instead, use resources like React Native Directory or awesome-react-native to find the best solution for you and your application.

Find an iOS simulator identifier

Sean McPherson — Mon, 04 Oct 2021 16:00:00 GMT

When running a device simulator on macOS, it is possible to navigate that system's directly through the command line (or Finder, if you'd prefer). To do that, navigate to to the following directory:

cd /Library/Developer/CoreSimulator

If you look around in this directory, you will probably see a number of subdirectories with UUIDs. Each of these corresponds to a simulator device which contains all of the data for that instance. In order to browse a specific simulator's files, you need to know its ID.

There are two ways to find that, one using the Xcode UI and another using the terminal.

Through Xcode

In the top menu, select "Window" > "Devices and Simulators"

You can use the shortcut shift+command+2.

In the left menu of the new window, select the "Simulators" tab
Select the device from the list below

Note: Make sure you match the device specs and iOS version

Look for "Identifier:" in the main panel and copy the value

Through the terminal

The following command require Xcode command-line tools, which you probably already have installed if you are running Xcode.

From anywhere on your system, run xcrun simctl list devices
Find the ID from the output by iOS version and device specs and copy the ID

If the device is already running, you can save yourself some time by passing a search argument:

# Show only running simulators
xcrun simctl list devices booted

That should surface the current simulator faster for copying.

Take a look around!

Once you have the simulator ID copied, you can navigate there in the terminal with:

cd /Library/Developer/CoreSimulator/SIMULATOR-ID-THAT-YOU-COPIED

For example, if you want to look into a specific app's bundle, you can find that data within the simulator directory at ./data/Containers/Bundle/Application/APP-ID. I have found this useful when debugging image paths in the final app bundle.

Happy browsing!

Using BEM names in React Native

Sean McPherson — Fri, 10 Sep 2021 16:00:00 GMT

When writing CSS classes, I prefer BEM's naming system. The pattern is clear to read and names are easy to generate. I believe the unwieldy length of some names is offset by the benefits.

React Native doesn't use CSS but JSON-based stylesheets that are applied directly to elements. This system has some advantages, notably co-locating concerns within the component file.

But you still have to name things within you style objects, and I find myself reaching for BEM even when removed from CSS.

For a quick overview of BEM, checkout the official documentation. The page is pretty short and summarizes the system with images. Okay, 1... 2... 3... I'm going to assume you're familiar with BEM.

To be fair, this is perfectly valid JavaScript and works out of the box:

const styles = StyleSheet.create({
    message: {},
    'message--warning': {},
    message__text: {},
})

<View style={[ styles.message, type === 'warning' && styles['message--warning'] ]}>
    <Text style={styles.message__text}>{text}</Text>
</View>

Here I'm following the pattern from BEM of naming blocks at the top level, using underscores for elements within a block, and hyphens for modifiers. And again, this works fine.

But I really dislike using strings as properties for an object. They're annoying to create and even worse to reference. And when we use hyphens to create modifier names, we're stuck with styles['message--warning']. I just want to use BEM without the added discomfort of string keys. What are our alternatives?

Turns out, there aren't many options. The underscore is taken, and most special characters are not valid in object properties. Numbers are an option, but none of them seemed to fit. The only other option on my keyboard was, perhaps surprisingly, the dollar sign: $. (Side note: Are all currency symbols valid for object properties?)

jQuery and Svelte both use the $ symbol for JavaScript, so why not here in React Native? If we swap double hyphens for double dollar signs in the previous snippet, we get:

const styles = StyleSheet.create({
    message: {},
    message$$warning: {},
    message__text: {},
})

<View style={[ styles.message, type === 'warning' && styles.message$$warning ]}>
    <Text style={styles.message__text}>{text}</Text>
</View>

Not bad. And I'd much rather use a slightly foreign symbol in a familiar system than string properties.

What do you think: good idea or bad idea? Or should I just use styled components already? Or maybe something else entirely? Let me know.

Until then, happy naming!

Reflecting on a new role

Sean McPherson — Wed, 18 Aug 2021 16:00:00 GMT

Recently I accepted a new position at Niche as a senior mobile software engineer. I will take the reigns of our mobile app (Android, iOS) and work on a dedicated product team building new features for our users. This is a shift in focus for my career but not uncharted territory.

While working for TSYS in 2018, I helped work on an unnamed mobile app in the consumer finance space. After joining Niche in 2019, I helped implement Apple Sign-In in our app and resolved some other issues. Now that I am fully dedicated to working on the mobile app, I'm looking forward to building new things and learning lots along the way.

I'm going to start sharing more mobile and React Native articles on this site as I learn. The first of those came out earlier this week: What is Hermes in React Native?. Some of the information may be applicable in React contexts, so I'll try to tag articles appropriately.

That said, I'm not leaving the web world entirely. A Chrome extension for teachers that I launched in 2018 has over 10,000 weekly users during the school year, and I just released a new version with some great features. I'm committed to continued development on that and all the other tools I've created.

I am so grateful for the opportunities that I have been given in software development. From the ability to attend a coding bootcamp full-time, to that first developer job with TSYS, to a new position closer to home with Niche, and now greater acclaim and responsibility at a company that is going places. If any one of those doors had been closed, then my situation now could look completely different.

It's humbling to remember that I don't deserve any of this; it's ultimately grace. But now my responsibility is to do the best I can with all that God has given me. To Him be the glory, now and forever. Amen.

If you're reading this and have experience working in mobile development or with React Native, then please reach out. I'd love to pick your brain for a bit.

Happy coding!

What is Hermes in React Native?

Sean McPherson — Tue, 17 Aug 2021 16:00:00 GMT

React Native is framework for building Android and iOS application using React and native capabilities. It allows developers to write JavaScript code that will interact with platform APIs and native components to build interactive user interfaces.

To accomplish that, React Native needs an engine to run JavaScript code on mobile devices. Apple includes JavaScriptCore (JSCore) on iOS devices, but Android does not have a JavaScript engine.

So React Native included a version of JSCore in Android builds to execute JavaScript. This resulted in larger Android application packages (APKs) for React Native apps, and some noticeable performance issues.

In 2019, the React Native team announced Hermes as "a new JavaScript engine optimized for React Native." Android apps built with React Native and Hermes were smaller, interactive faster, and used less memory.

React Native version 0.60.1 (2019) replaced JSCore with Hermes for Android builds. Later in version 0.64 (2021), React Native added support for Hermes on iOS. With one small change to your project's Podfile, you can include Hermes to improve your app's performance:

use_react_native!(
   :path => config[:reactNativePath],
   # to enable hermes on iOS, change `false` to `true` and then install pods
   :hermes_enabled => true
)

You'll want to do some profiling of iOS apps with JSCore and Hermes before committing to the change, but it is exciting to see more alignment between the two platforms.

To read more information about to use Hermes and how to debug it, check out the documentation.

Happy coding!

What is the song from Boston Dynamic's Spot Launch video?

Sean McPherson — Tue, 10 Aug 2021 16:00:00 GMT

My three-year-old son really likes Boston Dynamics videos. He frequently requests to watch them and will parade around the house as Spot, Atlas, or Stretch/Handle. As far as little kid fixations on machines go, I think robots are a pretty cool option; he's much more likely to work on/with robots in the future than steam engines!

One video he likes is Spot Launch, which features the titular robot navigating through a bunch of simulated work environments. It's an entertaining video, and my son really likes dancing to the song.

The song wasn't listed in the video description, and I couldn't find an answer via a Google search. I did find two unanswered and archived questions on Reddit asking for help identifying the song.

With my wife's help, I tried using the Google app's music recognition feature. I played the YouTube video on my phone, and she let the app listen on hers. Within 5 seconds, Google had identified the song as Banana by Stony Pony. Neat!

Here are the two videos for comparison:

https://www.youtube.com/watch?v=tZaAmapkp4Q

https://www.youtube.com/watch?v=wlkCQXHEgjA

The version in the Boston Dynamics video has removed the word "Banana" a few times, but it is otherwise the same song.

It's too late to answer those Reddit questions, but I added a comment to the video on YouTube. And hopefully the next person searching stumbles upon that or this article.

Happy listening!

Add a YouTube-embedder shortcode to your Eleventy site

Sean McPherson — Tue, 10 Aug 2021 16:00:00 GMT

For a recent article, I wanted to add some embedded YouTube videos. Through the share menu beneath the video, you can select "Embed" to copy and paste the code for an iframe that will load the YouTube video.

That works well, but if you want to customize that code at all for embedded videos, you need to remember to do that every time you copy and paste it into one of your pages. Rather than fiddling with that, I decided to create a custom shortcode to handle all of that for me.

Here is the code for my Eleventy site, but with a little tweaking you could make this work for any static-site generator:

// .eleventy.js
module.exports = (eleventyConfig) => {
  eleventyConfig.addShortcode("youtube", (videoURL, title) => {
    const url = new URL(videoURL);
    const id = url.searchParams.get("v");
    return `
<iframe class="yt-shortcode" src="https://www.youtube-nocookie.com/embed/${id}" title="YouTube video player${
      title ? ` for ${title}` : ""
    }" frameborder="0" allowfullscreen></iframe>
`;
  });
};

I removed a lot of the default permissions from the YouTube embed code, and opted for youtube-nocookie.com instead to save my visitors from some tracking. You can read more about that on Dries Buytaert's blog.

With that shortcode added, you can use it in any of your template files with the {% youtube %} syntax:

<!-- With title -->

{% youtube "https://www.youtube.com/watch?v=DhKHAopx7D0", "'Time Bomb' by
Rancid" %}

<!-- Without title -->

{% youtube "https://www.youtube.com/watch?v=LnaeImQ0TSg" %}

Finally, I added a bit of CSS to help the videos look good on my site. These styles might be different for your site:

iframe.yt-shortcode {
  height: 50vw;
  margin: 1rem 0;
  max-height: 25rem;
  width: 100%;
}

Now if I want to change the way I handle YouTube embeds, I need only to change the code in one place. Hope that helps!

Happy embedding!

Get innerHTML of Enzyme wrapper

Sean McPherson — Mon, 12 Jul 2021 16:00:00 GMT

In Enzyme, wrapper's have a handle .html() method that will return the outerHTML for that element in the tree. It's handy in the rare instance when the markup that your code outputs needs to be precise. You can read more about in the documentation.

However, there isn't a method that returns the innerHTML. A use case I came across for this was caring about the children of an element, but not caring about the element itself. I didn't want this test to fail if I needed to add an attribute to the parent element, only if the children changed.

So I wrote this little helper function to grab the innerHTML of a shallow wrapper in Enzyme:

function getInnerHTML(node) {
  return node.children().reduce((string, node) => {
    // A text node's html method doesn't return
    // anything, so we use text instead.
    return string + node.html() || node.text();
  }, "");
}

There might be other strategies using some of Enzyme's built-in methods like .reduce() or .forEach(), so let me know if you come up with a better alternative.

Happy testing!

Use remark to covert markdown into HTML

Sean McPherson — Sat, 03 Jul 2021 16:00:00 GMT

I've used remark in a few different projects, and each time I found it difficult to get started. For such a popular project, the documentation is quite terse.

To save myself the trouble of looking up how to do it in the future, here are the basic steps you need to get started converting markdown to HTML with remark.

First, install remark dependencies:

npm i remark remark-html

We will need the core library and a plugin for generating HTML. Then, import your dependencies and use them like so:

import remark from "remark";
import remarkHTML from "remark-html";

const html = remark().use(remarkHTML).processSync("Some **markdown** text");

That's all you need to get going. To help jump-start your progress, checkout this working repl in Node.js or sandbox in React.

Hope this guide helps you get up and running too!

Happy coding!

Count class methods in JavaScript

Sean McPherson — Mon, 21 Jun 2021 16:00:00 GMT

If you have a class in JavaScript and want to know the number of methods it contains, there are a few steps that you need to follow.

Let's say we have a class like the following:

class Pet {
  constructor(name) {
    this.name = name;
  }

  call() {
    console.log(this.name + " comes running");
  }
}

We don't have handy tools like Object.keys() for classes, so to count the number of methods in our Pet class, we need to first create an instance:

const abby = new Pet("Abby");

Now we can pass our instance to two Object methods that will grab the methods for us:

Object.getOwnPropertyNames(Object.getPrototypeOf(abby));

This returns an array of property names for the prototype of abby, which is the following:

["constructor", "call"];

If you're dealing with a simple class like the example above, you can add a .length to the end of the returned array and be done.

However, if you are dealing with subclasses, you may want to go a little deeper.

Let's update the example so that the class who's methods you want to count extends another:

class Pet {
  constructor(name) {
    this.name = name;
  }

  call() {
    console.log(this.name + " comes running");
  }
}

class Dog extends Pet {
  pet() {
    console.log(`${this.name} wags its tail`);
  }
}

Now if we try the following code with abby the Dog, we get a different answer:

const abby = new Dog("Abby");
Object.getOwnPropertyNames(Object.getPrototypeOf(abby));
// ['constructor', 'pet']

We lost the methods on the parent Pet class. To grab those too, we can create a reusable function to dive through the prototype chain:

function countClassMethods(_class) {
  const methods = new Set();
  let keepDiving = true;
  let prototype = Object.getPrototypeOf(_class);

  while (keepDiving) {
    Object.getOwnPropertyNames(prototype).forEach((name) => methods.add(name));
    prototype = Object.getPrototypeOf(prototype);

    if (!prototype.__proto__) keepDiving = false;
  }

  return methods.size;
}

This function takes a class and grabs its prototype. Then in a while loop, it iterates through the prototype's property names and adds them to a set. It then looks ahead to the next prototype to determine whether it should continue. If the next prototype's __proto__ property is falsy, then leave the loop and return the size of the set.

If you want to see a list of the methods, you could rename the function and return [...methods] or do something with method.values().

Now when I call my function with an instance of the Dog class, I get the answer that I'm expecting:

const abby = new Dog("Abby");
countClassMethods(abby); // 3
// Values: ['constructor', 'pet', 'call']

This is a pretty niche scenario, but I hope that is helpful for someone else.

Happy counting!

A modest redesign for 2021

Sean McPherson — Tue, 15 Jun 2021 16:00:00 GMT

It had been a minute since I last worked on the design for this site, so I decided to make some changes for 2021. I didn't want to undertake anything major – just tweak a few things to freshen everything up.

A few of the changes are a return to previous designs: I brought the scroll progress bar (top of the screen) and centered the content. I lightened the default background color and reduced the size of the headings.

There are two new features that I added, and the most notable of which is the light/dark mode toggle in the header. Under the hood, this is a checkbox with a change event listener that persists state in localStorage. The boxes are 100% CSS with ::before and ::after pseudo elements with a small transition. Pretty neat what can be done with CSS and a teeny bit of JavaScript!

The other new feature is a search listbox on /articles. Rather than implement something super complex, I opted for a search input with a datalist of articles. I added an event listener that redirects when an article is selected. You can view the implementation in article-search.js. This is a pattern that I've used twice now and might warrant its own article.

Beyond that, I updated some of the copy, changed the links in the header, included a picture to the /about page, and added a new page for my work availability (hey recruiters!).

Overall, I'm pretty happy with how the redesign turned out. We'll see how long that contentedness lasts!

Happy reading!

Latin phrases to know

Sean McPherson — Mon, 07 Jun 2021 16:00:00 GMT

Moved to gardens.

Handy git commands

Sean McPherson — Tue, 04 May 2021 16:00:00 GMT

Here are some of the git commands that I find useful when doing by work as a software engineer. Hopefully you will find them helpful too!

Commands

`git checkout -`

Quick: Checkout the previous branch

This is super handy when working with long or unwieldy branch names. With the - reference, you can convert the following set of commands into a reusable alias:

git checkout dev && git pull && git checkout - && git merge dev

`git checkout -- .`

Quick: Delete all changes in the current branch

When you just want to start from scratch on the current branch, this command is a huge timesaver. The -- refers to the current branch, while the . refers to all files. If you want to reset a particular file, you could swap the name with the ..

`git commit -m "init" --allow-empty`

Quick: Create a commit with no changes

When starting on a development task, sometimes it's nice to set up branches and PRs before getting started on the work. The --allow-empty flag enables you to create commits without changing any files.

I use this when I have a feature branch that will be the target of bunch of smaller branches. Initializing a those with an empty commit helps be get organized in the beginning.

`git diff branch_name -S "TODO:"`

Quick: Search the diff between the current branch and branch_name for all strings matching TODO:

When working on a new feature, I like to leave myself todos to address before the branch is merged. Tracking these down can be tricky because there are other TODO:s in the codebase. I used to grep through the diff, but git's -S flag is much easier.

`git diff branch_name -G "/*-action"`

Quick: Search the diff between the current branch and branch_name for all strings matching the /*-action RegEx pattern

Similar to the -S flag, -G lets you search through the diff using RegEx. I don't know too much about regular expressions, but it's nice to have the option in your toolbelt.

`git log --before="2021-01-01 00:00"`

Quick: Limit the log output to all commits before the provided date.

This is handy when you want to look at commits from a particular date or before a date (and/or after with --after=).

Let me know if you have any commands to add to the list.

Happy versioning!

Read URL search parameters with JavaScript

Sean McPherson — Sat, 01 May 2021 16:00:00 GMT

Search parameters, or query strings, are handy ways to store data on URLs. JavaScript provides an interface for reading search parameters called URLSearchParams. To use it, create an instance with the new keyword and pass your search parameter string as an argument:

let params = "?name=Sam&name=Ezra";
let usp = new URLSearchParams(params);

The returned URLSearchParams object has a few a bunch of useful methods, but we're going to focus on three:

get(): Returns the first value for a particular key
getAll(): Returns all of the values for a particular key
forEach(): Iterates over keys with a callback that receives value and key

If I call the get() method for name, then it will return the first value from my search parameter string:

usp.get("name");
// 'Sam'

When you are dealing with unique parameters, this method is all you need to get the job done. But in our example, there are multiple names being passed. To retrieve all of those values, we will call getAll() with name:

usp.getAll("name");
// ['Sam', 'Ezra']

If you are working with a few exact keys, you can probably stop there. But if you are dealing with a lot of keys or just want an easier way to read search parameters, you can use a helper function that iterates over all of the keys and stores them in an object:

/**
 * Read the search parameters from window location
 */
function readSearchParams() {
  let usp = new URLSearchParams(window.location.search);
  let params = {};
  usp.forEach((value, key) => {
    if (!params[key]) {
      params[key] = [];
    }
    params[key].push(value);
  });
  return params;
}

Then call the function whenever you need to reference the current location's search parameters:

// https://seanmcp.com/articles/read-url-search-parameters-with-javascript/
// ?greeting=Hello&name=World
let params = readSearchParams();

params.greeting;
// ['Hello']
params.name;
//['World']

To see it in action, try going to that url, or try adding your own search parameters.

Happy reading!

Fix 'downloadable font: rejected by sanitizer' error in Firefox

Sean McPherson — Thu, 01 Apr 2021 16:00:00 GMT

I ran into an issue today when I tried to serve a typeface I downloaded from Google Fonts. When I added the files and @font-face rules to my CSS, I got the following error in the Firefox console:

downloadable font: rejected by sanitizer
    (font-family: "Inter" style:normal weight:400 stretch:100 src index:0)
    source: http://localhost:8080/fonts/Inter-Regular.ttf

The Chrome console had nothing, so I figured this was a Firefox issue. After some searching around, I learned that Firefox is checking that a font file is valid before loading it, which can protect you against some attacks.

Inter is a pretty popular typeface, so I ruled out corrupt or malicious font files. Further digging lead me to some solutions, but they seemed situation specific.

I was prepared to live with the error, when I gave it one last look. The source url (which I've wrapped here but was broken on two lines in the console) was incorrect. The path to the font files should have been assets/fonts/Inter-Regular.ttf. Fixing that path in @font-face's src resolved the issue.

If you encounter a similar error, check to make sure that the path to your font file is correct. It would be helpful if the message was more descriptive: "downloadable font: rejected by sanitizer (file not found)".

Happy font serving!

Fix Netlify CMS YAML error 'Implicit map keys need to be on a single line'

Sean McPherson — Thu, 25 Mar 2021 16:00:00 GMT

When trying to setup Netlify CMS on a project, I kept getting this error on the /admin page:

Error loading the CMS configuration
Config Errors:

YAMLSemanticError: Implicit map keys need to be on a single line at line 1, column 1:

<!DOCTYPE html>
^^^^^^^^^^^^^^^…

Check your config.yml file.

I checked and doubled checked the YAML in my config.yml file, and everything was valid. I went through the Netlify Identity steps to verify that they were followed correctly, but that didn't help either.

Googling the error message brought up nothing useful.

Then it occurred to me: "What if Netlify CMS isn't getting the config file at all?"

Sure enough, my static-site generator was skipping the unrecognized .yml file when building the site. I added the configuration to copy that file to the build folder, and voilà: everything works as expected.

So if you are getting the same error, check to make sure that the config.yml file is making it to your built admin/ directory.

Happy debugging!

COVID-19 journal

Sean McPherson — Wed, 24 Mar 2021 16:00:00 GMT

I tested positive for COVID-19 in November of 2020, a few weeks after the birth of my second son. My wife was the first in our household to show symptoms, and I followed a few days later.

Most of my symptoms were mild. I had full-body aches and congestion but no fever nor loss of taste. The most dramatic symptom was fatigue that came in waves for the duration of my illness. I would go from feeling mostly fine, to feeling like I didn't have the energy to situp, then back to mostly fine in the span of thirty minutes. I'm thankful that I was on parental leave for the whole duration of my illness, because I would have been unable to work effectively through the waves of fatigue.

Once I recovered, that seemed to be the end of it. I warned by coworkers to take the virus seriously (they already were) and tried to be especially careful during the holidays.

Fast-forward to March of 2021, and now a new symptom has emerged. There are now certain scents that have changed for the worse: bananas, toothpaste, and shampoo. They all share the same smell, and it is quite unpleasant. A kind of savory/overly-ripe odor that I am keen to avoid. I used to eat a banana a day (or more), and now I can't stand to be too near to them.

I have heard that some people report a return to normal taste and smell after being vaccinated. Hopefully that is true, because I'd really like to enjoy eating bananas and brushing my teeth again.

In April of 2021, I got the first round of the Moderna COVID-19 vaccine. By the following morning, I experienced some typical "flu-like" symptoms: fatigue, full-body soreness, and skin sensitivity. The injection site – my left shoulder – was especially sore. By day two, most of the symptoms had resided.

Bananas, shampoo, and toothpaste still smell odd but to a lesser degree. I'm optimistic that that will improve in the coming weeks! The second round of vaccination is scheduled for early May – four weeks after the first round. By then, Lord willing, I'll be back to a banana a day!

Copy the last git commit hash on macOS

Sean McPherson — Wed, 24 Mar 2021 16:00:00 GMT

When responding to code-review requests, I like to point the reviewer to the specific commit where the issue was addressed with a message like:

Fixed in 4908c91a06258814077b1358210eb78cc718609c

GitHub will automatically detect the hash, shorten it, and convert it into a link to the commit view.

Rather than going into git log and copying the hash manually, I use the following one-liner in the terminal on macOS:

git rev-parse HEAD | pbcopy

The first half of the command returns the last commit hash from HEAD, which is a reference to the current branch. You could use git rev-parse name_of_branch too, but that is often longer to type.

The output of git rev-parse is then piped to pbcopy, the clipboard utility for macOS. If you were using a different platform like Unix or Windows, there are other options for you.

To save some more time, I added an alias my shell's rc file:

# git last commit (hash)
alias glc="git rev-parse HEAD | pbcopy"

Happy copying!

Add Heroicons to an Eleventy site

Sean McPherson — Tue, 09 Mar 2021 16:00:00 GMT

In a recent Eleventy project, I wanted an easy way to add Heroicons. That lead me to creating an Eleventy plugin that adds some handy Heroicon shortcodes. Here's how to get started:

First, install eleventy-plugin-heroicons:

npm i -D eleventy-plugin-heroicons

Then, add the plugin to your .eleventy.js settings file with any other plugins:

// .eleventy.js

module.exports = (eleventyConfig) => {
  eleventyConfig.addPlugin(require("eleventy-plugin-heroicons"));
};

With that in place, you are ready to use the heroicon shortcode. Head over to a markdown or template file and try it out:

<!-- contact.md -->

- {% heroicon "outline", "mail" %} Send me an email

Note: These examples are using Nunjucks syntax. If you are using Liquid, you can reference the official documentation for examples.

The heroicon shortcode takes a few arguments:

The style of icon (outline or solid)
The name of the icon
An optional alt tag for the SVG

To save yourself a bit of time, you can use the heroicon_outline or heroicon_solid shortcodes which pass the style automatically. We could replace the previous example with:

<!-- contact.md -->

- {% heroicon_outline "mail" %} Send me an email

And it would work the same.

If you use the shortcode without alt text, and aria-hidden="true" attribute is applied to the svg element. When alt text is provided, a title element is added as the first child to the svg:

<!-- Input -->
{% heroicon_outline "heart", "Love" %}

<!-- Output -->
<svg
  xmlns="http://www.w3.org/2000/svg"
  fill="none"
  viewBox="0 0 24 24"
  stroke="currentColor"
  data-heroicon-name="heart"
  data-heroicon-style="outline"
>
  <title>Love</title>
  <path
    stroke-linecap="round"
    stroke-linejoin="round"
    stroke-width="2"
    d="M4.318 6.318a4.5 4.5 0 000 6.364L12 20.364l7.682-7.682a4.5 4.5 0 00-6.364-6.364L12 7.636l-1.318-1.318a4.5 4.5 0 00-6.364 0z"
  />
</svg>

This will enable screen-reader and other assistive technology users to understand what the icon represents. Without an alt tag, you'll want to make sure that the meaning can be derived from context:

<button>
  {% heroicon_solid "plus" %}
  <span>Add item</span>
</button>

<button>
  {% heroicon_solid "x" %}
  <span class="visually-hidden">Close menu</span>
</button>

All of the icons have data-heroicon-name and data-heroicon-style attributes applied to the svg that you can use for styling:

[data-heroicon-style="outline"] {
  width: 24px;
}

[data-heroicon-style="solid"] {
  width: 20px;
}

[data-heroicon-name] {
  padding: 2px;
}

If you'd prefer to use a class name, you can pass one on a configuration object while adding the plugin:

// .eleventy.js

module.exports = (eleventyConfig) => {
  eleventyConfig.addPlugin(require("eleventy-plugin-heroicons"), {
    className: "icon",
  });
};

There is also an option to errorOnMissing icons, which might be nice to ensure that all icons display as intended.

Hopefully that helps! Let me know if you have any suggestions for the package. PRs are most welcome 😊.

Happy coding!

Create a URL shortener with Netlify

Sean McPherson — Fri, 26 Feb 2021 16:00:00 GMT

After hearing of a few people doing the same, I set up a mostly-free URL shortener with Netlify: smcp.dev. Here's the steps I followed to get it done.

1. Register a domain

Go to your favorite registrar and buy a new domain. Aim for something short and memorable, and consider the .link TLD. I heard a recommendation for Hover, which seems pretty cool, but I went with Google Domains for smcp.dev.

This is the only step that costs money, and the amount will depend on the domain/TLD that you choose. .dev TLDs on Google Domains cost $12/year.

2. Create a repo

I modelled my repo off of cassidoo/cass.run, which seems to be based off of kentcdodds/netlify-shortener-example. In order of importance, you have:

a _redirect file that maps short urls to destinations,
a package.json with a single (optional) dependency for adding links,
a README.md,
and some git stuff.

3. Add your project to Netlify

Build command: Nothing
Publish directory: Nothing

4. Setup your custom domain

In the main project view on Netlify, select "⚙️ Domain settings", then "Add custom domain". Enter the domain that you registered in step one and go through the flow.

You'll need to update the DNS settings with your registrar to point to Netlify's servers:

dns1.p05.nsone.net
dns2.p05.nsone.net
dns3.p05.nsone.net
dns4.p05.nsone.net

5. Wait

Depending on how quickly you went through steps 1-4, you may have to wait a few hours for everything to get setup from registrar and the DNS. For me, this took about thirty minutes, but your mileage may vary.

6. Enjoy

With all that in place, you should be able to use your URL shortener: smcp.dev/yt! To add a new URL, you can add a new line to the _redirect file manually or use the shorten script(if you added it)

Happy shortening!

Set innerHTML of an element in Svelte

Sean McPherson — Thu, 25 Feb 2021 16:00:00 GMT

When working on a Svelte application, I wanted to replace newline characters in a string with <br> elements and render the result as HTML. If you do the replace in your component markup, then the rendered output has escaped angle brackets:

<!-- Component.svelte -->
<p>{notes.replace(/\n/g, '<br />')}</p>

<!-- Output markup -->
<p>Line one&lt;br&gt;Line two</p>

From previous experience, I know that we're not rendering the replaced string as HTML, so I tried searching online for a solution involving innerHTML.

In the Svelte API docs, there are only three mentions of innerHTML, two of which refer to bindings with contenteditable elements. But I wanted to set the innerHTML of an element that would never change.

While searching through the Svelte Discord for innerHTML, I came across an unrelated post that mentioned {@html}. I had never encountered this before, so I looked it up in the Svelte docs^[1]:

In a text expression, characters like < and > are escaped; however, with HTML expressions, they're not.

Not the longest explanation, but that sounds like my problem. Back in my code, I tried wrapping the replaced text with {@html}:

<!-- Component.svelte -->
<p>{@html notes.replace(/\n/g, '<br />')}</p>

<p></p>

With that, everything rendered as expected:

<!-- Output markup -->
<p>
  Line one<br />
  Line two
</p>

So next time you want to set the innerHTML of an element in Svelte, use an HTML express with {@html}.

Happy escaping!

https://svelte.dev/docs#html ↩︎

Let's stop skinning cats

Sean McPherson — Thu, 18 Feb 2021 16:00:00 GMT

Idioms are interesting. They're phrases that have a functional meaning that is independent of their literal meaning. In English, we have idioms like "beating around the bush," which means to avoid saying what you really mean because it's uncomfortable ^[1].

When I was teaching a classroom of first- and second-generation Americans, we explicitly taught idioms so that students would understand the form if not remember examples when reading or speaking with others. I had an illustrated poster on the wall with some common US idioms.

Someone could certainly go on a crusade to rid a language of idioms. "Why say something purposely incorrect when you really mean something else?" they could argue. I'm not going to go that far; I think learning of idioms in other languages in kind of neat. That said, there is one English idiom that I would like to remove:

There is more than one way to skin a cat. 😿

If you are unfamiliar, the idiom means that there are multiple ways to complete a particular task. Since that is an axiom of sorts in programming, I see the idiom used relatively frequently.

Where it differs from an idiom like "barking up the wrong tree," is that the literal meaning of "skinning a cat" is so odd. Sure, you can skin a cat. But who does that?

I am not very old, nor have I had a vast set of life experiences. But I have never once needed to, seen, or heard of anyone skinning a cat. I don't know of any uses for cat fur, so skinning one seems unnecessary. Also, many people like cats and a phrase that involves removing their skin is a little insensitive.

I propose replacing this idiom with another:

There is more than one way to bake a cake. 🍰

This works on multiple levels. One, cakes are fun. Two, most people have heard of baking cakes and may have baked one themselves. And three, it doesn't involve skinning a beloved animal. And four, there is more than one way to make a cake!

At the end of the day, I don't care all that much. But I have started using "there is more than one way to bake a cake" in personal and professional conversations, and I haven't (to my knowledge) been misunderstood. So why not? Language is what we make of it, so let's make English a little more fun.

Happy baking!

I've made my way to this website on a number of occasions, and I think it's neat: https://www.ef.com/ca/english-resources/english-idioms/ ↩︎

Search all files for two strings

Sean McPherson — Mon, 15 Feb 2021 16:00:00 GMT

To search the current directory for all files that contain two independent strings, you can use the following terminal command:

grep -lr "common" $(grep -lr "rare" .)

In essence, this is saying "Recursively find all the files in the current directory with the string rare, and then look through those files to find any with the string common.

Depending on the directory, you may want to limit the number of directories that grep has to inspect. For me, that often includes directories like node_modules/ and cache. Here's the same command with a few excluded directories:

grep -lr "common" $(grep -lr --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=build --exclude-dir=cache "rare" .)

The order of the strings does matter, but putting the less commonly occurring string second is a little more efficient.

Happy searching!

Setup Netlify CMS with Eleventy

Sean McPherson — Mon, 08 Feb 2021 16:00:00 GMT

Netlify's guide for adding Netlify CMS to your site was really helpful. Consider this a supplemental guide to getting your Eleventy site up and running with Netlify CMS.

Your posts will probably have tags, or a list of strings for organizing content. Netlify CMS has a list widget type that will work nicely:

# admin/config.yml
collections:
- name: "blog"
    fields:
    - { label: "Tags", name: "tags", widget: "list" }

If you want editors to select from a specific set of options, the select widget type should work for you.

Eleventy will ignore Netlify CMS' config.yml when building your site, so you'll need to tell it to copy the file into your build directory:

// .eleventy.js
config.addPassthroughCopy("src/admin/config.yml");

Note: The actual path may vary based on your project structure.

Fix "Error: Could not resolve pagination key in template data" in Eleventy

Sean McPherson — Sat, 06 Feb 2021 16:00:00 GMT

In a recent Eleventy project, I wanted to create a single collection for tags with two keys: alphabetical for an array of all tags, and popular for an array of arrays with the tag and number of times it was used.

To access either "sub-collection", I could dive into the object like collections.tagList.alphabetical. This worked like a dream in my template and markdown files, and I thought maybe I was on to a new cool pattern for Eleventy.

But when I tried to paginate the sub-collection, everything fell apart. Eleventy errored with the following message:

Problem writing Eleventy templates: (more in DEBUG output)
> Could not resolve pagination key in template data: collections.tagList.alphabetical

`Error` was thrown:
    Error: Could not resolve pagination key in template data: collections.tagList.alphabetical

The pagination code in question looked like:

---
pagination:
  data: collections.tagList.alphabetical
  alias: tag
permalink: /tag//
---

Interesting. Maybe the collection hasn't been created by the time the pagination code runs, I guessed. To test this, I tried paginating collections.tagList to see if the alphabetical key was present:

---
pagination:
  data: collections.tagList
  alias: tag
permalink: /tag//
---

This created pages for alphabetical and popular, which proved my hypothesis wrong: the alphabetical data does exist when the pagination occurs.

Maybe it had something to do with paginating nested objects? To confirm, I added a test object to the frontmatter and tried to paginate it:

---
pagination:
  data: test.test.test
  alias: tag
permalink: /tag//
test:
  test:
    test: ["a", "b", "c"]
---

This worked as expected, creating pages for a, b, and c. So it isn't an issue with paginating deep objects.

With two incorrect hypotheses, it was time to look for outside help. I posted in 11ty Discord and did some searching. My initial queries brought up two issues: an actual bug from 2018 and some invalid JSON from 2019. Neither of which provided the solution here.

Feeling at a dead end, I decided to rethink the problem. I couldn't paginate over a nested collection object, but normal collections work just fine. If I could flatten my clever tagsList into multiple collections, the problem would be solved.

Instead of collections.tagList.alphabetical and collections.tagList.popular, I created two collections: collections.tagsAll and collections.tagsPopular. This required an addition iteration over the post data (one for each collection), but that small increase in build time isn't an issue for this project.

The final code to fix the "Error: could not resolve pagination key in template data" is a flattened collection:

---
pagination:
  data: collections.tagsAll
  alias: tag
permalink: /tag//
---

This works well, but I would still love to find a way to get the original solution to work. Let me know if you have a better way to solve this problem. 👍

Happy paginating!

Geddes' Guide to Crafting

Sean McPherson — Fri, 29 Jan 2021 16:00:00 GMT

I spent some time this week enjoying Dave Geddes' content. Three resources in particular have left me with a lot to think about, and I'm combining them into what I call "Geddes' Guide to Crafting".

Practice CSS Like an Artist (article): Geddes' draws comparisons between designing an application and painting a portrait. First you start with a rough sketch, then filling with broad strokes. Only once you have the foundation set do you add fine details.
When Should You Polish Your UI? (article): Geddes reflects of a few strategies for polishing the design for your application. Following the previous theme, he recommends a rough sketch with broad strokes (i.e prototyping) before polishing with fine details.
Build the zelda UI with Web Tech (video): Geddes completes the first phase of recreating Zelda: Breath of the Wild's menu screen in HTML and CSS. Here you can see rough sketching and broad strokes in practice. The video alludes to a part two, but it was never posted on YouTube.

As a developer, it can be tempting to spend too much time worrying about the fine details of what you are developing. But the best of products were not created perfect on the first try. They come from an on-going process of sketching, filling, and eventually polish.

So don't sweat the fine details in the beginning. Create a something that works, and then fill in those details later.

Happy crafting!

Send data to the window with Eleventy

Sean McPherson — Mon, 25 Jan 2021 16:00:00 GMT

Static-site generators like Eleventy are great at building websites. But when you want to add additional functionality, like a search feature, it might feel like they fall short.

All the data to generate your site exists at build time, how can you access that with some client-side JavaScript?

Here we'll look at one solution with Eleventy to expose data on the global window object to add interactive elements to your static site.

Besides familiarity with Eleventy, the only prerequisite here is creating custom shortcodes.

Nunjucks

Out-of-the-box, you can use Nunjucks' dump and safe filters to stringify data and leave it unescaped, respectively. Put that all within a script tag, and you have a simple method for exposing data:

<!-- index.njk -->
<script>
  window.__DATA__ = {{ ['hello', 'there'] | dump | safe }};
</script>

This works but is a little fiddly and limited to Nunjucks. For a more universal solution, let's create a custom shortcode.

Shortcode

A better solution to send data to the client is with a reusable shortcode. Let's add a it to .eleventy.js:

// .eleventy.js
module.exports = (eleventyConfig) => {
  eleventyConfig.addShortcode("expose", (data) => {
    return `<script>
            window.__DATA__=JSON.parse(${JSON.stringify(data)});
        </script>`;
  });

  return {
    /* ... */
  };
};

Then use the new shortcode like so:

<!-- index.njk -->
{% expose ['hello', 'there'] %}

Nice and simple! I'm going to offer an optional improvement to cleanup after exposing the data:

eleventyConfig.addShortcode("expose", (data) => {
  return `<script id="__EXPOSE__">
        window.__DATA__=JSON.parse(${JSON.stringify(data)});
        document.getElementById("__EXPOSE__").remove();
    </script>`;
});

With those changes, the script will execute on the client, add the data to the window, and then remove the script tag.

Hope that helps! Let me know if you have a better method of exposing data on the window, or how you can accomplish this with your favorite static-site generator.

Happy scripting!

Checkout the previous git branch

Sean McPherson — Fri, 22 Jan 2021 16:00:00 GMT

Today I needed to checkout a branch, pull the latest, then checkout dev, pull the latest, and merge dev into my branch.

This flow is pretty typical of my work, but I wondered: is there an easier way to go back to the previous branch in git?

Turns out there is, and StackOverflow came to the rescue:

git checkout -

This command will checkout the most recent branch. For more of an explanation, read the full response on StackOverflow.

To complete the steps above, I could run the following commands:

git checkout feature/branch-with-a-long-name
git pull
git checkout dev
git pull
git checkout -
git merge dev

If I can remember that command, it will be more efficient that going back through my command history. Hope that helps you too!

Happy version controlling!

Make all properties required in TypeScript

Sean McPherson — Sat, 19 Dec 2020 16:00:00 GMT

I have a type interface for shapes that looks something like this:

interface Shape {
  height?: number;
  width?: number;
}

Now I want to extend my interface for rectangles, but I want both height and width to be required. You can do that in TypeScript with a Required utility type.

Required takes a type and returns one with all required properties. You can use it by declaring a new type and passing the Shape interface:

type Rectangle = Required<Shape>;

Now when I try to create a new rectangle, I can use the Rectangle type to ensure that I provided all the required properties:

const rect: Rectangle = {
  height: 2,
  width: 4,
};

You can play around with these types in this TypeScript playground, and read more about Utility types on the TypeScript website.

Happy requiring!

Add text to the beginning of every file

Sean McPherson — Fri, 18 Dec 2020 16:00:00 GMT

While converting a JavaScript create-react-app project to TypeScript, I wanted a single line of text to every .tsx file. Searching for an answer brought me to this question on StackExchange, specifically this answer.

Using echo and cat, you can add new text to the old file's contents and send it to the original file. Combined with a for loop to iterate over the matching files, I came up with a one-liner^[1] that saved me a lot of time:

for f in **/*.tsx; do echo "// @ts-nocheck
$(cat "$f")" > "$f"; done

This script looks for all .tsx files in any directory, then adds // @ts-nocheck and a newline to the beginning of the file. But there is nothing magic about the selector or added text; you can use whatever you want for those values.

Hope that saves you a bit of time too!

Happy scripting!

Okay, with the newline it's kind of a two-liner, but you can copy and paste it directly into the command line. ↩︎

Sass converts hsla to hex incorrectly

Sean McPherson — Thu, 17 Dec 2020 16:00:00 GMT

I ran into an issue where Sass was converting hsla() values to hex incorrectly. It would take an input like this:

/* input.scss */
.subtle-blue {
  background-color: hsla(212, 50%, 50%, 10%);
}

And convert it into:

/* output.css */
.subtle-blue {
  background-color: #407bbf;
}

That is not the same color. When processing the input styles, Sass ignores the alpha (opacity) value and converts it into a standard hex.

You can see the different between the two values here:

hsla(212, 50%, 50%, 10%)

#407bbf

If you search around for an answer, you will find a few suggestions to use strings for hsl values or recreating the hsl and hsla functions in Sass. Neither of those seemed an idea solution.

Instead of changing how you declare hsl value or recreating the function, you can fix this issue by using decimal alpha values instead of percent. Going back to the original example, change 10% to 0.1:

/* Input Sass */
.subtle-blue {
  background-color: hsla(212, 50%, 50%, 0.1);
}

And Sass will convert it to alpha-supporting rgba:

/* Output css */
.subtle-blue {
  background-color: rgba(64, 123, 191, 0.1);
}

These values aren't identical because math is required, but they're infinitely closer than the non-alpha hex value:

hsla(212, 50%, 50%, 0.1)

rgba(64, 123, 191, 0.1)

You can see this behavior for yourself in this Sass playground but not in Sassmeister. So it may depend on the flavor and version of Sass that you are using.

But for a quick fix that doesn't involve wading into the release notes of your dependencies, opt for decimal alpha values in hsla.

Happy styling!

Change extensions of all files in a directory

Sean McPherson — Thu, 17 Dec 2020 16:00:00 GMT

for f in *.jsx; do mv -- "$f" "${f%.jsx}.tsx"; done

Increase the playback speed on any audio or video online

Sean McPherson — Tue, 15 Dec 2020 16:00:00 GMT

I like learning from audio and video, from podcasts to YouTube videos. My favorite applications let you alter the playback speed of the audio and video so that you can consume the content faster (or slower).

I find this particularly useful for unscripted podcasts or coding videos and will usually increase the speed to 2x (or more). At that rate, I can get through a 60 minute podcast in half the time!

However, I sometimes find myself on websites where they do not allow you to change the playback speed. Recently I was watching a coding tutorial on Vimeo and was stuck at the normal speed. Not a good use of my time.

Since online audio and video are played through native HTML elements, we have the ability to customize their behavior with the developer console.

First open the dev tools with your favorite method, and click on the "Console" tab. Then enter and run the following script^[1]:

$$("audio,video").forEach((n) => (n.playbackRate = 2.0));

This grabs all of the audio and video elements from the DOM, loops over each node, and sets the playback rate to 2.0 or 2x. If you prefer a different rate, you will only need to edit that last number.

If you are working on an application that plays audio or video, make sure to give the user the ability to change the playback rate. That way everyone can listen at the speed that is best for them^[2].

Happy listening/watching!

$$ is a shorthand for document.querySelectorAll() and works in all modern browsers ↩︎
For some light reading on the subject, checkout this paper on Human Listening Rates by the University of Washington CS department ↩︎

Standardize character width with CSS

Sean McPherson — Wed, 09 Dec 2020 16:00:00 GMT

Authors note: Before you read this article, you will want to click the "Start timer" button below to enable the live demos. You can cancel it at any time by clicking "Stop timer".

The width of a character is the amount of horizontal space that it occupies. This width varies between characters, weights, and typefaces. In Lato, for example, the letter W is wider than the letter I.

For most use cases, the varied width of characters isn't an issue. However, when you are creating an component like a timer, the differences in width can produce some undesirable movements as the numbers change.

Take a look at this example when timer running. Since the characters are all different widths, the number "jitters" around as it increments:

This isn't the end of the world, but it's not preferable.

To alleviate this, I have in the past turned to monospace typefaces. These allocate the same width for each character, regardless of the space that the stroke needs.

In this example, we can see that the jittering is resolved and the timer increments smoothly:

However, altering the typeface might not be the best solution for your product. Especially when the change was only made to prevent the jittering.

Instead, we can use two CSS properties^[1] to standardize the character width of an element:

.standardize-character-width {
  font-feature-settings: "tnum";
  font-variant-numeric: tabular-nums;
}

With those two in place, we can preserve the original typeface and avoid visual jittering:

A few things to note:

Adding these properties changes the tracking, or letter spacing, of the characters. This is necessary to standardize widths but might be undesirable for typography aficionados.
font-variant-numeric does not work in Internet Explorer
font-feature-settings supports IE but only works with OpenType fonts

That being said, this is CSS progressive enhancement: for whom it works, it improves the experience. I'm pretty happy with this solution, and I have used it in production with Contraction Tracker.

For more information about the CSS properties, you can read about font-feature-settings and font-variant-numetric on MDN.

Happy standardizing!

I first saw this solution from Tomek Sułkowski (@sulco) on Twitter. He shares lots of great tips like this and is worth the follow. ↩︎

See all package versions in npm cli

Sean McPherson — Wed, 09 Dec 2020 16:00:00 GMT

At work, I ran into an issue that may have been related to an external dependency. I wanted to update the package to see if a future release fixed the issue.

To get the latest version of a package, you can use the @latest tag:

npm i package-name@latest

But what if you need the next most recent release? Or five versions ago? I wanted to see a list of published versions without having to leave the command line.

A quick search led me to Viewing All Versions of an NPM Package (Including Pre-Release) by Will Anderson. He pointed to the npm view^[1] command and illustrated how to use it:

npm view package-name versions

This will print all of the published versions of any package on the registry. Pretty handy!

Anderson mentions that this was undocumented in 2015, but today we have a page dedicated to the view command on npm.

Anderson used the alias npm show ↩︎

TypeScript without TypeScript

Sean McPherson — Tue, 08 Dec 2020 16:00:00 GMT

As a superset of JavaScript, TypeScript provides a lot of useful features. It's no mystery why it is one of the "most loved" languages in software engineering. When everything is running smoothly, TypeScript can been a huge boon to productivity.

However, therein lies one of TypeScript's weaknesses: the setup. TS adds a level of overhead that is, in my opinion, prohibitively complex for most of my projects. So while I would love the benefits of working in TypeScript, I don't want to go through the trouble of setting it up.

In searching for a solution to my problem, I came across TypeScript without TypeScript -- JSDoc superpowers by @ddprrt on fettblog.eu. In it, the author highlights how JSDoc can provide some of the features of TypeScript without the setup.

I found the "Defining Objects" section to be particularly helpful. The ability to create "interfaces" for functions and objects in JavaScript is really powerful. If you combine that with // @ts-check and a TS-centric IDE like VS Code, you'll find yourself in a great position when developing.

Give the article a read and let me know what you think.

Happy typing!

Emulate iPhone & iPad in Safari

Sean McPherson — Wed, 02 Sep 2020 16:00:00 GMT

To emulate an iPhone or iPad in Safari, you first need to have the developer tools enabled.

Then when visiting a page that you want to test, select "Develop" in the application toolbar then "Enter Responsive Design Mode".

This will open a special window where you can emulate your website on an array of Apple devices and user agents.

Keyboard shortcut

To enter Responsive Design Mode without going through the toolbar, you can use the shortcut control command r.

Happy emulating!

Get started with Preact

Sean McPherson — Tue, 18 Aug 2020 16:00:00 GMT

Preact is a lightweight alternative to React. It provides the same^[1] modern API but at only 3kB minified and gzipped. For comparison, bundlephobia has react and react-dom at 38.5kB.

With many of the same features at a fraction of the size, Preact might be a better alternative for your simple client-side React app.

Sandbox

REPL

The Preact website has a REPL where you can test drive the library. The example as of writing using state and effect hooks and makes a request to the GitHub API with fetch:

const [items, setItems] = useState([]);

useEffect(() => {
  fetch("https://api.github.com/search/repositories?q=preact")
    .then((res) => res.json())
    .then((data) => setItems((data && data.items) || []));
}, []);

CodeSandbox.io

CodeSandbox has 54,000+ templates^[2] for Preact, including a starter template from the CodeSandbox Team. The code is similar to the official REPL, but with a class component:

export default class App extends Component {
  componentDidMount() {
    fetch(`https://api.github.com/search/repositories?q=preact`)
      .then((r) => r.json())
      .then((json) => {
        this.setState({
          results: (json && json.items) || [],
        });
      });
  }

  render(props, { results = [] }) {
    return (
      <div>
        <h1>Example</h1>
        <div class="list">
          {results.map((result) => (
            <Result result={result} />
          ))}
        </div>
      </div>
    );
  }
}

Mostly. ↩︎
Based on a template search for "preact". I did not verify this count. ↩︎

Make a POST request with fetch

Sean McPherson — Fri, 07 Aug 2020 16:00:00 GMT

fetch is utility for making HTTP requests from the browser. It is available in all modern browsers and has a popular polyfill for older browsers.

To make a GET request, just pass the endpoint to the global fetch method:

fetch("https://mirror-api.seanmcp.repl.co/get");

It returns a promise that will resolve with the server response. From there, you can convert the response to JSON and read the value in your code:

(async function () {
  const response = await fetch("https://mirror-api.seanmcp.repl.co/get");
  const data = await response.json();
  console.log(data);
})();

But fetch also handles other request methods. After GET, the first you will reach for is POST. But it isn't immediately apparent how to make a request with a different method.

How to `POST` with `fetch`

The global fetch function accepts a second options argument. There you can set the method, add a body, and set headers.

Here is an example POST request that sends a JSON body:

fetch("https://mirror-api.seanmcp.repl.co/post", {
  method: "POST",
  body: JSON.stringify({ message: "Hello API!" }),
  headers: {
    "Content-Type": "application/json",
  },
});

Once you have the request in order, you can handle the promises and get the server response.

For more information on the available including examples with other methods, checkout Using Fetch on MDN.

Happy fetching!

Why you shouldn't mutate parameters

Sean McPherson — Wed, 05 Aug 2020 16:00:00 GMT

When you pass an argument to a function, you can then access it as a parameter within the function.

Value arguments

When you pass a value argument like 2, true, or hello, you have access to that value within the function. As a result, you can mutate it like so:

function double(number) {
  number = number * 2;
  return number;
}

double(2); // 4

A value, or
A reference to a value?

Mutating parameters

When you pass a variable as an argument, you are handing a reference to the function – not a value. So when the function references its parameter, JavaScript traces the reference chain to the stored value.

Let's look at an example:

let colors = ["red", "orange", "yellow", "green"];

let warmColors = remove(colors, 3); // 'green' is not a warm color

function remove(array, index) {
  // 🎗 Remember: [] === [] is false
  console.log(array === colors);
}

What would you expect the console output to be? You might be surprised to see that the log is true. That's because we passed a reference to colors and not the value.

So if we go on to mutate the array parameter, we will make changes to the value that it and colors reference:

let colors = ["red", "orange", "yellow", "green"];

let warmColors = remove(colors, 3);

function remove(array, index) {
  array.splice(index);
  return array;
}

console.log(colors);
console.log(warmColors);

The log after running our remove() function shows that colors has been modified:

[ 'red', 'orange', 'yellow' ]
[ 'red', 'orange', 'yellow' ]

Remove an item at a given index in JavaScript

Sean McPherson — Wed, 05 Aug 2020 16:00:00 GMT

Removing an item from an array at a given index is a pretty common task in programming. So it is a little disappointing that the Array prototype in JavaScript doesn't have a method for that exact task.

If you search for an answer, you'll find solutions that use Array#slice:

function removeAtWithSlice(array, index) {
  return array.slice(index).contact(array.slice(index + 1));
}

And answers with Array#splice (which mutates the original array):

function removeAtWithSplice(array, index) {
  const copy = [...array];
  copy.splice(index, 1);
  return copy;
}

Both of these require that you remember the difference between the two methods, their behavior, and the arguments they require.

Personally, neither of these solutions are memorable, so I often find myself searching "how to remove an item at a given index JS".

Filtering

Instead of using slice/splice, I came upon a new method that is my favorite yet: Array#filter.

The filter method will iterate over your array and return a new one with values that pass a certain criterion. You have probably used Array#filter for a todo-like example before:

const done = todos.filter((todo) => todo.isComplete === true);

Like other array methods, you also have access to the current index as a parameter. So to use Array#filter to remove an item from an array, check if the indices match:

function removeAtWithFilter(array, index) {
  return array.filter((_, i) => i !== index);
}

Note: I'm using the _ to indicate a parameter that I don't intend to reference and a non-description i variable because index is already in scope.

As I mentioned above, this is now my preferred method of removing an item from an array. I am more familiar with Array#filter and the idea of "filtering out" in the unwanted index makes sense. The other two methods are harder for me to conceptualize.

There are two objective benefits to this method as well. First, it doesn't mutate the array (unlike Array#splice), which allows for functional programming without an additional step. And second, it only iterates the length of the array once (vs a potential two iterations for Array#slice).

For all those reasons, I recommend you use Array#filter for removing an item from an array at a given index in JavaScript. Let me know if you have an even better method; I'd love to hear it!

Happy filtering!

Tab focus not working in Safari?

Sean McPherson — Tue, 04 Aug 2020 16:00:00 GMT

While doing some cross-browser testing in Safari, I noted that tab was not working as expected. I was looking at a focus-managed component, so my first thought was that I had done something in my JavaScript that did not work in Safari.

After trying to debug the issue for a few minutes, I finally noticed that tab wasn't working anywhere, not just my component. This was both a relief (it wasn't me!) and a mystery. How could tab not work?

A quick Google search for "Safari tab order" lead me to this StackOverflow question and answer: Safari ignoring tabindex.

As it turns out, Safari does not enable tab highlighting by default. To turn it on:

Go to "Preferences"
Select the "Advanced" tab
Check "Press Tab to highlight each item on a webpage"

With that setting enabled, tab worked as I expected. Thanks graphicdivine!

While you're fiddling with settings, the A11y Project has a guide for enabling browser keyboard navigation on macOS that is worth checking out.

Setting you computer up for accessibility testing makes it that much easier to ensure that you're building a product that will work for everyone.

Happy tabbing!

Don't remove default focus styles, enhance them

Sean McPherson — Thu, 30 Jul 2020 16:00:00 GMT

I can't tell you how many times over the past fifteen years that I have searched "how to remove default focus styles". Something about that fuzzy blue glow around form elements has always looked terrible to me. So I, and countless other developers like me, have stumbled upon the code to remove focus styles:

*:focus {
  /*
        I'm sharing this for an illustration;
        please don't use this code.
    */
  outline: none;
}

But by removing those styles, you are removing a key feature of user agent styles: the focus outline! Let's look at why they are so important and what you can do to make them look less ugly.

Why focus styles?

That glowing blue outline lets you know when the browser is focused on a particular element. This is as necessary as having a :hover state for links; you shouldn't deploy without it.

Focus styles are also important for accessibility. Visual users who navigate by the keyboard need those distinct focus styles to indicate where they are on the page.

Imagine trying to navigate a webpage with an invisible mouse; it would be terrible. When you remove focus styles, you are doing the same thing to keyboard users.

Focus styles are a critical part of your website or applications design.

Better focus styles

Just because these styles are necessary, doesn't mean that they have to be a chore. By using the same kind of CSS properties that you style a site, you can give your focus styles the love they deserve.

All of the examples below are interactive, so make sure to click inside the input box to see the focus styles illustrated.

For comparison, this is what your browser's default focus styles look like:

`outline`

Instead of removing the outline with CSS, you can customize it. outline has accompanying -weight, -style, and -color properties that give you the same flexibility as border.

The one hangup is that it looks to the bounding box and ignores things like border radius:

input:focus {
  outline: 2px solid red;
}

That doesn't look great for rounded buttons, so you can use the outline-offset style to give your outline some more character:

input:focus {
  outline: 4px dotted red;
  outline-offset: 4px;
}

Niche.com does this for their button focus styles, and I think it looks great. I matches the brand while clearly signifying that the button is focused.

`box-shadow`

For a more flexible "outline", box-shadow is your probably your best option. You can dial down the "blur radius" and get an outline that honors the border radius of a button:

input:focus {
  box-shadow: 0 0 0 2px red;
  outline: 4px solid transparent;
}

Notice how I'm not removing the outline styles entirely. Some operating systems have a "high-contrast mode" that will alter the color of the outline, so leaving it as transparent will work for users with those settings.

The Economics of Software Development, Part III

Sean McPherson — Wed, 29 Jul 2020 16:00:00 GMT

This is the third post in a series on how economics helps explain the decisions we make when developing software. It is a response to "Summer School", a series from NPR's Planet Money.

This week's episode from Planet Money's "Summer School" was about elastic and inelastic demand. The elasticity of demand refers to how responsive consumers are to changes in price. If a small change in price has a big impact on demand, then it is considered elastic. If the consumer will buy the good no matter the price, then it is inelastic.

The best example of this I can think of is sitting on the desk in front of me.

Case study: the MacBook Pro

Apple has done a fantastic job of creating inelastic demand for their laptops. While it is by no means a monopoly, the popularity of the MacBook Pro in developer circles cannot be overstated. If you are developer, some people argue, you need to use a MacBook.

But Apple computers are very expensive, and they seem to grow more so every release. The latest iMac is priced between $6,000 and $50,000, depending on the features. Most people would never pay that much, but the fact that Apple can even consider charging that much illustrates the inelasticity of the demand.

Recent releases of the MacBook, however, have received mixed reviews. Apple's transition to the butterfly keyboard was largely unpopular, and seems to have resulted in hardware issues. I am typing this on a MacBook Pro that regularly has issues with overheating, visual bugs, and display inconsistencies.

Despite this, many developers (myself included) are still convinced that they need to have a MacBook to do their work. So the demand for the product remains fixed, regardless of rising prices or falling quality.

How to encourage elasticity

Whenever possible, we as consumers need to push back against inelastic demand. As developers, we can structure our tools and processes in a way that one could easily be exchanged for another.

If you are using a cloud provider, write a wrapper interface than can be switched from AWS to Google Cloud Platform or Microsoft Azure without touching any business logic. Architect your products so that they run on multiple platforms, environments, and browsers.

In JavaScript land, that can be as simple as using double quotes in Node.js scripts so that they work on Windows.

By embracing the inevitability of future change and planning for it, we will be in a better position to stay ahead of the competition.

Fix 'EMFILE: too many open files' error in Jest

Sean McPherson — Wed, 29 Jul 2020 16:00:00 GMT

When I tried to run jest --watch in a codebase, I received the following error:

Error: EMFILE: too many open files, watch
    at FSEvent.FSWatcher._handle.onchange (fs.js:1372:28)
Emitted 'error' event at:
    at NodeWatcher.checkedEmitError (/Users/seanmcp/dev/REPO/node_modules/sane/src/node_watcher.js:143:12)
    at FSWatcher.emit (events.js:182:13)
    at FSEvent.FSWatcher._handle.onchange (fs.js:1378:12)

A Google search of the error message produced three (!) results. The second was a PDF from Mozilla that recommended installing watchman.

Why `watchman`?

Watchman is a file-watching service from Facebook that will respond to changes in your files. Jest (also by Facebook) default to using watchman in --watch mode.

Watchman is available on all major platforms. On a Mac or Linux with Homebrew installed, you can run:

brew install watchman

With that installed, Jest's --watch flag works as expected.

I hope that works for you (and saves you some valuable time)!

Happy testing!

Updated TypeScript mega-course on Egghead.io

Sean McPherson — Mon, 27 Jul 2020 16:00:00 GMT

Last month, I embarked on a journey to learn TypeScript better. I hand-crafted a TypeScript"mega-course" on Egghead.io by cobbling multiple courses into one.

My goal was to complete the course in three weeks. Now a month and a half later, I have completed the course and am ready to reflect on my experience.

Overall, it was a beneficial experience. I learned a lot more about types and how to write meaningful generics that will help make my code more reusable.

I also gained a greater appreciation for TypeScript as a language. There were some examples where I needed to stop the video and try to read what was happened. I know TS is technically a super-set of JavaScript, but it is 100% a proficiency of its own.

Updated Mega-course

After completing the course, I want to update and annotate the original syllabus. Here is the updated course playlist:

Optional: Up and Running with TypeScript by John Lindquist (22 min)

This was helpful, but very basic. Consider skipping this if you already know how to set up a TypeScript project

Use Types Effectively in TypeScript by Ari Picker (29 min)

This was a great introduction into TypeScript on its own. I learned a lot about generics, which are an important feature.

Practical Advanced TypeScript by Rares Matei (62 min)

I took more notes on this course than any of the others. This was definitely the material I needed to introduce me to more advanced TypeScript.

Advanced Static Types in TypeScript by Marius Schulz (67 min)

There was some overlap between this course and the previous, but they both did a good job of explaining core type concepts.

The updated runtime is 2 hours and 38 minutes to 3 hours, depending on whether you include the optional introduction.

It also drops both of Basarat Ali Syed's courses, Async/Await using TypeScript and Use Typescript to develop React Applications. Both were fine but ultimately weren't substantial enough to be included in the mega-course.

I hope that was helpful! Let me know if you take this TypeScript "mega-course" on Egghead.io and what you think about it.

Happy learning!

The Economics of Software Development, Part II

Sean McPherson — Wed, 22 Jul 2020 16:00:00 GMT

This is the second post in a series on how economics helps explain the decisions we make when developing software. It is a response to "Summer School", a series from NPR's Planet Money.

This week's episode from Planet Money's "Summer School" was about markets: where supply and demand come together. It's where those decisions that Economists love so much get made.

Sometimes a marketplace is like a bazaar (which I tend to picture), but other times it looks more like the results page when searching for an NPM package. With that in mind, it's easy to see markets everywhere.

Markets can be freeing, if you're the one making the decisions. But if you aren't in the driver's chair, you might not even know they exist.

In general, we want as many decisions as possible to be made by the people who will be most affected by the decision. I'll add the caveat: "provided they affected have the information necessary to make that decision."

This is the ideal, but it isn't the only option.

Suffering in a "central market"

An alternative to individuals deciding is central planning. This is when a higher authority makes the decisions that affect everyone else.

At tech companies, you can see this in service contracts. In some organizations, the decision of what SaaS to use comes from the top, and the repercussions trickle their way down.

I worked at a large company that had a contract with Microsoft for all of their office software services. As a result, everyone at the company had to use Skype and an ancient program called Lync for all of our messaging needs^[1]. Both had significant shortcomings, and neither served the needs of the tech team well.

Instead of letting the market decide which messaging app to use, we were forced to struggle with the inefficiencies of central planning.

Rather than mandating a solution from the top, organizations should work hard to give teams and individuals the freedom to gather information and agency to make those decisions for themselves.

Encouraging markets

As developers, we want to structure as much of our infrastructure and processes to encourage a marketplace of ideas.

If you have a micro-service architecture, teams are free to choose whatever language and framework will work best for them. By using CSS for your design system, each project can pick the JS framework fits their needs.

Once you have an open marketplace, it's now on the individuals to make rational decisions. Now if only we would actually do that^[2]!

The company was rolling out Microsoft Teams when I left, which was much better. ↩︎
Ariely, Dan. (2009). The End of Rational Economics. Harvard Business Review. https://hbr.org/2009/07/the-end-of-rational-economics ↩︎

Access the home directory in Deno

Sean McPherson — Fri, 17 Jul 2020 16:00:00 GMT

If you want to access the home directory from you Deno program, you can use the Deno.env's get method with "HOME":

Deno.env.get("HOME");

In unix environments, returns a string along the lines of "/home/USER".

So if you want to write a script that accesses a configuration file like .bashrc, you could read the file with:

// read-bashrc.ts
const bashConfig = Deno.readTextFileSync(Deno.env.get("HOME") + "/.bashrc");

Since we are accessing Deno.env, we need to run the program with the env permission:

deno run --allow-env read-bashrc.ts

Here is a Repl where you can play around with accessing the home directory in Deno.

Happy coding!

The Economics of Software Development, Part I

Sean McPherson — Tue, 14 Jul 2020 16:00:00 GMT

This is the first post in a series on how economics helps explain the decisions we make when developing software. It is a response to "Summer School", a series from NPR's Planet Money.

Let's look at two concepts from Planet Money's "Summer School 1: Choices & Dating": opportunity cost, and sunk-cost fallacy.

Opportunity cost

This compilation process takes a long time. I'm going to get a snack while I wait.

Opportunity cost is the cost of doing activity A instead of activity B. For example, watching another YouTube video before bed comes at the cost of finishing that novel you started last year^[1].

I am reminded of opportunity cost whenever I'm waiting for webpack to rebuild a client and server in development. Every moment I spend waiting is a moment that I'm doing any development work (and a moment that I'm likely to switch to another task).

We should be attuned to these costs and advocate for the time to fix the underlying problem. If we can reduce these opportunity costs, then we can increase our productivity and even improve the developer experience.

Sunk-cost fallacy

We've already invested heavily in our Java architecture. Let's find a way to make it work for this machine-learning project.

A sunk cost is one that has already been paid and cannot be recovered. The fallacy comes from making altering future decisions based on those costs.

In development, it's common to take one of two paths: a) finding your hammer and using it for every problem, or b) chasing every new trend under the sun. Both can illustrate the sunk-cost fallacy, but the former is more straightforward.

Time spent learning a language, money spent on a subscription service, and effort spent working on a problem are all sunk costs. Once they're gone, they're gone. The experience can help inform future decisions, but it shouldn't limit them with artificial constraints.

This isn't autobiographical at all. ↩︎

Manage analysis paralysis while programming

Sean McPherson — Tue, 14 Jul 2020 16:00:00 GMT

References

Raypole, Crystal. (2020). How to Beat ‘Analysis Paralysis’ and Make All the Decisions. https://www.healthline.com/health/mental-health/analysis-paralysis
Lengsdorf, Jason. (2020, July 17). Twitter. https://twitter.com/jlengstorf/status/1284111359303659521
Adolos. (2020). Feeling unproductive? Maybe you should stop overthinking. https://adolos.substack.com/p/feeling-unproductive-maybe-you-should
"if you're a creator then you should be engaging in creative thinking on a regular basis. The more you do it, the better your brain becomes at thinking up ideas. This makes it easier for you to work on your projects because you won't get stuck as often"
"I've found that the best way to get into the habit of creative thinking is to engage in it daily"
"engaging in multiple forms of creative thinking will also help you get through creative blocks"
Groth, Aimee. (2013, February 12). SHERYL SANDBERG: Women Need To Get More Comfortable With Power. Business Insider. https://www.businessinsider.com/sheryl-sandberg-lean-in-2013-2
"done is better than perfect"

To reference

Grant, Heidi. (2014, February 14). How to Make Yourself Work When You Just Don’t Want To. https://hbr.org/2014/02/how-to-make-yourself-work-when-you-just-dont-want-to

Before You Debug

Sean McPherson — Fri, 10 Jul 2020 16:00:00 GMT

Debugging, "the process of finding and resolving defects within a computer system"^[1], is a critical skill for software development. It's how we figure out what went wrong and how to fix it.

This can be as informal as throwing * { outline: 1px solid red } on all your elements or sophisticated as using an IDE's debugger.

But whatever your method, there are certain steps that you can follow to help yourself debug more logically and efficiently.

This garden aims to detail everything you should do before you actually start debugging. Think of this as the prep work before you start cooking.

Pre-steps

Relax: Find a bug can be frustrating, and those emotions can impede the debugging process. Take a deep breath and dive in.
Describe what happened: Did the process exit? Did the page fail to render? Is there a message in the console? Does the UI not respond correctly? Understanding what happened is the first step to solving a problem. The "how" comes later.
Read the error message: Most errors will provide you useful information in the message. Some APIs provide a detailed explanation of what went wrong. So take the time and read it.
Follow the stack trace: If the error includes a stack, walk through each line. Where did the error originate? What it internal or external code?
Pinpoint the error: Try to isolate the exact point where something went wrong. In the stack trace, this will usually have a file name and a line number, e.g. app.js:25.
Inspect the line: Read the entire line where the error occurred. Is there anything that immediately jumps out to you? Sometimes the bug could be as simple as a typo or an unexpected type.
Review the block: Follow the block from start to finish, making note of the line in question. Try to get a good sense of how that code is working.
Scan any higher scopes: Make sure you understand at a high-level what the code is doing and what variables are needed/expected.
Make a hypothesis: You are a scientist, after all. Make an educated guess about what went wrong and what will fix it. Make sure to review your hypothesis while you're debugging.

Note

This is a living document and will change as my approach to debugging grows over time. If you have any suggestions, please let me know.

Additional reading

When debugging, your attitude matters by Julia Evans

https://en.wikipedia.org/wiki/Debugging ↩︎

Before Debugging

Sean McPherson — Fri, 10 Jul 2020 16:00:00 GMT

Debugging, "the process of finding and resolving defects within a computer system"^[1], is a critical skill for software development. It's how we figure out what went wrong and how to fix it.

This can be as informal as throwing * { outline: 1px solid red } on all your elements or sophisticated as using an IDE's debugger.

But whatever your method, there are certain steps that you can follow to help yourself debug more logically and efficiently.

This garden aims to detail everything you should do before you actually start debugging. Think of this as the prep work before you start cooking.

Pre-steps

Relax: Find a bug can be frustrating, and those emotions can impede the debugging process. Take a deep breath and dive in.
Describe what happened: Did the process exit? Did the page fail to render? Is there a message in the console? Does the UI not respond correctly? Understanding what happened is the first step to solving a problem. The "how" comes later.
Read the error message: Most errors will provide you useful information in the message. Some APIs provide a detailed explanation of what went wrong. So take the time and read it.
Follow the stack trace: If the error includes a stack, walk through each line. Where did the error originate? What it internal or external code?
Pinpoint the error: Try to isolate the exact point where something went wrong. In the stack trace, this will usually have a file name and a line number, e.g. app.js:25.
Inspect the line: Read the entire line where the error occurred. Is there anything that immediately jumps out to you? Sometimes the bug could be as simple as a typo or an unexpected type.
Review the block: Follow the block from start to finish, making note of the line in question. Try to get a good sense of how that code is working.
Scan any higher scopes: Make sure you understand at a high-level what the code is doing and what variables are needed/expected.
Make a hypothesis: You are a scientist, after all. Make an educated guess about what went wrong and what will fix it. Make sure to review your hypothesis while you're debugging.

Additional reading

When debugging, your attitude matters by Julia Evans

https://en.wikipedia.org/wiki/Debugging ↩︎

Intro to "The Economics of Software Development"

Sean McPherson — Thu, 09 Jul 2020 16:00:00 GMT

Economics was one of my favorite subjects in high school and college. Back before I made the career switch to software engineers, I would imagine the sweet "what ifs" of majoring in Econ instead of Education.

I was (and am) fascinated by economics as the study of decision making. Whether you prefer to put that in terms of "scarcity" and "resources" is up to you. For me, it's about analyzing "why" we do the things that we do.

You can take that analytical spotlight and shine it on monetary policy or production, which is probably what most people think of when they hear "economics."

But increasingly economists have been looking at other aspects of life, giving birth to the field of behavioral economics. Freakonomics, the book and radio program, is the most popular example of this field of study, but you may have heard of other examples from Richard Thaler or Daniel Kahneman.

When NPR's Planet Money announced a "Summer School" series focusing on key economics concepts, I was intrigued. Here was the perfect invitation to do a little bit of analytical thinking of my own.

With the release of each episode of "Planet Money Summer School," I'm going to respond by taking that lens and the concepts and focus them on the practice of software development.

I'm not interested in the business of software development, but rather the decisions that I and other developers make in building websites and applications. In other words: why we do the things that we do (and what we can do about it)!

I hope you'll find this series interesting, even if it's just to crack your knuckles and tell me how I have it all wrong.

Happy learning!

Nodemon for Deno

Sean McPherson — Wed, 01 Jul 2020 16:00:00 GMT

Update: As of Deno v1.4, there is a built in watch mode that you can enable with the --watch flag. Read more about that here.

Nodemon, or as I read it in my head Nodémon!, is a utility for restarting Node.js processes when the source changes. It's is the first dev dependency I add when working in Node, because it is so handy!

Deno, the secure runtime for JavaScript and TypeScript, doesn't work with Nodemon. When I first started building with Deno, I was reminded just how annoying it is to stop and start your server whenever there is a change.

Enter denon, the "replacement" for Nodemon in Deno land. As long as you're using deno@^1.0.1, you can get all the goodness of automattic restarting with denon.

Install

You can install denon with Deno's install command:

deno install --allow-read --allow-run --allow-write --allow-net -f --unstable https://deno.land/x/denon@v2.2.0/denon.ts

That command installs denon version 2.2.0, so reference the documentation for the most up-to-date instructions.

Simple usage

Once you have denon installed, you can use it as a straight replacement for all deno commands:

# With Deno
deno run --allow-net https://deno.land/std/examples/echo_server.ts

# With denon
denon run --allow-net https://deno.land/std/examples/echo_server.ts

This is the same behavior as node/nodemon. But running external code doesn't really illustrate the value of denon.

To see it in action, copy echo_server.ts locally and then run with denon:

denon run --allow-net echo_server.ts

Now when you make any changes to the source, you will see denon automatically restart the server.

Configuration

My favorite feature of denon is its configuration file: denon.json. With it, you get some of the "scripts" features of Node.js's package.json that are currently missing in Deno.

To create a configuration file, you can call denon with the --init flag:

denon --init

This will create a denon.json file where you can include scripts with commands, permissions, and environment variables.

We can create a "start" script for the echo_server.ts like so:

{
  "$schema": "https://deno.land/x/denon/schema.json",
  "scripts": {
    "start": {
      "cmd": "deno run echo_server.ts",
      "desc": "Start echo_server in watch mode",
      "allow": ["env", "net"],
      "env": {
        "PORT": "2525"
      }
    }
  }
}

Our "start" script has a command, description, permissions to allow, and an environment variable PORT that we are passing to our server.

To run the script, type:

denon start

And you're off to the races! I love the ability to start a Deno process without typing all those permissions. :chefs-kiss:

Learn more

The denon documentation lists the full feature set and includes a bunch of helpful examples. Make sure to check that out when setting up denon on your next Deno project.

Happy coding!

Adding images to my articles

Sean McPherson — Tue, 30 Jun 2020 16:00:00 GMT

Back in February, I set up post images to this blog. Very few of my articles had images, so you may not have noticed.

In the original design, an image spanned the width of the window, replacing the blue gradient on most pages.

This was problematic, because I needed to find large images for it to look decent on big screens. But I also needed to compress those huge images so that the file sizes weren't massive.

I don't know how to do the file sizing and compression during a build step, so instead I avoided added images to any future articles.

Fast forward a few months, and I wanted to take another crack at article images.

Updating the design

I didn't realize it initially, but choosing a design with full-screen images set me down a path of no return. There isn't a good way to find and serve images that large.

So rather than searching for an impossible solution, I changed the design. By limitting the width of article images, I opened a world of possibilities.

I now have access to more images, because the only need to be 800 pixels by 400 pixels. At that size, cropped and compressed images are super reasonable.

How to find images

When I want to find an image for an article, I can search the usual places: Unsplash, Pixabay, or an Google search. Then I can copy the image URL, and head over to ezgif.com.

From there, I will:

Resize the image
Crop it to 2:1
Compress to < 30 kB

Once that's done, I can save the image to this repo's img/ directory. The whole process takes about two minutes.

Room for improvement

It would be great to automate the resize and compression steps with a build process, so I'll be on the lookout for solutions there.

I would also like to give attribution for the images, where applicable. That seems best served through frontmatter, but I will have to look into that too.

I hope that helps you when deciding how to add images to your articles!

Happy writing!

Parse argument aliases in Deno

Sean McPherson — Fri, 26 Jun 2020 16:00:00 GMT

You can parse command-line arguments in Deno with the standard flags module:

import { parse } from "https://deno.land/std/flags/mod.ts";

console.dir(parse(Deno.args));

deno run https://deno.land/std/examples/flags.ts -a beep -b boop

{ _: [], a: 'beep', b: 'boop' }

The parse function has a second options argument where you can assign aliases. Before we do that, let's use a more description example.

Example scenario

Say you have a script, log.ts, that takes a message to display in the terminal. We would use our script like this:

deno run log.ts --message "Hello world"

Hello world

Now let's alias the --message flag to -M for ease of use.

Alias option

When we call parse in our script on Deno.args, we want to provide an additional options object with a key aliases.

That will be assigned to another object that will map flags to their aliases:

// log.ts
import { parse } from "https://deno.land/std/flags/mod.ts";

const flagToAliasMap = {
  message: "M",
};

const parsedArgs = parse(Deno.args, { aliases: flagToAliasMap });

console.log(parsedArgs.message);

Now we can call our script with those aliases:

deno run log.ts -M "That's better"

That's better

With that, the flags module does all of the hard lifting for you!

Wrap up

Two things to note about aliases:

flags doesn't care whether you use one or two hyphens for aliases, so -M and --M will both work.
Aliases are case sensitive, so you'll have to map m and M separately.

Happy coding!

Await multiple promises in JavaScript

Sean McPherson — Wed, 17 Jun 2020 16:00:00 GMT

Let's say I have two promises: the former resolves in three seconds, while the latter resolves in five. I need to wait for both of these before moving on to the next code block.

Depending on how you structure your promises, you will either have to wait five seconds or eight seconds before moving on.

What is the best way to await multiple promises?

Await happy

My first instinct in the above scenario was to use to await both promises. await is such a useful keyword in modern JS, that I tend to throw it places without a second thought:

await promiseOne(); // Resolves in three seconds
await promiseTwo(); // Resolves in five seconds

console.log("done");

This looks neat and clean, but how long will it take to resolve? 8 seconds.

Look back at the first line. We're asking the JavaScript engine to await the resolution of promiseOne. In effect, we're asking it to twiddle its thumbs for three seconds while we wait on the promise.

When the first resolves, then JavaScript quickly moves on to the next promise. After waiting for five seconds, it moves on to the log. 3 seconds + 5 seconds = 8 seconds.

Can we reduce that wait time by refactoring?

Call then await

Instead of reaching straight for await, let's think this through: we want to start both promises, then wait for their resolution. So let's change it up:

const promiseOnePromise = promiseOne();
const promiseTwoPromise = promiseOne();

await promiseOnePromise;
await promiseTwoPromise;

console.log("done");

How long will it take this code to resolve? 5 seconds (roughly).

By calling the functions that return promises initially, we are "starting the timer" for both. So the three-second and five-second promises are resolving in tandem.

When we await after calling the promises, we'll only wait as long as the slowest promise: five seconds in this case.

This is great, but there is one more solution that might be easier.

Promise.all

The Promise object has an all method that accepts any number of promises and resolves when all have been fulfilled. We just need to pass it an iterable like an array:

await Promise.all([promiseOne(), promiseTwo()]);

console.log("done");

This functions in a similar manner to the previous "call then await" example but is more succinct. In my tests, it was fractions of a millisecond slower, but your mileage may vary.

Live example

You can view a live example of this code on Repl:

Conclusion

There we go! Two solutions for how to await multiple promises in JavaScript. Hope that helped!

Happy coding!

TypeScript mega-course on Egghead.io

Sean McPherson — Mon, 15 Jun 2020 16:00:00 GMT

This playlist has been updated. Check out the latest version of my TypeScript "mega-course" on Egghead.io.

I would say that I have "functional" understanding of TypeScript. I can get the job done (at least most of the time), but as soon as the types get hairy I struggle.

As TypeScript contiues grow in popularity, this will become a liability. To fix this, I have set a professional goal to improve my understanding of TypeScript.

Niche.com provides us with a membership to Egghead.io, so I've cobbled together multiple courses on TypeScript:

Mega-course

Up and Running with TypeScript by John Lindquist (22 min)
Use Types Effectively in TypeScript by Ari Picker (29 min)
Async/Await using TypeScript by Basarat Ali Syed (17 min)
Practical Advanced TypeScript by Rares Matei (62 min)
Advanced Static Types in TypeScript by Marius Schulz (67 min)
Optional: Use TypeScript to develop React Applications by Basarat Ali Syed (27 min)

The plan is to complete these courses over the next three weeks. At the end, I'll review the mega-course and update the order if necessary.

Happy coding!

Six video update

Sean McPherson — Fri, 12 Jun 2020 16:00:00 GMT

A few weeks ago, I wrote about publishing my first YouTube video. In that article, I included my reasoning and what I hoped to gain from it.

My goal is to upload twelve videos, that get an average of twelve views, and get to twelve subscribers.

Last night, I uploaded my sixth video, Set Breakpoints In The Chrome DevTools, which puts me at the half-way mark.

6/12 or 50%

I wanted to share some of the lessons that I learned making and publishing videos 2-6.

Lessons learned

Recording gets easier

For me, it doesn't feel natural to sit and talk to myself in front of the computer. But with practice, I found myself getting more comfortable.

There is a long way to go, but it is encouraging to see growth after making six videos.

Keep it rolling

By keeping a continous recording, I am able to fix mistakes as they come and edit them out later. If anything sounds weird as I say it, I just take a break, and then try the line again.

This is far easier than trying to get a good "take" of the whole video. I found that a 3-4 minute video would come from 10-12 minutes of continous recording.

Editing gets easier

I don't think I could say that I like iMovie, but I'm getting used to the interface and the steps that I need to go through to edit my videos.

The biggest frustration that remains is the slider for audio volume (no input?) and the tendency to export the source video instead of the editted version (why is that possible?).

That being said, I think iMovie will be sufficient for the time being.

Equipment matters

I started off using a $50 microphone from Amazon. It worked, but the audio quality wasn't great and it didn't provide any control over the recording.

I traded that in for a Blue Yeti Nano, and the improvement has been noticeable. I'm still getting into the swing of things, but having the right tools makes a difference.

Very few views

Since that initial video, I have averaged 1.2 views per video and gained 2 subscribers (one of whom is my wife). This is lower than I expected, but good to know.

I want to stress again that gaining views and subscribers is not by end game. Including those two measurements in the goal was an attempt to gauge the utility.

This may be aided by more promotion on my end, but with everything going on in the world that didn't seem the most helpful thing to do.

Once I publish my twelfth video, I want to take a deeper dive into the performance of each video to see what I can glean going forward.

Until then, happy watching!

Read a json file in Deno

Sean McPherson — Thu, 28 May 2020 16:00:00 GMT

Deno is a secure runtine for JavaScript, so to read a file the program needs explicit permissions. We can enable file reading with the --allow-read flag in the command line:

deno run --allow-read read-json.ts

Once the permissions are straight, we need to read the file. There are a few methods on the Deno module to use, so let's look at two options: readFile, and readTextFile.

Let's take a look at them separately.

`readFile`

Deno's readFile method returns a Promise resolves with a Uint8Array. You can call the method like this:

console.log(await Deno.readFile("data.json"));

So if we run the following code in a directory with a data.json file, you would see a log like this:

Uint8Array(29) [
  123,  10,  32,  32,  32, 32,  34, 115,
  111, 117, 114,  99, 101, 34,  58,  32,
   34, 100,  97, 116,  97, 46, 106, 115,
  111, 110,  34,  10, 125
]

In order to read this, we need a new text decoder decoder with and pass the file's encoding:

const decoder = new TextDecoder("utf-8");
const data = await Deno.readFile("data.json");
console.log(decoder.decode(data));

Now when we run the code, we see the contents of data.json logged in the console:

{
    "source": "data.json"
}

This looks good, but it is just a formatted string. To consume this data, we need to use the global JSON object's parse method to get a usuable json object.

const decoder = new TextDecoder("utf-8");
const data = await Deno.readFile("data.json");
console.log(JSON.parse(decoder.decode(data)));

Run it again, and you will see whatever data you had stored in your json file logged to the console. You have successfully read a json file in Deno with readFile!

If you know that your data is utf8 encoded, you can skip a step with the next Deno method.

`readTextFile`

Deno's readTextFile method returns a Promise that resolves to a utf8 decoded string. You can call the method like this:

console.log(await Deno.readTextFile("data.json"));

Once again, if we run this code in a directory with a data.json file, you would see the file's contents logged in the console:

{
    "source": "data.json"
}

This looks good, but just like before it is only a formatted string. To consume this data, we need to use the global JSON object's parse method again to get a usuable json object.

const text = await Deno.readTextFile("data.json");
console.log(JSON.parse(text));

Run it again, and you will see whatever data you had stored in your json file logged to the console. You have successfully read a json file in Deno with readTextFile!

Conclusion

If you know that your file is utf8 encoded, using Deno.readTextFile is an easy way to grab the contents of a file. Otherwise, Deno.readFile and a decoder can get you on your way.

Whichever method you choose, just remember to parse the json data before trying to consume it.

Happy coding!

Read a json file in Node.js

Sean McPherson — Wed, 27 May 2020 16:00:00 GMT

To read any file in Node.js, you need to import the fs or file system module. From there, you have two methods from which to choose: readFile, and readFileSync.

Both are similar in that they return a Buffer of binary data from a file. readFile accepts a callback that will receive the Buffer, while readFileSync returns it synchronously.

In action, they look like:

const fs = require("fs");

fs.readFile("./data.json", (error, data) =>
  error ? console.error(error) : console.log(data)
);

try {
  console.log(fs.readFileSync("./data.json"));
} catch (error) {
  console.error(error);
}

If you run this code in a directory with a data.json file, boths methods will log something like:

<Buffer 7b 0a 20 20 22 64 61 74 61 22 3a 20 74 72 75 65 0a 7d>

Both are returning the same data, but it isn't consumable. In most instances, you will need to do one more operation in order to use the data that you have read from a file.

Since we are working with a json file, we can use the global JSON object to read the data. The parse method will convert this Buffer into a usuable JSON object:

const fs = require("fs");

fs.readFile("./data.json", (error, data) =>
  error ? console.error(error) : console.log(JSON.parse(data))
);

try {
  console.log(JSON.parse(fs.readFileSync("./data.json")));
} catch (error) {
  console.error(error);
}

Run it again, and you will see whatever data you had stored in your json file logged to the console. You have successfully read a json file in Node.js!

You can see the code in action here:

Happy coding!

Publishing my first YouTube video

Sean McPherson — Wed, 20 May 2020 16:00:00 GMT

Yesterday, I published my first video on YouTube: "Three Ways To Open The Firefox DevTools". As the title suggests, it covers the three main ways of opening the DevTools in Firefox, the browser menu, "Inspect Element", and the keyboard shortcut.

This is new territory for me, so I wanted to take a moment and reflect on why I started a YouTube channel, what I hope to gain from it, and what I learned in the process.

A new career goal

Before working as a software engineer, I worked for three years as a teacher. And while that specific career was right for me, I am still passionate about education and sharing what I know with others. So I am making it a career goal to teach on the side.

This focus will complement my work as an engineer for all the wonderful ways that teaching is helpful. It will help me be a better team member and mentor at work. And it is an opportunity to give back to a developer community that has already given me so much.

Eventually, I would like to lead workshops and teach on-line courses, but that is more of a 3-5 year plan.

Plans for YouTube

I am going to produce short, informative videos in the same style as Egghead.io. I have really enjoyed their content and think that there is a strong formula for laser-focused content.

With that in mind, I'm aiming for videos in the 3-10 minute range: long enough to be valuable, but not long winded.

My goal for YouTube is to put out twelve videos that have an average of twelve views and gain twelve subscribers. I'm hoping that this will take three months, but I don't want to commit to a hard timeline.

After hitting twelve videos, I will reassess my efforts and determine if YouTube is the right platform for this.

So this first video puts me one step on that journey.

1/12

Lessons learned

Harder than it looks

In a world of endless high-quality content on YouTube, it's easy to assume that making videos is easy. At least that's what I did. But every step of the process was more difficult that I had anticipated.

Writing, recording, and editing are all skills unto themselves, and ones that I am not very good at. All of this will require practice.

I need a script

When I was teaching, some lesson plans had a script for the teacher to read. In front of the classroom, I found this restricting and would avoid reading verbatim.

In front of a screen, however, the dynamic changes. You can't see faces to meter your delivery and the lesson pace. As a result, I find myself getting further off-topic during digital instruction than I did in-person.

But with a script, it's different. I can plan my thoughts ahead of time and hit all the intended points, only lingering when I intend. Writing this kind of script is a skill that I'm developing, but they are a valuable part of the lesson.

Things to improve

Editing

I edited this video with iMovie, and it was a new experience. The "Project" structure is a little confusing, and I had a little bit of trouble importing the video. But the biggest hangup was the preview, which would occassionally not follow the scrubber.

As a result, I didn't edit this video as much as I would have liked. Going forward, I want to watch a few videos on editing in iMovie and see if I can resolve those issues.

Multiple takes

Going into filming, I planned to get everything correct in one go. When something went wrong, I stopped the recording, reset, and then started from scratch.

That is not sustainable. Instead, I want to keep the "film rolling." If I mess up, just wait a beat and do the line correctly. This should increase the recordig process because I'm not repeating lines that are good for the sake of ones that need fixed.

Mouth sounds

Hoo boy, do I make a lot of mouth sounds. My wife had some helpful suggestions that I am going to try in the next recording:

Stay hydrated: Keep a glass of water on hand and drink when you're thirsty
Record one line at a time: Whether that is a sentence or a paragraph, do it in one go without swallowing

Once I can isolate the content better, it will be easier for me to edit out those unpleasant sounds.

I plan to post an update on my goal once I've hit the "six video" mark. Until then you can watch my progress on YouTube and subscribe to stay updated.

Happy watching!

How to get the browser and version in JavaScript

Sean McPherson — Tue, 19 May 2020 16:00:00 GMT

For a recent project, I wanted to display the browser and version on the screen. I figured that this would be possible in JavaScript, so I went searching around.

This led me to the User-Agent, "sniffing", and its wild and crazy history. I also read a bunch of articles on why serving different content to different browsers is a bad idea. I'll link them at the bottom of this article.

I just want to display the browser and version, so the referencing the user agent is a fine enough solution (even if temporary). But you should definitely think twice before you go user agent sniffing.

Accessing the user agent

You can access the user agent from the read-only global Navigator interface. That's as simple as writing:

console.log(navigator.userAgent);

Depending on your browser, you should see a few different outputs:

// Firefox
// Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:77.0) Gecko/20100101 Firefox/77.0

// Chrome
// Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.138 Safari/537.36

// Edge (Chromium)
// Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.138 Safari/537.36 Edg/81.0.416.77

// Safari
// Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1 Safari/605.1.15

These are fascinating, but for this article we are only interested in the differences. If we just look at the tail for each, we get:

Firefox: "Firefox/77.0"
Chrome: "Chrome/81.0.4044.138 Safari/537.36"
Edge (Chromium): "Chrome/81.0.4044.138 Safari/537.36 Edg/81.0.416.77"
Safari: "Version/13.1 Safari/605.1.15"

With this, we know have enough information to parse the string.

Sniffing logic

Chrome, Edge, and Safari all identify as "Safari", so let's start our logic with the simplest user agent: Firefox. After that, it's a process of determining who has a unique string to search for:

const { userAgent } = navigator;

if (userAgent.includes("Firefox/")) {
  // Firefox
} else if (userAgent.includes("Edg/")) {
  // Edge (Chromium)
} else if (userAgent.includes("Chrome/")) {
  // Chrome
} else if (userAgent.includes("Safari/")) {
  // Safari
}

Once you can identify the browser from the user agent, it's just a matter of using your favorite string parsing method to grab the version. Here's the code for Firefox:

if (userAgent.includes("Firefox/")) {
  // Firefox
  console.log(`Firefox v${userAgent.split("Firefox/")[1]}`);
}

If you know of a better way, please tweet me your solution and I'll give you a shoutout here.

Happy coding!

Additional reading

Browser detection using the user agent on MDN
Browser Detection is Bad by Chris Coyier on CSS-Tricks
History of the browser user-agent string by Aaron Andersen on WebAIM
Optimizing content for different browsers: the RIGHT way § 2.2 on W3

Logging with Eleventy and Nunjucks

Sean McPherson — Tue, 12 May 2020 16:00:00 GMT

This site was forked from the Eleventy base blog and uses Nunjucks templates. When everything is working, it is as smooth as can be. But when I run into an issue, I often find it difficult to debug.

Recently I was trying to do some logical rendering based on article tags. I knew the information was at my finger tips, but I couldn't guess the right key. All I need is a simple console.log()!

I searched combinations like "debugging in eleventy" and "console logging in nunjucks", but none of the suggestions quite worked. But they did give me an idea: a custom filter for logging.

Opening up .eleventy.js, I added the following lines:

eleventyConfig.addFilter("log", (value) => {
  console.log(value);
});

With that, I could then use the log filter in my Nunjuck template:


<li class="article"> ... </li>

Now I had Eleventy logging the entire article object in the terminal! Exactly what I needed.

I tinkered around with returning a <script> from the filter to log on the client too, but that required JSON.stringify() and piping the result into the safe filter. That was more than I wanted to mess with, but there might be a solution there that works for you.

Happy coding!

Store readable data

Sean McPherson — Mon, 11 May 2020 16:00:00 GMT

Imagine that you want to store data to look up the continent for every country in the world. The best data structure for this is a object/map/dictionary to quickly access the value without looping. I'll use the former for my examples:

Your object map will look something like this:

{
    "Algeria": "Africa",
    "Angola": "Africa",
    "Benin": "Africa,
    // ...
}

This is well and good, but you'll notice one bit of data is repeated: continent. Any time you have the same bit of data repeated, you run the risk of typing it incorrectly: "Africa" != "Afrcia". This is smell number one.

But let's ignore that for now. We want to include all of the countries in the world, so let's add a few more:

{
    "Afghanistan": "Asia",
    "Algeria": "Africa",
    "Argentina": "South America",
    "Armenia": "Asia",
    "Azerbaijan": "Asia",
    "Angola": "Africa",
    "Benin": "Africa,
    "Bolivia": "South America",
    "Brazil": "South America",
    // ...
}

As this structure grows to accommodate all of our data, it becomes less for humans and therefore less maintainable.

South America has 3 countries and/or territories that start with "B"... do we have them all? It's possible to answer that question, but it's not easy. This is is smell number two.

Instead of continuing down this path, let's go back to the drawing board.

Best for whom?

Our decision in choosing a data structure was to do what is best for the computer. Objects are a quick and easy way to retrieve the information that we need.

But in making that decision, we assumed that the best option was what is best for the computer. Instead, what if we stored data in the way that is best for the human maintaining it?

We would still start with an object/map/dictionary, but countries wouldn't be at the top level:

{
    "Africa": [
        "Algeria",
        "Angola",
        "Benin",
        // ...
    ],
    // ...
}

Instead we would put continents first. Why? Because our brains like to organize the information we encounter into useful groups. In this scenario, the most useful arrangement for counties is by continent.

With this approach, we made it easier to read and maintain, and removed duplicated data.

However, this structure is harder for the computer to read. So before we start this loop over again, let's add one more bit of code: a transformer.

Transformer

This is a function that will take our data in a particular format and "transform" it into another. In our example, it will turn our human readable code and turn it into computer usable code.

The implementation of this particular function isn't important, so just focus on the input and output:

humanReadable = {
    "Africa": [
        "Algeria",
        "Angola",
        "Benin",
    ]
}

computerUsable = {
    "Algeria": "Africa",
    "Angola": "Africa",
    "Benin": "Africa",
}

transformer(humanReadable) = computerUsable

If we run the transformer once at the beginning of our code, we now have the readibility of the first structure and the usability of the second.

So store readable data. You, or the developer after you, will thank you for it.

Happy coding!

MagnoliaJS 2020 conference notes

Sean McPherson — Thu, 16 Apr 2020 16:00:00 GMT

MagnoliaJS was thrown a COVID-19-sized curve ball for it's second annual conference. But that didn't stop the organizer's from hosting Mississippi's only technical conference: they cut the price and pivoted online with Zoom.

Niche graciously "sent" me to this two-day remote conference and here are some of my notes:

Day 1

Keynote: I'm Techie and I Know It

Speaker: Nashlie Sephus | @phenomenashlie

Find the area that you are most passionate about, and look for problems in that space
With that problem in mind, look for ways to use technology to solve it
There are ethnic disparities in data samples that negatively impact the products we create
We need to make a concerted effort to gather representative data
Good data in; good data out. Garbage in; garbage out.
Everybody has a responsibility to give back to the community that helped create them

ES8, ES9, ES10+… Let’s explore JavaScript’s exciting new features

Speaker: Tyler Clark | @iamtylerclark

Slides

In 2015 after a long quiet period, the largest release of JavaScript dropped
- This was ES6, and it was too much
Since then, there have been smaller, yearly releases
ES2016
- Array.includes() replaced ['foo'].indexOf('foo') > -1
  - Array.includes() has an optional second argument for starting point
- ** operator replaced Math.pow()
- Tagged template literals allow you to pass strings and values to functions
  - This pattern is used by libraries like styled-components
ES2017
- Promise.finally() allows you to write one cleanup step for promises
ES2019
- Array.flat() combines nested arrays into a single array
  - To flatten recursively, you can pass an Infitity argument
- Object.fromEntries() convert an array into an object
ES2020
- Dynamic imports: Global import() that returns a promise that resolves with the module
- Nullish coalescing: ?? checks for null or undefined js 0 || 'fallback' // 'fallback' 0 ?? 'fallback' // 0
- Optional chaining: ?. will returned undefined if any layer of an object doesn't exist
  - Works with dynamic properties: props?.data?.[props.name]
- Promise.allSettled: Like Promise.all() but fulfills even on rejection
Future
- Promise.any(): First promise that is a success or when all are rejected
- Private class methods and fields: #
- Top-level await: await does not need to be in wrapped in an async
- Renamed exports: export foo as bar from './file'
- Logical assignments: Assign variable based on logical conditions
  - Examples ||=, &&=, ??=

Static generated sites === great performance. What are you waiting for?

Speaker: Debbie O'Brien | @debs_obrien

Slides

Static is the new dynamic (which was the new static)
You can mix and match static sites and single-paged applications
- It's not "all or nothing"
Next/Nuxt are great options for walking the line
Performance tips:
- Audit your site for performance regularly
- Uses a service to optimize your images
  - Quality and format
- Reduce your CSS bundle with smart classes
- Send modern JavaScript to modern browsers
- Split your code
- Lazy-load as much as possible
- Audit your webpack build with the -a flag
Jamstack is worth it

Design Systems & CSS Variables: 2 Design 2 Systems

Speaker: Scott Tolinski | @stolinski

Slides

CSS variables are also known as CSS custom properties
- Not supported in IE
Declare a variable in a scope, and then reference it with the var() function
- First thought it was a liability
- After further reflection: scoping is a great feature
Reassign variables based on any selector: classes, media queries, etc.
Design systems comprise: Color, Type, Spacing, Character, Elevation
Pay attention to vertical spacing and font size
Margins are tricky: stick with margin-bottom
Styled Components allow you to scope CSS when you want it and embrace the cascade when you don't
- You can reference CSS variables insided styled components
Elements should be: simple, obvious, hard to break, and extensible
- Make components that can't be goofed up
You don't need a grid system: use CSS grid or flex box
Frameworks need to be taught
- Write only what you need, and use variables as the backbone
  - Colors, typography, and spacing

Vintage Bundles: Modern JavaScript for Modern Browsers

Speaker: Sia Karamalegos | @TheGreenGreek

Slides

Transpiling to older versions of JavaScript increases the side of our code
<script type="module"> is an indicator whether the browser supports ES2015+
You can save 24-70% in JS bundle sizes
Reduce load AND parse/eval time
- Translates to real business gains
Balance speed and support with differential serving
- Generate a modern bundle and a legacy bundle
- A main bundle that loads a polyfill on older browsers
Module scripts are supported by 90%+ of browsers by usage

Twitter Driven Development, Redux

Speaker: Justin Samuels | @ThugDebugger

Three keys of asking a good question in a tweet:
1. Ask: Is this a relevant question? Is it clear? Is it concise?
  - People have stuff to do, minimize the amount of time they need to take to help you
2. Pour: Share with others the knowledge that has been shared with you
  
  A candle doesn't lose it's intensity by lighting another
  - Offer to help other people
3. Effort: This is the hardest part
  - Don't make excuses; do the thing
Another acronym, ATL: ask the question, teach others, and learn new things

Create Dynamic Web Apps With Serverless and the Jamstack

Speaker: Jason Lengstorf | @jlengstorf

Demo

We still need servers
"Serverless" just means someone else's servers
- Managed infrastructure
- Let the experts (AWS, Microsoft, Google) do the heavy lifting
Serverless lets us focus on logic, not infrastructure
- It's hard, because it's a lot (and it's repetitive)
Live demo of Netlify Functions
- A way to add severless actions to static sites on Netlify
- Pretty cool

Day 2

Which Database? How to Choose the Best Place for your JSON Documents

Speaker: Suphatra Rufo | @skprufo

Database overview

Relational databases developed by IBM back in the 1970s
Non-relational databases respond better to unexpected events
- Instagram spikes at New Years handled better by non-relational dbs
JSON is the de facto way to communicate data

Key value

Dictionary data structure
- Pros: simple, ess memory, better performance, partiionable, horizontal scaling
- Cons: no query language, key management is vital, freeform search impossible
AWS DynamoDB

Document-oriented databases

A better way to store JSON

Multi-modes

Support and mange different models
Couchbase can normalize and denormalize documents
SQL querying with NQL

Thar Be Dragons: Rebuilding Native UIs on the Web

Speaker: Chance Strickland | @chancethedev

Slides

The web started as a platform for sharing documents
As it grew, we started to develop more interactive elements
Today, we have complex HTML elements for rich interactions
- Why don't we use them?
Reasons why we build custom controls: appearance, functionality, browser differences, accessibility issues
Libraries can only do so much to recreate native UI elements
Takeaways
1. Use HTML
2. Identify good primitives
3. Understand the full scope

Svelte and the Great Space Elevator

Speaker: Shawn Wang | @swyx

Slides | Talk

How do we get into space?
- There is a tradeoff between the amount of fuel you need (to carry valuable payload) and the weight from that additional fuel
How do we make the web?
- The web wasn't designed for everything that we use it for
- This is especially true for mobile web (low powered, slow connections)
- JavaScript is really heavy
- The framework that you choose has a big impact on the ultimate weight
- The tyranny of run-time frameworks:
  - Choose two:
    - Ship more features
    - Write less code
    - Send less JavaScript
A way out
- Put up a rope!
- A space elevator is a big upfront investment, but a low per use cost
Compilers as the future
- Tom Dale's Compilers are the new Frameworks
- Frameworks are shifting towards smart compiling to reduce bundles
- Svelte
  - Write less code: learn extra syntax, but it will be worth the time
    - Personal experience: 20% less code, 93% smaller bundle
  - No virtual DOM: it's as close to writing vanilla JS as possible
    - Compile Svelte in Your Head by Tan Li Hau
  - Truly reactive: Reponds to changes with $ syntax
- Lighter tooling that only makes it to the build when used

Progressive Enhancement in React

Speaker: Kayla Sween | @_kaylasween

Slides

Spectrum of delivery: HTLM > CSS > JavaScript
- Structure it with HTML
- Make it pretty with CSS
- Add behavior with JavaScript
Why Progressive Enhancement?
- Enhanced accessibility and performance
Start with core functionality and choose the simplest technologies to make it work
Then you can sprinkle on optional features

Building JAMstack CMS: A Full Stack CMS for the Modern Age

Speaker: Nader Dabit

Slides

A Wordpress alternative with all jamstack technologies
More information: https://github.com/jamstack-cms

Handling Data with React Query

Speaker: Domitrius Clark | @domitriusclark

Slides | Course

I accidentally missed this!

Canvas: The Final Escape Hatch

Speaker: Ken Wheeler | @ken_wheeler

Slides

Canvas is a browser API to draw 2D graphics
WebGL: alternative, high performance API for drawing on the canvas element with the GL language
For games, data vizualization, high-performance graphics, granular control over rendering
Drawbacks: No layouts, no z-index, bad a11y, with a strange imperative API
Drawing methods
- Immediate: Redraws the entire canvas every time
  - Tough on CPU
- Patching: Only redraw pars that have changed
  - Hard to handle full draws
- Compositing: Layering convases
Events: All events are listening to the parent canvas
- Use a spacial index with a library like RBush
Scroll: Let the browser and DOM help you
- Using overflow and elements porportional to the content
- You can use a layout solution like Yoga (yoga-layout)
Plug: react-blazing
Other libraries: Skia, Lottie, PixiJS

How to Supercharge Teams with Carefully Crafted Conventions

Speaker: Chris Ball | @cball_

Slides

Every good scalable system relies on process and automation
- How you develop, your workflows, how you do things
Process is built by conventions
How to be your best dev:
- Play to your strengths
- Understand what slows you down
- Eliminate decision fatigue
Examples in the wild
- Next.js: leans in to standardized conventions in React
- GraphQL: a system for requesting data and documenting
- Utility css frameworks
- Semantic versioning
Crafting your own
- Find a base and build on it
  - If you're disabling everything, it means that you are following the wrong convention
- Create a plugin for your team
- Add a PR checklist
  - Screenshots (GIFs)
  - Automated tests
Leverage generators
- Hygen templates that live alongside the code
How to perfect process
- Synchronization: Understand the vision with RFCs
  - Summary, motivation, examples, how to teach, how to enforce, drawbacks, and questions
- Repitition: Continually refining with retros

Reflection

I enjoyed having a single track of JS-focused talks. The remote conference had it's own technical issues, but overall I think it was a great content delivery method for these types of topics.

Some of the talks were prerecorded, which might sound like a let down, but the speakers were presents in the chat and willing to answer questions live. That was a neat feature that other conferences cannot offer.

Whether it's remote or in-person in 2021, I recommend checking out MagnoliaJS Conference.

How to open the Dev Tools

Sean McPherson — Wed, 15 Apr 2020 16:00:00 GMT

As a web developer, one of the most powerful tools in your arsenal is the browser's developer tools.

Here is a list of all the ways to access the dev tools for your browser and operating system.

With your mouse

In the window

You can enter the dev tools with the mouse by right clicking on any element. In the menu that appears, select "Inspect" or "Inspect Element":

Chrome: Right click > Inspect
Firefox: Right click > Inspect Element

Through settings

You can also enter the dev tools through your browser's settings menu.

Chrome: Three dot menu > More tools > Developer tools
Firefox: Three bar menu > Web Developer > Toggle Tools

Keyboard shortcuts

Beyond the mouse, there are shortcuts that you can use to open the dev tools without leaving your keyboard.

The shortcuts differ by browser and operating system, so I've tried to group them logically below.^[1] Windows and Linux commands are the same, so I've comibined them into "Win/Lin".

Elements/Inspector

The default tab, it allows you to inspect and edit the elements in the DOM, their properties, and styles.

Chrome & Firefox

macOS: command + option + c
Win/Lin: control + shift + c OR F12

Console

This tab prints the console calls from your code and allows you to write JavaScript that interacts with the current web page.

Chrome

macOS: command + option + j
Win/Lin: control + shift + j

Firefox

macOS: command + option + k
Win/Lin: control + shift + k

Debugger

This tab shows all the source code for your project and allows you to debug with breakpoints.

Firefox

macOS: command + option + z
Win/Lin: control + shift + z

Network

This tab logs all network requests and provides detailed information about the responses.

Firefox

macOS: command + option + e
Win/Lin: control + shift + e

Most recent

This will open the most recently opened tab. In my experience, it's the shortcut that I reach for most often.

Chrome & Firefox

macOS: command + option + i
Win/Lin: control + shift + i

Phew! That was a bigger undertaking than I first imagined. If I made any mistakes, please let me know.

I hope that helps! Happy tooling!

I spent a good deal of time debating how to outline this article. I eventually decided to group things by dev tool tab instead of browser or operating system. There is more in common than not, so this seemed the simplest. ↩︎

Tools for custom Slack emojis

Sean McPherson — Tue, 14 Apr 2020 16:00:00 GMT

Custom emojis are a fun way to customize your Slack workplace. The fun, silly, and can provide some genuine utility for the rest of your team.

Slack already has a guide for adding custom emojis, so I won't be reinventing the wheel here. But I wanted to share some of the online tools that I use to whip out some fresh emojis for every occasion.

Tools

Google Images

When looking for an emoji, I usually start with a Google Images search. Once I get the results, I use their tools to change the color and the usage rights.

Tools > Color > Transparent: Gets you those sweet transparent backgrounds
Tools > Usage Rights: I don't often do this because most images are not correctly labelled, but it's still good to know

Once I find the perfect image, just right-click and download the image or save the URL to use in another tool.

SVG to PNG

Sometimes the perfect image from Google is an SVG, but sadly Slack does not support SVG emojis. Enter SVG to PNG, which – you guessed it – converts SVGs to usable PNGs.

Remove BG

Other times the perfect image is a JPG or something with a solid white background. You can use these as emojis, but they don't look as nice. Instead, you can take that image and easily remove the background with removebg.

EZ Gif

This is probably my favorite tool on this list because it works so well. Despite the name, EZGif.com is for editing all types of images with crops, resizes, optimizations, and other effects. The neatest bit is that you can pipe the output from one edit into another.

You might start with one image from Google, then crop it, resize it, and optimize it to make it ready for Slack.

I hope that helps! Happy reacting!

Laws I Love

Sean McPherson — Tue, 14 Apr 2020 16:00:00 GMT

Laws

The Golden Rule: Treat your neighbor as you would like to be treated
Campbell's Law: Using an social indicator for decision-making will lead to distortion and corruption of the process it is intended to monitor (source)
Goodhart's Law: When a measure becomes a target, it ceases to be a good measure
Parkinson's Law: Work expands to the time allotted

Programming reads

Sean McPherson — Fri, 20 Mar 2020 16:00:00 GMT

This is an alphabetical list that has helped shape the way that I think about software engineering.

At some point in the future I may add some commentary on why I found these insightful. Until then, you'll have to form those opinions for yourself.

Articles

Give it five minutes by Jason Fried
Optimize for change by Dan Abramov
The wrong abstraction by Sandi Metz
Write code. Not too much. Mostly functions. by Brandon Smith
Write code that is easy to delete, not easy to extend. by tef

Great programming reads

Sean McPherson — Fri, 20 Mar 2020 16:00:00 GMT

This is an alphabetical list that has helped shape the way that I think about software engineering.

At some point in the future I may add some commentary on why I found these insightful. Until then, you'll have to form those opinions for yourself.

Articles

Give it five minutes by Jason Fried
Optimize for change by Dan Abramov
The wrong abstraction by Sandi Metz
Write code. Not too much. Mostly functions. by Brandon Smith
Write code that is easy to delete, not easy to extend. by tef

Free to grow

Sean McPherson — Mon, 17 Feb 2020 16:00:00 GMT

I previously wrote about testing UI components, and why I recommend that you don't use snapshots. I finished that article with this line:

Your tests should give me the confidence to refactor any component to your heart's content. They should fail if you change functionality, not structure.

Instead, I advocate for writing entirely functional tests, asserting based on the required functionality of the component.

This type of testing is certainly more difficult and time-consuming (especially compared to snapshots). But I think the benefits are clear: they hold up under refactoring, promote iteration, and gives you the confidence to grow.

Refactoring

I have yet to come across a component or complex function I've written that couldn't use refactoring. Maybe it's a new technique that is perfect for these situation, or perhaps it's logic that appeared logical at the time that isn't on a second look.

Whatever the case, refactoring code is a constant in this profession, and tests (should) help you embrace it.

When you write a functional test, you start with a statement like "With A input, my function should output B." Then you write a test that covers that condition. Your test doesn't care how you get from A to B, just that you always do.

Maybe the first time through you take a long an circuitous path with lots of conditional logic. Next time you refactor, you take a more direct route. Then you decide that some of those conditions were necessary. The test doesn't care, so long as fn(A) = B.

Iteration

Refactoring is looking back at code, while iterating is looking ahead. Our goal as software engineers should be to continuously deliver incremental improvements on our active products. This means slowing building on what we already have.

Maybe you designed a function with situation A in mind, but notice that with a minor adjustment it can easily handle B and C. Once you are done making that change, the functional test that you wrote for situation A should be the barometer for moving forward.

If the test passes, then you're good to proceed. If not, then you've made a breaking change; go back and rethink your approach.

When you're looking to add a new feature to your product, a passing test suite should give you full confidence that all of your changes are backwards compatible.

Free to grow

A redwood tree doesn't grow to 300 feet over night. Rather, a journey of a thousand miles begins with a single step^[1].

Great software is not written in one sitting. It is fine tuned and improved slowly over the lifespan of the product.

This means a regular cycle of refactoring and iteration–improving and expanding. The more your software is able to do this, the healthier it is and the better it will become over time.

A functional test suite enables and encourages your software to grow this way. You can make improvements to your code and verify that it still functions. You can add more features while being assured that there are no breaking changes.

To set your team or product up on a thousand-mile journey, start with your best foot forward. Write the kind of tests that enable you to take each successive step with confidence.

Write functional tests.

Paraphrased from Laozi's Tao Te Ching ↩︎

How to check npm scripts in current directory

Sean McPherson — Thu, 06 Feb 2020 16:00:00 GMT

As a front-end engineer, I spend a lot of time jumping in-between JavaScript projects. Often times I want to run a command from those projects to start watchmode or spin up a service.

The commands that I want to use are in the package.json under "scripts". When I haven't memorized the common commands, I need to either open the file in my editor or use a Unix utility like cat.

# In my editor
code package.json

# In the terminal
cat package.json

Both of these commands work, but they are slow. package.json files can be massive, including dozens of dependencies, dev depenendencies, and other fields. To find the scripts, I need to sort through the cruft to find the information that I want. This isn't very efficient.

Instead, I wrote a short bash scripts to quickly do the work for me. Here is the code in all of its glory:

#!/bin/bash

if [[ -f "package.json" ]]; then
    node -pe "JSON.parse(require('fs').readFileSync('package.json').toString()).scripts"
else
    echo "There is no `package.json` in this directory"
fi

First, I let the computer know to run this file with bash. Then I set up an if block: if there is a package.json file in this directory, then run the following code; if not, then print a "can't find it" message.

The code to run, inspired by a StackOverflow comment, is a node process with two flags:

-e tells node to evaluate the script that you pass
-p tells node to print the results to the console

Within the script, I am using JSON to parse the results of a fs.readFileSync() of the package.json, then diving down to the scripts key.

I set it up by running chmod with two flags on the file in a scripts/ directory:

chmod u+x ~/scripts/npm-scripts

Then I could resource my terminal and run the command with npm-scripts. Bish bash bosh.

Everything worked fine, but I wanted an easier way to share my script with others. The chmod command and flags are hard to remember, so it would be easier if the script could be compressed into a one-liner that could be aliased in their ~/.bash_profile.

To do that, I removed all the new lines and added semicolons to separate the statements. The alias needed to be wrapped in quotes, so I escaped all the double quotes within the script.

Now I had a handy alias to share:

alias ns="if [[ -f \"package.json\" ]]; then node -pe \"JSON.parse(require('fs').readFileSync('package.json').toString()).scripts\"; else echo \"There is no package.json in this directory\"; fi"

Overall, I'm pretty happy with this utility. Going forward, I would like to extend it so that you can lookup and key on package.json by passing an argument.

Update – Apr 4, 2020

I created a new script to which you could pass an argument to pick a key from the package.json. This script is in zsh, but I think it ports to bash:

# rpj - Read package.json
function rpj () {
  if [[ -f "package.json" ]]; then
      node -pe "JSON.parse(require('fs').readFileSync('package.json').toString())['$1' || 'scripts']"
  else
      echo "There is no `package.json` in this directory"
  fi
}

Note how the shell arguments need to be wrapped in '' in order to work. Otherwise JavaScript thinkgs that it is looking for a variable, which is undefined.

If no argument is provided, then it falls back to printing the scripts which is probably the most common use case for me.

I also named the new function rpj for "Read package.json" to avoid any confusion with name servers.

For the next iteration, I would like to handle errors, but that is a project for another day.

What to include in every node module

Sean McPherson — Mon, 03 Feb 2020 16:00:00 GMT

All that is required to publish a node module is a package.json file with a few fields. However, there are more components to a good package.

Here are a few things to include in every node module that you publish:

README.md

`README.md`

A README contains all the information necessary to use your node module. They come in all shapes and sizes: decorated, detailed, and simple. But they all need to include a one important detail: how to use the package.

There are many ways to create a good README, I like the format set out by "Make a README".

How to remove duplicates from an object array?

Sean McPherson — Mon, 03 Feb 2020 16:00:00 GMT

Reviewing a recent code exercise at work, we came across a situation where a candidate wanted to ensure that there were no duplicates in an array of objects.

The solution, which seemed to have been cobbled together from suggestions in this Stack Overflow thread, included Array.from(), new Set, Array.map(), and Array.find().

It worked, but it definitely fulfilled the definition of "frankencode".

Let's look at a simpler solution to this common problem with a simple O(n) complexity.

Setup

The data here could be pretty complicated, so I'm going to reduce it to the simplest form. We have an array of possibly duplicate objects, and we'll know that they're duplicated based on the name key:

const listWithDups = [
  { name: "one" },
  { name: "two" },
  { name: "one" }, // <-- Duplicate
  { name: "three" },
];

We want to be able to loop through this data as few times as possible in order to remove that duplicate entry.

Steps

There are a few things that we are going to need in order to solve this problem. First, we're going to need a new array to which we'll add unique items. Second, we're going to need a way to keep track of the items that we have already seen. And third, we're going to need a way to iterate through the data.

Let's look at those one at a time.

New array

For this process, we want this to create a new unique array without modifying the original. This is a good practice, because it gives you the ability to compare your data down the road.

const uniqueList = [];

When we are iterating through our original array and come across a unique object, we'll add it to uniqueList with Array.push().

Unique key tracker

In order to know if an object is unique, we need to know all of the keys that we have seen before.

There are a few different data types that we could use, but the best option here is an object; they're perfect for looking up information based on a known key.

This object only exists to track those keys. It will not be returned and no other process depends on its information. That makes it a temporary variable, and we should name it as such:

const temp = {};

For every object in our list, we'll check to see if their name key exists on our temp object. If it does not, then we'll add it to the object and then add the object to the unique list. If it does not, then we know that it is a duplicate and can move on.

Iterate

Since we are going to be iterating through data, the easiest^[1] way to do that is with a for loop. We're going to use a for...of here because we don't care about the index number:

for (let item of listWithDups) {
  // TODO: Check if item is unique.
  // If so, add it to the list and remember it's name.
  // If not, pass over; it's a duplicate.
}

Now we can go about implementing the steps above.

Since we're using our temp object to track all of the items that we have already encountered, we can check to see if each item's name exists as a key on temp.

Note: We haven't written the logic to add items to temp yet, but we know that this is how we want the application to work.

for (let item of listWithDups) {
  // If we haven't seen this name before...
  if (!temp[item.name]) {
  }
}

Within this if block, we'll do our "unique name" logic. We want to add the item to our unique list and remember the name for next time.

for (let item of listWithDups) {
  // If we haven't seen this name before...
  if (!temp[item.name]) {
    uniqueItems.push(item); // Add to unique list
    temp[item.name] = true; // Remember the name
  }
}

Once that loop has run, we will have built our uniqueItems array without duplicating any values. We have successfully de-duped our array with only a single iteration!

Sample

Here is a Repl of the solution. Feel free to fork it, make improvements, and share your code with me.

Happy coding!

YMMV ↩︎

Write a draft script for your SSG blog

Sean McPherson — Fri, 31 Jan 2020 16:00:00 GMT

This site is powered by Eleventy, a simple static-site generator. All of the pages and articles exists as markdown files that are converted into HTML files via Nunjuck templates at build time.

For a blogging platform, it's pretty neat. I enjoy being able to run the whole site from the comfort of my text editor and the command line (with a little help from Netlify for continual deployments).

The secret sauce behind markdown-based sites is the frontmatter: specially formatted content at the top of a markdown file that is read by the generator. Here's what the frontmatter for a typical article looks like:

---
layout: "@layouts/ArticleLayout.astro"
title: Add event listener for class change
description:
  How to create a custom event listener for class names using the
  MutationObserver API
date: 2019-05-10
tags:
  - JavaScript
  - Web
---

<!-- Start writing your article here -->

When I want to write a new article, I need to make sure I have all of those fields populated in a particular way in order for Eleventy to generate the page correctly.

Formatting and required fields are not something that I care to remember, so I wanted to develop an easier method for generating a draft for this blog. This is my journey.

Setup

Most static-site generators will have a directory for you to store some files that are excluded from the build process. For Eleventy, that default directory is _includes/. I added a subdirectory for templates/ and added an article.md. All it contains is the bare-bones frontmatter for a new article:

---
title:
description:
date: 2020-01-01
tags:
  - SAMPLE_TAG
---

I hard coded the date because I have a hard time remembering the YYYY-MM-DD format. It would be cool for the script to generate that for me.

Solution 1: Bash script

Now that I have a template to reference, all I really need to do is write a simple script to copy that file to the articles/ directory. I added the following code to a create-draft.sh file in the root directory:

#!/usr/bin/env bash

title=draft

if [ "$1" ]
then
    title=$1
fi

cp "_includes/templates/article.md" "articles/_$title.md"

This script declares a variable title and sets the value to the string "draft". Then it checks to see if another argument is passed. If so, then it reassigns title to that value.

Then it copies the article template to the articles/ directory with the filename title.

Note: I am prepending an underscore to the name of the file because I have configured Eleventy to ignore markdown files that begin with an underscore from the build. The solution got Eleventy's stamp of approval.

I added a draft script to packages.json:

{
  "scripts": {
    "draft": "sh create-draft.sh"
  }
}

Once that was in place, I could call my script by running:

npm run draft my-new-article

This worked, but it was pretty simple. I needed to remember to use kebab case for the title of the article so that the file name would work. It didn't add the title to the copied file, nor set a date.

It served me well for a while, but eventually time came for a change.

Solution 2: node.js script

To be fair, the original bash script could have been improved to meet all of my needs. But I'm not as comfortable with Bash as I am with JavaScript, and I jump at every opportunity to work in node.js.

A new Twitter handle

Sean McPherson — Tue, 28 Jan 2020 16:00:00 GMT

I have had a difficult relationship with Twitter. When it launched, I was in high school and still active on a number of forums and AOL instant messenger. Around the same time, Facebook opened up to non-collegiate users, so I and a lot of my friends signed up. Later I went all in on Google+.

Twitter always seemed different. Rather than connection-based interactions, Twitter was more simply a broadcast platform. This meant that the reach of your message was tied not the the number of individuals with whom you could connect, but instead the number that you could impress. It was a popularity platform.

As a teenage contrarian, that was intensely unappealing to me.

Fast forward a few years and I started doing freelance web design and development while in college. By then both Twitter and I had matured, and I saw it as an opportunity to promote my business. @seanmcp was taken, so I registered the handle @sean_mcp. After a largely unsuccessful go, I shuttered the business and deleted the account.

The decision to delete that account is one that I have regretted for the past eight years.

By the mid 2010s, I was interested in getting on the platform for some soccer journalism I was doing. Most iterations of my name were taken, so I settled on @mcpsoccer. That served me well and still exists today.

I was teaching at the time too, so I created a professional account for my classroom: @mrseanmcp. When that era ended, I changed the handle first to @seanthemcp and then @mcpmakes and then @mcpcodes.

By this time I had settled on a new career path and saw the value of Twitter as a developer. In an effort to consolidate my online brand™, I changed the handle to @_seanmcp. But while some folks are able to own the underscore, it left me with a sense of insecurity. Why had I given up @sean_mcp all those years ago?

In 2020, I sat down with my wife and brainstormed some ideas for a new handle. Here is a short list of the options we enumerated in alphabetical order:

@askseanmcp
@biseanfrise
@nabasson^[1]
@seanaroll
@seancloudnine
@seanmcpdotcom
@seantheupandup
@snmcp
@thierryseanry

As you can probably guess, we had a good time coming up with the punnier options.

After much internal deliberation, I settled on @snmcp. First, it's as close to my brand as possible. Second, it doesn't add additional words, letters, or symbols. And third, it's short and quick to type.

At first I didn't like the look of the new handle, but after a few weeks it's starting to grow on me. I'm hoping that, starting this new decade, I will finally be content on Twitter (LW).

Like Barnabas, which means "son of encouragement" ↩︎

What default parameters do (and don't do)

Sean McPherson — Mon, 13 Jan 2020 16:00:00 GMT

Default parameters are a handy feature in JavaScript. MDN has a more thorough explanation, but imagine a function that greets a user:

function greetUser(name) {
  return `Hello ${name}!`;
}

When we call our function and pass a name, we get the expected log:

greetUser("Abby");
// Hello Abby!

But what about when we don't pass a name? Quiz time: What is going to log?

greetUser();
// Hello undefined!

Is that what you expected? Since we passed no argument, the name parameter is undefined.

JavaScript — ever the helpful friend — sees that we want to include that value in a string, so it coerces it into the correct type, and then logs it.

You probably don't want your function to return Hello undefined!, so let's try a default parameter.

What default parameters do

Add the following to the declaration line of greetUser():

function greetUser(name = "there") {
  return `Hello ${name}!`;
}

Now we're saying to our function, "if you don't receive an argument, set the value of the name parameter to be "there"." When we call our function and pass an argument, we get the same result:

greetUser("Abby");
// Hello Abby!

However, when we call this updated function without passing an argument, the default parameter kicks in:

greetUser();
// Hello there!

Bingo! Now if our function is called without an argument, then the resulting log still makes sense.

In this situation, the default parameter is working as a fallback value. This is probably the most common use case. But you will also find default parameters useful to reduce existential checking.

Reduce checks

Imagine a user object with a name key that we want to log. In order to update our original function to handle this use case, I might do something like this:

function greetUser(user) {
  if (user && user.name) {
    console.log(`Hello ${user.name}!`);
  } else {
    console.log("Hello there!");
  }
}

You can imagine the complexity of this dive check growing with the size of the user object. Instead, we can save ourselves some trouble by defaulting that parameter to something that we can use right away:

function greetUser(user = { name: "there" }) {
  console.log(`Hello ${user.name}!`);
}

We set the default value of the user parameter to be an object with a name key that we could access.

I use this pattern often; default props make it easier to see what types and shapes of arguments that any given function or component is expecting.

What default parameters don't do

A parameter will only default to a given value if it the argument passed is undefined. So either no argument is passed, or the function specifically receives undefined as an argument.

When I first learned about default parameters, I developed the wrong mental model — associating them with falsy values in JavaScript. My incorrect thinking went like this:

When ever I pass an argument that evaluates to false, the default parameter will kick in and save me from errors!
— Sean, being wrong

I ran into this problem at work when I expected a function to return the default parameter when passed a null argument.

function favoriteAnimal(animal = "wolf") {
  console.log("Favorite animal:", animal);
}

favoriteAnimal("manatee");
// Favorite animal: manatee

favoriteAnimal();
// Favorite animal: wolf

favoriteAnimal(null);
// Favorite animal: null

That's because null is a deliberately passed value (even if I didn't know that I was deliberately passing it). Default parameters will only kick in if that argument is omitted or passed as undefined.

To state it plainly: falsy values do NOT become default parameters. It only works for undefined.

So the above code is worked as designed, even if it's not what I expected. Time to update that mental model!

Hopefully that clears up the mystery of default parameters for you. Happy coding!

Reviewing 2019 goals

Sean McPherson — Wed, 08 Jan 2020 16:00:00 GMT

To kick-off 2019, I wrote an article in which I set some goals for 2019. I had planned to check in on those goals more frequently:

I am going to check back on these goals throughout the year and track my progress in a different article.

But alas, the best laid plans of mice and men!

Now that it is ~~December of 2019~~ January of 2020, I wanted to take the chance to measure my progress towards those goals that I set.

Review

👎 Dive deeper into Python

I didn't do anything more with Python this year. I even turned away from Python for simple scripting projects in favor of Bash or node.js. I'm still a fan, but I don't see a big use case for Python in my current career path.

👎 Learn machine learning

ML sounds cool and exciting, but there weren't a lot of opportunities to utilize it in my work as a front-end engineer.

👎 Demystify module bundlers

This is still a good idea, but I haven't done it (yet).

🎉 Release two npm packages

I published two npm packages in January of 2019 alone. This is something I want to continue to do going forward.

🤷‍♂️ Investigate React tooling

I learned a lot this year about tooling in a JavaScript environment, but I think my goal was a little misguiding in thinking that a dotfiles repo would be the answer.

👎 Publish 24 articles

By my count, I published about a dozen articles in 2019. I would like to strive for this goal in 2020 too.

👎 A partner for Jr Devs

I moved to Pittsburgh in the summer of 2019, but Jr Devs had stalled before that. I never found the right fit within the Atlanta developer community, and a partner wasn't going to change that.

🎉 Speaking on tech

While I did not present at another Meetup in 2019, I did give a talk about React and Accessibility at the Connect.Tech conference in Atlanta. I enjoyed the experience, but I think sharing at Meetups is a little more my speed.

👎 Dating my wife

We didn't schedule any official dates in 2019, but I don't think either of us missed it. I need to check with my wife again to see if this is something we want to try in 2020.

🎉 Being a good father

While we were living in Atlanta, I cared for our son on Saturdays while my wife worked. We would regularly go to the park or around town on errands while she was gone. Here in Pittsburgh, her schedule has changed and I don't have that dedicated parenting time.

Once the winter is through, I want to sieze opportunities to take my son on new adventures in a new city.

🎉 Leading our household

In 2019 we continued to have regular family worship in the evenings and added another time over the breakfast table. It has been a huge encouragement to see my son begin to develop the skills necessary to worship God throughout his life: sitting, listening, singing, and praying (sort of). I no longer teach Sunday school but am open to that possibility here in Pittsburgh.

👎 Work out

I wasn't even close. This is something to reassess in 2020.

👎 Play soccer

I was not able to attend pick-up soccer regularly in Atlanta and have yet to find a group in Pittsburgh. This is something that I would like to try again in 2020. Maybe twice a month, though.

Total score: 4/12 (33.33%)

At face value, that's not a great completion rate. But it is all a learning opportunity.

You can see by going through the list the difference between goals that I thought were important vs. the ones that were actually important. I'm happy with the four successes and am looking forward to reaching towards the other goals in this new year.

Here's to new attempts in a new year!

2019 into 2020

Sean McPherson — Wed, 08 Jan 2020 16:00:00 GMT

2019 was an exciting year, though perhaps not as eventful as 2018. Here are some of the major events and accomplishments of the past year in mostly chronological order.

2019 in review

Last year, I:

Officially hit one year in the industry: My previous experience is valuable but scattered; this is one year straight of work
Took on new work responsibilities: I began work as a UI Engineer lead at TSYS
Accepted first conference talk: I got the news in June that I was accepted to speak at Connect.Tech 2019
Attended two conferences: Abstractions in Pittsburgh and Connect.Tech in Atlanta
Interviewed at multiple companies: Dusted off the ol' code challenge skills
Accepted an offer at Niche: Front-end Software Engineer at an exciting company in Pittsburgh
Moved to Pittsburgh: Said a sad "goodbye" to all our wonderful friends in Atlanta
Added some new features to Niche.com: Most of them minor, but it's neat to see your work in action
Spoke at a conference: React and Accessibility at Connect.Tech 2019
Started a learning program at Niche: Weekly tech learning sessions over lunch with live demos
Published eleven npm packages: And learned a lot about package management along the way
Passed 10K downloads on a package: a11y-react-emoji is off to the races!
Published thirteen articles: Off the mark, but still solid

Some of these things were fulfilling goals that I had set in the previous year, while others were completely out of the blue. I'm so thankful for the opportunity to try new things this past year.

Previewing 2020

Looking forward to this year, there are several things that I want to learn and do. I am going to list some general goals, followed by measurable ways that I can accomplish them.

Read more: I want to read four professional and six personal books
Open source: I want to become a maintainer on an open-source library (that I didn't create)
Write more: Last year I missed the mark, so I'm going to set a goal of publishing 18 articles in 2020
Speaking: I want to create a deck and present at a Meetup here in Pittsburgh
Father: I want to use the time I have with my son more productively, going on father-son outings twice a month
Faith: I want lead family worship every day, and read/reflect on the Bible daily
Fitness: I want to exercise 5 days a week
Soccer: I want to find room in the family schedule to play a pick-up game twice a month

The fastest way to look for object properties

Sean McPherson — Tue, 31 Dec 2019 16:00:00 GMT

I manage a library called onkey-event-manager that helps users map functions to keyboard actions. Part of the library is a validation step that looks for properties on an object.

To make this step as performant as possible, I wanted to know what the fastest method for checking an object for a given property.

Contenders

`Object.hasOwnProperty()`

This is the built-in method for checking an object for properties. The only question is whether this method is more performant than other options.

const obj = {};

console.log(
    obj.hasOwnProperty('test');
    ? 'exists'
    : 'does not'
)
// -> 'does not'

`Object[]`

By referencing the property on the object directly, you can let JavaScript's type coercion to force a boolean.

const obj = {};

console.log(obj.test ? "exists" : "does not");
// -> 'does not'

Note: This method for checking a property will fail if the value at the given property is false/falsey (e.g. const obj = { test: false }). Since I can guarantee that case won't happen, I can still use it.

"Stop Teaching Code" in JavaScript

Sean McPherson — Tue, 26 Nov 2019 16:00:00 GMT

At some time in the future, I would like to return to the classroom to teach programming to middle school students. That is the age when I first starting coding, and I would love the opportunity to inspire the next generation of developers at an early age.

So I'm on the lookout for good techniques, strategies, and patterns for teaching the basics of computer science. Hit me up if you have any.

Today I read "Stop Teaching Code" by Jeff Olson where he described a different approach to teaching programming. He advocated for ditching the definitions, unrealistic examples, and non-sensical names and use real-world puzzles for students to solve.

It's an interesting read, and I recommend it if you have any dreams of teaching programming.

All of the examples in Olson's article are in Python, but I plan on introducing students to code with JavaScript. So here are all of the examples from his article rewritten in JavaScript:

Translated Examples

Note: I've linked to the nearest anchor on Medium, but they appear to be generated and might change. Your mileage may vary.

1. Code for Predictions

let name = "Tamara";

console.log("Hello" + name);

2. Example 1: Conditionals

let age = 15;

if (age >= 18) {
  console.log("You're old enough to buy a ticket for an R-rated film.");
} else {
  console.log(`You'll be old enough in ${18 - age} years`);
}

3. Example 2: Collections

let favorite_foods = ["Sushi", "Tamales", "Mofongo", "Pizza", "Chicken Tikka"];

console.log(favorite_foods[2]);

3. Example 3: Objects

let user1 = User("Ty", "Tdog@aol.com", 16, "Pa$$word");
let user2 = User("Sarai", "SMendes@hotmail.com", 15, "Kangaroo!");
let user3 = User("Osu", "Osu22@gmail.com", 12, "12345abcde");

console.log(user2.age);

I hope that helps. Happy coding!

5 Lessons from 10k open-source downloads

Sean McPherson — Mon, 25 Nov 2019 16:00:00 GMT

In April of 2018, I wrote an article "How to use emojis in React". At the time, the default eslint configuration for Create React App would flash an error if you put an emoji in a rendered string.

The answer was to wrap the emoji in a span with some appropriate attributes to notify screen readers that it was being used as an image. Since it was React specific, I included a component that handles all the attribute logic for you.

The article gained some traction and, thanks to Medium's SEO, remains the first page on a Google search for "use emojis react". Later that same year, I decided to create and release a package for the included React component. Thus, a11y-react-emoji was born.

Twelve months and 17 versions later, and my little package has 10,000 downloads from the npm registry. Beyond that, the repo has 15 stars on GitHub and is used by 61 other projects.

There have been some maintainer highs and lows in that time, so here are the five biggest lessons I learned along the way.

1. Packages can be simple

Before stepping into the world of open source, I thought of packages as a black box. But I've since learned that they are much simpler than they appear.

In the JavaScript world, a package is just four files:

A package.json with a few fields,
an index.js,
a README.md,
and a LICENSE

And the last two are optional. Once I got over the hurdle of publishing my first package, the curtain of mystery fell away.

Take a moment and look through the node_modules/ of you next project, and you'll see a bunch of directories with those files mentioned above. Not too scary!

2. Dependencies can get tricky

If you're publishing a basic utility, you may not need to worry about dependencies. But the more complex your library becomes, the more tricky it becomes to manage your dependencies.

a11y-react-emoji was a shared React component written in TypeScript, which meant I needed to manage React and TypeScript dependencies. I wanted the component to be fully tested, so add Jest and Babel to the mix. Error checking? Add ESLint. Consistent formatting? Bring Prettier along.

Before long, your dependency tree can grow really big. Keep something in mind when creating a package: every dependency you add is another dependency that you have to be willing to manage. That can add a maintenance work to your package.

3. Security is a hassle

I'm not an expert on security. So when GitHub flags one of my packages for potential security risks, I still feel a chill run down my spine.

When I first created the a11y-react-emoji, I was quick to address every security risk highlight, merge the changes, and release a new version of the package. Every time it felt like I was just a few clicks in front of the next Equifax data breach.

But after a few months at the helm, I stopped caring so much. Part of that is how the project is structured: a11y-react-emoji has no dependencies, which means that no flagged security issues present a risk in production.

Every potential issue is within the dev dependency tree, which isn't a big deal to the package user.

However, keeping a large-scale library with tons of dependency ahead of all security risks would be a nightmare. That's not something I'm chomping at the bit to do in my spare time.

4. Leverage the community

Earlier this year, @bdbaraban filed an issue with a11y-react-emoji concerning its types. I was just learning TypeScript when I wrote the library, and his suggestion was an improvement to the existing code.

I asked him if he wanted to open a pull request to make the change but quickly got antsy and did it myself.

That was a mistake. The beauty of open-source is the community; it's the product of our collective intelligence. It didn't matter that the current types for the package were limited. What would have been more important would be to wait and give someone else the opportunity to contribute.

To encourage more community involvement, you should include the following:

An ISSUE_TEMPLATE.md to standardize issues,
labels for good-first-issue and first-timers-only,
and contact information in the README.MD

When someone reaches out or files an issue, give them a few days to respond. Security bugs should be fixed immediately; features and small fixes can wait.

5. Don't lose yourself

There is an undeniable high that comes from seeing your code used by someone else in the wild or stars the project on GitHub. I'm not immune; I've found myself getting caught up in that ever-growing download count since releasing the package.

It's important to remember that your worth is not determined by the number or popularity of your open-source contributions. It has nothing to do with how many Twitter followers you have, claps you've received on Medium, or unique traffic to your personal website.

You are infinitely valuable for just being you.

If you want to publish packages because you think it's fun or you want to help other people, then open source is a great way to contribute. But don't lose sight of that motivation.

I hope those were helpful. If you have any questions about open source or want to share some tips of your own, please let me know.

Should I snapshot my UI components?

Sean McPherson — Wed, 11 Sep 2019 16:00:00 GMT

If you are writing tests for React components in 2019, you will probably find your way to Airbnb's Enzyme testing utilities. The recent industry standard, Enzyme provides you some useful tools for rendering your components.

Often times, folks will turn to snapshot testing with Enzyme because it a) is easy, b) provides significant test coverage, and c) seems like a good idea. I worked for a company where the default test suite for any component was a snapshot, then any additional tests were added to bump coverage to an acceptible level.

However, the ease of use is often a double-edged sword. Here I wanted to outline some common issues that arise from using snapshot tests for your UI components.

Issue #1: False positives

If you've every worked in a codebase that snapshots UI components, you'll know: snapshot tests fail all the time. This is because snapshots collect a JSON-ified version of the shallow render from Enzyme. Whenever anything changes to the structure of the render, the output is different and therefore the snapshot fails.

Whenever you need to refactor a component, you can be assured that the test will fail because the new snapshot doesn't match the one on record.

Because snapshot tests fail all the time, they become false positives: results which incorrectly indicate that a problem is present. You snapshot can fail, even though everything about the component will still function as expected.

If your test can fail when the function still works, what value is the snapshot test adding?

I have seen deployments fail because the snapshot encountered an unexpected div tag. The "solution" was simple enough: update the snapshot and then deploy again. But that has its own problems.

Issue #2: Combating false positives

Since failing snapshot tests are so common, it is common to run you rest suite with the -u, --update-snapshot flag:

npm run test -u

This rewrites the snapshot to match the current value instead of comparing it to the previous one. Since the updated snapshot will always match the new value, the test passes. Running the update snapshot flag is kind of like doing this:

let snapshot;

// npm test -u
let value = 5;
snapshot = value;

if (value === snapshot) {
  console.log("Passed!");
}

This is a little silly, but I think it illustrates the point. On its own, updating a snapshot will automatically pass a test without providing you any valuable information.

Since failing tests are so common, you will be tempted to add the updated snapshot flag to every test run. I know that I got a little too quick the the -u flag.

But as illustrated above, running updated snapshot tests provides no valuable information. So if you need to update the snapshot test every time, what value is the snapshot test adding?

If you find yourself backed into this corner, take heart in knowing that it's not your fault. Snapshot testing forces us to focus on structure.

Issue #3: Structure over function

Snapshot tests value the structure of a component over its functionality. They don't tell you how the component will work in your application; it only tells you how the JSX will look. So you need to ask yourself: Do I want my test suite to care about the structure of my components?

Let's imagine an IconButton component that looks something like this:

function IconButton({ children, icon, ...props }) {
  return (
    <button {...props}>
      <Icon icon={icon} />
      <div>{children}</div>
    </button>
  );
}

After reviewing with the design team, you determing that it would be better for the button text to be inline with the Icon, so you swap the div for a span:

function IconButton({ children, icon, ...props }) {
  return (
    <button {...props}>
      <Icon icon={icon} />
      <span>{children}</span>
    </button>
  );
}

After this change, should the test for IconButton fail? I'd argue: no.

The functionality of the IconButton hasn't changed; it still renders an Icon and passes the onClick handler to the button element. I and every developer after me should be free to refactor as much as I need so long as the component still functions in the same manner when we're done.

But a snapshot test disagrees and will fail because you changed that tag. You might anticipate the test failing and run it with the update snapshot flag, which has all the problems listed above. So again, what value is the snapshot test adding?

Snapshots are a bad fit for UI testing

Shallow rendering + snapshot tests. pic.twitter.com/3TIa4VIhsc
— Mark Dalgleish (@markdalgleish) August 14, 2019

In most instances, snapshots provde no additional value for your UI tests. They are easy and feel good to write, but I think they add little confidence to your testing suite for any given component.

You may stumble across scenarios with a highly specialized component, definite structure, and specific attributes that would benefit from a snapshot. But these are an exception to the rule. In general, avoid snapshot testing for UI components.

Another way

Instead of defaulting to snapshots, ask yourself: What does this component need to do? Then write a test that ensures the component can do just that.

If you're working with Enzyme, use find() to insure that any necessary elements render with the appropriate attributes. Use simulate() to interact with your components in a meaningful way, focusing on functionality.

Your tests should give me the confidence to refactor any component to your heart's content. They should fail if you change functionality, not structure.

Lessons Learned at Abstractions 2019

Sean McPherson — Tue, 27 Aug 2019 16:00:00 GMT

Two weeks into the job, my new employer sent me and a dozen other engineers, qa's, and designers to Abstractions 2019, a cross-discipline software conference in Pittsburgh, PA. Headlining the group of speakers was the YouTuber and creater Simone Gertz, Chris Coyier of CodePen and CSS-Tricks, and Guillermo Rauch of Zeit.

I took down some notes for my team and me to reference after the event. If I have time, I'll add more details including speakers, videos, and links. Until then, enjoy this for what it is!

Wednesday

Your Work Has Moral Implications

Tech has great power and great responsibility. Ensure that your team has a policy in place and make plans to protect yourself from moral crises.

How to Build a Community from Scratch

Find a consistent schedule to hold interesting meetings in an intimate environment.

Deep Learning for Developers

The barrier to entry for machine learning is lower than ever. Check it out!

Resources

TensorFlow
PyTorch
IBM Max

Building Accessibility Together

Every team should plan and work with accessibility in mind. Stick to best practices in design, markup, and scripting to help insure that products work well for everyone.

Software for people who don't want it

Consider the end user when making all software decisions. Strive for an application that is as accessible and usable as possible.

Programming Productivity

Take the time to create tooling to standardize best practices. Use the JavaScript AST to write custom lint tools or CodeMods that will work across the codebase.

Thursday

Practical Open Source Security

Use available tools like npm audit to scan your dependencies regularly. Make it part of the regular code reviews and automate the process as much as possible.

Resources:

mitre
Snyk
webhint
Lighthouse
Dependabot

Those Who Can Do Should Also Teach

Teaching is a great way to reinforce your knowledge, and help people. Prepare your students for the challenges of learning something new and how to work through them. Teach targetted interactive lessons in 10-15 minute bursts.

Mentoring the Way to a More Inclusive Workplace

The tenants of good mentorship align with those of an inclusive workplace. List realistic criteria on job postings and provide specific constructive feedback throughout the hiring process. Have clear and structured onboarding, learning groups, and formalized mentorship/sponsorship. Don't forget: mentorship is a learned skill that must be honed.

Readability & Web

Reading is a complex cognitive task. Around 10% of the global population has some degree of dyslexia. Improving readability for users with dyslexia helps everyone. Readability is about anything communicating meaningful information, including icons.

Fours C's of readability

Continuity: reputation of the information until the endpoint
Conspicuity: beating easily seen or noticeable
Consistency: keeping the same wording along the way
Clarity: the message need to be clearly understandable

Building Afghanistan 2.0 with #AfghanGirlsCode

An Unforgettable Developer Experience

Everything we do is for the human being on the other side. There is a lot of value from making things more accessible. Make the process work for both novices and experts.

Friday

Humane Design Patterns

Considering the well-being of the user in your designs. Habit-forming products and sticky experiences might be bad for the people using them. Instead, align human goals and tech goals.

Resources

Abstract on Netflix
Humane by Design

Pedagogy in Pairing

Scope the activity so that it lends itself to joint productive activity. Remove all distractions during the session (e.g. phones). Point to the source of information; don't spoon feed. Ground your activity in areas that your partner already understands.

Accessibility as a Bridge Between Designers and Engineers

We can communicate effectively only by speaking the same language: developers must understand design, and vice versa. Collaboration is key to an accessible product.

Resources

Accessibility Insights for Web
Vox Accessibility Guidelines

Teaching High School Computer Science

There are differences between teaching high schoolers and junior developers, but there are also a lot of similarities. Try to direct the student towards self discovery. Help work them through failures with learning in mind. GitHub pages provided a great experience with quick feedback.

Resources

TEALS
Pitt TLI Summer Program

Oops I Guess We're Full-stack Developers Now

Certain tasks have shifted from the backend of the application to the front. There is a divide between frontend developers who focus on the front of the frontend and those who focus on the back.

Building UX Teams

Managers empower the team to realize its full potential. People have different skills, can work together, can learn, and can teach.

Edit a previous commit message

Sean McPherson — Fri, 23 Aug 2019 16:00:00 GMT

At my previous company, all commit messages need to begin with a ticket name and number from Jira. If I'm working on the Bananas project and am assigned ticket 5, my commit messages will look like:

BANANAS-5 Add user authentication

If you forget to add the ticket to the commit message, you are unable to push your code to the project repository on BitBucket.

Since I commit a lot outside of work and am the type of developer who makes mistakes, I find myself with commit messages that are missing the required ticket.

You might not have the same policy on your project, but you may have found yourself wanting to change a commit message. Here are two options for editing a previous commit message.

Change the most recent commit

Sometimes you can catch the error quickly after making your commit. If you need to change the most recent commit message, you can use the amend flag.

In your project directory in the terminal, enter:

git commit --amend

This will bring the most recent commit message open in your default editor. Make the necessary changes to the message, mind the formatting, save the file, and exit. You should see a read out with the updated commit message.

Change an old commit

More often than not, I don't find my commit message error until many commits later. In those cases, the amend flag won't help use. We need to rebase.

Rebasing in git is a way to change commits from long ago by reapplying all the commits from a point in time. When you rebase you can rewrite the history of your project; so proceed with caution.

First, you need to find the commit message from which you want to start your rebase. To do that, go to the log:

git log

Now find find the commit immediately prior to the one you want to change and copy the hash (long series of letters and numbers). With that point of reference, you're ready to rebase!

Enter the rebase command with the interactive flag (you can also use -i for short) and the commit hash you copied:

git rebase --interactive <prior_commit_hash>

This will open the default editor with a list of all the commits after the hash you provided. There is a good bit going on here, but don't be overwhelmed. Focus on the top of where you can see a list of the commits and their messages.

It should look something like this:

pick a8fc26a BANANAS-5 This is a good commit message
pick 60ac057 Change me!

# Rebase 5923966..60ac057 onto 5923966 (2 commands)

Now, find the commit message you want to change, and replace the word pick with reword:

pick a8fc26a BANANAS-5 This is a good commit message
reword 60ac057 Change me!

Then save and exit the editor.

Arguments or parameters?

Sean McPherson — Tue, 30 Jul 2019 16:00:00 GMT

I have a hard time remembering the difference between two common programming terms: arguments, and parameters.

This simple inability leads to real insecurity when I speak with coworkers with more education and experience. Nothing inspires imposter syndrome in a more than not remembering the fundamentals!

Here is the difference between the two similar terms:

Arguments

Arguments are the data passed to a function. Think of something simple like console.log(). In order to get a message written to the console, you need to pass it some information.

console.log("One", 2, false, null);

Every bit of information that you pass to a function is an argument. In the above example, we are assigning four arguments to console.log(): "One", 2, false, and null.

Parameters

Parameters are the data that a function is expecting. Let's say you have a function that takes two numbers and returns the sum. It will look something like this:

function sum(a, b) {
  return a + b;
}

The variables that a function is expecting are its parameters. In our sum() function, we are expecting two parameters: a, and b.

Remembering the difference

I've been wracking my brain for a mnemonic device for remembering the difference, but have yet to come up with a great one. In the meantime, this will have to do:

Arguments are data you assign to a function, while parameters are variables that the function is prepared to accept.

If I hear of or come up with a better one, I'll update this article.

I hope that helps!

Reasons to use prop-types

Sean McPherson — Thu, 27 Jun 2019 16:00:00 GMT

I work in an environment where we have dozens of developers across multiple locations and countries working on a few central applications. This requires a level of organization and coordination to ensure that the team is working collaboratively and efficiently.

One of the ways we can encourage efficient collaboration is by type checking in our React applications with the prop-types library.

Here are two reasons why you should be using prop-types in your React applications.

Catch errors

The most immediate benefit to using prop-types is that you can catch and diagnose errors quickly while working on your application. If you instantiate a component and pass invalid props or forget to pass required props, the library will send you a console warning that details each mistake.

Let's say you have a OrderedList component that renders children based on an array of items passed as a prop. It might look like this:

import React from "react";

function OrderedList(props) {
  return (
    <ol>
      {props.items.map((item) => (
        <Item key={item.meta.id}>{item.value}</Item>
      ))}
    </ol>
  );
}

export default OrderedList;

Now what would happen if instantiated this component without passing it an array of items? React will throw an error:

TypeError

props.items is undefined

We could probably resolve the issue from that message, but what would happen if OrderedList was passed an array, but the items were strings, or numbers, or objects with different properties?

TypeError

item.meta is undefined

Document components

When you are working on a larger code base with multiple users, it is easy to lose track of the available components. When you want to use a component that you didn't create or haven't look at in a while, it can be difficult to determine what props that component requires.

Take for example the this LoginForm component using Formik. Try to quickly determine what props this component requires:

const LoginForm = (props) => {
  const Heading = `h${props.headingLevel}`;
  return (
    <div>
      <Heading>Login</Heading>
      <Formik
        initialValues={{ email: "", password: "" }}
        onSubmit={async (values, actions) => {
          await props.login(values);
          actions.resetForm();
        }}
        render={(props) => (
          <form onSubmit={props.handleSubmit}>
            <Input name="email" label="Email" />
            <Input name="password" label="Password" type="password" />
            <Button type="submit">Login</Button>
          </form>
        )}
      />
    </div>
  );
};

You could do it, but it is time consuming and can be a nightmare for larger class components. Now imagine we had the same component above with the following prop-types declared below:

const LoginForm = (props) => {
  // ...
};

LoginForm.propTypes = {
  login: PropTypes.func.isRequired,
  headingLevel: PropTypes.oneOf([1, 2, 3, 4, 5, 6]).isRequired,
};

Now at a glance we can determine that this component needs two props, level and login, and what their types and restrictions are. When I want to use LoginForm, I know I need to pass it a headingLevel (from 1-6) and a login function. Nice and easy.

How to pronounce my name

Sean McPherson — Sat, 15 Jun 2019 16:00:00 GMT

My name is Sean McPherson, and I have an often-mispronounced name. I wanted to take the opportunity for all those curious the history and pronunciation of my first and last names, and handle.

tl;dr My name is pronounced "Shon Mick·Fur·sen" and my handle is "Shon Mick·Pea"

Sean

Sean is an Irish counterpart to the English name John and the French name Jean. They all come from the Hebrew name Yohanan which means "God is gracious."

Irish names in general are difficult for English-speakers to read, because the letters represent different phonemes, or sounds. To resolve this, Sean is often Anglicized as the more English phonetic "Shaun" or "Shawn."

I pronounce Sean as "Shon." This is the most common pronunciation, though you may have the good pleasure of coming across a "Seen" in your life. I've been told that there is a pronunciation of Sean that is closer to the English "Shane", but I've never met one.

If you know a "Shon" spelled Sean in your life, please do pronounce the name appropriately. Chances are they, like me, have had their name mispronounced many times in their life, both accidentally and deliberately, and chafe at the sound of "Seen."

Mispronuncations to avoid

"Seen"
"Say-on"
"See-an"

McPherson

McPherson is a version of the Scottish surname Macpherson. In the original Scots Gaelic, the name is rendered Mac a' Phearsain and means "son of the parson."

Macpherson is the name of a clan that hails from the Scottish Highlands. From there, the Macphersons spread throughout the British Isles, to the Americas, Australia, and the rest of the world.

Said with a Scottish accent, Macpherson is approximately pronounced "Mack·Fair·sen." I've learned from Scots that there is no major distinction between "Mac" and "Mc" names; it's largely a family or individual decision.

I pronounce McPherson as "Mick·Fur·sen." In my experience, this is less common than a "Mick·Fear·sen" pronunciation. However, I feel my version is a) closer to the Scottish pronunciation, and b) more phonetic in American English. There are members of my own family who disagree and prefer "Fear" to "Fur."

Mispronuncations to avoid

"Mick·Fear·sen"
"Mick·Person"

McP

Scottish and Irish surnames beginning with Mac/Mc are often abbreviated with the first letter after the prefix. For example, the name "McDonald" could be shortened to "McD."

When reading one of the abbreviated names, the pronunciation is preserved for the prefix, but the letter is read by its name. "McD" would be read as "Mick·Dee" and not "Em·See·Dee" nor "Mick·Duh."

I pronounce McP as "Mick·Pea." My surname is unique in that the first letter after the prefix, p, is not pronounced in the full version. Despite this, I am still a McP along with all the McPattersons, and McPartlands of the world.

This article was originally posted on SeanMcP.com, which you now know is read "Shon Mick·Pea Dot Com."

Mispronuncations to avoid

"Em·See·Pea"
"Mick·Puh"

To each their own

You may come across another Sean McPherson who pronounces his name differently than I do; and that's okay. It is our reasonable responsibility to learn and use the correct pronunciation of our neighbor's name to the best of our ability.

Add event listener for class change

Sean McPherson — Fri, 10 May 2019 16:00:00 GMT

🆕 Update: I created a reusable function to listen for class changes on any element that is more robust that the solution here.

If you're like me and spent some time searching for an event listener for class changes, let me save you some time: there isn't one.

However, you can create your own custom event listener using the MutationObserver API. Let's look at how to create a simple listener for class changes.

MutationObserver is a constructor that can allows you to watch any changes to the DOM tree. The constructor takes a callback function that will receive two arguments: a list of MutationRecords, and a reference to the observer.

First, let's first create a callback that logs its parameters and then construct a new MutationObserver:

function callback(mutationsList, observer) {
  console.log("Mutations:", mutationsList);
  console.log("Observer:", observer);
}

const mutationObserver = new MutationObserver(callback);

We've constructed basic custom observer, but we need to listen for changes on something. To add our custom event listener, we need to call the created observer's observe() method.

MutationObserver.observe() takes two arguments: the DOM node target, and an optional options object. We'll call this method and pass it a node reference and one option:

mutationObserver.observe(document.getElementById("main"), { attributes: true });

This set our MutationObserver to look for any changes to the main's attributes. If we trigger a change, we can see the two logs from callback():

Mutations:
[MutationRecord]

Observer:
MutationObserver

On each MutationRecord object, there is an attributeName property. If that value is equal to 'class', then we know that there has been a change to the element's class name.

Now we can update the callback function by adding a condition:

function callback(mutationsList) {
  mutationsList.forEach((mutation) => {
    if (mutation.attributeName === "class") {
      alert("Ch-ch-ch-changes!");
    }
  });
}

This code will fire an alert if any item in mutationsList records a change to main's class attribute.

If you need to stop your custom event listener later, use MutationObserver's disconnect() method to remove it like you would a normal event listener:

mutationObserver.disconnect();

Example

Checkout a working example of custom event listener for class change on CodePen:

See the Pen Event listener for class change by Sean McPherson (@SeanMcP) on CodePen.

Happy coding!

Why I switched from Gatsby to Eleventy

Sean McPherson — Fri, 12 Apr 2019 16:00:00 GMT

I spent the last few weeks exploring Eleventy, a simpler static-site generator. After tinkering for a few days, I decided to transition this website from Gatsby to Eleventy.

I'm going to take the opportunity explain my decision for the benefit of myself and others who are looking for a static-site generator.

Disclaimer

Before I dive into my reasons for switching from Gatsby to Eleventy, I would like to state: I like Gatsby. I have no major criticisms of the project and would turn to it first if I were making a rich static site for a small business or enterprise. All of the following are not reasons why Gatsby is bad but rather why I preferred Eleventy for this blog.

The initial decision

After kicking around the idea of moving off Medium to a personal blog, I decided to take the plunge in the Fall of 2018. After a quick survey of the options, I settled on Gatsby for the following reasons:

React based: I am a React developer and loved the idea of using a familiar library for creating the components of my personal website.
GraphQL powered: I didn't know much about GraphQL at the time, but everything I heard was positive.
Growing popularity: It seemed that everyone in the React community was launching a new Gatsby site. All aboard the hype train!

I tinkered around with the setup for a few weeks, then launched the site late in 2018.

Honeymoon

Gatsby has a bit of a learning curve, but after the first few weeks I felt comfortable working in their environment. Whenever I wanted to tweak the layout, design, and/or functionality of the site, I felt comfortable diving into the JavaScript to make the change.

Gatsby's integration with Netlify was seamless as well^[1], which made pushing changes to production as easy as pushing code.

With my Gatsby personal site and blog, I was riding high with the cool kids.

Cracks start to form

As the months rolled by, however, I started to struggle with my Gatsby-powered site. There were a few specific ways where those manifested themselves.

Tinker temptation

I found myself spending significantly more time making minor tweaks to the site than I did writing. This is partly a personal problem; I have a fixed mindset about writing that can throw significant blocks. I'm working on valuing production over perfection in that error.

And the fact that my site was written in React provided me ample temptation to postpone writing in favor of tinkering. Whenever I found it difficult to write, I would create, then refactor, then recreate, then refactor components ad nauseam.

It was not uncommon for me to have over a dozen commits on my blog a week, but no article to show for it. Gatsby's strength of using React ended up a weakness for me as a writer.

Modern complication

Gatsby's surge in popularity at the end of 2018 drew criticism from certain sections of the web. The criticism usually centered around Gatsby's modern tooling, which is more advanced than some of its competitors.

Mark Dalgleish, one of my funniest follows on Twitter, shared that sentiment with this gem of a meme:

I think this criticism is a little misguided, but there is a truth to the implied question: "Why do you need to use all these fancy tools for a simple blog?"

As I struggled with the aforementioned temptation to tinker instead of write, that question was left ringing in my ears. Maybe there was a simpler system for my site?

The final straw

I have a 2010 MacBook Pro on which I occasionally do some work. Despite it's age, the computer still does a great job keeping up with the modern development environment. Up until recently, I used that laptop exclusively for personal projects, and it never had a problem (besides speed).

That is, until it met Gatsby.

Try as I might, I could not get my Gatsby site to run on that computer. I changed Node versions, updated gatsby-cli, and cloned and re-cloned the repository, but to no avail.

I just resigned myself to not using that computer (it is almost ten years old). But then, a two months ago out of the blue, I had the same problem with my work computer (2015 MacBook Pro). Try as I might, I couldn't get Gatsby running.

Now there is almost certainly a solution to the problem on both of my computers. But I searched for a while, tried a few workarounds, and couldn't find it. At some point, you need to ask: is it worth it?

I decided that, instead of sinking more time tracking down this problem, I would instead investigate different generator solutions.

Investigating alternatives

Making the switch

Simplicity
Meme
Diagnosing Gatsby problems
Gatsby problems on older systems
Not React
React === reusability
Felt wrong creating 90+% single-use components

In retrospect, I think this has more to do with Netlify's amazing service than Gatsby. ↩︎

Storing data in state vs. class variable

Sean McPherson — Fri, 12 Apr 2019 16:00:00 GMT

This past week I was working with a new coworker who has previous experience developing but is new to React. After picking up a few syntax cues, he started writing class components in what was a familiar manner for him: storing information as class variables in the constructor.

The constructor from one of his components looked like this:

constructor(props) {
  super(props)

  this.value = 'default'
}

Later on, when he wanted to update the value stored on the object, he did with a simple reassignment:

this.value = "new value";

After reviewing his code, I tried to explain the "correct" pattern for storing data in React. I said (something like):

I see that you're using class variables to store information on your React component. That's not a common pattern. Instead, we use a state object that is referenced with this.state.whatever. When we want to update the data, we call this.setState and pass the new information.

He naturally asked why that was the case, because his code was working as is. I went into a mealy-mouthed explanation with gem quotes like "classes in React aren't true classes", and "state isn't actually stored in the component". None of what I stumbled through answered his original question.

Realizing that I was talking out of ignorance, I stopped and offered a more honest: "Actually, I don't really know." Then I turned to Google to find the answer.

Class variables

I thought that storing class variables was almost always a bad idea. The only use cases that I had personally encountered before were:

Setting and clearing timeouts
Storing frequently-referenced values

However, my colleague's work showed that class variables can be used to manage and update data.

Here's an example of using class variables to create a counter:

class VariableCounter extends React.Component {
  count = 0;

  render() {
    return (
      <div>
        <p>The count is: {this.count}</p>
        <button onClick={this.increment}>Add one</button
      </div>
    );
  }

  increment = () => {
    this.count = this.count + 1;
  };
}

When the component is initiated, a class variable named count is set to 0. When the increment method is called, it updates count by adding one to the previous value. The rest of the component is pretty standard.

After writing up this simple example, I thought this code would work. But I was wrong. You can click the button as much as you want, but the count value displayed in the component will never change.

If you throw a breakpoint or add a console.log to increment(), you'd see that the method is indeed called and the value of this.count is incremented, but the component never reflects the change.

That's because React components will only re-render when there are changes to props or state.

Updating the class variable involves neither, so it does not trigger a re-render. This explains why the count changes in our example, but the displayed value never updates.

In order to use class variables, we need to take the responsibility of triggering the re-render when our data changes. To do that, we need to add a line to our example:

class VariableCounter extends React.Component {
  count = 0;

  render() {
    return (
      <div>
        <p>The count is: {this.count}</p>
        <button onClick={this.increment}>Add one</button
      </div>
    );
  }

  increment = () => {
    this.count = this.count + 1;
    this.forceUpdate();
  };
}

React class components have a forceUpdate method that triggers the render method. By calling this.forceUpdate() after incrementing our class value, we can get our displayed value to update.

I had never heard of this method before, and there is a reason why: the React team doesn't recommend using it. Here's a line from the React documentation on forceUpdate:

Normally you should try to avoid all uses of forceUpdate() and only read from this.props and this.state in render().

In some instances you may receive data from other sources, but otherwise try to avoid manually managing a component's render.

The alternative to using class variables and forcing updates is leveraging React's component state.

Component State

Instead of setting our count as a class variable, let's instead create a state object on our class and store the data there.

We only need to make a few modifications to the VariableCounter for our new component:

class StateCounter extends React.Component {
  state = {
    count: 0
  };

  render() {
    return (
      <div>
        <p>The count is: {this.state.count}</p>
        <button onClick={this.increment}>Add one</button
      </div>
    );
  }

  increment = () => {
    this.setState(
      prevState => ({ count: prevState.count + 1 })
    )
  };
}

While instantiating a state object might look like the previous example using a class variable, state is a protected keyword in React that refers to stored component data.

You can access data from state with normal object dot or bracket notation, so the current count can be referenced with this.state.count.

The major difference between using class variables and state is updating data. Instead of manually reassigning the variable, you call this.setState() and pass it an object or a function that returns an object.

When you call this.setState(), React merges the passed object into the current state to create a new state object. Then it compares this new state to the previous state. If there is a change, React re-renders the component, resulting in the updated count value displayed on the screen.

By using this.setState(), you let React handle the logic of whether to re-render the component. This is a feature of React and one of the reasons it has become so popular.

Example

I created a CodeSandbox example of the components discussed above. There are working state and class variable counters; with a bonus functional component using React.useState(), and a broken class variable counter without this.forceUpdate(). Check it out:

Summary

Contrary to what I initially thought, it's okay to store component data as a class variable. However, if you're going to render that data, you should instead store it in state so that any changes trigger a re-render. Ninety-five percent of the time, you'll store data in state.

Now that you know the difference between storing data in state and class variables, you can be more helpful than I was to your fellow developers.

Happy coding!

Filter out premium Medium articles

Sean McPherson — Mon, 08 Apr 2019 16:00:00 GMT

Medium has received a lot of flack recently for their push to monetize the platform. And while I don't fault them for moving some of their best articles behind a pay wall, I have no interest in subscribing to their platform.

There is still a lot of high-quality free content on Medium, but you have to navigate around all of the premium content that the platform is pushing.

I wanted to write a console script that would do that filtering work for me.

Reach for the stars

On Medium, premium articles can be identified on the homepage by their ★ icon. Using the inspector, you can see that the star is an svg element nested in a span with the class svgIcon--star. Bingo!

Now, using the handy querySelectorAll-esque selector $$, we can find all the stars on the page. Our console script starts out like this:

$$("span.svgIcon--star");

Now that we've selected all stars, we need to iterate over them. Since we need to do something for every item in our iterable, we'll use forEach:

$$("span.svgIcon--star").forEach((star) => {
  // Hide parent element
});

Now that we're iterating over the stars, we need to find and hide the appropriate parent element. To do this, we'll use a neat Element method called closest.

Finding a parent with `closest`

You may be familiar with the querySelector method, which starts with a given element and then searches down the DOM tree and returns the first match.

closest works the same way, but in reverse. It starts with an element, then travels up the DOM tree. This makes it the perfect method for starting with an element and looking for a specific parent.

Using the inspector again, we can see that articles outside the featured section are divs with the class streamItem. Using closest, we'll grab those elements:

$$("span.svgIcon--star").forEach((star) => {
  star.closest(".streamItem"); // Hide element
});

I had never used the closest method before and was glad to find it. As always, I read up about it on MDN before using it.

We've selected the correct parent element; now we need to hide it.

Hiding an element

Removing an element in JavaScript is more difficult than it should be. There is no remove method on the global Element. Instead, you need to jump up to the parent element and then use removeChild. The normal strategy looks like this:

const element = document.querySelector(".remove-me");

element.parentElement.removeChild(element);

I think this pattern is annoying and try to avoid it whenever possible. But we could use it in our instance by first creating a variable to reference the element to be removed:

// Option 1 - Remove element
$$("span.svgIcon--star").forEach((star) => {
  const article = star.closest(".streamItem");
  article.parentElement.removeChild(article);
});

This is your best option if you need to remove the element from the DOM.

My preferred method leaves the element in the DOM and applies CSS styles to hide it from view. We'll set the article element's display style to 'none':

// Option 2 - Hide element
$$("span.svgIcon--star").forEach((star) => {
  star.closest(".streamItem").style.display = "none";
});

Unless you need to remove and element from the DOM, the simpler solution is to just hide the element.

Save for later

Chrome has a handy feature in the "Sources" tab called snippets. Here you can save bits of code for use later.

I created a snippet title "Medium" and saved the above code. Now when I want to filter out premium articles, I just need to run that snippet with command + enter.

Read on

Now the next time I want to find an article to read on Medium, I can run the snippet and filter out premium articles.

For a more reusable solution, we could turn this snippet into a browser extension, but that's the topic of another article.

Adding accessibility checks to your React app

Sean McPherson — Mon, 04 Mar 2019 16:00:00 GMT

Updated - 3/9/19 This article was initially released with a reference to a third tool for React accessibility checking: react-a11y. Since publication, that library has been deprecated. The article has been updated to reflect that change.

Whether you are working for a startup, non-profit, or Fortune 500 company, accessibility is a critical component of your product. Not only it is a legal requirement in many countries^[1], but creating accessible applications maximizes the number of potential users. And it often has a positive impact on all users (read about the "Curb Cut Effect").

As React developers, we have a responsibility to avoid hiding in the virtual DOM and work to ensure that the components we craft are going to work for everyone. Fortunately for us, React has React has accessibility features built into the platform to make our jobs easier.

In this article, we're going to look at two additional tools than can help React developers create awesome and accessible applications for all.

Setup

To demonstrate these features, I'm going to bootstrap a new project with React's Create React App. It's a great way to spin up a new project and works nicely with the accessibility checks we're going to implement.

If you're looking to add these checks to a current project, the only dependency is ESLint, which we'll look at later in this article. Now, let's jump in!

React-axe

Create React App already has wonderfully helpful console messages, and react-axe is an out-of-the-box solution that adds accessibility checking to your console.

React-axe is developed by Deque, the makers of the fantastic accessibility tools like the Axe browser extension (which I highly recommend). Install it in the usual way:

yarn add --dev react-axe

Once installed, we'll check for a development environment before requiring and calling react-axe's axe function and passing certain parameters.

import React from "react";
import ReactDOM from "react-dom";
import App from "./components/App";

if (process.evn.NODE_ENV === "development") {
  const axe = require("react-axe");
  axe(React, ReactDOM, 1000);
}

ReactDOM.render(<App />, document.getElementById("root"));

The final parameter for axe is "a timing delay in milliseconds that will be observed between each component change and the time the analysis starts" (source). We'll set it to 1000ms, or one second.

Now if I give an element an invalid role (e.g. role="Test"), I'm met with the following console message:

▸ critical: ARIA roles used must conform to valid values
https://dequeuniversity.com/rules/axe/3.1/aria-roles?application=axeAPI

Expanding the message provides a reference to the original document, and a file and line reference to fix the issue. The console errors are helpful without being overwhelming and provide all the information and resources you need to fix the issue.

Console warnings are great, but let's add another tool to help catch mistakes before they make it to the browser.

Jsx-a11y is an ESLint plugin that looks over your code for some key accessibility considerations. If you don't have ESLint added to your project yet, follow their get started guide.

If you bootstrapped your React app with create-react-app like I did, it already has ESLint and some of jsx-a11y's accessibility checking included. For the sake of this article, we're going to add the full set of rules, so we'll need to install the plugin library:

yarn add --dev eslint-plugin-jsx-a11y

Then modify the ESLint configs in your package.json to match the following:

{
  "eslintConfig": {
    "plugins": ["jsx-a11y"],
    "extends": ["react-app", "plugin:jsx-a11y/recommended"]
  }
}

Now if we make a change that reduces our app's accessibility, like removing the alt attribute for an <img>, we're met with the following lint warning:

./src/components/App/App.js
    Line 10:  img elements must have an alt prop, either with meaningful text, or an empty string for decorative images  jsx-a11y/alt-text

For more customization over which rules jsx-a11y uses, refer to the official documentation.

If you are using a text editor like VS Code that features in-line linting, you can identify and fix potential accessibility issues before you even save.

With these tools in place, you're well on your way to creating more accessible React applications!

I created a11y-react-starter, a lightly-configured create-react-app with both of the above accessibility tools baked in. Check it out for a reference or use it as a starting point for your next app.

Conclusion

By enabling these accessibility features, you're adding the wisdom and knowledge of the many developers who have gone before you. With their help, and a little bit of learning, anyone can create accessible applications that work for all users.

Happy coding!

Web accessibility: Web accessibility legislation on Wikipedia ↩︎

Three reasons to learn Python

Sean McPherson — Thu, 21 Feb 2019 16:00:00 GMT

There are tons of reasons to learn a programming language. Maybe you are new to coding and are looking for a good place to start. Maybe you’re interested in new technologies like machine learning and artificial intelligence and want to learn more. Or maybe you’re a seasoned developer who is looking to add a new language to his/her skill set.

But which to choose? There are hundreds of programming languages out there, each one vying for your attention. What should you do?

Never fear, faithful reader! Here are three reasons why you (yes, you!) should learn the Python programming language.

1-- Versatile

Python’s creator, Guido van Rossum, designed Python to be a general purpose programming language. As a result, Python can be used in a wide variety of cases: machine learning, web development, GUI development, scientific and numeric applications, software development, system administration, and more. Whatever type of programming sparks your interest, there is probably a Python application or framework for it.

Major companies like Google, Instagram, Dropbox, Spotify, Reddit, Duolingo, and BitBucket; government organizations; educational institutions; and non-profits use Python for its versatility.

2-- Beginner friendly

In addition to being a general purpose programming language, Python advertises itself as being “easy to use”. It achieves this by utilizing a simple and intuitive syntax and offering high-level data types like dictionaries.

Since 1999, Python has been guided by a series of 19 principles called the “Zen of Python.” Among these are specific guidelines to keep things simple:

Simple is better than complex.
Readability counts.
If the implementation is hard to explain, it's a bad idea.

As a result of this, Python is often used as the language in introductory computer science courses (notably MIT). If you are looking to learn your first language or add to a growing toolbelt, Python is a great choice.

3-- Highly rated

In my experience, every Python developer I have met loves working in Python. And it turns out that my anecdotal observation may be right!

In StackOverlow’s Developer Survey-- which compiles user responses to demographic, technology, and work questions--shows that Python is a desirable language. It has been listed among the “Most Loved” languages for a while and has topped the charts in the past two years as the “Most Desired” language. If a lot of other developers like using Python, or want to learn Python, then it is probably going to be a good experience.

[Sidebar: If you haven’t before, take the time to look over the results of the 2018 Developer Survey. It isn’t perfect, suffering from both participation and response bias, but does open a window into the world of development.]

Bonus-- Python jokes!

Van Rossum named the Python programming language not after the serpent genus (as I previously assumed) but after the British TV comedy “Monty Python’s Flying Circus.” According to the Python Software Foundation, “Making references to Monty Python skits in documentation is not only allowed, it is encouraged!”

There you go: three (and a half) reasons why you should learn Python.

If you are looking for a good place to get started, I recommend the Python Docs: they are well-written and -paced for a beginner diving into the language.

Happy coding!

JS Basics: Generate a random number

Sean McPherson — Mon, 11 Feb 2019 16:00:00 GMT

Whether you are simulating a die roll or pulling any index from an array, computers can be used to generate a random number. In JavaScript, random numbers require a combination of methods on the Math object that can be a little tricky to understand your first time through.

Random die roll

Let’s say you want to create a digital six-sided die, which will give you a random number between one and six when called. Our function to simulate a die roll will look like this:

const rollDie = (sides) => Math.floor(Math.random() * sides) + 1;

rollDie(6); // 1

Every time we call the function, it will return any number from one to six, inclusive. But why? To answer that question, we need to know more about the two methods on the Math object we called.

Math methods

Math.random() is a method that generates an integer (number with a decimal) from zero to one, including zero but excluding one. The output of Math.random() could be 0, 0.1, 0.2, 0.3343424587866554652345, or 0.99. Anything from zero to nearly one is a possibility.

Math.floor is a method that rounds an integer down to the nearest whole number. Rounding down, 0.1 becomes 0, 3.6 becomes 3, and 5.4 becomes 5. Think of it as rounding all the way down to the floor. (Note: there is also a Math.ceil function for rounding up that I'll mention later).

By combining these two methods, we can generate the random number for our die. Starting on the inside of our function and working outward:

Math.random() returns an integer between zero and nearly one: 0.16
Next we multiply that integer by the number of sides: 0.16 * 6 = 0.96
Then we round that product up with Math.floor: 0.96 -> 0
Finally, we add one to get our final random number: 0 + 1 = 1

The result of our rollDie(6) function is 1!

Our function allows for a varying number of sides, so you would only need to pass a different argument if you were rolling a different die (much to the satisfaction of all D&D players out there).

You might even create some help functions to simplify calling different sided dice:

const rollD6 = () => rollDie(6);
const rollD12 = () => rollDie(12);
const rollD20 = () => rollDie(20);
// etc...

I used functions like these in Dice Roller, a handy dice rolling app for table-top gaming. You can view the project's source code here.

Common questions

Here are some questions you may have (I know I did!) about our rollDie function:

“Why did we need to add one to our number?”

Math.floor(Math.random() * 6) alone will generate a random number between 0 and 5. That is six options, but I've never seen a die numbered from zero to five. We add one to the output so that it makes sense for our situation.

"Wouldn't using `Math.ceil` make the `+ 1` unnecessary?"

In the same manner that Math.floor rounded our integer down to the nearest whole number, Math.ceil--short for "ceiling"--rounds an integer up. At face value, this would simplify our solution--but for one issue:

Math.ceil(0); // 0

Since Math.random() can^[1] return a 0, using Math.ceil would on a rare instance return an unexpected value. So it's safer to use Math.floor and add one.

"Does the math always work out?"

I’ve included a few additional examples at the bottom of this post^[2]. Try it out for yourself and see! 😊

Random item from an array

The rollDie works well for our dice example, but what if you want to select a random item from an array? Remember, that arrays are zero-indexed (MDN), which means that the first item of an array is accessed with a zero (0):

const myArray = ["first", "second", "third"];

myArray[0]; // 'first'

Our rollDie function will never return a 0 because we're always adding one. By removing that addition, we can create a new function that will work well with arrays. Let's use the code from the previous block and add:

const randomIndex = (arrayLength) => Math.floor(Math.random() * arrayLength);

randomIndex(myArray.length); // 0

By calling our function and passing the length of our array, we can pull a random item from our array:

myArray[randomIndex(myArray.length)]; // 'second'
myArray[randomIndex(myArray.length)]; // 'first'
myArray[randomIndex(myArray.length)]; // 'second'

Using our function in this manner is a little repetitive, so let's create another function that will simplify the process for us:

const randomItemFrom = (array) => array[randomIndex(array.length)];

randomItemFrom(myArray); // 'third'
randomItemFrom(myArray); // 'second'

Now we have a few handy utility functions:

rollDie for simulating a die roll with a given number of sides,
randomIndex for getting a valid index from an array, and
randomItemFrom for returning a random item from an array

While building those, we learned about JavaScript's Math object and some of its methods: random, floor, and ceil.

Happy coding!

I emphasize "can" because it is an edge case (Wikipedia): a statistically unlikely but possible event. Programmers need to be on the lookout and account for edge cases when possible. ↩︎

Additional examples stepping through the rollDie function:

1. Math.random()    // 0.4
2. Multiply by 6    // 2.4
3. Math.floor       // 2
4. Add one          // 3
Random number: 3

1. Math.random()    // 0.9
2. Multiply by 6    // 5.4
3. Math.floor       // 5
4. Add one          // 6
Random number: 6

1. Math.random()    // 0.642
2. Multiply by 6    // 3.8520000000000003
3. Math.floor       // 3
4. Add one          // 4
Random number: 4

↩︎

JS Basics: Ternary Operator

Sean McPherson — Fri, 08 Feb 2019 16:00:00 GMT

A ternary or conditional operator is like an inline if statement. In JavaScript, you can identify them by their unique use of a question mark, ?, and colon, :.

When I first started coding, I found ternary operators more than a little confusing, so let's try to unpack them. Look at this common example:

<span className={`Todo ${props.isDone ? "Todo--done" : ""}`}>{props.text}</span>

Here we have a snippet from a React to-do app with a ternary operator. The class ( className in JSX) is being set based on a condition in our props object. Here’s how to read a ternary operator:

If props.isDone is true/truthy, then return the string "Todo--done"; otherwise return an empty string.

Written out, a ternary operator looks like an if statement. We could express the same code like this:

if (props.isDone === true) {
  return "Todo--done";
} else {
  return "";
}

That looks more familiar! Ternary operators are useful because they allow you to add inline conditions to your code. Compare the original code to our final if statement. The ternary operator is shorter, cleaner, and more efficient.

MDN has a great list of other examples for you to reference. You can check them out here: Conditional (ternary) operators

Happy coding!

Convert class components to functions with React Hooks

Sean McPherson — Wed, 06 Feb 2019 16:00:00 GMT

Last year, the React team announced hooks, a feature to more easily abstract logic into reusable components. On the day of the announcement, I wrote and article explaining how to refactor a render prop component with hook.

Starting this week with release of React v16.8, you can now add hooks in your projects!

Today, I want to look at a typical class component and demonstrate how you can covert it into a functional component with React hooks. Let's jump in.

Terminology

Note: Skip this section if you're familiar with class and functional React components.

I'm going to use the terms "class" and "functional" components to refer to the modern options for creating components. A class component looks something like this:

class ClassExample extends React.Component {
  state = { greeting: "Hello" };
  render() {
    return (
      <span>
        {this.state.greeting}, {this.props.name}!
      </span>
    );
  }
}

Class components have access to internal state; default, custom, and lifecycle methods; and a this to reference. These components have been the powerhouses of React development throughout its history.

The aptly named functional components are functions that return JSX. Here's a typical example:

const FunctionalExample = (props) => {
  const greeting = "Howdy";
  return (
    <span>
      {greeting}, {props.name}!
    </span>
  );
};

Functional components lack an internal state, methods, and this. In order to access passed props, we refer to the props parameter.

Because they contain less internal logic, functional components are sometimes referred to as "dumb" or "presentational" components.

Although different in composition, class and functional components are used in the same manner. Let's reference both examples from above in a hypothetical parent component:

return (
  <section>
    <ClassExample name="Sean" />
    <FunctionalExample name="partner" />
  </section>
);

From the parent's perspective, the two types of components are identical. To understand how React internally understands and processes these two different types of components, I recommend Dan Abramov's "How Does React Tell a Class from a Function?".

These are simplified definitions and examples, but they will provide us with a good basis for the rest of the article.

Class component

I have a component that makes an API request on mount, stores the response in state, then renders some JSX based on the data. Here's the code:

class ClassComponent extends React.Component {
  state = {
    url: null,
  };
  componentDidMount() {
    fetch("https://random.dog/woof.json")
      .then((raw) => raw.json())
      .then((res) => this.setState(res));
  }
  render() {
    return (
      <section>
        <h2>Doggo!</h2>
        {this.state.url ? (
          <img src={this.state.url} alt="A cute dog" />
        ) : (
          <p>Fetching</p>
        )}
      </section>
    );
  }
}

Note: To create this example, I looked through Todd Motto's awesome list of "Public APIs". Check it out and give it a star if you find it useful.

I used the fetch library to keep the example straight forward (and it seemed fitting for an app that displays dog photos), but I recommend using a more robust option like Axios with better error handling for your applications.

Functional Component

Using React Hooks, we can create the same example from above using a functional component.

Setup

First, we'll create a new file for our functional code and set up a basic function. Then copy the return from our class component and remove all references to this.state. We need to declare a variable to prevent reference errors, so let's call it url.

const FunctionalComponent = props => {
  const url // We'll change this later
  return (
    <section>
      <h2>Doggo!</h2>
      {url ? <img src={url} alt="A cute dog" /> : <p>Fetching</p>}
    </section>
  )
}

useEffect

In our class component, we make an AJAX request when the component mounted and stored that data in state. componentDidMount and the other lifecycle methods are limited to classes. However, the React team was able to implement those features with the useEffect hook.

useEffect is a method that takes two parameters: 1) a function to call on mount, and 2) an array of variables to watch for updating.

For the first parameter, we'll pass an anonymous function that calls fetch, processes the data, and logs the response. The second argument just be an empty array for now.

const FunctionalComponent = props => {
  const url
  React.useEffect(() => {
    fetch('https://random.dog/woof.json')
      .then(raw => raw.json())
      .then(res => console.log(res))
  }, [])
  return (
    <section>
      <h2>Doggo!</h2>
      {url ? <img src={url} alt="A cute dog" /> : <p>Fetching</p>}
    </section>
  )
}

If you are coding along, you should see something like the following in your console when the component mounts:

{ "url": "https://random.dog/867580b3d005.jpg" }

This shows us that our API call is working, but logging the response isn't our goal; we need to store the data for later. Let's revisit the url variable that we created.

useState

Now that we have the response from our API, we need to be able to capture and reference that value. In our class component, we used its state and the setState method to remember that data.

React's useState hook gives us access to a similar API without using a class. When calling the function and optionally passing a default value, we receive two returned variables: 1) a reference to the value, and 2) a function to update that value, respectively.

Using array destructuring, we can grab those variables and assign a name according to the convention: x and setX. For our example, we'll call the value url and the setter function setUrl.

We'll replace our old url with the results from useState:

const FunctionalComponent = (props) => {
  const [url, setUrl] = React.useState(null);
  React.useEffect(() => {
    fetch("https://random.dog/woof.json")
      .then((raw) => raw.json())
      .then((res) => console.log(res));
  }, []);
  return (
    <section>
      <h2>Doggo!</h2>
      {url ? <img src={url} alt="A cute dog" /> : <p>Fetching</p>}
    </section>
  );
};

Using useState, we can quickly add basic state to our functional component.

In the code above, we're just logging the response from our API. Now we want to use the setUrl function to set the value or url in our component's state.

const FunctionalComponent = (props) => {
  const [url, setUrl] = React.useState(null);
  React.useEffect(() => {
    fetch("https://random.dog/woof.json")
      .then((raw) => raw.json())
      .then((res) => setUrl(res.url));
  }, []);
  return (
    <section>
      <h2>Doggo!</h2>
      {url ? <img src={url} alt="A cute dog" /> : <p>Fetching</p>}
    </section>
  );
};

Now let's take a second to revisit the second parameter passed to useEffect. Remember, it contains a list of variables that will trigger the effect to run again on change.

Our effect depends on one outside variable: setUrl. This function is generated once by useState, and adding it to the array will ensure that our fetch call isn't fired repeatedly.^[1]

const FunctionalComponent = (props) => {
  const [url, setUrl] = React.useState(null);
  React.useEffect(() => {
    fetch("https://random.dog/woof.json")
      .then((raw) => raw.json())
      .then((res) => setUrl(res.url));
  }, [setUrl]);
  return (
    <section>
      <h2>Doggo!</h2>
      {url ? <img src={url} alt="A cute dog" /> : <p>Fetching</p>}
    </section>
  );
};

That's it! Checkout the live example on CodeSandbox to see the two components side-by-side.

Comparison

Let's take a moment and consider our two components. The new functional component is a little shorter than the original class component, and the variables are shorter and easier to reference.

Those are nice benefits, but I don't find either a convincing reason to go back and convert all my class components.

More important to me is the fact that you can now use a functional component for nearly everything in your application. Since every component is functional, it makes the process of bringing in or removing state and lifecycle effects much easier.

Embrace the class-less future

For those reasons and others, the future of React is class-less. And that's a good thing. Hooks provide more flexibility when creating and managing components, to say nothing of custom hooks.

But don't panic and convert all your class components right now; "they'll be supported for a looooong time". However, when you have the opportunity to refactor a class component going forward, consider converting it into a functional component with hooks.

Happy coding!

A big thanks to Hung Tran Van on Medium for highlighting a previous issue with this article. While fixing my mistake, I found How the useEffect Hook Works by David Ceddia to be super helpful. ↩︎

Accessibility Wednesday

Sean McPherson — Wed, 06 Feb 2019 16:00:00 GMT

In the fall of 2018, I had the good pleasure of attending the Connect.Tech conference in Atlanta, GA. There were great talks about React, user experience design, and exciting new features for JavaScript.

But the sessions that had the greatest impact on me were all focused on accessibility.

Accessibility is important

It might seem obvious to you, but I needed to hear that loudly proclaimed from the keynote stage.

Accessibility isn't just about our friends and neighbors with disabilities; it's about making applications that work well for everyone. The Curb Cut Effect is a perfect example about how accommodations make everyone's lives easier.

I was treating accessibility as if it was icing on a cake--something that was nice to have but not essential. Unfortunately, it was that type of thinking that allows inaccessible apps to flourish.

Accessibility is not a feature; it's part of the product. If our app isn't accessible, then it isn't done.

"Whoa, what was I doing before?"

Hearing all that was like a light switch being flipped in my mind--and with that came loads of guilt and regret for all the neighbors I had neglected for the decade I had been developing. I felt especially convicted by my experiences in my previous career.

Before becoming a developer, I studied education in college and spent three years working as a teacher. The importance of creating an inclusive environment and the value of accommodations was drilled into us early on, and we studied how great accommodations increase learning outcomes for all students.

Further yet, I had seen those benefits first hand while working in over a dozen schools across Pennsylvania and Georgia.

If accessibility was so important to my previous career, why wouldn't it be the same in my new one as a developer?

"Okay... now what?"

Impressed with a sudden desire to make all the things accessible, I left the conference and looked online for resources to help.

I first tried to read the Web Content Accessibility Guidelines 2.1, which weren't as difficult to grasp as I had feared. Even so, the content was dense and a tough slog for a newbie.

Seeking more digestible information, I found other resources on W3C to be helpful, especially those specifically for developers.

I was working with React Native at the time, so I created Awesome React Native Accessibility, a repo with a list of mobile-specific resources. Progress on that halted when I switched to a React project at work.

At this point, I was starting to feel a little overwhelmed. Everywhere I looked were categories, rules, laws, practices, and oodles of examples of companies doing it wrong. It all seemed like too much.

Accessibility is hard

I was beginning to think that maybe accessibility was too difficult, too technical, too intricate for me. And I'm sure that I am not alone in having thought that.

But the reality is that developing for accessibility is a skill. And just like any other skill, it requires little bites and regular practice. Over time you will improve, and eventually what seemed difficult will become second nature.

There is a reason we don't learn to walk by running. Our brains weren't designed to work that way. As the father of a now-cruising baby, I feel particularly qualified to say that learning to walk is hard work. It's filled with failures, bumps, and bruises. Same with riding a bike, learning to read, or adjusting to a AAC device.

You will fail at first (and second and third), but as long as you persevere, you can be successful. You can learn. You can grow.

Let's learn about accessibility

I am determined: I want to become an accessible developer. I want to bake accessibility in for as many neighbors as possible into every application on which I work.

In order to meet that goal, I need to learn more about accessibility. And that's where this article comes in. This is the kick-off to a series called "Accessibility Wednesday" where I will share accessibility tid-bits for developers.

These won't be full articles--neither you nor I have time for that. Rather, I'll share images, links, and code samples on Twitter with the hashtag #a11ywednesday. Everything will be available in a GitHub repo for easy reference.

Remember: I'm no expert (yet)

Since I am not an authoritative resource on accessibility, I will make sure to include references and citations to every applicable tidbit. Is MLA formatting still a thing? (s/o PurdueOWL)

This is a learning exercise for me as much as it is for everyone else. With that in mind, I will almost certainly make mistakes. All of us fall short of the target. That's why I encourage you to help me correct my mistakes.

File an issue on GitHub referencing the tip in question, or--better yet--make a pull request with the fix. I happily welcome any and all contributions the the project.

If you notice the mistake on Twitter, please respond or direct message to let me know. I will remove the tweet, make the correction, and share the updated information later.

Stronger together

As time goes on, I'm hoping that Accessibility Wednesday grows into a catalog of useful information for developers of all levels to make more accessible applications. We know that there is power in our collective knowledge.

As a wise man once penned, "with great power there must also come--great responsibility!"^[1] Let's use our power for good and make the web more accessible for everyone.

Join the discussion on Twitter or GitHub. I look forward to learning and sharing with you all!

I learned while writing this article that the original phrase from Spider-Man is slightly different than the modern variation. (source) ↩︎

2018 into 2019

Sean McPherson — Mon, 31 Dec 2018 16:00:00 GMT

As 2018 comes to a close, I was inspired by Tania Rascia to write a year in review. I'm hoping to turn this into an annual opportunity to reflect on the successes, failures, and challenges from the previous year, and set goals for the next.

2018 was probably the most eventful year of my life, edging 2014 in which I graduated from college, married, and received my first teaching position. I've attempted to list all of the major events and accomplishments of the past year in mostly chronological order.

2018 in review

Last year, I:

Received three tech job offers: Node developer with a crypto company, QA with CNN Politics, and React Developer with TSYS
Accepted my first software developer position: TSYS offered a contract-to-hire position that worked well for my family
Deployed two apps: Dice Roller and Contraction Tracker
Attended two conferences: NG ATL, and Connect Tech
Became a father: My first child was born in March, changing our lives forever
Converted from contract to salaried employee: After a three-month trial, TSYS was happy to offer me an official position with the company
Organized Jr Devs: a Meetup for learners with over 200 members
Gave a lightning talk at a Meetup: Intro to CSS Animations
Learned some Python: created a few scripts, a Flask app for gaming, and a text-based adventure game Rimoria
Created two NPM packages: vanilla-include and nodify-string
Represented TSYS at a job fair
Worked on an application at work in React Native
Launched a Chrome extension: Popsicle Sticks
Helped TSYS create an engineering blog and GitHub organization
Published 12 articles (including two on this website)

After sitting down and writing it all out, I am impressed with the things that I have accomplished in 2018. Especially considering how uncertain I was about continuing my search for work in the tech industry by the end of 2017.

Last year was a long stretch of giving from God: blessed be the name of the LORD (read Job 1).

Previewing 2019

Looking forward to next year, there are several things that I want to learn and do. I am going to list some general goals, followed by measurable ways that I can accomplish them.

Python: I want to dive deeper in Python applications, including environments and dependencies, by deploying a Python app
Machine learning: TSYS is interested in integrating ML into their applications, so I will complete a course in either Udacity or Udemy
Module bundlers: I am lost (and confused) when it comes to module bundling, so I am going to de-mystify bundlers by publishing React setup guides for Webpack, Parcel, and Rollup
NPM Packages: I want to learn about creating and maintaining open-source software by publishing two new packages
Tooling: I want to investigate tooling options for React development that streamline the process and create a personalized dot files repo
Publish more articles: It is my mission to help people, and one way to do that is to publish 24 articles (bi-monthly)
Jr Devs Meetup: I want to partner with a coding bootcamp to provide instructors at every meeting
Speaking: I want to create a deck and present at another Meetup
Husband: I want to take dating my wife seriously and schedule a babysitter four times a year for real dates
Father: I want to use the time I have with my son more productively, going on father-son outings twice a month
Faith: I want to continue teaching Sunday school, lead family worship every evening, and read/reflect on the Bible daily
Personal: Dad bod is a real thing and is only around the corner, so I want to exercise 6 days a week (don't forget a day of rest)
Soccer: I want to find room in the family schedule to play a pick-up game every week

I could go on longer, but twelve seems like a fitting number. I am going to check back on these goals throughout the year and track my progress in a different article.

How was your year?

As I mentioned above, this is not a new or unique idea. But I think it's a good one, and I encourage you to give it a try. You might be pleasantly surprise (like I was), at how much you've accomplished.

If not, then ask yourself: What can I do to help myself accomplish my goals next year? You don't need to be a super hero; just try to be a little better than you were the day before.

I hope this was half as inspiring to you as it was helpful to me. Happy new year! 🎉

Why a blog?

Sean McPherson — Tue, 04 Dec 2018 16:00:00 GMT

For over a year and half I have been happily blogging on Medium. I was quick to sign up when the platform first launched (and snag that elusive @seanmcp handle) but was slow to start writing.

Then, in the summer of 2017, I enrolled in the Iron Yard and was encouraged to blog my process. After looking at Blogger for a minute (seriously), I settled on Medium. I appreciated the design esthetic and attention to typographical detail. Composing was simple and I found code blocks quite useful.

I never really settled into a consistent writing schedule but did find some success writing about JavaScript and React. My most popular article, "How to use emojis in React", continues to receive "applause" six months after I published.

All that is to say, Medium was a perfectly suitable platform for what I needed. And it still is a good platform, but my needs have changed.

Recent criticism of Medium aside, ownership of my content was the biggest catalyst for looking elsewhere. Medium is popular now, but will it be in two years? Five years? Ten years? Will we be reading Medium posts about terraforming when we colonize the moon? Or will Medium's popularity wane and be shuttered before we get there? No one can know.

Regardless of the future of the platform, I'd like my content to live on. My goal is to help people (help people), so my words--as feeble as they are--need to persist long enough to do that.

"The grass withers and the flowers fade"; nothing is permanent in this life. But having more direct ownership and control of my content puts me in a better position to continue helping people for the long-run.

That's why I'm starting this blog. For the immediate future, I will be cross-posting everything I write on Medium and linking back here. After then? We'll see what the web looks like.

In the meantime, thank you for stopping by. Check back weekly or subscribe with your favorite RSS reader.

How to create a render prop component

Sean McPherson — Tue, 09 Oct 2018 16:00:00 GMT

It's been a year since Michael Jackson published "Use a Render Prop!", which encouraged using render props instead of higher order components (HOCs). Since then, "render props" has grown into a bigger and bigger buzzword in the React community.

If you are new to React or just new to the concept, the look of a render prop can be a little daunting. Checkout this example from react-spring's documentation:

import { Spring } from 'react-spring'

<Spring from={{ opacity: 0 }} to={{ opacity: 1 }}>
  {styles => <div style={styles}>i will fade in</div>} // <-- Here
</Spring>

If that makes perfect sense to you, awesome 🎉! Skip this article and get back to coding. If not, don't worry; I didn't get it at first either. Stick around, and I'll attempt to break down render props and show you how to make your own.

Background

What is a render prop?

At its core, render prop is "a simple technique for sharing code between React components using a prop whose value is a function."^[1] Instead of passing a string or object, you pass a function as a prop.

<Name renderProp={() => "Passing a function as a prop!"} />

The code above won't accomplish much - the arrow function just returns a string - but it introduces a new paradigm. What if, within Name we pass some data to our props.renderProp function?

const Name = (props) => {
  const name = "Sean";
  return props.renderProp(name);
};

When Name renders, it calls props.renderProp and passes some data; in this case, a string with my name.

We have designed our Name component with the sole purpose of storing the name data and passing it on to the props.renderProps function. The is the secret sauce that makes render props so powerful.

Going back to the implementation of Name, the function I pass to renderProp can look for this data as a parameter:

<Name renderProp={(name) => `Hello, my name is ${name}!`} />

When Name is called, it creates variable name with the value 'Sean', then calls the props.renderProp function and passes name. Finally, it returns a string that reads Hello, my name is Sean!.

But we aren't just limited to strings; this is React! You can return JSX in your function to render new elements in the VirtualDOM:

<Name renderProp={(name) => <span>Hello, my name is {name}!</span>} />

That's it! Render props provide us a method of passing props from a parent component to a child via function props. Using these same principles, we can create useful and reusable "logic" components to implement in any application.

Note: I called our prop renderProp, but there is nothing special about that name; you can use whatever name you want. I'll give you my recommendation for passing function props later on.

What does render props replace?

In most use cases, render props will replace HOCs. If we wanted to accomplish the above example with an HOC, we might use something like this:

const withName = (Component) => <Component name="Sean" />;

Then our parent component would be passed to withName, usually during the export. Once that is done, we could access props.name and render our greeting:

const App = (props) => <span>Hello, my name is {props.name}!</span>;

export default withName(App);

This works, and certainly has its use cases, but can introduce issues such as naming collisions. I recommend Jackson's article for a more detailed dive into render props and HOCs.

How To

Note: Facebook provides an introduction to render props in their React documentation. It is a useful resource, but their example was contrived and therefore difficult to reapply to new scenarios. Here I will provide a tried-and-true example that I have utilized in multiple projects.

Setting up our app

Let's imagine you're creating an application with drawer menu. Most of the time the menu is hidden, but when you hit a toggle button, the menu opens. Within the menu, you want to have an accordion that reveals additional links when open. In order to accomplish this, you might do something like this:

export class App extends React.Component {
  state = {
    menuIsOpen: false,
  };

  render() {
    return (
      <div className="app">
        {this.state.menuIsOpen && <Menu toggle={this.toggle} />}
        <main>
          <button onClick={this.toggle} type="button">
            MENU
          </button>
        </main>
      </div>
    );
  }

  toggle = () => this.setState({ menuIsOpen: !this.state.menuIsOpen });
}

We made App a stateful component and keep track of a boolean for the menu. Additionally, we added a toggle method to open and close the menu.

Now we need to create Menu:

export class Menu extends React.Component {
  state = {
    socialsIsOpen: false,
  };

  render() {
    return (
      <div className="menu">
        <button onClick={this.props.toggle} type="button">
          CLOSE
        </button>
        <h2>Menu</h2>
        <button onClick={this.toggle} type="button">
          SOCIALS {this.state.socialsIsOpen ? "▴" : "▾"}
        </button>
        {this.state.socialsIsOpen && <Socials />}
      </div>
    );
  }

  toggle = () => this.setState({ socialsIsOpen: !this.state.socialsIsOpen });
}

Look familiar? We reused the state from App (🚩 red flag no 1) so that we could keep track of whether or not to display our Socials component (just an unordered list of links). Menu needed to be toggled too, so we copy and pasted the method from App (🚩 red flag no. 2).

This works, but there are two main problems:

👎 Not DRY: In order to achieve the same function in two different components, I needed to repeat myself by copying and pasting the state and toggle method.
👎 Not extensible: Imagine I want to add another toggle feature to my app. What do I need to do? Copy and paste the necessary state and method again, which compounds my problem.

Fortunately, we can solve both of these problems easily with a simple render prop component.

Creating a render prop

The purpose of our render prop component will be to manage an open and closed state. It will also need a method to toggle the state like the examples above. Then it will take the state and method and pass it as arguments to a prop.

My preference for render props is to use a Component's children prop. This allows us to utilize opening and closing tags - a familiar convention in React - and makes indentation a little more manageable.

Our render prop component looks like this:

import React from "react";

export default class Open extends React.Component {
  state = { isOpen: false };

  toggle = () => this.setState({ isOpen: !this.state.isOpen });

  render() {
    const renderProps = {
      isOpen: this.state.isOpen,
      toggle: this.toggle,
    };

    return typeof this.props.children === "function"
      ? this.props.children(renderProps)
      : this.props.children;
  }
}

Just like the previous examples, I am keeping track of an "open" state and toggling it with a method. Here I simplified the name of the boolean in the state to isOpen because our component doesn't care what is and is not open. The only thing Open cares about is whether or not isOpen is true or false.

Render props components do not care about presentational logic. Their sole purpose is to keep track of simple bits of data and pass it on.

The toggle method is the same as previous examples.

Within the render method, I create a renderProps object with which I can pass on the current value of isOpen and my toggle method.

Finally I do a quick typeof check while returning. If this.props.children is a function, as I expect, then it will pass renderProps as an argument. If not, then it will fail softly by simply returning this.props.children.

You can optionally do some type-checking to ensure that children is a function, but I chose not to add an additional library here.

Implementing our render prop

Now that we have abstracted the open/close logic to Open, we can clean up our App component:

export const App = () => (
  <Open>
    {(openProps) => (
      <div className="app">
        {openProps.isOpen && <NewMenu toggle={openProps.toggle} />}
        <main>
          <button onClick={openProps.toggle} type="button">
            MENU
          </button>
          <Welcome />
        </main>
      </div>
    )}
  </Open>
);

We pass Open a child function that looks for our render props. Now I just need to switch out all references to this.state.menuIsOpen and this.toggle to refer to openProps.

Notice that App no longer needs a state; we can convert it to a functional component and let Open do all the work.

Next, let's do the same thing with Menu:

export const Menu = (props) => (
  <Open>
    {(openProps) => (
      <div className="menu">
        <button onClick={props.toggle} type="button">
          CLOSE
        </button>
        <h2>Menu</h2>
        <button onClick={openProps.toggle} type="button">
          SOCIALS {openProps.isOpen ? "▴" : "▾"}
        </button>
        {openProps.isOpen && <Socials />}
      </div>
    )}
  </Open>
);

Likewise, we were able to simplify Menu by converting it to a functional component as well. This may not seem like a big deal now, but it will be increasingly important as an application scales.

The fewer states and methods that you need to manage, the better.

You can see our render prop live, in all its glory, here on CodeSandbox:

Review

The render props technique is a great way to abstract reusable logic into specialized components. These components pass their logic/data/methods as arguments to functions passed as props.

Utilizing render props components solves the two problems above:

👍 DRY: The only code repeated is <Open>. You'll never have to write another toggle method.
👍 Extensible: Next time you want to add opening and closing to your app, all you need to add is Open.

Now that we've reviewed, let's take a look back at that original example from react-spring:

import { Spring } from 'react-spring'

<Spring from={{ opacity: 0 }} to={{ opacity: 1 }}>
  {styles => <div style={styles}>i will fade in</div>} // <-- Here
</Spring>

We can see that this Spring component is passed a this.props.children function. It then gives some data, in this case a style object, to that function as an argument. Finally, those styles are applied to the div.

Not bad, right? Now that you've mastered render props, make sure to check out this curated list of awesome render props. In the words of Captain Planet, "The power is yours!"

I hope this article helped; I know I learned a lot while writing it. Let me know if you have any questions about or problems.

Happy coding!

https://reactjs.org/docs/render-props.html ↩︎