seanmcp.com

We don't understand AI

Sean McPherson — Mon, 06 Jul 2026 14:14:00 GMT

While reading Ursula K. Le Guin's The Farthest Shore, I was struck by this quote from the main character:

To claim power over what you do not understand is not wise, nor is the end of it likely to be good.

After thinking about AI all week at work, my brain connected that sentence to the concept of interpretability, our understanding of a model's inner workings. An interpretable model is one that humans can understand its decision-making processes. Is that the case for today's models?

People outside the field are often surprised and alarmed to learn that we do not understand how our own AI creations work. They are right to be concerned...
– Dario Amodei, Anthropic

We certainly have not solved interpretability
– Sam Altman, OpenAI

Fictional characters know better than to harness an incomprensible power and expect good. Why do we treat AI differently?

Aside: Moments like this are why you should read more and widely. There is no end to previous wisdom that can be shared and reapplied to today's problems.

What is VS Code doing?

Sean McPherson — Tue, 28 Apr 2026 19:47:00 GMT

I have been a VS Code user for many years now. It was a soft landing from Atom (RIP), and there haven't been any significant features from other editors that have tempted me away. I have never experienced the performance issues that others have cited. It wasn't always as cool as the competitors, but it worked and worked well. Until recently.

This week VS Code started adding Co-authored-by: Copilot <copilot@github.com> to my commit messages automatically when commiting from the UI. In two instances that I documented at work, the commits included zero generative AI. But Copilot got the attribution anyway. In a world with increasing contributions from AI, it is important to me that any messaging about AI use is clear and accurate. This is not, and I'm disappointed that any decision makers working on VS Code thought that this was a reasonable default.

Then VS Code broke Intellisense – far and away its most valuable feature. Instead of providing the fast and intuitive help that users have come to expect, they have conceded to AI-powered Inline Suggestions. Previously the two systems were battling for supremacy, but the result was usually reasonable: Intellisense when it detected something and Inline Suggestions when it couldn't. It was a détente that I could live with. But now Inline Suggestions seem to have won the war at the expense of users. Most painful to me are the loss of snippets and automatic imports.

At one point in time VS Code was the undeniable king of cross-platform code editors. Then AI took over the engineering world and forks drew some folks away. I've enjoyed a lot of the AI-focused features that VS Code has implemented over the years – he first few generations of GitHub Copilot were truly magic and transformative for my work. But these most recent changes feel like crossing the Rubicon. The progress ad cacatum has begun and there is no going back.

I'm writing this in exile from Zed. I don't want to be here; I want my editor back. But I'm afraid that the writing is on the wall. /Lamentation

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.

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! ↩︎

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.

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.

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 ↩︎

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

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. ↩︎

Getting started with Eleventy

Sean McPherson — Mon, 27 May 2024 17:45:00 GMT

Eleventy has "Get Started" documentation that shows you how to get from a single markdown file to a built site. That is a nice "proof of idea", but I haven't found it to be a helpful way to actually get started with Eleventy. This garden aims to be a better guide for building a simple Eleventy site from scratch.

Setup

Create a new directory for your project: mkdir getting-started-eleventy
In that directory, initialize a new project: npm init -y
Install Eleventy: npm install @11ty/eleventy@canary --save-exact^[1]

Add dev and build scripts to your package.json:

{
  "scripts": {
    "dev": "eleventy --serve",
    "build": "eleventy"
  }
}

At this point you're probably tempted to run the dev script, but hold off for a little bit. We need to add some configuration to keep the project organized.

Configuration

Create a new src directory: mkdir src
Create your first markdown file: echo "# Hello, world!" > src/index.md
Create a .eleventy.js file in the root directory: touch .eleventy.js

Add the following configuration to .eleventy.js:

export default function (eleventyConfig) {
  return {
    dir: {
      input: "src",
      output: "dist", // Or whatever build directory you prefer
    },
  };
}

This configuration will tell Eleventy to look for source files in the src/ directory, and skip generating webpages for your project README.md. You can stick with the default _site/ output directory, but I like explicitly setting the output directory so that you know where they're going.

Add a .gitignore file to the root directory:

node_modules/
dist/ # Or whatever build directory you chose in .eleventy.js

At this point, you can run npm run build to generate your site. You should see a single index.html file in your build directory. But your site is probably going to need more than HTML, so we'll configure Eleventy to handle assets.

Assets

Create a new public/ directory in the root of your project: mkdir public
Add a line to your .eleventy.js configuration to copy the public/ directory to the build directory:
```
export default function (eleventyConfig) {
  eleventyConfig.addPassthroughCopy({ public: "/" });

  return {
    /* ... */
  };
}
```
This will copy all of the files within your public/ directory to the root of the build directory. You can test this by adding a CSS files to the public/ directory and running npm run build:

echo "body { font-family: system-ui }" > public/styles.css
npm run build
ls dist

You should see styles.css in the build directory, but the styles won't apply because the CSS files isn't linked to the HTML. To do that, we'll need to create a layout.

Layouts

Eleventy supports a bunch of different templating languages for layouts. I don't like any of them^[2], but JavaScript is good enough.

Create a new _includes/ directory in src/: mkdir src/_includes
Create a new base.11ty.js file there: touch src/_includes/base.11ty.js

This will serve as our base layout that includes all the HTML boilerplate. In that file, add the following:

export default class Base {
  render(data) {
    return `
      <!DOCTYPE html>
      <html lang="en">
        <head>
          <meta charset="UTF-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title>${data.title}</title>
          <meta name="description" content="${
            data.metaDescription || "Generic site description"
          }">
          <link rel="stylesheet" href="/styles.css">
        </head>
        <body>
          ${data.content}
        </body>
      </html>
    `;
  }
}

This layout will render an HTML document with title, metaDescription, and content properties. Noticed that we've now linked the CSS file that we copied in the "Assets" sections. Now we need to configure our markdown file to use this layout.

Update your index.md file to use the layout:

---
layout: base.11ty.js
layout: page.liquid
title: Home
metaDescription: The homepage of my site
---

The "body" of markdown files becomes `content` in layouts.

Now when you run your build again, you should see your index.html file with the additional markup including applied styles.

When you want to chain a layout in JavaScript, you need to refer to the parent layout in the class's data method:

export default class Page {
  data() {
    return {
      layout: "base.11ty.js",
    };
  }

  render(data) {
    return `
      <main>
        <h1>${data.title}</h1>
        ${data.content}
      </main>
    `;
  }
}

This new Page layout will render within the Base layout, giving you the power of composition when building pages. I typically have a base layout and then 2-3 other layouts that I use for different types of pages.

The next thing you'll probably want are UI "components" that you can reuse across your site, and for that we'll turn to Eleventy's "shortcodes".

Shortcodes

You could organize this section however you want. I'm going to show you one way that works well for smaller projects.

Create a directory for shortcodes in _includes/: mkdir src/_includes/shortcodes
Create your first shortcode file: touch src/_includes/shortcodes/emoji.js

Add the following to emoji.js:

/** An accessible emoji shortcode */
export default function emojiShortcode(emoji, label) {
  let attributes = [
    "role=img",
    label ? `aria-label=${label}` : "aria-hidden=true",
  ];
  return `<span ${attributes.join(" ")}>${emoji}</span>`;
}

Add the shortcode in your .eleventy.js config file:

import emojiShortcode from "./src/_includes/shortcodes/emoji";

export default function (eleventyConfig) {
  eleventyConfig.addShortcode("emoji", emojiShortcode);

  return {
    /* ... */
  };
}

Use the new shortcode in your markdown file:

---
layout: page.11ty.js
layout: page.liquid
title: Home
---

{% emoji "👋" "Waving hand" %} Hi there!

Use the new shortcode in your layout file:

export default class Page {
  data() {
    return {
      layout: "base.11ty.js",
    };
  }

  render(data) {
    return `
       <main>
         <h1>${data.title}</h1>
         ${data.content}
         ${this.emoji("👋", "Waving hand")} Thanks for visiting!
       </main>
     `;
  }
}

Build your site and you should see the emoji rendering with the appropriate markup.

Syntax highlighting

Eleventy will format inline code and code blocks correctly, but you need a plugin for syntax highlighting.

Install the official plugin: pnpm i @11ty/eleventy-plugin-syntaxhighlight
Add the plugin to the .eleventy.js config:

import syntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight";

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(syntaxHighlight);

  return {
    /* ... */
  };
}

Now the generated markup will have token classes. To style those differently, you can either create your own theme or download a Prism theme.
Link those styles in your base or page template and syntax highlighting will work for code blocks. (You may want to tweak the styles to apply to inline code too.)

Footnotes

Eleventy does not have an official plugin for markdown footnotes, but the markdown parser it uses does.

Install the markdown-it plugin: pnpm i markdown-it markdown-it-footnote
Add the config to .eleventy.js:

import markdownIt from "markdown-it";
import markdownItFootnote from "markdown-it-footnote";

export default function (eleventyConfig) {
  eleventyConfig.setLibrary("md", markdownIt().use(markdownItFootnote));

  return {
    /* ... */
  };
}

Configure the plugin to meet your needs: markdown-it-footnote documentation

Conclusion

There is a lot more that we could do, but at this point you are definitely started. With this little bit of organization and configuration, you're now on your way to building real sites with Eleventy.

I'm recommending the canary release here because it includes ECMAScript module support. This is the future of JavaScript and Eleventy, so might as well get on board now. ↩︎
I've been spoiled by composition patterns in JSX, Svelte, and Astro. I find it difficult to build UI in the way that my mind wants to think using templating languages like Nunjucks or Liquid. ↩︎

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.

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.

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.

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!

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.

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.

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.

Python Reference

Sean McPherson — Wed, 07 Feb 2024 24:19:00 GMT

Command-line arguments

Use argparse to configure command-line arguments:

import argparse

VERSION = "1.0.0"

parser = argparse.ArgumentParser(description='Describe your CLI')
parser.add_argument("-v", "--version", action="version", version=f"lorem {VERSION}", help="print version and exit")
parser.add_argument("count", nargs="?", default=1, type=int, help="number of sentences to generate (default: 1)")

args = parser.parse_args()
count = args.count

Read about argparse

Catching exceptions

Use try and except to catch exceptions:

try:
    # Code that might raise an exception
    if bad_condition:
        # Or throw your own
        raise Exception("Something went wrong")
except Exception as e:
    print(f"An error occurred: {e}")

Formatting strings

Use f strings:

name = "world"
print(f"Hello {name}!")

Reading a file

Use open to read a file:

with open("file.txt", "r") as file:
    contents = file.read()

Using with ensures the file is closed when the block is exited.

Writing a file

Use open to write a file:

with open("file.txt", "w") as file:
    file.write("Hello, world!")

Using with ensures the file is closed when the block is exited.

Requirements files

To generate a requirements.txt file:

pip freeze > requirements.txt

To install dependencies from a requirements.txt file:

pip install -r requirements.txt

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.

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.

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.

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

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.

Writing Prompts for Programmers

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

The most effective way I know to improve your writing is to do freewriting exercises regularly. -- Peter Elbow

Prompts

What is a tool that you have been using lately?
What tool would you miss the most if it were to disappear?
What is the first thing that you look to do when setting up a new computer?
What is a process that has been painful recently? How might you fix it?
What is a product that you think should exist?
What is a programming pattern that you have been appreciating lately?
What is a programming pattern that you have been avoiding lately?
Is there any value in bikeshedding? Why or why not?
How would you compare two solutions to a problem?
What are three strategies for reversing a list of strings?

How to use these prompts

These prompts were curated for freewriting, an exercise to help you get started writing. To start, follow these steps:

Pick a prompt that piques your interest
Grab a pen and paper or open a text editor
Set a timer for 5, 10, or 15 minutes
Write until the timer goes off

Once you are done, it's up to you: stop or continue, discard or publish. The goal was to write and strengthen those muscles, and you've succeeded!

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

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.

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.

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:

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:

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.

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!

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!

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!

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!

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 🚀

Jest

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.

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!

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!

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!

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!

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!

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!

Git

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=).

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!

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!

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!

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!

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!

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!

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!

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!

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 ↩︎

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!

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!

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!

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.

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.

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!

"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.

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!

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!

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) ↩︎

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 ↩︎