I just spent far too long trying to bend Zed to my will. It reminded me of how I needed multiple weeks on and off configuring and reconfiguring VSCode to work for me. It is rare that the defaults provided in a code editor work for me. So I tried, and I’ve given up for a few very important (to me) reasons.

But before that, all of this takes me back to my history with code editors. The main theme that’s stuck with me across each one is that I want it to be a code editor. Not an IDE. I don’t want a terminal, I don’t want to run tests, I don’t want a million and one features that are better handled by other tools and apps.

Code editor timeline

An approximate timeline, as near as I can remember would look something like this:

1990s - Script kiddie

I started nerding out with various things when I was too young to even know what I was doing, but I had fun doing it. I worked on all kinds of various things, but nothing noteworthy. I do remember having a Windows computer at home as our main machine for a stint on which I used Windows Notepad.

2002 - BBEdit

About this time I started ditching Adobe GoLive and going all in with BBEdit. I landed a job on my college campus building websites for our student union, student groups, and more. I got really good at writing HTML by hand. CSS was really just starting to proliferate and I was hooked.

2005 - TextMate

TextMate was already available, but we didn’t make the switch until it was really getting popular. TextMate did everything I needed and nothing more.

2011 - Sublime Text

I’ve spent more time using Sublime Text than any other editor. I would be really interested in knowing the full stats of hours spent in the application over the course of ~10 years.

I loved Sublime Text. It was fast, boosted my productivity, and simple – nothing about Sublime Text ever got in my way.

2021 - VSCode

I begrudgingly switched to VSCode. I never wanted to. In fact, over the course of at least three years, I tried to sit down and force myself to use it and configure it to my liking for a week at a time on at least four different occassions.

VSCode was slow. It does far too much for a “code editor” and is nearly a full-blown IDE… and at this point, with the right extensions, it is a full IDE.

I really only switched to VSCode for a few reasons:

1. The Sublime Text LSP for TypeScript sucked (and it still sucks). “Go to definition” rarely, if ever works.
2. SublimeLinter is very difficult to configure correctly.
3. As a principal-level leader who needed to spend a lot of time pair-programming and teaching others, it was too difficult to not work in the same editor everyone else was.

I finally got VSCode to a point where it typically is not noticeably slow and 90% of its features are tucked away, hidden, or completely disabled. These are the things that are either unnecessary or poorly implemented for me:

• Terminal: tends to be problematic or have integration issues
• Debugger: takes too long to set up and configure for every project. I just use Node’s --inspect --inspect-brk flags and pop open an inspector in a chromium-based browser
• All the tooltips: VSCode is way too aggressive about showing overlay hints and tooltips while I’m typing. I’m still typing. I actually type pretty darn fast, but these tooltips appear even faster and they’re always wrong.
• Disabled/hidden: Most of the UI panels other than the explorer view
• The search UI is horrible. I’ve moved it over to a panel, but it’s missing the ability to do regex replacements. You have to use the side bar’s find tab for this.

Trying something new

I recently tried to go back to Sublime Text, but I just couldn’t figure out how to get by the same first two issues that led me to switching to VSCode in the first place. So I threw that out the window.

I have the following hard requirements for an editor:

1. Ability for custom keyboard shortcut snippets.

   I’ve used the same custom snippet since my days with BBEdit: CMD+CTRL+, will add <div></div> and highlight div to change to any other HTML tag. I must use this snippet hundreds of times per day and I cannot live without it.

2. Two & three pane views.

   The panes need to stay open even when there is no file open in them. As visible in my VSCode screenshot above, keeping the panes open prevents any sort of unwrap/reflow of text in the open pane.

3. Stop shoving AI at me.

   I prefer to write things myself and know what I’m actually doing instead of hoping that an LLM connected the dots between keywords and syntax correctly.

4. “Go to definition” must actually work.

   Including going to definitions from node_modules (which Sublime Text doesn’t support).

Zed

Non-starters:

• Missing custom snippets. The inability to add my snippets in Zed made it a non-starter (and I spent a good hour scouring through discussions and issues trying to find a solution).
• Extra panes disappear when empty and there’s no way to prevent that.

Annoying, but I can live with:

• I absolutely hate that the settings are only in JSON. This is actually the same as Sublime Text, but annoyingly, you have to manually open both the defaults and your custom settings in order to know what is actually possible.

• Minimal/lack of documentation on how to configure key bindings.

  I can eventually get used to different key bindings for things, but the syntax currently requires I know the internals of Zed and its code to perform actions.

• AI - at least it can be disabled, but how do I know that what I’m writing isn’t being fed to some machine to learn from?

Lapce

Honestly, I didn’t spend enough time here and I probably should, but…

Non-starters:

• Like Zed, no snippet support.
• Extra panes disappear when empty and there’s no way to prevent that.

Annoying and I don’t want to deal with:

• It feels like it’s trying to be VSCode with all the features, bells & whistles, but I can’t make them go away.
• No native OS X menubar

Super annoying, but I can live with:

• I closed a couple panels upon first open and I can’t figure out how to get them back.
• What the heck goes in the right panel? It’s just blank and click/right-click does nothing in it.
• It took me a good 5 minutes to figure out how to open a folder/project in the editor.

Sitting for now

I guess I’ll be sitting with VSCode for now. Despite my annoyances – at least most of them can be hidden away or disabled.

About a year ago, I asked a friend what their thoughts were about me writing, for the fourth time, a monorepo toolchain – but this time, open sourcing it. They told me I’m doing the same thing that every JavaScript developer does – creates yet another way to do the same thing.

That hit pretty hard, even though I had thought about it a bit already, it was the first an external voice was reinforcing my fears. I was talking about doing the exact thing that I get annoyed about with the ecosystem. Why are there no less than 6 published modules to accomplish the same thing? Why do people keep creating their own instead of contributing back to the already established modules?

I sat with these thoughts for a good while. I hated what I wanted to do… but one thing kept bringing me back – none of the tools available were designed for the same developer experience, usability, extendability, and strict safety that I had become accustomed to.

Introducing oneRepo

oneRepo is a command-line interface, an API, and a toolchain for streamlining development with JavaScript and TypeScript monorepos. It’s more than a build system, more than (and not) a build enhancer using cache; it’s a full suite of tools to help teams work faster, smarter, and safer with apps and their source dependencies within monorepos of all sizes.

I’m thrilled to announce that oneRepo has officially reached version 1.0.0!

Features

Other monorepo tooling ends up being overly complicated or lacking in functionality, making it challenging for distributed organizations to maintain healthy interdependent code within a monorepo.

oneRepo is a full suite of tools for managing JavaScript and TypeScript monorepos, with the goal of enabling speed and confidence for all changes:

Automating tasks

oneRepo simplifies automation by handling common tasks for you and your team. Say goodbye to spending excessive time tinkering with tooling and hello to focusing on your applications.

Check out the oneRepo task system.

Strict safety & checks

Gone are the days of manually configuring file glob patterns for Workspace integrity and decision making for whether or not checks and tasks must run. oneRepo automatically and accurately determines which Workspaces, tasks, and checks are necessary for any given change.

Learn more about oneRepo’s built-in validation checks.

Stop recompiling dependencies

With oneRepo, you can utilize shared Workspaces as source-level dependencies. This means that all import/require chains within the monorepo originate from the source files, eliminating the need to rebuild shared packages to capture changes.

See how oneRepo prevents recompiling for every change using source dependencies.

Not another language

oneRepo and its APIs, plugins, and configurations are all written in JavaScript (and TypeScript). There’s no need to learn a new language or decipher YAML/JSON schema DSLs to configure your tooling.

Use oneRepo’s full featured API to write your own commands.

Human-readable output

Logging output from every command and tool in oneRepo is carefully grouped, documented, and prevented from overlapping parallel executions. Every line includes context, timing, and log-type information.

Clear, concise, and obvious log output for humans.

No upsells

Once you’ve installed oneRepo, you’re all set. There’s no need to pay extra for additional features; simply bring your own infrastructure and enjoy the full feature set.

---

A personal history

I have a pretty deep history with monorepos at this point. My first exposure to them was at Twitter, starting in 2015. I was hired on to the small team that was re-writing the entire web stack from Scala into React. Using Node.js and purely JavaScript was very new to Twitter. There were no user-facing services written fully in JavaScript at the time. We were pioneering something new. However, Twitter’s source monorepo was primarily focused on serving the dominant language, Scala.

All of Twitter’s tooling, including an entire engineering team (larger than the entire web team), was focused on ensuring micro-service interopability, scalability, and speed of development – for Scala. Sure, there were some other languages thrown in there that had some optimizations as well, but none of them worked anything like JavaScript.

Problems arose quickly as we started to scale our application’s codebase, shared (internal) dependencies, and team. One of the worst issues we had, that was unique to working with JavaScript within source, was that it would take 30-60 seconds to create a new git branch.

Yes. One entire minute wait just to git checkout -b ….

After what seemed like months of back and forth with the team responsible for our monorepo tooling: the issue was having a large number of ignored files within the repository. Because JavaScript projects typically include one or more node_modules folders that are ignored – with thousands of files in them.

Problems

The branching issue was just the tip of the iceberg of the issues the web team was facing. Some of the other major issues we were facing:

1. We weren’t sharing code with any other services outside of our own application and sub-packages. Similarly, no other team depended on any of our code. We were just a small fish in a huge ocean.
2. The tooling couldn’t determine the dependency graph of our application and sub-packages – we could not do any deterministic test or CI tasks based on what changed across Workspaces.
3. Poor discoverability of commands, shared modules, patterns, and documentation.
4. Knowing when to run npm install after pulling the main branch.
5. Speed of all aspects of the development cycle (see previously mentioned issue with switching brances).
6. And many more lost to my memory at this point…

We were essentially a client application. The iOS and Android client applications had their own repositories to avoid the exact same problems we were experiencing, being a unique language with non-shared code that didn’t fit into the rest of the stack.

Solutions

So what’d we do about it? In 2017 I started pushing hard to allow the web team to move out of the source repo. It was a very uphill battle for many months. At most, I counted one VP, four Directors, at least five Senior Managers, and at least a dozen engineers in a meeting while trying to get the source monorepo team to allow us to move out. Why we needed their permission is still over my head, even though this was my project from the start.

Eventually, we hired a new Director for that team and I had a one-on-one meeting with her. I was prepared with the same engineer productivity stats that I had presented time and time again.

We could save nearly two hours of wait time per developer, per week.

We had nearly 30 developers working on the new web stack at the time. I’ll never forget her response to me:

What? That’s material time. Why are we wasting our time now talking about this? Just go and do it.

She told me she’d deal with her team and shield us from the fallout. I finally was able to get our team in motion in 2018 to build what we needed.

My experience building the web monorepo tooling became the foundation for what is now available as oneRepo.

Rewriting

After Twitter, I ended up writing nearly the same monorepo tooling internally two more times. Once at Zillow Rentals and once at Microsoft for Startups. In between those two times, I also started writing it with the intention of being able to open source it. I didn’t get very far, as work and life took much more out of me and I wasn’t able to devote enough time to making it be something usable.

---

Another monorepo tool

Back to the beginning of 2023. I had started a new position with the express directive to pull a disorganized frontend organization together, help them grow, and figure out how we can work faster.

Our CTO came at me with this simplified question that he wanted answered:

Why does it take so dang long to put a button on a page?

The answer was not one of skill, laziness, or anything that could be related to one or many persons. Instead, the answer was that we had over 126 individual frontend repositories. Of those, there was a varying amount of code sharing through a private npm registry, often with varying versions and duplications of the same packages.

It was a completely different root problem than we had at Twitter, but with a similar result – it took forever to do anything and teams were all working in silos, rarely sharing code and knowledge.

I set out to solve this problem first. Yes, there were many problems – 126 frontends is also a major issue, but that’s not our focus here…, but the first step was to figure out what we have, what we need or don’t, and how we can share and merge.

By now you’ve probably guessed what the solution would be: merge our frontend repositories down to a single monorepo.

Choosing the right tools

But what monorepo tooling would we choose? I did my due diligence again to look at Nx, Turbo, and Bazel. With each tool I had the same issues:

• ❌ Reading and following log output was very difficult for the varying debugging skill levels we had.
• ❌ They piggy-backed on npm scripts, which meant:
  • We would still have to write custom tooling.
  • It would be too easy to reject standards and allow Workspaces to create one-off different ways of doing the same things.
  • It is difficult to determine what script does what – there’s little to no --help documentation
  • Finding the source of the scripts requires deep knowledge.
• ❌ They rely heavily on caching input & output to give a perception of speed. Setting the cache determinism is a manual process that is really easy to mis-configure, resulting in false results during all lifecycles of code.
• ❌ They use custom DSLs, often YAML to configure.
• ❌ They upsell cost-prohibitive paid services.
• ❌ They do not enforce strict correctness and standards across Workspace boundaries.

Really, my list goes on. Maybe you can make the tools work differently and satisfy some of my issues, but not without a lot of extra work and requiring deeper knowledge of the tools – or building entire extra systems to work in tandem.

Open sourcing

Instead of any of the available tools, I got the go ahead to finish working on oneRepo as open source code, still under my ownership, but with the primary intention of enabling it internally to serivce our teams.

While this was very exciting to me, knowing I already had a good start and the experience to back up making it robust enough for many different teams, it was still nagging me that I was writing yet another tool to throw out in the public to choose from.

Eventually, my desire to have tooling that’s easy to use, easy to read, performant, and strict overcame my hesitations. And anyway, the worst case scenario is that no one likes what I’ve made and no one uses it. Well that’s actually easier for me, because it means less to support.

---

oneRepo

First and foremost, oneRepo was created with the understanding that everyone cannot be expected to know everything. Every aspect of oneRepo should feel familiar, or at the very least, obvious how to learn and debug.

• One entry point

  oneRepo is a command-line interface: one. It is the one entrypoint for all of your one repository’s management.

• Help output

  Any time you’re not sure what to do with the CLI or what something does, help is just a couple keystrokes away with --help (or -h)

• Tab completion

  Yargs provides us with out of the box tab-completion. Just run one install and you’ll be good to TAB to completion any time.

• Generated docs

  Use the first-party plugin @onerepo/plugin-docgen to generate and share documentation as Markdown or other formats. It’s super easy to use and makes clear and readable documentation.

Empowering developers

The source of all commands, custom or built-in, are written in the same language as the rest of your repository. Each command is represented by a distinct file, easy to find within the commands directory. This enables everyone on your team that works with JavaScript to be able to learn and contribute to the repo’s tooling without always needing to learn a new language or interrupt a specialist.

Clear output

One big frustration that I always have with other tooling is the log output is difficult for humans to read. My experience debugging with others, particularly more junior developers, has been that they expect errors to be obvious, front and center, without all of the other context.

Particularly when running tasks in parallel, most monorepo tooling will buffer everything immediately to the output, interleaving tasks together, making it difficult to follow what is happening and where there may be issues or all is fine.

@internal-tests/todo-list:test: +++
@internal-tests/todo-list:test:
@internal-tests/todo-list:test: dependencies:
@internal-tests/todo-list:test: + @internal-tests/todo-list 0.0.0-development
@internal-tests/todo-list:test: + @types/node 16.11.41
@internal-tests/todo-list:test: + typescript 4.7.3
@internal-tests/todo-list:test:
@internal-kit/ts:setup:test: Progress: resolved 117, reused 110, downloaded 1, added 0
@internal-tests/todo-list:test: Progress: resolved 3, reused 2, downloaded 1, added 3, done
@internal-tests/todo-list:test:
@internal-kit/ts:setup:test: Progress: resolved 219, reused 208, downloaded 1, added 0
@internal-tests/todo-list:test:  PASS  src/__test__/usingCli.test.ts
@internal-kit/ts:setup:test: Progress: resolved 310, reused 292, downloaded 1, added 0
@internal-kit/ts:setup:test: Progress: 421, reused 402, downloaded 1, added 0
@internal-tests/todo-list:test:  PASS  src/__test__/usingAsLibrary.test.ts
@internal-tests/todo-list:test:
@internal-tests/todo-list:test: Test Suites:  2 passed, 2 total
@internal-tests/todo-list:test: Tests:        2 passed, 2 total
@internal-tests/todo-list:test: Snapshots:    8 passed, 8 total
@internal-tests/todo-list:test: Time:         2.9122s, estimated 3 s
@internal-tests/todo-list:test: Ran all test suites.

oneRepo solves for this by waiting grouping output by individual task. While running, by default, only the most recent or most important information will be shown. Output will never be interwoven between individual tasks. And without manually requesting more verbose output, superfluous information will be hidden:

 ┌ Run tests for @internal-tests/todo-list-cli
 └ ✔ 3s
 ┌ Run tests for @internal-kit/ts
 │ Progress: 421, reused 402, downloaded 1, added 0
 └ ⠙

Integrated CLI

Other monorepo tooling requires you to decide how to write commands and tasks yourself. Either you’re delegating directly to third-parties through large DSL configurations or you’re writing custom scripts as one-off solutions with mashed-together setups for logging, type safety, error handling – or none of the above. There are too many choices to make and that ends up with repos having scripts that are difficult to find and trace in the event of an issue.

Furthermore, I’ve been frustrated recently by all of the new fancy tools popping up that are written in Rust/Zig/other-fancy-new-C-compiled-languages. They are written for JavaScript, but fall short of offering a way for JavaScript interfaces and enhancements.

oneRepo on the other hand is a fully JavaScript and TypeScript-compatible command-line interface and PI that’s made for adding any extra scripting or commands you can think of. But no need to worry about adding Rust and learning it to your JS monorepo – plugins and CLI commands are written in JS/TS. This makes it easy for you and your team to write custom commands directly for your Repository and Workspace’s needs.

import type { Builder, Handler } from 'onerepo';

export const command = 'new-branch';

export const description = 'Create a new branch using our team’s standard naming format.';

export const builder: Builder = (yargs) => yargs.usage(`$0 ${command}`);

export const handler: Handler = async (argv, { graph, logger }) => {
  // Everything you need is easily handled here
};

No cache

Avoiding extra work by utilizing cached responses based on a set of input files is a great time saver in theory. The problem is that the responsibility of knowing exactly what files and Workspaces affect the cache for each individual task lies on you and your team.

oneRepo purposefully does not use a cache to avoid false positives and promote strictness over minor speed improvements. Checkl out some extra details on common pitfalls and cache inconsistency on the oneRepo docs.

More to come

I tend to freeze up trying to promote my own open source projects. Writing the code is so much easier than selling people on the idea of using something new and different. And as usual, I’ve written an overly verbose blog post about something I’m passionate about.

But that’s just it. I haven’t been able to stop being passionate about monorepo tooling for years – and I finally have something that’s open source that I can use and share with others. Improvements will continue to roll and I’m excited to see what others do and accomplish with oneRepo.

npx --package=onerepo one install

❌ No support for custom rules and plugins

That’s it. While Biome intends to explore (supporting) plugins, there are no concrete plans in either tool – nor are they likely to support plugins via JavaScript/TypeScript.

Why is this a problem?

While I understand that the intention for both of these projects is to be opinionated, at the same time, those opinions have been formed slowly over time by the large community of JavaScript developers. Blocking the ability to support new ideas – or even blocking behind another language barrier – will result in stagnating progress.

Furthermore, individual teams often have very sutom needs to help prevent problematic patterns and catch errors that are unique to their software. I’ve written tens of custom ESLint rules over the last decade for teams that helped us prevent real problems that otherwise could go unnoticed until they persisted in production for weeks.

I’m hopeful that these Rust-based tools succeed, because they are fast. But I can’t imagine they will without a JS-based plugin & custom rule API.

T[]

Why you should use the Array type

• Immediately clear when reading left-to-right that the type is an Array.

  type MyStuff = Array<{ some: BigObject }>;
  

• Matches the syntax for Set<T> and Map<K, V>

  type MyArr = Array<T>;
  type MySet = Set<T>;
  type MyMap = Map<K, V>;
  

Why you should not use Array shorthand

• Easily overused on complex types

  type MyStuff = { some: BigObject }[];
  

  You’re probably going to argue that { some: BigObject } should be further extracted out, and you’re right, but remember that people are inherently lazy and won’t always do that.

• Easily mistaken between tuple types, but they are not identical:

  [string] !== string[]
  

Automate the good syntax

Arguably, it’s hard to enforce a single way when two different syntaxes have the exact same meaning. Luckily, there’s an auto-fixing ESLint rule for that: Use @typescript-eslint/array-type set to "generic":

module.exports = {
  rules: {
    '@typescript-eslint/array-type': ['error', { default: 'generic', readonly: 'generic' }],
  },
};

Last year, I posted “Six things I want to see in JavaScript and Frontend development in 2023”. It’s been just over one year since that post and I thought it’d be fun to do a quick recap and grade each one.

Unfortunately, I have to give us all overall GPA 1.0 due to way too many failures.

1. Usage of Axios declines or goes EOL

   Grade: F

   I am sorely disappointed. What I’ve learned from working with various teams is that Axios tends to be what people use when they’re uninformed, not up to date with standards, and just copying examples from the Internet.

2. Successful use of the Node.js Test Runner

   Grade: D

   I haven’t really seen anyone pick this up in a full context yet. I would still love to see this happen. I did actually think about it, but there’s still too much complexity when you’re writing TypeScript and have other complex needs.

3. Less divisive stances on CSS solutions

   Grade: F

   Nope. Everyone is still an armchair expert that will tell you whatever you’re using is terrible and you should use their favorite solution instead.

4. Less venture capital backed open source

   Grade: C

   I honestly don’t know. Maybe that’s a good thing. I haven’t seen a lot of new big open source stuff popping up with VC funding, but I have heard of a lot of startups getting going.

5. Decline of weak Eslint rules and configs

   Grade: B

   We’re getting there! A few projects like Biome and Oxlint are even making alternatives to ESLint without all the fluff that are nearly hundreds of times faster.

   ESLint itself is deprecating formatting rules in favor of allowing a proper formatter to do them for you.

   Overall, things are better, but we’re not quite there yet.

6. React either gets it’s crap together or gets out of the way

   Grade: F

   Nope. React is worse than ever and continually seen as a frustration point.

Oh well, we failed miserably – but there are some things to look forward to yet.

Here’s a little trend for 2023 that’s going around: listing out the default apps (and tools!) that I’ve used in 2023. I enjoy this little go around, as I’ve been getting to discover new apps that I might want to try.

I also did something similar last year, but in a much more limited capacity.

• 📨 Mail client:

  • Personal: Apple Mail – I’m transitioning my personal life away from GMail and Google services. Who knows if Apple is actually better from a privacy standpoint, but I already pay for iCloud and own my own domain. It has worked will for the past half of this year.
  • Work: Gmail, but saved to the Dock through Safari.

• 📮 Mail server: (see also Mail client)

  • Personal: iCloud Mail
  • Work: Gmail

• 📆 Calendar: (see also Mail client)

  • Personal: Apple Calendar – fits with the whole moving away from Google thing.
  • Work: Google Calendar – Again, I don’t have a choice on this, but I do have the app saved to Dock

• 📝 Notes: Notion

  I had a lot of hesitation with Notion until I was forced to use it through work. I would prefer an open source alternative, but none have as powerful of database features as Notion does and I’m making heavy use of them.

  I was previously trying to use Nextcloud to handle notes and many other things, but the web UI is slow and painfully cumbersome.

• ✅ To-Do:

  • Personal: Notion – with heavy use of database tables and ability to cross-link items to other pages in Notion really helps me keep track of what I’ve got going on.
  • Open source: GitHub issues
  • Work: Shortcut – I dislike this tool almost as much as JIRA. It gets too complicated as soon as managers, project managers, compliance, and legal start adding requirements.

• 📷 Photo Shooting: iPhone 13 Pro

• 🎨 Photo Editing: None

• 📁 Cloud file storage: NextCloud

  I keep this privately hosted. It’s nice to know that my files are actually my files. I also have quite a few local backups.

• 📖 RSS: NextCloud News

• 🙍🏻‍♂️ Contacts: Apple Contacts

• 🌐 Browser: Arc

• 💬 Chat:

  • Messages – SMS/texts and iMessage
  • Slack – Both for work and the local BendJS meetup group.
  • Signal – Because privacy matters

• 🔖 Bookmarks: Arc

• 📑 Read It Later: Arc, recently Notion Web Clipper

• 📜 Word Processing: VSCode, Markdown, Notion

• 📈 Spreadsheets: If I really need to do some complex manipulation, Google Sheets, but I’m equally or more likely to write a script with Node.js and process JSON files.

• 📊 Presentations:

  • Personal: I haven’t given any talks or presentations in a few years. I’d like to get back into it, but I haven’t found the right fit.
  • Work: Google Sheets

• 🛒 Shopping Lists: Notion

• 🍴 Meal Planning: Notion

• 💰 Budgeting and Personal Finance: N/A (😬)

• 📰 News: RSS, Reddit, Mastodon

• 🎵 Music: Plexamp

  I have a very large library of music collected over more than two decades. I just can’t let go of the super rare albums and EPs that will never be on any of the cloud services.

• 🎤 Podcasts: None. I can’t pay attention to podcasts and do anything else at the same time.

• 🔐 Password Management: 1Password

• 🧑‍💻 Code Editor: VSCode

  I reluctantly gave up trying to continue using Sublime Text. It took me 4 tries over nearly as many months to get VSCode configured in a way that didn’t feel overly intrusive. There are still a lot of quirks about it that I don’t like, but being on the same editor as those I work with has been really helpful.

• ✈️ VPN: OpenVPN

Bonus

• 🚀 Launcher: Alfred

  I bought a “Mega Supporter” Powerpack license years ago. I’ve had free upgrades for years and never a single complaint.

• 🎥 Screen recording: Screenflick

• ☕️ No sleep: KeepingYouAwake

  Don’t tell your IT/security team about this. When you work from home and work requires and resets your screensaver/sleep timeout down to 5 minutes, waking up and logging into your computer can be a nuisance when you make frequent kitchen & bathroom breaks. This little gem can keep your computer active for hours – no mouse jiggler required.

• 🪟 Window organization: Moom

  I’ve bound a bunch of custom keyboard shortcuts for organizing windows across my screen(s). This has been a staple of my productivity toolchain for years.

The company I worked for displayed timelines of user-generated content using our React application. Each entry on that timeline we referred to as a “Tweet”. And in this timeline of Tweets, we had promoted content, or as many people would call them, “advertisements”. Selling advertisements was how the company made money.

In order to appropriately bill the advertiser, we needed to have a reliable count of how many times their advertisement was displayed for each and every user. It also helped us know that the advertisement was displayed the correct number of times per the sale contract with the advertiser.

Each one of these promoted Tweets needed to have an attribution property, something like promotedContentId. This property was then used when logging visible Tweets that it was in fact displayed. It was a relational ID that told the backend systems exactly which Tweet from which advertiser was being displayed.

{
  entries.map((entry) => {
    return (
      <TimelineEntry
        entry={entry}
        id={entry.id}
        promotedContemtId={entry.promoted ? entry.promoted.id : undefined}
        userId={entry.user.id}
      />
    );
  });
}

We made a typo. Instead of promotedContentId="value" being passed to the React component, we use promotedContemtId="value". Did you catch it? Maybe because you were looking for it. But for the code author and reviewers looking at a change with a couple hundred lines of code differing, it would be really easy to miss in a sea of red and green.

This typo caused a few things:

1. The same advertisements were being displayed over and over again to the same viewers. Since they were never attributed as being seen, it was assumed that the advertisement still hadn’t reached the viewer that it was intended to.
2. We were unable to bill the advertiser for the views on their advertisement. According to our database, the advertisement was never displayed, so there was no count of views, so we had not yet fulfilled our end of the contract.

We were using the prop-types package, like everyone else at the time. From the prop-types readme (emphasis mine):

You can use prop-types to document the intended types of properties passed to components. React will check props passed to your components against those definitions, and warn in development if they don’t match.

Warnings are pointless. They are nothing but noise and invisible unless you’re explicitly looking for potential issues and remember to do anything about it. They do not block and cannot be statically analyzed in CI systems.

Because there was no real error, just a warning, this issue went into production and was there for at least a few days before it was noticed. It potentially cost the company hundreds of thousands of dollars in revenue – probably more.

We had a post-mortem on the issue and came out of it with the following action items:

• Add an integration test.

  At the very least, adding an integration test will prevent this same issue from happening in this same manner.

• Add strict type safety.

  The integration test will help, but only for this exact path on this exact issue; it won’t prevent similar issues from happening in other places in the future. The only thing that can prevent similar issues was to make all of our attributes and argument keys absolutely strict & fail during prevent pull-requests from merging when failing the type checking via automated CI processes.

I could see common counter arguments here that there should just be more end-to-end and integration testing. But how strong and reliable are your test environments to ensure that this all works correctly? How much effort, time, and money does it take to maintain full testing solutions? Sure, you could have some and keep them lightweight, but now you’re picking and choosing what’s important to test and what’s not. Strict type safety is the cheapest solution that can apply to everything, everywhere. It’s a contract that cannot be broken.

So we converted our codebase from plain JavaScript over the next year or so to have full strict type safety. We never had the same type of issue again, because our pull requests were always strictly enforced, requiring conformance with strict type safety.

In the end, type safety likely saved us from losing more money. How many countless other issues did type safety solve? It’s impossible to tell, because it prevented us from ever encountering them.

One final note: I only ever mention strict type safety. That is TypeScript’s strict mode and more: any, Function, object, and other ambiguous types are also explicitly disallowed, as they are a rejection of purpose of type checking.

The any type was a mistake and never should have been included in TypeScript in the first place. It is disappointing to see the number of published libraries that embrace any types, making it difficult to verify with certainty that code is correct.

Path aliasing, sometimes referred to as import or module resolution, in the earliest and most naïve sense, is a method of overloading the Node Require Resolution Algorithm so that it first looks in some particular defined folders for modules of a given name before looking for installed modules of the same name in node_modules folders. In the early days of Node.js first availability, this was somewhat common practice to overload the require.paths array with some extra stuff:

require.paths.unshift(path.join(__dirname, 'src'));

With modern tooling, like TypeScript compiler paths, Vite resolve.alias, WebPack resolve.alias, @rollup/plugin-alias, esbuild-plugin-alias, and many others, more specific aliasing or even prefixes for entire paths can be used:

When configured using the above, any TypeScript project can have files that import from the prefixed alias, short-circuiting the relative lookups that are normally done.

import { Button } from '@/components/Button';

The problems with import path aliasing

Import path aliasing is a crutch for poorly organized and architected codebases.

The following example probably looks fine to most people:

import Button from '@/components/Button';
import TextInput from '@/components/TextInput';
import useGetUserQuery from '@/shared/api/get-user';
import useLoginMutation from '@/shared/api/login';

Expanded out to use the relative paths, it may be more clear why people tend to read for prefix aliasing. It’s messy to read repetitive ../ and determine if they are correct or not.

import Button from '../../../../../../../components/Button';
import TextInput from '../../../../../../../components/TextInput';
import useGetUserQuery from '../../../../../../../shared/api/get-user';
import useLoginMutation from '../../../../../../../shared/api/login';

But this code smells. This seven-level deep import in the previous example means that the source file is nested at least seven directories within the root of the project. When code is actively and commonly importing from many levels higher in its file tree and reaching deep into separate folders, the organization of the application as a whole is going to be really difficult to follow and maintain – especially for new team members or infrequent contributors.

Hiding the organizational issues behind path aliasing does nothing for the greater organization, but puts it off for another day.

Lack of standards

The most major issue is that there are no standards across frameworks and tooling. Every setup is ad-hoc. While some projects tend to use something like ~/ or @/ to point to the src/ directory, many do not. Some even alias unprefixed straight to one or more directories.

From project to project, there’s no way to know what the correct aliasing is without referencing the configuration(s). And furthermore, just because a project has aliasing, doesn’t mean that it is enforced. Imports can always written as relative imports.

Enforcement

There’s no way to enforce and ensure that aliases are always used. Files end up with a mix of aliases and relative imports and it is unclear whether the filepath imports are located next to each other or not.

import { Button } from '@/components/form/Button';
import { TextField } from '../../../components/form/TextField';

Confusion

The following two examples are canonical, but one is longer and more complicated than the other – and it’s not the alias version.

import { Label } from './Label';

Maintenance issues

Then there are other static analyzers that don’t understand how to read a tsconfig, vite.config, or whatever is in use to set up aliases. There are many potential places and ways to configure aliasing – and not all of them are compatible with reusing a single configuration, but will have to be done as duplicated configurations slightly differently.

Consider ESLint and using eslint-plugin-import rule import/no-cycle or import/no-self-import: neither are directly configurable to understand aliasing. Instead, another plugin for ESLint is now required with an array-map configuration, completely different from tsconfig and other setups: eslint-import-resolver-alias.

Down the rabbit hole

There are countless other tools and static analyzers that might need to be configure to use the aliasing as well.

More times than I can remember I have also needed to write large code transforms that read through ImportDeclarations, looking for particular files and updating references, imported methods, and then rewriting code based on them. When shared across different applications with different setups, I’ve needed to figure out how to take in custom configurations in order to do the mapping from alias to resolved path.

Published modules

If a reusable module is using path aliasing and is going to be published to a registry, it needs ensure that its build tools also rewrite the aliasing before publish. Not all of the plugins and tools enabling aliasing do this automatically, so it’s yet another step to create with caution and care.

Pandora’s box

A team might say that they’re going to standardize on just using the @/* → ./src/* aliasing across all of codebases and teams in order to reduce maintenance issues.

But by adding aliasing in the first place, the door is already open for endless possible aliases. Why can’t someone add another alias for a set of common utils that they keep needing? What’s actually stopping them from doing it? If it’s okay, how is it communicated to the team? How is it enforced?

Better organization

Often times, the reason codebases develop problems that make path aliasing attractive comes from the many frameworks with short-sighted recommendations (and sometimes requirements) for how to organize code in an application. Typically for web application, api, pages, components, hooks, and modules are seen as top-level and everything is thrown into them.

└── src
    ├── api
    ├── components
    ├── hooks
    ├── modules
    └── pages
        ├── auth
        │   ├── login.tsx
        │   └── logout.tsx
        ├── dashboard
        └── home

This looks just fine when getting started, but it fails to think forward to the application growing into a feature-rich and complex application. Frustrations start to arise when directories have too many files at a single level, so people come through and try to organize similar things together.

└── src
    └── components
        ├── auth
        │   └── login
        │       └── Form.tsx
        ├── cards
        │   └── …
        ├── form
        │   ├── inputs
        │   │   ├── PasswordInput.tsx
        │   │   ├── NumberInput.tsx
        │   │   └── TextInput.tsx
        │   └── buttons
        │       ├── PrimaryButton.tsx
        │       └── SecondaryButton.tsx
        └── grids
            └── …

And this may work in the short term. But as teams grow and communication is less clear, these structures become cluttered with internal acronyms, duplication, and much more complex nesting.

Typically, teams become focused as part of a “product pillar”. These pillars allow optimization and specialization in varying areas, which makes colocation all of the application’s code more fragmented, despite best intentions to reuse as much as possible.

Use a monorepo

*                         infra-team
app/src/pages/home        home-team
app/src/pages/dashboard   dashboard-team-team
app/src/pages/auth        auth-team
modules/components        ui-team
modules/api               api-team, infra-team
modules/hooks             infra-team

Bonus mentions

In no particular order and less important, but worth calling out, here are some other pitfalls to avoid:

• Names of modules and directories that are too generic.

  utils tends to become a dumping ground for everything. Take an extra minute to plan where something should be based on it usage, reusability, and purpose.

• Reduce the number of imports in components.

  Importing from 20 or 30 files for a single component means the component is doing too much. Splitting it into logical bits will make it both easier to maintaing and test. Not only that, but patterns may arise that suggest that portions would be better organized somewhere else within the codebase.

Easily revert path aliasing

Hopefully I’ve done a good job and convinced some readers to stop using path aliasing. Unfortunately, the reversion process to move back from aliases to relative imports is manual, difficult, and error-prone.

However, I’ve had to help teams out enough times over the years to finally realize I should make my codemod public and easy to use.

Introducing remove-aliasing

npx remove-aliasing@latest --root="src/" --prefix="@/" src/

Bonus VSCode settings

Updated 2024-03-06.

VSCode comes out of the box with an inconsistent setting: when adding imports for you, it will choose the shortest import path. So if your relative import is even 1-character longer than it would be as an alias, the alias will be used.

You should turn this off.

{
  "javascript.preferences.importModuleSpecifier": "project-relative",
  "typescript.preferences.importModuleSpecifier": "project-relative"
}

As another helper, make sure that VSCode automatically updates import paths when you move files. This will save you some confusion in those rare instances where things need to be moved around. Be warned, though: moving files across Workspaces in a monorepo may have unexpected results.

{
  "javascript.updateImportsOnFileMove.enabled": "always",
  "javascript.preferences.importModuleSpecifier": "project-relative",
  "typescript.updateImportsOnFileMove.enabled": "always",
  "typescript.preferences.importModuleSpecifier": "project-relative"
}

When was the last time you stopped to think about the cost of a new third-party package that you’re adding into your process?

Where do you recommend balancing between “not invented here” syndrome (NIH) and using packages just because they exist? I always come back to the “left-pad incident” as an extreme example to avoid the latter, but where should we be drawing the line between the two?

While npm doesn’t publish statistics of the number of packages in its registry, in 2019 they passed the 1 million package mark. That means we have at least 1 million packages we could possibly consider using.

That is utterly too many packages. I’m sure we’ve all contributed in some way to the proliferation of a module for everything, but where can we start drawing the line and how do we actually determine whether we should be using one package over another over writing it ourselves?

Some considerations that I’ve been thinking about when looking at third-party JavaScript modules:

• Can we actually do it all on our own?
• What’s the cost of maintenance and bug fixes?
• How will a third-party module affect bundle size?
• Will the effort to build an equivalent be too high?
• Do we already have a package that satisfies this use case?
• Is there an equivalent standard API?
• Does the module actually work as advertised?

Internal ability and understanding

I’m currently torn between writing some (what I would consider) simple DOM layout measurements for tooltip positioning versus reaching for floating-ui to do it for me. The library actually has much more than I need, but it’s tree-shakeable, so maybe that’s okay.

I’m confident that I can write and maintain my own measurements and ResizeObserver, but does my team all feel the same? But then again, if they can’t, maybe I should be helping and encouraging them to learn.

There’s no single answer to all of this and it should be carefully taken into consideration. Just because we can, doesn’t mean we should.

Maintenance and bug fixing

Extending from the internal ability and understanding, reaching for a library without the knowledge of what it’s actually doing can be worse than copy/pasting from StackOverflow. At least with copying code from somewhere, while you didn’t write it, it’s now yours and your team’s to understand and maintain. If it ends up having a bug in it, you are responsibe and should be able to fix and deploy it at any time.

When pulling in a third-party module, you’re at the mercy of the open source authors & maintainers – even if you create a pull request, will it get fixed, merged, and deployed for you? Would you even have been able to get ramped up on contributing to the open source repository in a realistic timeframe?

Let’s say you decide to fork a library and maintain it internally. Well now you’ve got an issue of how its repository is set up, standards, lint rules, etc. There are many concerns to consider when forking.

Bundle size

One of my first stops when evaluating a third-party package is BundlePhobia. This gives me a general idea of how much a the package will increase my overall bundle size after building and deploying for production, as well as show what other dependencies it has and how their makeup affects the build.

• Is the relative size of the package realistic for what I’m expecting it to do?
• Do any of its dependencies overlap with what I’m already using, and thus may not actually increase my final bundle size as much as this says?

Is the juice worth the squeeze?

I have a team rebuilding our core shared component library at work and we have a strict mandate to ensure WCAG 2.0 accessibility standards. The team knows what they’re doing and can absolutely succeed at meeting those on their own. However, while building the previous iteration of the library, the <DatePicker /> component took nearly three months to build.

I challenged the team, despite their hesitation about ARIA, to try using react-aria, a major library of React hooks that aid in providing accessible UI primitives for design systems. One person came back on the same day with a prototype of a fully accessible <DatePicker /> and stated that it took them about two hours to build what previously took over two months.

Essentially, “is the juice worth the squeeze” means we can determine whether the output is worth the effort. In cases like the above, I can safely answer “no” and move forward with pulling in the dependency. Other times, maybe not.

Duplicate concerns

Do we already have a package that fulfills this use case? I can’t even count how many applications I’ve seen running a combination of state management libraries like Redux, Redux Toolkit, React Query, and Zustand (among a scattering of others). Pick one and stick with it; don’t reach for a new library just because you heard it’s new.

Standard APIs

Is there a standard API that can already do much of the same thing? Check your browser support matrix via MDN or caniuse.com and consider standars in favor of older packages that fulfill the same purposes. Here are just a few of the packages and their standard equivalents that came up for me recently when auditing bundle bloat in applications:

Code review

Have we actually looked at the source of the module and verified that it does what it says? Does have tests asserting its behavior works as advertised, or has it been thrown together without concern?

We should actually read the code. Maybe it’s great, but maybe it’s also fundamentally flawed and we might pick that up by reading the code. Or just maybe we realize that it’s simple and we could have written this ourselves…

What am I forgetting and what considerations do you make when pulling in new third party packages? Or did you forget to think through any of that today?

• There are files right there that never get used. Why aren’t you deleting them?
• Why did you just comment out that big block of code you’re never going to use again instead of deleting it?
• Why do you keep including that unused dependency in your package.json?

One of the responses I got was that changing something you don’t know carries too much risk that you don’t have time to deal with if it goes awry:

often the risk of changing unknowns is higher than the benefit. Maybe that dep does something and removing it will cause a build incident that’ll take a week to address.

– @kpk@macaw.social

Think of the same situation a little differently:

When you moved into your office, there were a pile of neatly folded towels in the corner of the room. You and all of your coworkers left them there, because you weren’t sure who was responsible and they didn’t seem to be causing a problem.

After a few months, some black mold starts spreading out from under the towels. Now you need to leave immediately, maybe go get checked up with your doctor, and have your office torn apart and the mold dealt with.

Was it really better just letting it go and not dealing with it?

Many years ago I was trying to track down a layout error on a major sign in page. There was a random CSS class name being applied to a form element and some stylesheet getting added to the document <head /> – the class name did not exist in any form within our codebase. How was this possible?

As it turns out, someone had added a Ruby gem a couple of years prior. The mere existence of this gem caused various side effects to form fields that went completely unnoticed for over a year. I’m sure there was a good reason it was added initially, but it no longer served a purpose other than the fact that it broke our layouts.

It took me about 3 days to track this down and less than a minute to remove the dependency. I wish I could get those 3 days back.

Let’s be honest, you’re not going to leave a pile of towels sitting around for no reason in an office. They don’t belong there. Just as well, you should not be leaving dependencies sitting around if they don’t serve a real, tested, obvious, or documented purpose.

The lesson is, if you spot a mess in code and dependencies, you’re better off cleaning it up now, lest it fester and cause bigger issues later.

People choose React, Angular, Vue, etc because they are easier for the developer and they make sense in order to accomplish professional and company goals. They are making a tradeoff for on perf (for example) in order to actually work faster. On the company’s dollar, web components are more expensive.

In my experience, Web Components really had a few big pieces that made them completely unapproachable:

• Testability

  If you wanted to test your web components, you needed to have a full browser environment to run the tests. While this is no longer the case, there was a huge burden initially to be able to actually make an application. It took until 2019 for Happy-DOM to come on the scene and not until 2020 for JSDOM to have support. That’s at least 4 years too late to even think about competing with other frameworks.

• Lack of unified frameworks

  How do you build Web Components? Well the short answer is you just write them according to spec. The long answer is that you probably use a framework that’s meant for building components. There are a few, so choose wisely. But that’s just the individual component level. Most developers are not just building piecemeal things and sharing them around – they’re paid to build applications.

  Say you want to build an application. Let’s ignore the Single page application (SPA) vs Multi-page application (MPA) argument for a moment. Even just building an MPA, you were on your own to write build tooling, integrations, and everything in-between.

  There are some out there, but I honestly can’t figure out where and/or how. I think you could maybe just use WebPack/Parcel/Vite? Maybe web components work in any framework, but apparently it can be a lot of work.

• Cross-component state management

  Honestly, I don’t know – you’re probably on your own here. This just goes straight back to the previous point about lack of unified frameworks.

• Three languages in one

  I thought CSS-in-JS was such a bad thing? That’s what all the purists told me. Well now we’ve got CSS-in-JS and HTML-in-JS and now my editor needs to support three syntax highlighters in every file and I need to hope my string templates all compile correctly.

  import { html, css, LitElement } from 'lit';
  import { customElement, property } from 'lit/decorators.js';
  
  @customElement('simple-greeting')
  export class SimpleGreeting extends LitElement {
    static styles = css`
      p {
        color: blue;
      }
    `;
  
    @property()
    name = 'Somebody';
  
    render() {
      return html`<p>Hello, ${this.name}!</p>`;
    }
  }
  

• Purists…

  Speaking of those same purists that yell about CSS-in-JS being bad, they are the biggest thing that has put me off of Web Components.

  The people who I refer to as “purists” that keep shouting about how we’re all wrong for using something else. I get it, Web Components probably are the better choice for the browser, performance, and end user when it is all said and done. But you’re the ones that created this stuff in a void – have you ever had to build a web application and maintain it for at least 5 years? Probably not since before 2010. Things were different then.

  Just go build stuff and be proud of it. Stop shouting at me that I’m terrible for trying to get my job done.

Let’s imagine that I want to get start on Web Components today.

1. Go to WebComponents.org. The homepage is basically just a random list of featured components that I could import. Okay neat, but I want to write an application, so let me continue on.

2. There’s no “Documentation” or “Docs” page. Where do I go?

3. Oh, I see an “Introduction” link. This must be the start of the docs

4. Uh-oh, this is just a link to specifications for Custom Elements, Shadow DOM, ES Modules, and HTML template elements.

   I’ll be back in a couple weeks after I read all of these.

5. Oh wait, there still isn’t a recommended way to actually build and application, just individual components.

   Guess I’ll just go build one myself.

   Just kidding, I’m just not even going to try.

1. Usage of Axios declines or goes EOL

   Axios was the original on promise-based XHRs for the web. However, fetch is now standard and well supported. It’s different enough from Axios Savings: 7-11kB, depending on if you need the fetch polyfill.

   I originally posted this quick hot take about Axios on Mastodon and was surprised that I wasn’t bombarded with hate. Maybe this is the year!

2. Successful use of the Node.js Test Runner

   This is definitely a new one, but it ticks almost all of the boxes for testing, and as a standard library! The only downside is for those using TypeScript and/or needing any sort of runtime. Although using a node loader/register may be enough, as I tested this out and it seemed to work nicely:

   > node --loader esbuild-register/loader -r esbuild-register --test src/foo.test.ts
   
   TAP version 13
   # Subtest: project/src/foo.test.ts
   ok 1 - project/src/foo.test.ts
     ---
     duration_ms: 274.373517
     ...
   1..1
   # tests 1
   # pass 1
   # fail 0
   # cancelled 0
   # skipped 0
   # todo 0
   # duration_ms 276.471144
   

   Now I guess we will just need some pretty-printing tools and reporters.

3. Less divisive stances on CSS solutions

   I like Tailwindcss. It’s not perfect, but it works very well. I also like some other CSS frameworks and CSS-in-JS solutions. I also don’t like quite a good many of them as well, but you won’t see me throwing hate about them.

4. Less venture capital backed open source

   We all love free open source software. But when VCs get involved, it means they expect a huge monetary return. These things just don’t go together.

5. Decline of weak Eslint rules and configs

   I’m actually a huge fan of linters – but only those that either 1) rewrite for you or 2) give errors for actual problematic code and patterns.

   Stop defaulting to report warnings and remove any rules that are stylistic choices in favor of Prettier¹.

6. React either gets it’s crap together or gets out of the way

   Okay, this is my hot take. Please bear with me as I write this with the best intentions of hoping that React can succeed.

   I’ve been on-board with React for the greater part of a decade. I’ve been a part of teams that have helped shaped the ecosystem, the patterns, and the anti-patterns. Now in 2023, React is the defacto tool for building most new websites. I will also still be using React and leading teams using it for the foreseeable future.

   And the React Core Team are making a mess of it all.

   The React Core Team initially moved fast and gave us amazing results one after another, but now they’re struggling to ship anything at all.

   • Current documentation is out of date and missing many best practices. The beta docs were announced more than two years ago, with a promise of fixing this issue, but have not been fully deployed as the main source of truth. As of writing this post, they are listed as ~99% complete.

   • Remember how long it took to get Suspense? Or Fibers?

   • They shipped useCallback, then kept telling us we shouldn’t be using it. Then took over three years to realize their mistake and year to correct their mistake and get the useEvent hook considered, but four more months to give up and decide on another direction. That was four months ago from writing this post. The future is uncertain.

   • The virtual DOM is slow, and other projects² know this. React has made no intention to change course.

   • SSR with hooks? They just gave up and took years to try to figure out server components. Is that even ready, or is it only a Next.js thing? This author can’t even keep track anymore.

   🔥 So here’s my hot take: React is suffering from slow technical leadership, no clear vision, and inability to ship. But more importantly that it, like every JS framework has shown, will not stay on top forever. The ecosystem is too fragmented. Everyone claims they can do it better and writes their own framework instead of contributing to a single one, and now we’re all eyeing the hot new thing and ignoring the elephant in the room that we are still actually working with.

   The latter part of my previous take is not React’s fault, but React could be the solution to it, if they got their act together on the issues they’re creating.

I got an email last week spouting nonsense about how my organization is going to require that all meetings start at 5-minutes after (e.g. 12:05 or 12:35) to help everyone be more on time. Listen, that’s just dumb. A change in what time meetings start does not change peoples’ behaviors and this is a smoke & mirrors non-solution to bigger issues with your meetings.

What does change meeting behavior is actually changing behavior. I’m a bit of a stickler about meetings. If I can, I like to instill a healthy meeting culture in teams I work with to make them understandable, helpful, and on-time. Not all meetings are bad, but I have some rules that I like to follow to ensure that they don’t become that way.

Keep in mind that I’m in no way an expert, but I’ve been in my fair share of meetings for nearly 20 years. This list of tidbits is from personal experience of what I’ve seen has worked and what hasn’t.

General meetings

• Stay on schedule and end early.

  I get the intention of the “5-minute after” starts, but it’s just a silly time to start meetings. Instead of starting late, schedule “short meetings”, eg 25- or 50-minute meetings only.

• Include an agenda with your meeting invitation.

  Agendas must include a desired outcome of the meeting. If you don’t yet know what that is, you’re not ready to have a meeting. An agenda also helps invitees understand whether it is important to attend the meeting or not – they may also already have a resolution for you and can reach out with it, making the whole meeting unnecessary in the first place.

• Put a pin in off-topic discussions.

  You probably see it often – you’ve got six people in a room and two start going off on a tangentially related problem and start solving that, even though it is not related to your agenda.

  Politely interrupt, recognize that importance of the discussion, but remind the group of the purpose of this meeting and ask if it can be revisited either after the primary agenda item has been resolved or moved to another discussion time.

• Recap the resolution in an email.

  Full meeting notes tend to be a waste of effort, and prevent the note-taker from participating in discussion. However, the meeting organizer should recap the resolution and share it with attendees and those that were unable to make the meeting. This helps both for future reference and for fact checking to double check that everyone left the meeting with the same understanding.

  Alternatively, any action items could be created as tasks or issues and prioritized on scrum/kanban boards.

  A recap can also be an unnecessary step. Use your best judgement here.

• It’s okay to decline meetings.

  Declining meetings is hard and scary – especially for those in a more junior position. I’m not advocating for just constantly declining meetings because you hate them, but rather, knowing when it is okay to decline a meeting and providing context to the organizer.

  If you’re invited to a lot of meetings (with many attendees) and find the information is rarely useful to your position and duties, you probably don’t need to be there. Decline the meeting and ask that if your presence is necessary, that the organizer reach back out.

  Or if you have something to work on that you know is more important and timely than the meeting, because you’ve seen the agenda ahead. Don’t say “maybe” – just decline, let the organizer know that you have other priorities right now, and suggest a better day and time.

• Meeting notes are rarely helpful.

  For general meetings, notes are not all that helpful. Instead, consider sending a short recap email with any resolutions (see previous point on recaps)

  On the other hand, meeting types that I have seen notes be helpful afterwards are those that have historical importance, like post-mortems.

  If the content of a meeting would otherwise be helpful for those who are not able to participate, a recording is much more helpful, as nothing will be missed, visual aids will be intact, and all participant’s voices will be included.

1-on-1s

From the senior, lead, or manager side

• Always be on time and avoid rescheduling.

  1-on-1s are less importantant to the leader side of the meeting, since typically you will have multiple of these with various people on the team and be able to get a bird’s eye view from there, so it can be tempting to brush off a 1-on-1 with some individuals in favor of other meetings or tasks, but remember that your report likely only has one of these every week or two. This is their time to have your undivided attention; breaking the schedule interrupts their flow and could signal feelings of lacking importance in your eyes.

• Set expectations up front.

  You likely have a standing agenda of what you’re looking to get out of having 1-on-1s with your reports or team. You should be clear with each person what you’re looking for and also make it clear that this comes secondary to their needs and goals. During your first 1-on-1, find out what it is each person is looking to get out of their time with you.

• Meeting notes are helpful!

  For other meetings, I tend to shy away from requiring meeting notes. For 1-on-1s, however, they can be incredibly helpful. These notes should not be a long detailed list, but a bullet point or two about progress, what’s next, and what we’re thinking about long-term. That’s all. These notes can be helpful for both parties to see progression over time.

  When I’m leading 1-on-1s, I scribble things into a notebook during the conversation (because typing is distracting) and then move them to a shared doc immediately after the meeting.

• Feedback is a gift.

  Each of these meetings should include an exchange of feedback and it is your responsibility to ensure this happens. Start by offering something that the other person is doing well. Explain how they’re impacting the others, the team, the product, etc and ensure they know it is appreciated and to keep it up. I like to finish the meetings with bringing up something that is not going well, but focusing on what can be done to turn that around into positive feedback next time.

  But remember, your 1-on-1s are not a 1-way street! It may be hard to get unfiltered feedback from everyone, but continue to ask. Ensure others know that your most important work is helping them and the best way for you to know how to do that is to know what you’re doing well and what you can do differently or better.

From the more junior or IC-side

• Plan ahead.

  The agenda for your 1-on-1 should be set by you. Every day that you have a 1-on-1 with a manager or team lead, spend 15 minutes (maybe when you just sit down at the beginning of the day) to jot down a couple of bullet points for an agenda.

  If you’re meeting with a technical leader, this is a great chance to do a short code pairing session, get an in-person review, or have them walk through their work for you.

• Ask for feedback.

  You should never be leaving a 1-on-1 without some actionable feedback, both positive and negative. Praise is wonderfule and it is great to help understand what you’re doing that is going well, but walk out of this meeting by focusing on how to turn the negative feedback around. If it’s unclear what you can do to do better, ask!

• The benefits of these meetings are up to you.

  1-on-1s are your time to have your manager/lead’s undivided attention. What do you want to get out of this time with them? Let them know regularly how things are going and what you feel like you’re missing out on or need to help step up your game.

  Lastly, don’t decline these meetings. Your manager/lead may have important timely feedback that is best given in person, with context.

Parting thoughts

This post actually started out sounding like I was going to rant about how poor meeting culture can be in many organizations, but ended up spurring me to be a little more positive. I hope that something in here is useful for making meetings better and more useful.

I’ve been thinking back to my time as a core member of the original team that built the Twitter web app. I learned a great many lessons there and thinking through them: How would I rebuild something similar to the Twitter web app today, like a Mastodon or Activity Pub web client?

No React Native for Web

We used React Native for Web (RNW) and I have been bullish on its benefits for years. It served me – and us — very well. In fact, its creator was our team’s tech lead for the first few years until he left to join the React core team. While we got a lot out of RNW, we didn’t get any benefit out of the core selling point: cross-platform components. The native apps are highly optimized, do not, and will not use React Native. Without going into too much detail, I’ll just say it is not a battle to even try to fight.

Just as well, web developers tended to have a lot of issues with RNW. Not directly, just that it wasn’t very ergonomic and took too much time to understand. While RNW (and React Native, for that matter) are moving to better direct web compatibility by accepting more web-native styles and props like aria-*= (instead of accessiblity*=), it’s still a bit too much of a shift and frankly the library is falling behind.

For the most part now, all RNW is getting the team now is default styling, automatic LTR/RTL text direction swapping, and some performance help under the hood. None of which aren’t easily handled otherwise.

And while RNW is not a hit on performance directly, pseudo-selectors and interactivity must be handled through React hooks, even just for simple style changes on hover or focus. This does actually translate to an interactivity performance issue.

Choosing Flow over TypeScript

Back in about 2016, typing JavaScript was still coming into the scene. At Twitter, we were evaluating both TypeScript and Flow. We wanted to add type-safety because it was too easy to accidentally miss required props across components that ensured ads were attributed as such. Without that information, Twitter wouldn’t get paid. The fact is, it happened and we lost out on a lot of money across a few days.

We ended up choosing Flow because:

• We had many Babel plugins we needed to use and Babel was not TypeScript-compatible. Switching to TypeScript would mean using tsc and ts-loader with Webpack and we would have to rewrite our entire compilation setup and change any Babel plugins into Webpack plugins. This would have been a huge undertaking.
• React was written using Flow and thus was poised to be a better support model.
• TypeScript either did not have a strict-enough mode in it. There were too many examples at the time that would just pass through, despite best intentions by developers to produce strictness.
• TypeScript was slow across large codebases.
  • Flow as fast. We were able to get checking across an entire monorepo with about 10,000 Flow-typed files to run in about 20 seconds.

Flow ended up being a mistake because:

• Adoption lagged. While we jumped on Flow, everyone else started jumping to TypeScript.
• The core team at Facebook changed directions multiple times and eventually stated publicly that they didn’t really intend to continue interfacing with the open source community, but would continue publishing releases.

Unfortunately, before we realized that TypeScript was taking over and would have been a better choice, we were somewhere like 75-85% Flow coverage. Interop between Flow and TS is not possible and so another slow migration over to TS would not be possible.

Lesson for type safety

I’m not sure that at the time we could have seen it coming that Flow would essentially be dead for anyone external to Facebook/Meta. Next time something like this comes up, I will try to do more due-diligence in checking with the open source teams in understanding their roadmap as well as watch the community’s traction more closely. I would also try to make sure we have an ejection plan if things go sour with the choice we make.

Using a multi-language monorepo

This has actually happened multiple times. The first was at Twitter, which historically had a single “source” repo. Everything was in this repo: from Scala, Python, Ruby, some PHP, and yes, JavaScript. While there was a team dedicated to ensuring that the CI pipelines and tooling were all fast, JavaScript teams were small and spread, without much agreement on stacks. Because of that, the DX team prioritized Scala over anything else. While things “worked” for JavaScript projects, everything was unacceptably slow or poorly linked (eg, 30-60 seconds to switch git branches locally and 30+ minute pull-request CI runs).

After many months of planning, campaigning, and meetings with the DX team, I was able to get my team to build our own monorepo that was for meant for JavaScript only. The results were staggeringly awesome. We were able to cut the amount of time developers in our codebases wasted just waiting around for slow process by about 2 hours per developer per week. Across about 75 contributors weekly, this was a very material gain. On top of that, I received quite a number of kind words of appreciation and happiness for this work 💙.

The second time I made the mistake of using a multi-language repository was at Microsoft for Startups. While our tech stack was small across just Python and Node/JavaScript, it was still really troublesome to feel confident and safe with changes across the different languages. Because of the weak connection between the two stacks, changes needed to be tested carefully and it was always confusing what command you ran to check each individual piece.

Lesson for monorepos

My lesson for Monorepos is that they are actually good, but they only scale as long as you’re using a single language and every workspace internally has some connection to the same graph. As soon as you have a workspace or project that doesn’t use any of the same stack, tools, or language, a new repo is likely the best course forward.

Flash of inAccurate coloR Themes¹, or FART, as coined by Chris Coyier is the fancy acronym visit a website and it quickly flashes from one color theme to another. This is most prominent for those that prefer dark mode and see pages render in light mode for a split second, then flipping over to the dark variant. It’s minor, yes, but also super annoying to anyone with a slightly slower connection, as the time at which the theme will switch to dark is dependent on the speed that the JavaScript can download and execute.

I came across a post by Jason Lengstorf about avoiding the FART by using Netlify’s new Edge Functions. Lucky me, I’m using Netlify and a statically-built site, so I figured this would be a great approach for me.

Except there was a big issue.

Many theme pickers, including the example I was following, allow picking one theme and then sticking to it. While it’s kind to provide a choice, most theme pickers miss out on providing an option for their own system to choose for them. This is handled by the CSS media query prefers-color-scheme.

Tailwindcss, which I’m using, allows a one-or-the-other approach as well. By default it uses the prefers-color-scheme approach. Alternatively, you can change it to darkMode: 'class' to control it yourself.

I originally wanted to avoid using any sort of server-side code for my site, but getting around the FART is not possible without some level of server-side processing.

In this post, I’ll walk through how I got rid of the flash of inaccurate color themes for Tailwindcss dark mode, building upon Jason’s work to add “auto” theme support using HTTP client hints and media queries.

Theme switcher component

I’m going to skip over most of my theme switch toggle button code, as mine is in Solid-js and may look a little funky if you’re used to React.

However, here are the important bits of the theme switcher, translated into React:

First, in order to manually control the light and dark mode themes with Tailwindcss, we need toset darkMode: 'class' in our configuration:

module.exports = {
  content: ['src/**/*.{astro,md,mdx,tsx,ts}'],
  darkMode: 'class',
};

To save our theme and whether or not auto-selection is preferred, we can use a basic fetch call with URLSearchParams. Nothing too special is necessary here:

function saveTheme(theme: Theme, auto: boolean) {
  const params = new URLSearchParams({ theme, auto: auto ? 'true' : 'false' });
  fetch(`/api/theme/?${params.toString()}`);
}

Then, in our <ThemeSwitcher />, we need to create an effect that runs any time our theme or auto modes have changed and call our API. Note that I’m also tracking the source of truth for “auto” mode with a data attribute attached to the <html> element.

Here’s an example effect in React. Take special note of the highlighted lines regarding the “auto” mode:

export function ThemeSwitcher() {
  const [theme, setTheme] = React.useState(document.documentElement.classList.contains('dark') ? 'dark' : 'light');
  const [auto, setAuto] = React.useState(document.documentElement.dataset.autoTheme === 'true');

  React.useEffect(() => {
    document.documentElement.dataset.autoTheme = auto ? 'true' : 'false';

    if (theme === 'dark') {
      document.documentElement.classList.add('dark');
    } else {
      document.documentElement.classList.remove('dark');
    }

    save(theme, auto);
  }, [theme, auto]);

  // ...
  // there’s more needed here, this is just for demonstration purposes
  // ...
}

This results in our first two steps:

1. The theme is tracked on the <html> element, using the className and data- attribute: <html class="dark" data-auto-theme="true">
2. Our API (which we’ll cover later) is called every time the user setting changes manually.

Prefers color scheme media query

Now that the basic plumbing is set up and we have manual tracking, we need to make sure that when theme switching is set to “auto” mode that we start respecting the prefers-color-scheme media query using the matchMedia API.

Follow the comments inline for any needed explanations.

React.useEffect(() => {
  if (!auto) {
    // do nothing if not in auto mode.
    return;
  }

  // On change to auto-mode, set the theme based on the current media query preference
  const isDark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
  setTheme(isDark ? 'dark' : 'light');

  // Add an event listener any time the device requests a change to the color scheme
  function listener(event: MediaQueryListEvent) {
    setTheme(event.matches ? 'dark' : 'light');
  }
  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', listener);

  // Return a cleanup function when unloading so we stop listening to the media change
  return () => {
    window.matchMedia('(prefers-color-scheme: dark)').removeEventListener('change', listener);
  };
}, [auto]);

That should be it for our theme switcher. Your implementation is really up to you; whether you’re using a dropdown, button, or some other UI is up to you. I’m going to gloss over all of that in favor of getting into the trickier parts of this article. If you’d like an example, you can always check out my Solid-js implementation: ThemeSwitcher.tsx.

Edge functions

As mentioned previously, we’re going to use Netlify’s Edge Functions to handle the server-side portion of our requests.

API endpoint

First, let’s write our little cookie-setting API as a Netlify Edge Function. To start accepting calls to a URL, edit the Netlify config and add an edge_functions declaration. In my case, I put the pathname as /api/theme/ and I’ll place the code in netlify/edge-functions/set-theme.ts:

[[edge_functions]]
	path = "/api/theme/*"
	function = "set-theme"

Now that we have declared our endpoint, let’s actually write it to save the user’s theme choice as a server-side secure cookie:

import type { Context } from 'https://edge.netlify.com/';

export default async (req: Request, context: Context) => {
  const url = new URL(req.url);
  const params = url.searchParams;

  // Set a server-side secure cookie with the requested URL search params
  context.cookies.set({
    name: 'theme',
    value: params.toString(),
    path: '/',
    secure: true,
    httpOnly: true,
    sameSite: 'Strict',
    // Set a *REALLY* big expires value
    expires: new Date(Date.now() + 2_592_000_000),
  });

  // Respond with a success JSON payload
  return new Response(JSON.stringify({ error: false }), {
    status: 200,
    headers: {
      'content-type': 'application/json',
    },
  });
};

Well, astute reader… did you notice that I didn’t add any error handling here? Technically, someone could try to set any theme they want, even if it were invalid.

Let’s make sure we handle that both if a theme setting is not sent and if the theme is invalid:

import type { Context } from 'https://edge.netlify.com/';

const themes = ['light', 'dark'] as const;

export default async (req: Request, context: Context) => {
  const url = new URL(req.url);
  const params = url.searchParams;

  // Didn't include a default or fallback theme
  if (!params.has('theme')) {
    return new Response(JSON.stringify({ error: 'Missing theme parameter' }), {
      status: 400,
      headers: {
        'content-type': 'application/json',
      },
    });
  }

  const theme = params.get('theme') as (typeof themes)[number];
  const auto = params.get('auto') === 'true';

  // Sent a theme that's not valid for our site?
  if (!themes.includes(theme)) {
    return new Response(JSON.stringify({ error: `Invalid theme: ${theme}` }), {
      status: 400,
      headers: {
        'content-type': 'application/json',
      },
    });
  }

  context.cookies.set({
    name: 'theme',
    value: params.toString(),
    path: '/',
    secure: true,
    httpOnly: true,
    sameSite: 'Strict',
    expires: new Date(Date.now() + 2_592_000_000),
  });

  return new Response(JSON.stringify({ error: false }), {
    status: 200,
    headers: {
      'content-type': 'application/json',
    },
  });
};

Rewriting static HTML responses

Next, again, we’ll take a hint from our inspiration article and rewrite part of our HTML responses for the static-generated multi-page site using Edge Functions. However, this is where we start deviating a lot more:

Accepting Client Hint headers

Since we want to be able to allow users to select an “auto” select for the “light” or “dark” mode, we need a way for the browser to tell us ahead of time what it actually wants on page load. In comes a new standard, Client Hint Headers.

Client hints are a newer set of HTTP request headers that enable a server to request more information from a browser about the device, network, user, and user-agent specific preferences. In particular, we’re interested in the prefers-color-scheme client hint, which will instruct browsers to send back to our server the same data that would normally only be available in CSS media queries.

To get started accepting Client Headers, we need our HTTP responses to add an accept-ch header with each hint that we’re asking for. Since we only need one, this is fairly short to add to the Netlify _headers file:

/*
	accept-ch: sec-ch-prefers-color-scheme

Now that we’re requesting the client hints, we need to actually do something with them. First, let’s start with a barebones edge function that merely:

import type { Context } from 'https://edge.netlify.com/';
import { HTMLRewriter, Element } from 'https://ghuc.cc/worker-tools/html-rewriter/index.ts';

export default async (req: Request, context: Context) => {
  // Get the default response for this URL. This will grab the actual response as if we were not running this function
  const res = await context.next();

  // Check the content type. If we're not serving HTML, running the rest of this function will be a waste of compute time and power
  const type = res.headers.get('content-type');
  if (!type?.startsWith('text/html')) {
    return;
  }

  return res;
};

Next, we need to try to read the cookie and fall back on a default value if it’s not available. Using nullish-coalescing, we can make this fairly simple:

const rawCookie = context.cookies.get(COOKIE_NAME) ?? 'auto=true&theme=light';
const params = new URLSearchParams(rawCookie);
const isAuto = params.get('auto') === 'true';
const theme = params.get('theme') || 'light';

But the whole point of the auto setting on our theme switcher is that we want to read from the prefers-color-scheme client hint. So we’ll modify this block just a smidge to read the header and if the cookie states that auto-mode is preferred, we’ll use the header value if it’s available!

const prefers = req.headers.get('sec-ch-prefers-color-scheme');
const rawCookie = context.cookies.get(COOKIE_NAME) ?? 'auto=true&theme=light';
const params = new URLSearchParams(rawCookie);
const isAuto = params.get('auto') === 'true';
const theme = isAuto && prefers ? prefers : params.get('theme') || 'light';

Lastly, just like in the inspiration from “Learn with Jason”, we’ll use the HTMLRewriter and update the className and data-auto-theme attributes on our <html> element. All-together, our function looks like this:

import type { Context } from 'https://edge.netlify.com/';
import { HTMLRewriter, Element } from 'https://ghuc.cc/worker-tools/html-rewriter/index.ts';

export default async (req: Request, context: Context) => {
  const res = await context.next();
  const type = res.headers.get('content-type');
  if (!type?.startsWith('text/html')) {
    return;
  }

  const prefers = req.headers.get('sec-ch-prefers-color-scheme');
  const rawCookie = context.cookies.get('theme') ?? 'auto=true&theme=light';
  const params = new URLSearchParams(rawCookie);
  const isAuto = params.get('auto') === 'true';
  const theme = isAuto && prefers ? prefers : params.get('theme') || 'light';

  return new HTMLRewriter()
    .on('html', {
      element(element: Element) {
        const original = element.getAttribute('class') || false;
        element.setAttribute('class', [original, theme].filter(Boolean).join(' '));
        element.setAttribute('data-auto-theme', isAuto ? 'true' : 'false');
      },
    })
    .transform(res);
};

Now we actually need to enable the edge function. In our netlify.toml, like we did before for the set-theme function³:

[[edge_functions]]
  path = "/*"
  function = "theme"

And that’s it! You can try it out on the page that you’re currently reading! Just click the theme switcher button in the site header to something different, reload or browse around the site and be amazed as there is no more FART on a statically generated HTML site!

Downsides

First and foremost: Client Hints are still considered “experimental” and only available in Chromium-based browsers. For anyone not using one of those, the auto-theme selection won’t work and the theme setting edge function will fall back on the last known theme value per the cookie. That fallback should be mostly okay, but still a bummer.

Secondly, Client Hints are not provided by the browser to the server on first load. While there are ongoing discussions about allowing this to happen, there are technical challenges in making browsers first check which hints are being requested in order to send them. All this means that the even if you’re using a browser that supports Client Hints, your first page load to the site will always have a FART.

We could work around that by forcing a redirect/reload on first load, but that would require quite a bit of extra work that is frankly not worth the effort.

Updates

I’ve made some changes to how things are done since originally posting this. Hopefully I’ll remember to keep things up to date:

• 2022-12-04: Switched the theme tracking from the body element to the documentElement/html element. This fixes an issue in some mobile browsers where they showed a white background at the bottom of a full-page scroll by moving the background color classNames up from a wrapping div element and onto the body element – then moving the dark className up to the html element.

However, I’ve just come across a major company’s design system that does not use border-box across all elements. And worse, if I try to set that manually for myself, the reusable components that they’ve exposed will all break. Why? Why would do this to me?

html {
  box-sizing: border-box;
}
*,
*:before,
*:after {
  box-sizing: inherit;
}

Please just add that as your default and never revert back.

I built my website with Astro, without having intended to. I often use my own personal site as a test-bed for learning new frameworks and tech. In testing out Astro, it just sort of stuck. As I continued, it became clear why – but the reason may be surprising.

The current headline on the Astro.build home page is “Build faster websites.” This was a big selling point, initially, in getting me to try Astro. When building a static website, there’s not a lot of point in sending large frameworks (like React) over the wire – even for server-generated content, really. While this is one of my main requirements, it’s not the reason I’ve found to stick with Astro.

Astro also uses Vite for development and building. It’s a nice bonus how fast the site runs in dev and builds for production. But again, it’s not why Astro is best for me now.

The real icing on the cake comes from two parts of Astro combined:

1. Astro Islands

   Statically generated content getting hydrated as minimal islands for small interactive pieces of the UI is just what I found I ended up needing over time. While I could have done dark & light mode for the site automatically chosen by the prefers-color-scheme CSS media query, I wanted to be able to manually toggle modes as well – and who knows, maybe one day I’ll add a third or more other themes. This type of thing requires JavaScript.

2. Astro integrations

   Now here’s the kicker. I wanted to use Astro Islands, but I didn’t want to have to load all of React in order to get it done. I went with SolidJS for the main interactive bits of the site. At the moment there are 3: the theme switcher, the “scroll to top” button that appears on longer pages when scrolling, and the “share widget” at the bottom of every blog post.

But wait! There’s more! It isn’t just that I could use one framework (an integration) for islands. The fact is that where I want it, I can use any framework. I’ve started a labs section of the site using just that!

There’s only one item there so far, but I’m so excited about how it turned out, that I wanted to boast about Astro and the fact that I have a super fast, statically generated, multi-page site that allows me to use almost any tech without worry about bleeding JS libraries across pages.

Open up your network inspector as you browse across my site and you can see for yourself how the page weight is as minimal as possible from one page to another:

Want to see how this is all built? My website’s code is available for browsing on Github at paularmstrong/paularmstrong.dev!

It is odd to feel this way, I admit. But with Twitter’s new management, I feel like I’m mourning the loss of something that was near and dear to me. Not just because I worked there and poured a lot of my care and creativity into every day, but because I’m losing something that has in part gotten me to where I am today.

I have an account so old that it has an numeric, incremental ID number attached to it. I was the 766,247^th account signed up on Twitter. I used the platform as a way to connect with my peers, to make friends, to learn.

Twitter has been a part of my life for sixteen years. I’ve been letting that thought sink in and wondering if it will continue to be a place that I frequent, that I learn from, and that I socialize on.

And that’s just it: Twitter was an actual socialization and networking tool for me. My timeline was free of trolls, bigots, spam, and all the negative sides that many others saw. I carefully curated what I wanted to see and learn about over just shy of 16 years. It helped me get to know a few people, to share my work and creativity with the world.

I have truly loved it as a platform.

I don’t want to quit it. But I also don’t want to support what it has and is becoming.

Previously, I wrote about how I created a DIY Photobooth for my wedding reception and the results were amazing. Now we can get to the choices, technical details, and hurdles I went through writing the Photo Booth application. You might consider this a post-mortem tech design.

High-level plan

My general plan was to create a full DIY photo booth for my wedding and spend as little money as possible. The photo booth would need the following features:

• Take a number of photos in succession and stitch them together as a collage.
• Upload the final photo collages to a Firebase storage bucket immediately after creation.
• Record video messages, up to 30 seconds, as an alternative to a guest book.
• Be easy to use: both cognitively and physically.

Design choices

Electron application

Most software developers would instantly judge that a native application would be the best choice to build a Photo Booth. And really, they’re probably right. A native application would likely give the speed and stability you want from something incredibly interactive that that needs to work with large images and videos.

That being said, I decided to use Electron for two reasons:

1. I didn’t have the time to spend re-learning native app development.
2. I really wanted to have a reason to learn and use the MediaStream & MediaRecorder web APIs and x-state as a full-blown state-machine.

So, while Electron is not the best choice, it’s still a choice that worked and there’s nothing wrong with that.

Webcam

In a best-case scenario, I would hook up a DSLR camera through an HDMI capture card and run it as a webcam to get the best quality images out of any photo taken through the MediaStream API. Unfortunately, I didn’t want to jump into buying an HDMI capture card and I also wanted to keep my DSLR handy for other purposes. Otherwise, I’d need to buy both another DSLR and capture card. That would quickly blow up the budget (and then some) on this project.

So we’re stuck using a webcams, but unfortunately, webcams are notoriously crappy. Most are 720p and the ones that say they are 1080p have poor sensors that don’t process light well and make your images come out pretty grainy. Even the “top end” webcams are not without their issues.

However, GoPros can also be used as webcams now, given that you have the GoPro Webcam app installed. Well guess what, I just happen to have a GoPro Hero 10 that can do this.

While still running at a maximum of 1080p, the images from the GoPro over the MediaStream API come out crisp, clear, bright, and all-around better than good enough!

User interaction

Assuming I would not have access to a large touch-screen, I already owned an Elgato Stream Deck Mini. I could use the 6 buttons on here as an interactive user interface for navigating menus and options.

Execution

Electron

Finding the right path to get started with Electron using modern Javascript (or TypeScript) and frameworks that require build tooling took longer than I would have liked. Similar to trying to figure out what is needed to just set up a website built with JS these days, Electron was just as bad or worse.

I stepped in thinking it would just be built-in that webpack would build my application with some useful defaults. Unfortunately, there really isn’t any build tooling to be found out of the box other than compiling to a runnable application.

I first tried electron-vite, wanting the new hotness of building esmodules, thinking it’d make things faster to iterate. Unfortunately, I quickly hit the limitations of that when pulling in the @elgato-stream-deck/node package, as it requires linking to a native dependency, which I couldn’t figure out how to do with Vite, but am well familiar with it in webpack. (If anyone knows, please reach out and point me in the right direction!)

So after attempting to set up a bunch of inter-connected webpack processes myself, I thankfully gave up and replaced everything with Electron Forge. This simplified the whole setup process, allowed me to hook into the webpack module rules and add the node-loader.

After that, most of the Electron setup is pretty run-of-the-mill stuff. I tried to follow best-practices for inter-process communication between node and the client, as well as only allowing the ability to load and save to directories with the correct permissions.

My biggest criticism for Electron is that there is far too much outdate information around the web on how to do the more detailed bits with security, best practices, and even event listeners. The documentation is pretty good, but naming conventions don’t always match what I would expect, coming frmo a Node.js server and JavaScript client background.

State machine

Given the complexity of managing state across two user interfaces, the screen and the StreamDeck Mini, I wanted to ensure that both were in sync at all times. To do this, I chose to build a full state machine (main/src/state/machine.ts) using x-state, run by the Electron Node.js process.

This machine handles the entire state of the application: backend, frontend (GUI), and other frontend (Stream Deck). When entering any state, we assign an array of possible keys and their transition type to the machine’s context, then call the renderKeys action.

Communicating between the main and renderer process

Sending messages back and forth between the two processes is crucial for most Electron applications, since they run in separate sandboxed processes.

const service = interpret(machine);
service.start();

service.onTransition((state) => {
  const { streamdeck, ...meta } = state.context;
  webContents.send('transition', { value: state.toStrings(), meta } as TransitionData);
});

ipcMain.on('transition', (event, action) => {
  service.send(action);
});

Let’s look at what happens when taking our four photos has completed and we want to prompt the participants to select a layout for their collage. We have four layouts to choose from, so we render those to the first four buttons, then we want our “Done” action as the last, bottom-right action. So we set up our entry assign handler to assign the keys and actions:

// State snippet: photo.reviewing.selecting
{
	selecting: {
		entry: [
			assign({
				keys: () => [
					{ key: 'quad', type: 'SELECT' },
					{ key: 'quadtych', type: 'SELECT' },
					{ key: 'collage', type: 'SELECT' },
					{ key: 'random', type: 'SELECT' },
					null,
					{ key: 'done', type: 'DONE', description: 'Save your collage' },
				],
			}),
			'renderKeys',
		],
	},
}

Then our renderKeys action is immediately fired and renders the defined images to each key, clearing out null (blank) keys along the way.

{
	actions: {
		renderKeys: async (context) => {
			const { keys, streamdeck } = context;

			for (let i = 0; i < keys.length; i++) {
				const { key } = keys[i] || {};
				if (!key) {
					streamdeck.clearKey(i);
					continue;
				}

				streamdeck.fillKeyBuffer(i, images[key]);
			}
		},
	}
}

One small design choice: It was inefficient to send the entire Stream Deck object into the state machine’s context and didn’t mesh well with normal patterns in x-state. However, not passing the entire Stream Deck object to the state machine’s context required a bit of digging into the state’s key context to send the correct action back into the service. Turns out that this really wasn’t too bad.

streamdeck.on('up', (keyIndex: number) => {
  const action = service.state.context.keys[keyIndex];
  if (!action) {
    return;
  }
  service.send(action);
});

Syncing state between main and renderer process

On each state transition, we also pass the state context to the renderer application and use a custom useLocation() hook to merge the state machine’s context into the React Router Location state. This then lets us extract out each key and render it to a <HelpCard /> on screen.

Since the routing and location needed to be determined by the state machine that’s run in the main node.js process, I added a new faux-context wrapper NavigationProvider, that listens to the transition event passed to the renderer process, and calls React Router’s navigate() function.

import { useLocation as useRRLocation, useNavigate } from 'react-router-dom';

export function NavigationProvider({ children }: { children: React.ReactNode }) {
  const navigate = useNavigate();

  React.useEffect(() => {
    const remove = window.api.addListener('transition', ({ value, meta }) => {
      navigate(
        {
          // Important: need to convert x-state value from an array/dot-notation to URL-compatible paths
          // eg. ['photo', 'capturing', 'photo.capturing'] -> /photo/capturing
          pathname: `/${value[value.length - 1].replace(/\./g, '/')}`,
        },
        { state: meta },
      );
    });

    return remove;
  }, []);

  return <>{children}</>;
}

Then, in order to ensure that our state object always reported to Typescript with the correct shape, I needed a custom useLocation() hook that forced the type.

import type { TransitionData } from '@pb/main';

export function useLocation() {
  const { state, ...location } = useRRLocation();
  return { state: state as TransitionData['meta'], ...location };
}

User interface

I left this detail out of the plan, because I didn’t care too much about what I ended up going with. I picked React and Tailwindcss, as I figured that’d be the least overhead in terms of familiarity – I wouldn’t need to learn something new here.

Animation

In the initial working iterations, the application still felt a bit too much like it was meant to be a web application, not eagerly loading the next view and not able to smoothly transition from one state to another. I decided that this was jarring in practice, so I explored how I could make everything feel like it was flowing, fun, and more like a “native” application.

Given that I was using Tailwindcss, CSSTransition from React Transition Group came through as an obvious choice. With it, you can easily add and remove CSS classes for various states of transitioning from one state to another. The hard part came in hooking this into react-router in order to transition from one view to another via animating the different parts of the screen.

After a bunch of trial and error, the key was to forego using react-router’s Routes (v6+) or Switch (v5) in favor of my own implementation that could pass the transition state down through to each view. This required a few parts:

First, we need a route mapping for all views that will be shown. In order for every view to receive transition state, we cannot use nested routing. So we create a routeMap

const routeMap: Record<string, React.FunctionComponent<Props>> = {
  '/photo/confirming': PhotoConfirm,
  '/photo/capturing': PhotoCapture,
  // This state may have multiple sub-states, but they are mostly invisible to the user
  '/photo/reviewing/*': PhotoSave,
  '/photo/complete': PhotoReview,
  '/video/confirming': VideoConfirm,
  '/video/recording/readying': Readying,
  // This state may have multiple sub-states, but they are mostly invisible to the user
  '/video/recording/*': VideoRecord,
  '/video/reviewing': VideoReview,
  '/main/preferences': Preferences,
  '/main/help': MainHelp,
  '/main/*': Main,
  '/setup': Startup,
};

const routes = Object.keys(routeMap).map((path) => ({ path }));

Once that’s set up, we can use the SwitchTransition and CSSTransition components from React Transition Group to handle moving from one route to another

import { HashRouter, matchRoutes } from 'react-router-dom';
import { CSSTransition, SwitchTransition } from 'react-transition-group';
import { useLocation } from './context';

function Router() {
  const location = useLocation();

  const match = React.useMemo(() => {
    const matched = matchRoutes(routes, location);
    return !matched ? null : matched[0].route;
  }, [location]);

  return (
    <SwitchTransition>
      <CSSTransition
        // ensuring match.path here should not be necessary if we had a better guarantee
        // that every route would be accounted for
        timeout={match?.path ? 250 : 0}
        key={match?.path || ''}
      >
        {(status) => {
          // Again, just in-case, so we don't crash during development
          if (!match || !match.path) {
            return null;
          }
          const Component = routeMap[match.path];
          // Important! The CSS Transition status gets sent through to be handled by
          // each individual View, since all may have their own layout and components
          // needing specific animations
          return <Component status={status} />;
        }}
      </CSSTransition>
    </SwitchTransition>
  );
}

Okay, that was a bit of setup, but not too bad. Now, for the payoff, each route’s view can accept the status property and add CSS classes for each possible transition status:

import clsx from 'clsx';

export function ExampleView({ status }: Props) {
  return (
    <div
      className={clsx({
        'opacity-0': status === 'entering' || status === 'exited' || status === 'unmounted',
        'transition-all ease-out opacity-1': status === 'entered',
        'transition-all ease-in opacity-0': status === 'exiting',
      })}
    >
      {/* content to fade in/out */}
    </div>
  );
}

In use, that became cumbersome to remember, so I ended up creating a transition() function helper. This made it easy to reuse transitions across different views and components.

import { transition } from '../modules/transition';

export function ExampleView({ status }: Props) {
  return (
    <div className={clsx('...', status ? transition(status, 'slideUp') : undefined)}>
      {/* content to slide up when entering and down when exiting */}
    </div>
  );
}

Last minute additions

After confirming that the GoPro worked as a webcam, I didn’t really leave it set up to run all of the time during development, as it was just a bit too much to have hanging around. What I didn’t realize though was that if you had multiple cameras available, eg: a laptop with a built-in camera, the GoPro would never be chosen as the default camera.

I quickly needed to add preferences to the application, so I threw together a few settings that would probably make it helpful if anyone else ever wanted to pick up the source code and repurpose it for their own party.

Result

I’m super happy with the end result. There isn’t much more to say other than it worked and it worked well – just as well as a $1,500 rental would have.

So here’s me messing around with it at home and trying to get Milo to pose with me.

Apps

• 1Password - I tried Bitwarden, hosting an open source version myself, but nothing quite works as seamlessly as 1Password. I’ll keep giving them my money until something better comes along.
• Plexamp - I have a lot of music. Many old and rare albums that just aren’t available on streaming services. And I’m continually finding and purchasing more. Plexamp gives me all the best of what a streaming service can offer, but with my music library.
• Sublime Text - I keep giving VS Code a shot, but it just tends to do too much and get in my way more than it helps. I’ll stick with Sublime Text until it either no longer works or VS Code gets better for my workflow.

Terminal

• zsh-autosuggestions - Suggests commands from your history without needing to type ⌃+R. Hit your → key to accept the suggestion, then Enter to run – or keep typing to do something else.
• Terminalizer - record terminal input/output and create GIFs and videos for sharing how-to and examples.
• Powerline - Better looking and more informative PS1 and status lines.
• tmux - terminal multiplexer

Hardware

• Logitech MX Master 3 - Get yourself a great mouse.
• Keychron K6 - Gotta have a keyboard that fits your typing style and feels great.
• CalDigit TS3 Plus - I switch between my person Mac Mini and work laptop multiple times per day. Enabling me to use the same keyboard and dual monitors (along with the Bluetooth switching on the Logitech MX Master 3), it’s almost like having a KVM that supports USB-C/Thunderbolt.
• Blue Yeti X microphone on a scissor swing-arm microphone stand - I don’t do much or any streaming anymore, but ensuring that I’m clear in video calls is wonderful.
• Ember Mug² - It’s not without flaws, but it sure is nice to have my tea kept hot while I’m working. Nothing’s worse than taking a sip and getting something lukewarm.

As teams grow, become distributed, and not everyone is able to be involved in every decision, it becomes more important to record what’s happening and why decisions are and were made. From a technical standpoint, Tech Designs are a great way to structure this information and keep around long-term for posterity.

The following is a template that I’ve used and introduced to teams I’ve worked with in the past. This template is a great starting point and not intended to be an end-all do-or-die approach, so take this more as inspiration than anything else.

Setting up Firebase

Setting up a Firebase project was actually a delightful experience.

First, create the project in the Firebase console. This step just takes a couple clicks.

After creating the project in the Firebase console, you need to hook something up to actually deploy and work with configurations from the command-line.

If you don’t have it already, install firebase-tools and log into the commandline interface:

npm install -g firebase-tools
firebase login

Once installed, we can log into firebase and initialize the database. Run the following command, select your project, and customize as you want. I didn’t change any of the defaults to get started.

firebase init firestore

Next, we are going to want hosting, because it’s free. Again, run the init and walk through the wizard.

firebase init hosting

From there, the initialization script actually walked through a few questions which didn’t seem patronizing for a wizard. Then it noticed that the origin for my git repo pointed to Github, so it asked if I wanted to set up automated Github actions to deploy on merge to main and stage deploys for PRs. Heck yes!

Parcel dev environment & bundling

Let me get one thing straight: using Parcel was the absolute most straightforward and easy dev/build framework that I’ve ever picked up. I don’t know that I needed to do anything more than point it at a root index.html file – and that was really it!

yarn add preact preact-router
yarn add --dev autoprefixer parcel postcss tailwindcss

Next we need some basic setup for Parcel, Preact, and Tailwind. Create the following files following this structure, with copypasta contents to follow:

wedding-app/
├─ src/
│  ├─ index.html
│  ├─ index.css
│  └─ index.jsx
├─ package.json
└─ tailwind.config.js

src/index.html This will be the main entrypoint for Parcel to run its development server and build for production.

<!doctype html>
<html lang="en" dir="ltr">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kelly & Paul’s wedding</title>

    // Parcel will pick up references to CSS files and compile them as necessary // This makes Tailwind setup in the
    next step a breeze
    <link rel="stylesheet" href="./index.css" />
  </head>
  <body>
    // This will be the root element that we use for the Preact application
    <div id="root"></div>
    // Parcel will pick up references to JavaScript files (or Typescript) and compile them
    <script type="module" src="./index.jsx"></script>
  </body>
</html>

./src/index.jsx

import { h, render } from 'preact';
import { App } from './App';

const root = document.getElementById('root');
render(<App />, root!);

Tailwind CSS

If you prefer a more in-depth setup, checkout Tailwindcss‘s installation guide.

./src/index.css

@tailwind base;
@tailwind components;
@tailwind utilities;

./tailwind.config.js

module.exports = {
  content: ['./src/**/*.{html,ts,tsx}'],
};

./postcssrc.json One little gotcha here: don’t forget to add a Postcss configuration for Parcel to pick up so that it knows it should be using Tailwind!

{
  "plugins": {
    "tailwindcss": {}
  }
}

That’s all!

./package.json We just need a couple quick scripts in our root package configuration in order to run the Parcel dev server and build for production

{
  "name": "wedding-app",
  "private": true,
  "scripts": {
    "start": "parcel src/index.html",
    "build": "rm -rf dist && NODE_ENV=production parcel build ./src/*.html --public-url /"
  }
}

Honestly, this was kind of everything that I needed to get started. I know this is a little nitty gritty into some weird details, but hopefully helpful for someone (or myself) down the line.

From here, we can run yarn start and see our application running in the browser immediately.

I needed an escape while stressing about my (previously) upcoming wedding. Having some personal annoyances with how difficult it would be to personalize Docusaurus, I sat down and hacked at Astro for a day and a half. I came up with a fully working static website & blog in no time.

Requirements

I had just a few requirements for my site:

• The ability to write pages and blog posts with Markdown and MDX.
  • I originally used Docusaurus because I wanted to force myself to spend more time writing than tinkering with the page. This worked, to a point, and I’d like to keep it easy to focus on writing.
• The site should be served as statically built HTML pages.
  • There really should be no need for a big backend CMS. Just write pages and push to a source control origin.
• The layout should be fully customizable.
  • This is the kicker that is moving me away from Docusaurus. While much of the framework’s built-in components can be swizzled and replaced with custom versions, much of it still cannot, and I do not feel like I have the knowledge depth to contribute.

Options

I set out looking at options:

• Docusaurus I absolutely love Docusaurus. I will continue to use it for documentation sites as the first tool I reach for. But for my personal site, it just wasn’t cutting it.
• Next.js People seem to love this. I’m still not fully convinced that the weight of the development environment and the prescriptive way of building things is best for me. I have been forcing myself to use it for a couple things, but it just isn’t clicking as the killer framework to me.
• Gatsby No. Just no. Every time I see a Gatsby site, it pulls down at least 10MB of JavaScript. Honestly, I haven’t actually tried Gatsby in a number of years, but last I did, I was turned off by the ergonomics of it. I have no idea if the anecdote about JS size is real or just a red herring.
• Eleventy Looks great, haven’t tried it. (aside: The amount of effort the eleventy documentation spends trying to convince me to use it makes me extra skeptical)
• Astro I’ve heard a lot of rave reviews. So I started with this one, just thought I was diving in.

Accidentally choosing Astro

I started just toying with Astro for building my site, and before I knew it, within just a few hours, I was mostly done building the basic framework with something that was pleasing enough to look at and work with.

Sitting back for a minute on it, I decided to just run with it. So far, it has been a pleasure to work with and has actually inspired me to really get some content written. Let’s hope it continues.

Details

Framework: Astro

As stated above, I sort of accidentally ended up going to production with Astro. I really liked how easy the plugin system is and the things the community has build:

• @astrojs/mdx
  • While I want to write with Markdown, it’s really hard to make things beautiful without some carefully crafted, reusable components. Being able to import and use them directly in Markdown is mostly a necessity now.
• @astrojs/solid
  • See Interaction: Solid-js for details.
• @astrojs/tailwind
  • See CSS: Tailwind CSS for details.
• @astrojs/image
  • I first started out manually creating multiple variants of images with webp, avif, png, and jpeg and writing the HTML by hand. That was a mistake. This plugin does it for you.
  • It definitely increases build times, but they’re still tolerable at this time. I’d love to see if this plugin could get a mode to pre-build the image variants and add them to source control.

Interaction: Solid-js

I originally thought that I wouldn’t need any interactive components, so I wasn’t going to add any React/Preact/Solid-js/etc framework.

But then I realized that I’d like a dark-mode theme switcher with the ability to use both automatic selection as well as user-defined preference.

I’ve used Solid-js for some small things before, and the small weight of the library seemed like a good choice for now. I’d like to do a comparison using Svelte, Vue, Lit, and bare web components. That’s going to be for another day, though.

CSS: Tailwind CSS

I’ve been here since CSS was first introduced. Heck, I was here using nested <table> and <imagemap> elements. CSS is great, but if there’s one thing that has really changed the way that I write CSS since CSS-in-JS, it’s Tailwind CSS.

Mostly, it’s easy, it’s predictable, and I don’t really have to think too hard to create something beautiful. Especially paired with the typography plugin – making a plain markdown post easy to read has never been more simple.

Hosting

I was originally hosting my site on Github pages, until I realized that the longest cache time set for any resource is 10 minutes. I quickly changed over to Netlify today without much fuss.

I really can’t complain after measuring using various tools and having the home page come out super fast, performant, accessible, and search optimized.

View source

Go and take a look! I have kept the code for this site open source and MIT-licensed (except for blog posts, images, and page content).

I recently got married – and as we know, weddings are expensive. Previously, I documented saving money by creating my own website and foregoing spending money on paper RSVPs. We also decided to skip paying a photographer the exorbitant extra fees to also photograph our reception, but we still wanted to have lots of memories from the event.

I’ve always loved getting in photo booths, having a bunch of laughs, and keeping the printed photos for later. But do you know how much a photobooth rental is? At least $1,500! And even then, they usually print out photos instead of providing a digital version that you can actually save and use long-term.

Well, in keeping with my theme of not spending money, but instead spending way too much time over-engineering a similar solution: I set out to build my own. And I succeeded.

Application demo

The application, which is open-sourced on Github, is built with Electron, React, Tailwindcss, and x-state. It uses browser APIs like MediaDevices, MediaStream, and MediaRecorder to record your webcam and pass the data to an HTML canvas to create collage images, as well as video recordings.

I had a script running to watch the directory where the application saved the photos. That script looked at each new image, resized, and uploaded them directly to my Firebase storage account for immediate display in a gallery on the wedding website.

The “Memory Shack”

From a physical standpoint, the photo “booth” was renamed to the “Memory Shack”. It consisted of a borrowed portable USB-C LCD screen, a 6-button StreamDeck mini (because the screen was not a touch screen), a ring light, and a GoPro running as a webcam.

All of the wood used was donated from a friend and it was all pretty warped. We did the best we could with making it look nice – and it did turn out nice, if you don’t mind that it looks like an old shack in the woods. So, we renamed it to the “Memory Shack”.

Unfortunately, through the chaos of it all, I forgot to get a photo of the actual photobooth at the reception.

The result

It may have looked janky and silly, but this thing was a hit! We had props, hats, glasses, and whatever silly things we could find from costumes between ourselves and friends. And the photos turned out absolutely hilarious and fun.

All-in-all, I spent at least 200 hours between research, prototyping, building, tweaking, and playing around with this. If I tried to cost:benefit ratio it all out with an hourly rate of my time, it probably would have been cheaper to rent a photobooth. However, after seeing the result of what I made, I think that I made the right choice by building this photobooth myself.

Express in a node.js server doesn’t handle this by itself. Instead you need to add something like the connect-timeout middleware. However, the default example for this leaves you open to forgetting to add the timeout check within your middleware chain.

import express from 'express';
import timeout from 'connect-timeout';

function haltOnTimedout(req, res, next) {
  if (!req.timedout) next();
}

const app = express()
  .use(timeout(5_000))
  .use(bodyParser())
  .use(haltOnTimedout)
  .use(cookieParser())
  .use(haltOnTimedout)
  .use(myMiddleware())
  .use(haltOnTimedout)
  .use(handleRequest());

Notice that you need to manually add the haltOnTimedout middleware after each other middleware in the chain. This may be fine and dandy for a small personal project that you, as the sole developer, know all about. However, as you start distributing knowledge to a larger team, it’s imperative that this is easy and automatic. There are few, if any, cases where you would want to opt-out of the behavior of timing out a request if it’s taking too long.

So, here’s a pattern that I’ve used a number of times for various purposes – proxying the Express application and wrapping the use() function for some automatic behavior. It’s as simple as wrapping the initial express application (or the application after any setup):

const app = proxyTimeoutMiddleware(express().use(timeout(5_000)))
  .use(bodyParser())
  .use(cookieParser())
  .use(myMiddleware())
  .use(handleRequest());

How does it work?

We create a Proxy that wraps the use() function. This is fairly basic setup to pull out the middleware that is added to express and wrap it with another function:

function proxyTimeoutMiddleware<T extends Application | Router>(app: T) {
  return new Proxy(app, {
    get(this: T, target, property, receiver) {
      // If the target property is not express's `.use()` function, pass through to the default behavior
      if (property !== 'use') {
        return Reflect.get(target, property, receiver);
      }

      // Otherwise, return a new function that wraps the first argument, given that it is a function
      // with our timeout wrapper
      return function useWithTimeout(...args) {
        const wrappedArgs = args.map((arg) => {
          if (typeof arg === 'function') {
            return wrapMiddlewareWithTimeout(arg);
          }
          return arg;
        });
        return Reflect.get(target, property, receiver).apply(this, wrappedArgs);
      };
    },
  });
}

Then, our wrapping function returns a new middleware function that checks first if the request is timed out (req.timedout is added via the connect-timeout middleware that we previously added) and returns. Upon early return, not calling req.end(), req.send() or next(), express will return the default 500 response.

Then as well, we wrap the next() function passed to our actual middleware and check if the request timedout after running the middleware and again, if so, early return. Otherwise we call the next() function and continue on.

function wrapMiddlewareWithTimeout(middleware: (req: Request, res: Response, next: NextFunction) => void) {
  return function timeoutWrappedMiddleware(req: Request, res: Response, next: NextFunction) {
    const { name } = middleware;
    if (req.timedout) {
      // logger.error(`Request timed out before middleware "${name}".`);
      return;
    }

    middleware(req, res, function wrappedNext(...args) {
      if (req.timedout) {
        // logger.error(`Request timed out after middleware "${name}".`);
        return;
      }

      next.apply(this, args);
    });
  };
}

That’s it! Once this is set up, no one will ever have to think about adding the timeout halting middleware in the future.

Other uses

This same pattern can be used for similar before/after actions on middleware. You may have noticed a couple commented out logging lines in the timeoutWrappedMiddleware example previously. We could also do something similar to record the amount of time each middleware is taking in order to help us track down problem code that could be optimized:

const NANOSECONDS_PER_MILLISECOND = 1e6;
const MILLISECONDS_PER_SECOND = 1e3;

function wrapMiddlewareWithMetrics(middleware: (req: Request, res: Response, next: NextFunction) => void) {
  return function metricsWrappedMiddleware(req: Request, res: Response, next: NextFunction) {
    const { name } = middleware;
    const [seconds, nseconds] = hrtime();
    // Get the high resolution time in milliseconds
    const start = seconds * MILLISECONDS_PER_SECOND + nseconds / NANOSECONDS_PER_MILLISECOND;

    middleware(req, res, function wrappedNext(...args) {
      const [seconds, nseconds] = hrtime();
      const end = seconds * MILLISECONDS_PER_SECOND + nseconds / NANOSECONDS_PER_MILLISECOND;
      myMetrics.float({ metric: `middleware/${name || 'unknown'}`, value: end - start });

      next.apply(this, args);
    });
  };
}

It hurts to hear about each and every one of these. Many others probably feel the same, but there’s something different about needing to text your family and friends so they know you’re okay.

I can’t imagine how it feels to be on the other side waiting to get a message that your loved one is safe – only to never hear back.

Something must be done. It needs to be drastic. People will scream about hundred year old laws – laws that are not needed today – laws that we need the opposite of today.

Please: no more guns.

import FirebaseImage from ’../../images/blog/wedding/firebase.png’; import AWSImage from ’../../images/blog/wedding/aws-amplify.png’; import SupabaseImage from ’../../images/blog/wedding/supabase.png’; import ParseImage from ’../../images/blog/wedding/parse.png’; import PreactImage from ’../../images/blog/wedding/preact.webp’; import TailwindImage from ’../../images/blog/wedding/tailwind.png’; import ParcelImage from ’../../images/blog/wedding/parcel.png’;

Now that we know what we need, it’s time to choose the right tools for the job. From our previously set requirements, the following items stood out as important for what we choose here:

• Free or very cheap hosting with a custom domain and SSL
• Invitees must be able to
  • Sign in with their email address and no password (magic link email)
  • Receive automated emails for their invitation and RSVP confirmation
• All significant information must come from a protected database

Hosting & backend

Google Firebase

I’ve used Google Firebase before, but never deployed a full web application for it. It has always been a bit more tailored for native mobile apps, but I have seen that they’ve worked really hard in making the web tools top-notch.

Downsides

• Locking in to Google
• Worse, Firebase is full lock-in and you can’t just replace the API with a different REST of GraphQL endpoint like you could with Amplify. Maybe you could refactor out to Supabase or another similar alternative, but your options are still very limited.
• Despite efforts to trim bundle sizes, Firebase JavaScript packages still come in pretty hefty.

Blockers

There are no blockers given the requirements that I initially laid out.

Alternatives considered

Hosting and backend framework evalutation can get long and tiring. I considered a few others otuside of Google Firebase – at least one of them I had initially thought I would end up using before considering Firebase.

AWS Amplify

Initially, I had hoped to be able to try out AWS Amplify. It would be an opportunity to learn something new that I hadn’t worked with before. It has a free tier and I thought it should cover everything that I wanted. Unfortunately there were roadblocks from the start.

Downsides

• The documentation pushed me through a web wizard. This wizard, while neat and provided a small overview to me of what might be capable, I tend to only really learn by doing and writing code. I did find the docs I needed eventually by searching for “AWS Amplify getting started JavaScript”.
• “To set up the project, we’ll first create a new React app with create-react-app” — I don’t want create-react-app! Where are the instructions to do this differently?
• Everything in their documentation kept pushing me at @aws-amplify/ui-react. It seemed basic enough, but wanting to get this together quickly, I didn’t want to also learn another UI component framework.
• Locking in to Amazon
• It seemed like Amplify is really just a little piece of the Amazon puzzle and I’d mostly need to string a bunch of services together, eg SES for sending emails.

Blockers

Unfortunately, there were a number of blockers that came up for me during investigation and prototyping:

• It’s not possible to sign in with just an email address.
• I really didn’t want to use GraphQL, even if it’s the “new hotness”. That’s just overkill for what I was looking to do.
• REST might have been okay, but also still overkill needing to pick & choose the right tools to fetch data and manage state.

Supabase

I would have liked to have tried Supabase since it’s open-source and free. However, I didn’t dive too far into it after the two blockers that I found:

• Cloud functions are only experimental and very limited
• No automated HTML email sending available

Parse Platform

Parse is another open source platform that I looked at briefly. Unfortunately, it had too many blockers to consider even prototyping.

• No email sending available
• It’s not possible to sign in with just an email address.
• Hosting limitations and potential cost
  • Hosting a Parse Platform application would either require a lot of setup and cost with another provider, or using Back4App’s free plan, which doesn’t appear to have SSL.

Application frameworks & tools

Preact

I could have used React, but I initially wanted to see how small I could keep the build size and didn’t think I’d need any of the extra weight from React for such a small site.

Tailwindcss

I have built a few things with Tailwind before and it really makes things simple while keeping the final build sizes small.

Parcel

I have used Parcel before for some really small projects like this and it’s pretty dead simple as a bundler to get set up. I also didn’t want to spend a week tweaking my compilation process to get things just right like I tend to do with Webpack.

Weddings are expensive. Trying to do one on a budget while following the social norms and expectations of planning and putting on a wedding just don’t really mix. After getting engaged, Kelly and I discussed what we did and definitely did not want when it came to our wedding.

One of the first things to do that we threw out was the idea of sending paper invites. Not only is it incredibly wasteful, but we had just received a wedding invitation in the mail and it just seemed expensive, tacky, and impersonal. Take this RSVP card option that comes from popular wedding registry website redacted:

Call me not old-fashioned, but the “M____” line makes no sense to me. After researching, I guess you’re supposed to fill in “Mr…”, “Mrs…”, or “Ms…”, but who uses that anymore? And what if you’re extra fancy and it should be “Dr…”? But really, why isn’t this filled in for me? You should know who I am!

And you know what else? I’m just going to lose that if you send it to me. I’m not saying it happened… well, actually yeah it happened.

Do something better

So we decided we could do something better. I figure I’ve been building websites long enough that I should be able to handle it.

The following series will recount building a modern wedding website as a replacement for paper snail mail RSVPs.

Requirements

Before starting, we made a list of things that we needed in terms of functionality both for us and for our guests:

• Free or very cheap hosting (wedding websites like theknot are already free, afterall) with a custom domain and SSL
• Invitees must be able to
  • Sign in with their email address and no password (magic link email)
  • Manage their RSVP, as well as their plus-one and/or family, directly on the site
  • View a schedule of events with maps, times, details
  • RSVP separately for optional hosted events
  • Receive automated emails for their invitation and RSVP confirmation
• All significant information must come from a protected database
  • For example, exact dates & locations should require authentication and not be compiled directly into JavaScript/HTML bundles
  • Mostly this is minor paranoia on my part to have some security on private information
• Ability to import guest/invitee information from CSV
  • Immediately send invitation emails upon import
• Ability to export RSVPs to a CSV for use in a spreadsheet (no “admin” site necessary)
  • Spreadsheets are much quicker for iteration and data manipulation than writing, committing, and deploying code
  • Allows my partner to have freedom and ownership
• Minimal maintenance overhead
  • I’m not going to be “on-call” for this. I just want it up and running.

Today marks nine full years of sobriety for me. Just a few weeks ago, my fiance asked me a question that’s been nagging her for a bit.

What can I do to help you celebrate your milesone?

My response surprised even me.

Nothing. Please don’t do anything special.

After giving it a moment of thought, the answer was clear. I don’t want any single day to be more special than the previous or the next. Every moment since the 17th of May, 2013 has been a challenge and a gift. It doesn’t matter what arbitrary measure of time we use to describe it—be it hours, days, months, or years — because I don’t want today to outshine tomorrow.

I avoid talking about the journey that got me to the point of cutting alcohol out of my life. In fact, there are only a handful of people who are in my life now that were there before – even fewer that really understand where I was and why I’ve made the choices that I have.

The ony things that anyone reading this should take away:

• Every moment staying sober can be a major a milestone.
• No one needs a reason to quit drinking.
• No one owes you an explanation of why they quit drinking.
• Never ask anyone why they don’t drink.

As of October 26^th, 2021, I have resigned from the AMP Technical Steering Committee. Though no small part of it was brought on by mounting responsibilities at work and at home, I cannot in good conscience recommend AMP to my peers due to recent disclosures about Google’s advertising conduct and its positioning of AMP.

Why not just stick to web standards and build meat and potatoes web pages that can work with whatever ad exchange you need?

Because Google can also simultaneously exert pressure onto publishers to use AMP to increase likelihood of search ranking performance.

— Lívia Labate (@livlab) October 25, 2021

History

Communication from Google to the public has always been that AMP was not given direct favoritism on their platform in any way. In order to help that perception and ensure that the project continued to mature and be a great option to build on, Google set out to relinquish direct control over the entire project.

First, a Technical Steering Committee (TSC), an Advisory Committee (AC), and a set of working groups were formed.

The initial goal of the TSC was to have a group of diverse people with less than half of the members representing Google. But instead, we ended up with 50% of members being Google employees who were directly affiliated with AMP internally. The rest was made up as individual people from Twitter (me), Pantheon, Microsoft, and Pinterest.

In a positive light, I think the best thing that we helped facilitate as the TSC was the moving copyright and IP to the OpenJS Foundation.

Failing core priorities

Outside of that, I’m honestly not sure what we accomplished, if anything, other than signing off on the hard work that the rest of the Advisory Committe and Working Groups were doing.

At AMP Conf in Tokyo, 2019, we promised we would make the TSC a diverse group. We failed at that. For about 1 year we had a member that was not male. Outside of that, we all looked alike and exactly who you would expect to be on a sort of “board of directors” (white men).

I’m sorry that I didn’t do more to continue to push on the issue. I knew it was a problem from the first time we were all on a video call together, saw it worse when we were all physically on stage at AMP Conf, and was fired up to do something about it. And then it fell off of my, and everyone else’s, priorities. Next time I’m in a similar situation, I promise to do better.

What else did we fail on?

• Signed Exchanges (SXG)

  • David Strauss, also since resigned from the TSC, worked very hard to help get this moving forward. He has a lot of great insight into this and I’ll avoid speaking for him. Hopefully he will share his opinions publicly soon.

• Keeping AMP relevant

  • Google/Chrome’s pushing of Core Web Vitals has given everyone clearer targets to hit. They’ve also proved that they’re achievable. Already we are seeing many companies and groups ditching AMP because other tools give them more freedom while still being able to deliver fast experiences.

    Is performance on the web getting better? The answer is yes :) 33% of origins now meet the Core Web Vitals thresholds! Lots of improvements from sites using a framework too. – Addy Osmani (@addyosmani) November 4, 2021

• Changing the perception that Google isn’t the controller of AMP

  • I don’t think this could have changed without getting a vast majority of contributions to the AMP codebase coming from the community instead of Google employees.
  • Google employs great developers whose sole priorities seem to be to work on AMP
  • Only one of the design reviews that I attended for AMP projects did I see a proposal come from a non-Google employee

These last two points, along with other mounting responsibilities, had been making me wonder if I really cared about AMP anymore. Honestly, I’d never actually used it–despite believing in it and believing that it really was/is a technologically amazing framework.

The dirtiest trick AMP pulled was to get really smart, earnest, well spoken developers to work on it and advocate for it.

— Chris Coyier (@chriscoyier) October 25, 2021

The original goals of the project are sound and something to admire. From a tech standpoint, I believe that AMP accomplished some amazing feats. A lot of incredible, smart, and thoughtful people put some seriously hard work into it and it shows. It’s performant, it’s fast, and it’s robust. That’s what we needed.

But that’s not all we got.

The worst parts

A recent civil complaint (1:21-md-03010-PKC) gives us some troubling detail into how Google positioned AMP for publishers as a necessity and pulled a fast one on winning heaps of advertising business by hindering header bidding.

Honestly, I can’t do justice summarizing all of it. Please read the relevant sections of the complaint, Page 89–92, sections 245–252 (it’s relaly not that much to read). At the very least, check out this part:

247. Google ad server employees met with AMP employees to strategize about using AMP to impede header bidding, addressing in particular how much pressure publishers and advertisers would tolerate. First, Google restricted the AMP code to prohibit publishers from routing their bids to, or sharing their user data with, more than a few exchanges a time, thereby severely limiting AMP’s compatibility with header bidding. However, Google made AMP fully compatible with routing to exchanges through Google’s ad server. Google also designed AMP to force publishers to route rival exchange bids through Google’s ad server so that Google could continue to peek at their bids and trade on inside information. Third, Google designed AMP so that users loading AMP pages would directly communicate with Google cache servers rather than publishers’ servers. This enabled Google’s access to publishers’ inside and non-public user data. AMP pages also limit the number of ads on a page, the types of ads publishers can sell, and the variety of enriched content that publishers can have on their pages.

Resigning

I sent my resignation to the rest of the TSC on 2021-10-26. Within hours, another member replied in announcement of their own resignation.

I do very much appreciate having had the privilege to try to help AMP and its community of developers & users. But at the same time, I noted in my resignation that “I no longer feel comfortable recommending AMP to colleagues both out of necessity and fears of recently filed complaints against Google.”

While I understand that Google employees likely aren’t allowed to respond to anything regarding the legal complaint, it’s been more than two weeks and I haven’t gotten any sort of formal acknowledgement of my resignation or personal note of any kind.

Though it does appear that I was removed from the list of members the following week.

So, short to say, I’m disappointed all around.

I’ve been sitting on this decision for a long time. It’s not easy to abandon something I have poured a lot of thought, care, time, and effort into. It’s almost like quitting a job… except I never got paid for the job.

Open source was, is, and will continue to be the gateway for my entire skillset. Without it, I don’t think I would have ever learned how write software, let alone ever have become a software developer.

Some history

Years ago, before React, Angular, Vue, all of the great frameworks that we’re currently using, we (maybe just me?) obsessed over templating engines. Some were good, some were bad, and some were Jinja. I absolutely loved Jinja. It’s flexibility, composition, and inheritance made it amazing for building out complex web sites.

Maybe more correct, I fell in love with the PHP version of Jinja, Twig. At the time, I was working for a small company with a massive PHP website–a massive spaghetti-code PHP website. SQL queries were embedded in the top of PHP pages, security holes, and every bad practice you could imagine existed in its codebase. There wasn’t a single hint that a skilled “frontend developer” had ever worked there. (Fun side note: one did for a hot minute before I joined. Apparently they rage-quit within a month because of how bad everything was.)

We went full-gas implementing an MVC for our PHP website. Fixing the security holes, getting those SQL queries shored up, and most importantly (to me) setting up a reusable templating system with Twig. I loved it. The template engine was easy to learn, extend, reuse, and teach.

Then I got more and more into node.js and I wanted a project to help me learn more. I noticed there wasn’t a good templating engine with the features that Twig and Jinja offered. So in came Swig. Initially it was nearly compatible with Twig. It actually took off quite a bit.

It had nearly 100% code coverage, was used by quite a few real companies selling real products. I felt like I was making it as an open source developer.

Except I wasn’t. Other than Swig’s own documentation, I never actually got to use Swig for anything. It was my favorite thing I’d created, and I never got to enjoy it.

But that’s not why I abandoned it.

I abandoned it because I wasn’t able to create a healthy community around it. It felt like every notification I got from Github was someone filing an issue or requesting another feature. But barely single pull request was ever there. I tried for a time to keep up fixing and implementing to keep the issues clear. But it became too much. I tried to help others do it themselves, but I would get silence in return. It was exhausting and unrewarding.

With a heavy heart, I opened an issue looking for maintainers. I updated the README to point to it. I left it be for a few months and no one stepped up.

So I closed the issues, stopped accepting any PRs, and marked the repository as archived and unmaintained.

Backlash

People were unhappy, to say the least. Some were mad directly at me. How could I do this?

And I’ve seen a few posts, polls, and discussions lately about open source maintainers and long-term maintenance and viability. A good number of people have rational responses, but there are still some that try to argue that as an open source maintainer, it is your duty to continue maintaining what you’ve written. For free. Your time, your effort, your life.

And therein lies the point of this post:

I’m afraid of the backlash. I shouldn’t be, I know that. And I know that there’s a silent majority that understand and will just go on with their lives. But I also know that it’s disheartening when there’s something that you use and rely on that suddenly looks like it’s going to disappear.

Anyway, that’s my little moment of vulnerability. This little post has taken me almost an entire day to write. I haven’t even scratched the surface of my fears around asking for help and relinquishing control of a project. But know that I have it–and there’s a lot of it.

What’s happening

So why am I writing all of this? Well, because I just don’t have the time right now–and haven’t for most of this year–and doubt I will magically create more hours in the day any time soon. And I don’t want to screw up, disappoint, and lose trust like I did last time.

I’m going through my open source repositories and deciding which need maintainers. Not just contributors, but people able to admin the repository and publish to NPM as well.

This time around, I really don’t want to just shut anything down, archive it, and tell people to fork it themselves. I’d like to see what I’ve written continue to thrive, become better, and be useful tools.

First up, Normalizr. I haven’t been active with Normalizr for years. It’s not a tool I’ve needed to reach for and I believe it’s pretty stable. I do fear, however, that I may be a little disconnected from the needs of the actual users.

There are too many choices for server-side rendering HTML pages. Avoiding the heavy hitter frameworks like React, that require a lot more work and will drain server resources quickly, you may find yourself reaching for a templating engine that can dynamically help you build up HTML responses for your JavaScript server.

Having written a templating engine¹, I know that many of them include features that make them really attractive to many users. However, you may really not need one at all.

The biggest feature that templating engines tend to provide is safety from Cross-Site Scripting (XSS). Let’s look at a very simplistic example. Let’s say you want to greet a person by name by using some user-submitted information. To make it easy, let’s grab that value from the query param ?name from the URL. Fire this snippet up with Node.js:

const express = require('express');

const app = express();

app.get('/', (req, res) => {
  res.send(`<p>Hello, ${req.query.name}!</p>`);
});

app.listen(3000);

When I run the above and visit http://localhost:3000/?name=Paul, I am greeted with Hello, Paul!. Awesome! But there’s just one problem. What if someone shares a link that looks like this: http://localhost:3000/?name=%3Cscript%3Ealert(%27got%20you%27);%3C/script%3E?

You might see the problem without even pasting that in your browser. The server will directly inject a <script> and allow the “attacker” to execute any JavaScript on the page. While this example doesn’t do anything bad other than alert on the page, more complicated attacks could load scripts from somewhere else². This kind of attack is known as Cross Site Scripting (or XSS for short).

Templating engines

So, with XSS in mind, many templating engines have, by default, protected against that by making their default variable insertion escape the output unless the developer marks it as safe.

Handlebars

Handlebars output syntax {{expression}} is html-escaped, while {{{expression}}} (three curly-braces) is not.

<p>Hello, {{name}}!</p>

EJS

EJS ouput syntax <%= is html-escaped, while <%- is not.

<p>Hello, <%= name %>!</p>

Swig

Swig ouput syntax {{ variable }} is html-escaped, while {{ variable|raw }} is not.

<p>Hello, {{variable}}!</p>

Marko

Marko ouput syntax ${variable} is html-escaped, while $!{variable} is not.

<p>Hello, ${escaped}!</p>

Of all of the above examples, we notice that automatic HTML-escaping is the default and recommended syntax for each language. And that’s really awesome! But again, you might be able to do this much quicker and simpler.

Moving away from template engines

Originally, at Twitter, we had written part of our server-side HTML rendering using Handlebars. At the time (2014/15), it was the best choice. It had all of the general features you’d want: automatic HTML escaping was a big piece of that.

We had also looked into JavaScript tagged templates. However, we weren’t quite transitioned to Node 4.0.0 (released 2015-09-08) and tagged templates weren’t available to us.

Fast-forward 5 years and I had been auditing a bunch of our server rendering code. What really stuck out to me was that we were using Handlebars and it was largely unchanged. We didn’t use any of the more complex features and the indirection was causing a few issues with figuring out where code was between the logic of our middleware and the actual rendering of the HTML itself.

Tagged template functions are really cool and they’re pretty simple themselves, just with a funny syntax (that you may recognize from implementations of things like Styled Components).

Let’s implement a simple tagged template function first, to get the feel for it.

function html(stringParts: TemplateStringsArray, ...values: Array<unknown>) {
  return `${stringParts[0]}${name}${stringParts[1]}`;
}

const name = 'Paul';

html`Hello, ${name}!`;

Hello, Paul!

In the above, you can see the two parts that make up a tagged template function:

• stringParts is an array of strings. Think of these as each part of the tagged string split up by each variable ${...}. If you don’t have any variables, the length will be 1. For 1 variable, the length will be two; 2 variables will be length 3, and so on.
• name (and any further arguments) are the variables that you are inserting into the stringParts

This works well, but we’d like it to accept any number of inserted variables. To do that, we can spread the arguments and write a reduce the stringParts, merging them with each value in order:

function html(stringParts: TemplateStringsArray, ...values: Array<unknown>) {
  return stringParts.reduce((accumulator, part, i) => {
    const value = values[i] || '';
    return `${accumulator}${part}${value}`;
  }, '');
}

const personOne = 'Jane';
const personTwo = 'Jim';

html`Hello, ${personOne} and ${personTwo}!`;

Hello, Jane and Jim!

Strings only

We still haven’t fixed our big security hole, though! Starting with the most basic, we can escape each value using the escape-html package when we add it to the accumulator. This time, you can see that attempting to write a <script> tag to the output ends up getting escaped, exactly as we would like:

import escape from 'escape-html';

function html(stringParts: TemplateStringsArray, ...values: Array<unknown>) {
  return stringParts.reduce((accumulator, part, i) => {
    const value = values[i] || '';
    return `${accumulator}${part}${escape(value)}`;
  }, '');
}
const name = '<script>alert("hello");</script>';

html`Hello, ${name}!`;

Hello, %3Cscript%3Ealert%28%22hello%22%29%3B%3C/script%3E!;

A fully-featured result

This works really well, is simple and fast. For completeness, we can take it a couple of steps further and ensure that any value can be mixed type (JSON, Date, etc):

import escape from 'escape-html';

function html(stringParts: TemplateStringsArray, ...values: Array<unknown>) {
  return stringParts.reduce((accumulator, part, i) => {
    const value = values[i] || '';
    let escapedValue = '';
    // If we have a string, just escape it
    if (typeof value === 'string') {
      escapedValue = escape(value);
      // Arrays and plain JavaScript objects can be JSON stringified with a custom function to ensure each individual value gets escaped
    } else if (value && (Array.isArray(value) || Object.prototype.toString.call(value) === '[object Object]')) {
      escapedValue = JSON.stringify(value, (key, value) => (typeof value === 'string' ? escape(value) : value));
      // If we're dealing with a class of some other type, try to use the `toString` method
    } else if ('toString' in Reflect.ownKeys(value)) {
      escapedValue = escape(value.toString());
      // otherwise, just escape the String value
    } else {
      escapedValue = escape(String(value));
    }
    return `${accumulator}${part}${escapedValue}`;
  }, '');
}

const name = 'Paul';
const description = '<script>alert("hello");</script>';
const jsonContent = { content: '<script>alert("hello");</script>' };

html`<h1>Hello, ${name}!</h1>
  <p>${description}</p>
  <script>
    window.DATA = ${jsonContent};
  </script>`;

<h1>Hello, Paul!</h1>
<p>%3Cscript%3Ealert%28%22hello%22%29%3B%3C/script%3E</p>
<script>
  window.DATA = {"content":"%3Cscript%3Ealert%28%22hello%22%29%3B%3C/script%3E"};
</script>

And that’s it! That’s the full implementation³ of a Tagged Template function for JavaScript-based servers that allows you to output XSS-safe. Any HTML within the stringParts content will be written verbatim, while all variables injected will automatically be escaped.

It’s not easy trying to stream code development and sit around talking to yourself for hours on end. I keep finding myself needing a rubber duck to explain things to while no one is active in the chat.

In comes the Rubber Ducky chat bot. Check out the code on GitHub at paularmstrong/rubber_duck_bot.

• main - quickly jump back to the default/HEAD branch of your repo without needing to know what the name of that branch is.
• rebase - rebase your current branch against the current state of the default/HEAD branch as it is on the remote server.
• rmbranch - delete your current working branch and move to the default/HEAD branch. Great for PR cleanup!

main

The industry seems to be agreeing that main is a much better default than the outdated term master. Unfortunately, there are still some repos that I’ve needed to work with that use other names.

This function can help remove the guessing game if you work with a bunch of repos that are still transitioning and/or use different names for the default/HEAD branch and you want to quickly get there from your current branch:

function main() {
	DEFAULT_BRANCH=`git remote show origin | grep "HEAD branch" | sed 's/.*: //'`
	git checkout $DEFAULT_BRANCH
	git pull
}

Usage:

main

rmbranch

I’m often in a position where the current branch I’m on had its PR was completed, merged, and branch removed from the remote. I dislike keeping old copies of branches around that I don’t need and I want them cleaned up immediately.

This function deletes the current branch and moves to the default tracked branch, avoiding doing the whold dance yourself. Bonus: it does the same thing as the previous main function and figures out which default/HEAD branch to switch to.

function rmbranch() {
	BRANCH=`git rev-parse --abbrev-ref HEAD`
	DEFAULT_BRANCH=`git remote show origin | grep "HEAD branch" | sed 's/.*: //'`
	git checkout $DEFAULT_BRANCH
	git branch -D $BRANCH
	git pull
}

Usage:

rmbranch

rebase

Super helpful for workplaces that prefer flat commits and don’t allow merge commits – or you just find it easier to rebase. Quickly fetches your default branch and rebases on top of the latest changes.

Again, this figures out the default/HEAD branch automatically so you don’t have to think about it.

function rebase() {
	DEFAULT_BRANCH=`git remote show origin | grep "HEAD branch" | sed 's/.*: //'`
	git fetch origin $DEFAULT_BRANCH
	git rebase origin/$DEFAULT_BRANCH
}

Usage:

rebase

A look into removing common and uncommon performance bottlenecks in one of the worlds largest React.js PWAs, Twitter Lite.

Creating a fast web application involves many cycles of measuring where time is wasted, understanding why it’s happening, and applying potential solutions. Unfortunately, there’s never just one quick fix. Performance is a continuous game of watching and measuring for areas to improve. With Twitter Lite, we made small improvements across many areas: from initial load times, to React component rendering (and prevention re-rendering), to image loading, and much more. Most changes tend to be small, but they add up, and the end result is that we have one of the largest and fastest progressive web applications.

Before Reading On:

If you’re just starting to measure and work toward increasing the performance of your web application, I highly recommend learning how to read flame graphs, if you don’t know how already.

Each section below includes example screenshots of timeline recordings from Chrome’s Developer Tools. To make things more clear, I’ve highlighted each pair of examples with what’s bad versus what’s good.

Optimizing for the Browser

Use Route-Based Code Splitting

Webpack is powerful but difficult to learn. For some time, we had issues with the CommonsChunkPlugin and the way it worked with some of our circular code dependencies. Because of that, we ended up with only 3 JavaScript asset files, totaling over 1MB in size (420KB gzip transfer size).

Loading a single, or even just a few very large JavaScript files in order to run a site is a huge bottleneck for mobile users to see and interact with a website. Not only does the amount of time it takes for your scripts to transfer over a network increase with their size, but the time it takes for the browser to parse increases as well.

After much wrangling, we were finally able to break up common areas by routes into separate chunks (example below). The day finally came when this code review dropped into our inboxes:

const plugins = [
  // extract vendor and webpack's module manifest
  new webpack.optimize.CommonsChunkPlugin({
    names: ['vendor', 'manifest'],
    minChunks: Infinity,
  }),
  // extract common modules from all the chunks (requires no 'name' property)
  new webpack.optimize.CommonsChunkPlugin({
    async: true,
    children: true,
    minChunks: 4,
  }),
];

Adds granular, route-based code-splitting. Faster initial and HomeTimeline render is traded for greater overall app size, which is spread over 40 on-demand chunks and amortized over the length of the session. — Nicolas Gallagher

Our original setup (above) took over 5 seconds to load our main bundle, while after splitting out code by routes and common chunks (below), it takes barely 3 seconds (on a simulated 3G network).

This was done early on in our performance focus sprints, but this single change made a huge difference when running Google’s Lighthouse web application auditing tool:

Avoid Functions that Cause Jank

Over many iterations of our infinite scrolling timelines, we used different ways to calculate your scroll position and direction to determine if we needed to ask the API for more Tweets to display. Up until recently, we were using react-waypoint, which worked well for us. However, in chasing the best possible performance for one of the main underlying components of our application, it just wasn’t fast enough.

Waypoints work by calculating many different heights, widths, and positions of elements in order to determine your current scroll position, how far from each end you are, and which direction you’re going. All of this information is useful, but since it’s done on every scroll event it comes at a cost: making those calculations causes jank–and lots of it.

But first, we have to understand what the developer tools mean when they tell us that there is “jank”.

Over time, we developed a new infinite scrolling component called VirtualScroller. With this new component, we know exactly what slice of Tweets are being rendered into a timeline at any given time, avoiding the need to make expensive calculations as to where we are visually.

It may not look like much, but before (above) while scrolling, we would cause render jank by trying to calculate the height of various elements. After (below) we cause no jank and reduce the stuttering while scrolling timelines at fast speeds.

By avoiding function calls that cause extra jank, scrolling a timeline of Tweets looks and feels more seamless, giving us a much more rich, almost native experience. While it can always be better, this change makes a noticeable improvement to the smoothness of scrolling timelines. It was a good reminder that every little bit counts when looking at performance.

Use Smaller Images

We first started pushing to use less bandwidth on Twitter Lite by working with multiple teams to get new and smaller sizes of images available from our CDNs. It turns out, that by reducing the size of the images we were rendering to be only what we absolutely needed (both in terms of dimensions and quality), we found that not only did we reduce bandwidth usage, but that we were also able to increase performance in the browser, especially while scrolling through image-heavy timelines of Tweets.

In order to determine how much better smaller images are for performance, we can look at the Raster timeline in Chrome Developer Tools. Before we reduced the size of images, it could take 300ms or more just to decode a single image, as shown in the timeline recording below. This is the processing time after an image has been downloaded, but before it can be displayed on the page.

When you’re scrolling a page and aiming for the 60 frame-per-second rendering standard, we want to keep as much processing as possible under 16.667ms (1 frame). It’s taking us nearly 18 frames just to get a single image rendered into the viewport, which is too many. One other thing to note in the timeline: you can see that the Main timeline is mostly blocked from continuing until this image has finished decoding (as shown by the whitespace). This means we’ve got quite a performance bottleneck here!

Large images (above) can block the main thread from continuing for 18 frames. Small images (below) take only about 1 frame.

Now, after we’ve reduced the size of our images (above), we’re looking at just over a single frame to decode our largest images.

Optimizing React

Make use of the shouldComponentUpdate method

A common tip for optimizing the performance of React applications is to use the shouldComponentUpdate method. We try to do this wherever possible, but sometimes things slip through the cracks.

Here’s an example of a component that was always updating: When clicking the heart icon to like a Tweet in the home timeline, any Conversation component on screen would also re-render. In the animated example, you should see green boxes highlighting where the browser has to re-paint because we’re making the entire Conversation component below the Tweet we’re acting on update.

Below, you’ll see two flame graphs of this action. Without shouldComponentUpdate, we can see its entire tree updated and re-rendered, just to change the color of a heart somewhere else on the screen. After adding shouldComponentUpdate (second image below), we prevent the entire tree from updating and prevent wasting more than one-tenth of a second running unnecessary processing.

Defer Unnecessary Work until componentDidMount

This change may seem like a bit of a no-brainer, but it’s easy to forget about the little things when developing a large application like Twitter Lite.

We found that we had a lot of places in our code where we were doing expensive calculations for the sake of analytics during the componentWillMount React lifecycle method. Every time we did this, we blocked rendering of components a little more. 20ms here, 90ms there, it all adds up quickly. Originally, we were trying to record which tweets were being rendered to our data analytics service in componentWillMount, before they were actually rendered (below).

By moving that calculation and network call to the React component’s componentDidMount method, we unblocked the main thread and reduced unwanted jank when rendering our components (below).

Avoid dangerouslySetInnerHTML

In Twitter Lite, we use SVG icons, as they’re the most portable and scalable option available to us. Unfortunately, in older versions of React, most SVG attributes were not supported when creating elements from components. So, when we first started writing the application, we were forced to use dangerouslySetInnerHTML in order to use SVG icons as React components.

For example, our original HeartIcon looked something like this:

const HeartIcon = (props) =>
  React.createElement('svg', {
    ...props,
    dangerouslySetInnerHTML: {
      __html:
        '<g><path d="M38.723 12c-7.187 0-11.16 7.306-11.723 8.131C26.437 19.306 22.504 12 15.277 12 8.791 12 3.533 18.163 3.533 24.647 3.533 39.964 21.891 55.907 27 56c5.109-.093 23.467-16.036 23.467-31.353C50.467 18.163 45.209 12 38.723 12z"></path></g>',
    },
    viewBox: '0 0 54 72',
  });

Not only is it discouraged to use dangerouslySetInnerHTML, but it turns out that it’s actually a source of slowness when mounting and rendering.

Before (above), you’ll see it takes roughly 20ms to mount 4 SVG icons, while after (below) it takes around 8.

Analyzing the flame graphs above, our original code (above) shows that it takes about 20ms on a slow device to mount the actions at the bottom of a Tweet containing four SVG icons. While this may not seem like much on its own, knowing that we need to render many of these at once, all while scrolling a timeline of infinite Tweets, we realized that this is a huge waste of time.

Since React v15 added support for most SVG attributes, we went ahead and looked to see what would happen if we avoided dangerouslySetInnerHTML. Checking the patched flame graph (above right), we get about an average of 60% savings each time we need to mount and render one of these sets of icons!

Now, our SVG icons are simple stateless components, don’t use “dangerous” functions, and mount an average of 60% faster. They look like this:

const HeartIcon = (props = {}) => (
	<svg {...props} viewBox=`0 0 ${width} ${height}`>
		<g>
			<path d="M38.723 12c-7.187 0-11.16 7.306-11.723 8.131C26.437 19.306 22.504 12 15.277 12 8.791 12 3.533 18.163 3.533 24.647 3.533 39.964 21.891 55.907 27 56c5.109-.093 23.467-16.036 23.467-31.353C50.467 18.163 45.209 12 38.723 12z"></path>
		</g>
	</svg>
);

Defer Rendering When Mounting & Unmounting Many Components

On slower devices, we noticed that it could take a long time for our main navigation bar to appear to respond to taps, often leading us to tap multiple times, thinking that perhaps the first tap didn’t register.

Notice in the image below how the Home icon takes nearly 2 seconds to update and show that it was tapped:

No, that wasn’t just the GIF running a slow frame rate. It actually was that slow. But, all of the data for the Home screen was already loaded, so why is it taking so long to show anything? It turns out that mounting and unmounting large trees of components (like timelines of Tweets) is very expensive in React.

At the very least, we wanted to remove the perception of the navigation bar not reacting to user input. For that, we created a small higher-order-component:

import hoistStatics from 'hoist-non-react-statics';
import React from 'react';

/**
 * Allows two animation frames to complete to allow other components to update
 * and re-render before mounting and rendering an expensive `WrappedComponent`.
 */
export default function deferComponentRender(WrappedComponent) {
  class DeferredRenderWrapper extends React.Component {
    constructor(props, context) {
      super(props, context);
      this.state = { shouldRender: false };
    }

    componentDidMount() {
      window.requestAnimationFrame(() => {
        window.requestAnimationFrame(() => this.setState({ shouldRender: true }));
      });
    }

    render() {
      return this.state.shouldRender ? <WrappedComponent {...this.props} /> : null;
    }
  }

  return hoistStatics(DeferredRenderWrapper, WrappedComponent);
}

Once applied to our HomeTimeline, we saw near-instant responses of the navigation bar, leading to a perceived improvement overall.

const DeferredTimeline = deferComponentRender(HomeTimeline);
render(<DeferredTimeline />);

Optimizing Redux

Avoid Storing State Too Often

While controlled components seem to be the recommended approach, making inputs controlled means that they have to update and re-render for every keypress.

While this is not very taxing on a 3GHz desktop computer, a small mobile device with very limited CPU will notice significant lag while typing–especially when deleting many characters from the input.

In order to persist the value of composing Tweets, as well as calculating the number of characters remaining, we were using a controlled component and also passing the current value of the input to our Redux state at each keypress.

Above, on a typical Android 5 device, every keypress leading to a change could cause nearly 200ms of overhead. Compound this by a fast typist, and we ended up in a really bad state, with users often reporting that their character insertion point was moving all over the place, resulting in jumbled sentences.

By removing the draft Tweet state from updating the main Redux state on every keypress and keeping things local in the React component’s state, we were able to reduce the overhead by over 50% (above).

Batch Actions into a Single Dispatch

In Twitter Lite, we’re using redux with (react-redux)[http://redux.js.org/docs/basics/UsageWithReact.html] to subscribe our components to data state changes. We’ve optimized our data into separate areas of a larger store with Normalizr and combineReducers. This all works wonderfully to prevent duplication of data and keep our stores small. However, each time we get new data, we have to dispatch multiple actions in order to add it to the appropriate stores.

With the way that react-redux works, this means that every action dispatched will cause our connected components (called Containers) to recalculate changes and possibly re-render.

While we use a custom middleware, there are other batch middleware available. Choose the one that’s right for you, or write your own.

The best way to illustrate the benefits of batching actions is by using the Chrome React Perf Extension. After the initial load, we pre-cache and calculate unread DMs in the background. When that happens we add a lot of various entities (conversations, users, message entries, etc). Without batching (first image below), you can see that we end up with double the number of times we render each component (~16) versus with batching (~8) (second image below).

Service Workers

While Service Workers aren’t available in all browsers yet, they’re an invaluable part of Twitter Lite. When available, we use ours for push notifications, to pre-cache application assets, and more. Unfortunately, being a fairly new technology, there’s still a lot to learn around performance.

Pre-Cache Assets

Like most products, Twitter Lite is by no means done. We’re still actively developing it, adding features, fixing bugs, and making it faster. This means we frequently need to deploy new versions of our JavaScript assets.

Unfortunately, this can be a burden when users come back to the application and need to re-download a bunch of script files just to view a single Tweet.

In ServiceWorker-enabled browsers, we get the benefit of being able to have the worker automatically update, download, and cache any changed files in the background, on its own, before you come back.

So what does this mean for the user? Near instant subsequent application loads, even after we’ve deployed a new version!

As illustrated (above) without ServiceWorker pre-caching, every asset for the current view is forced to load from the network when returning to the application. It takes about 6 seconds on a good 3G network to finish loading. However, when the assets are pre-cached by the ServiceWorker (below), the same 3G network takes less than 1.5 seconds before the page is finished loading. A 75% improvement!

Delay ServiceWorker Registration

In many applications, it’s safe to register a ServiceWorker immediately on page load:

<script>window.navigator.serviceWorker.register('/sw.js');</script>

While we try to send as much data to the browser as possible to render a complete-looking page, in Twitter Lite this isn’t always possible. We may not have sent enough data, or the page you’re landing on may not support data pre-filled from the server. Because of this and various other limitations, we need to make some API requests immediately after the initial page load.

Normally, this isn’t a problem. However, if the browser hasn’t installed the current version of our ServiceWorker yet, we need to tell it to install–and with that comes about 50 requests to pre-cache various JS, CSS, and image assets.

When we were using the simple approach of registering our ServiceWorker immediately, we could see the network contention happening within the browser, maxing out our parallel request limit (below).

Notice how when registering your service worker immediately, it can block all other network requests (above). Deferring the service worker (below) allows your initial page load to make required network requests without getting blocked by the concurrent connection limit of the browser.

By delaying the ServiceWorker registration until we’ve finished loading extra API requests, CSS and image assets, we allow the page to finish rendering and be responsive, as illustrated in the after screenshot (above).

Overall, this is a list of just some of the many improvements that we’ve made over time to Twitter Lite. There are certainly more to come and we hope to continue sharing the problems we find and the ways that we work to overcome them. For more about what’s going on in real-time and more React & PWA insights, follow me and the team on Twitter.