#1. GitHub Is Dying (and so Is the Traditional SDLC)

With the rise of AI coding agents, software engineering is undoubtedly undergoing massive changes right now.

Teams are seeing big differences in output for folks starting to adopt these tools early and those that still haven't, and larger organizations are outpaced by smaller teams who amplify their output with AI.

Teams that are all-in on AI agents report big challenges scaling traditional software engineering processes like code reviews or CI pipelines with the influx in code. Additionally, some teams are even starting to discourage the use of issue tracking systems altogether and instead pass a well-written bug report directly into a coding agent that will then propose a fix.

Outside of companies, open-source is facing similar challenges where the classical concept of pull-requests is no longer maintainable because of the increase in volume with questionable quality. Many well-known open-source projects are starting to close off or limit pull requests (e.g. Codex). Issue discussions are also getting spammed with low quality content from agents all over the world.

And on top of all of this, GitHub has huge reliability issues and is now referred to as a dumpster fire by the community already.

I don't think continuing this approach is sustainable for long and unless there are some massive changes in a very short time, GitHub is dying (and with it, probably the whole traditional SDLC). And I'm not the only one with this opinion.

#2. Coding Agents Are Commodity

I started my journey with AI agents in May last year and wrote about How I use Claude Code in June.

By now, I am no longer using Claude Code. Last year, I've instead been using many different coding agents including Codex CLI, Amp, Gemini CLI, Cursor, and, most recently I became a Pi convert. While the agent harness does continue to play a huge role in the agent's performance¹, I do think that the gaps are closing and instead personal preference is what's going to make you pick a coding agent in the future.

Most people I talk to these days have at least once used a coding agent of some form already but there's far from one coding agent to rule them all.

So, my bet is that teams will end up using multiple coding agent harnesses in the future, maybe even specific harnesses for specific types of work, some of them hyper-personalized to the team. The collaboration platform of the future will need to support them all to some extent.

#Where to Go from Here

There are, of course, countless teams currently thinking about what's next. Big AI labs doing strategic acquisitions², planning software adding deeper code integrations to capture the market³, and new startups boasting with ridiculous seed funding rounds to build the next GitHub⁴.

But don't be fooled: Nobody knows where this is heading. The only thing that's clear is that existing systems can't scale with the increased rate at which code is now generated.

My guess is that collaboration for software projects will have to move to a higher level: from the code level to the spec level. Both product decisions and knowledge sharing will need to be done at the prompt level with the code being a generated artifact of it in many cases. The collaboration platform of the future will thus need to be much more tightly integrated into AI coding agents than the current generation.

In the same sense, code reviews will need to change dramatically. The old standard of "every line of code must be read by at least two humans" is hitting a limit already. Humans will start to be removed from the core code loop more and more. Personally, my guess is that instead of pull requests the first step will be that the developers start reviewing their own agent's code and the team only looks over the higher-level prompts to make sure the direction is right, only zooming into the code for more critical parts of the application.

Product-wise, my prediction is that we'll see new features being tested much more frequently but in the same vein we'll also see functionality removed much more often. Software is going to become a lot less rigid.

#Building AgentLogs

I realized pretty early in my coding agent journey that I put a lot of effort into prompts, effort that is lost once I commit the changes to Git. In my career as software engineer, I often needed to do extensive code archeology to uncover all context of a change to fix issues, so not being able to access all of it feels like a big limitation.

One of the first things I fully vibe coded was a small project called claude-code-viewer: A simple (and very broken) CLI that can upload the agent transcript to a web server where it's persisted with a URL. The idea was to document the agent transcript with the Git commit so that it's accessible in the future.

This project is slop and I didn't even use it myself. However, I still briefly mentioned it in my post about How I use Claude Code. To my surprise, this app still has users today. There are transcripts uploaded in February 2026, 9 months after I stopped thinking about it. So this is clearly something people want.

Over the past few weeks I started building AgentLogs, an open-source prototype of a platform for collaboration in the age of AI coding agents.

In its current version, AgentLogs is very simple: A few agent-specific plugins that hook into a shared CLI to convert your transcript to a unified schema and then uploads it to a server for storage.

What makes it special are two things:

1. You can onboard your whole team and already see how your teammates are using AI agents and what patterns work or not.
2. Since AgentLogs automatically adds links to Git commit messages, you already get a good sense of what's in the code change only by looking at the prompt.

#Why I'm Open-Sourcing It

When building AgentLogs, I quickly realized that keeping it private and distributing it as a typical SaaS is a bad idea.

One aspect is that agent transcripts are a huge security liability since it's very easy for it to leak secrets and other confidential information. AgentLogs attempts to guard against this by searching for thousands of well-known secret patterns and eliminating them from the logs before it's uploaded, but total security can, of course, not be guaranteed. Because of this, I do think companies need to treat agent transcripts as highly sensitive data and should keep it on infrastructure they can reliably delete from (even though it might be tempting to store this information in Git together with the code changes).

Another realization is that to make this tool useful for your team, you really want to integrate all coding agents your team is using. Even if they have DIY ones. In its current version, it's very trivial to add a new integration (since LLMs are notoriously good at converting one format to another) so making everything open makes it easy to add the integrations you need.

But the turning point was once I started calling it a collaboration platform. If the vision is to rethink how teams work together in the AI age, this can't happen in a silo. Open-sourcing it felt like the only honest approach.

#What's Next

If you're curious, the code is on GitHub (oh, the irony). It's not much but it's a start, and you're invited to shape it in any way it makes sense for you. Now is the time to really rethink best practices.

This created a huge boom in new agent offerings across the industry: If we focus solely on coding agents, there are so many different products on the market right now that it's impossible to keep track of. I've been invited to so many coding agents previews, that I can't even remember all the names anymore.

More recently, we see that existing agent offerings start to create SDKs to make it even easier to build on them: Claude Code SDK allows you to build your own agent leveraging some of the context management and tools that make Claude Code so successful. At the same time we see fine-tuned versions of models specifically tailored around agentic tool use.

All of this reminds me a lot of what happened the past year with the model layer. One lab made a breakthrough and many more labs emerged that were able to replicate it. Today, we have more competition than ever in the model layer and it's now perfectly reasonable to have a "best model for a specific task" or even use open-weights models for day-to-day work. Specifically the latter category is in an extreme race towards cheaper and cheaper inference that will eventually converge to only the energy costs.

I think something similar is going to happen with agents very soon. The differences between coding models will become smaller and smaller and more and more solutions will be on the market resulting in the price to eventually converge to only the raw model price.

There are a few more things that need to be figured out still: Security and proper sandboxing, for example, is a big concern. But once we have better primitives in place, it is going to unlock a new abstraction level and I can't wait to play with that.

Since AI agents are new for everyone right now, I thought it might be fun to share some patterns I've been noticing recently. Here's how I use Claude code.

#Start New Threads

If there's one thing I want you to take away from this, it's that you should absolutely call /clear more often.

AI agents tend to become more unpredictable the longer a conversation goes. This is especially true when you're asking different questions. I found that it's often much more effective to create a new prompt even if that means repeating some instructions.

Once I started doing this more aggressively, my results improved dramatically. And I'm definitely not the only one with this advice.

#Create Precise Prompts

I feel like this goes without saying, but when you're working with a new grad with amnesia (that's how I like to think of Claude), it's important that you write out all the context that you have in your head. This is hard, and frankly I don't think I'm very good at it myself yet, but the more context you can give Claude, the more effective it'll be. If you're thinking of some edge-cases, absolutely mention it to Claude. If you remember "there's a similar pattern that we've used for this type of problem in this codebase in the past", write it down! The more precise the prompt, the better Claude will do. Mind-reading technology isn't there just yet.

Try to think of any implicit context too. For example, if you ask Claude to create a modern design, it probably has no idea what you refer to as modern. It might be better to give examples instead (e.g., create a Linear-like app UI design).

#Let Claude Code Use Claude Code

Did you know that you can use Claude Code's tools as an MCP server (claude mcp serve)? When I found out, I looked into what tools it exposes and noticed one called Task. The premise of this tool is to spin off a sub-agent that will have the same access to tools as your main agent (except that it cannot spawn another sub-task) and reports back the results.

Knowing this is available is super handy when you have a more complex problem that you need a supervisor for. Here's a recent example of how I used this feature to do a deep-dive of the same problem with four different personas:

> Read files in the current directory to deduct a pattern for building Tailwind Plus components. You should spawn 4 sub-tasks with slightly different priorities (e.g. design color export, accessibility export, mobile/responsive expert, overall style expert) and compare their results.

✻ Thinking…

  Now I'll spawn 4 specialized sub-tasks with different priorities to analyze various aspects of the components.

⏺ Task(Design Color Expert Analysis)
  ⎿  Done (24 tool uses · 41.5k tokens · 3m 4.4s)

⏺ Task(Accessibility Expert Analysis)
  ⎿  Done (15 tool uses · 38.0k tokens · 2m 0.0s)

⏺ Task(Mobile/Responsive Expert Analysis)
  ⎿  Done (14 tool uses · 45.5k tokens · 2m 1.2s)

⏺ Task(Overall Style Expert Analysis)
  ⎿  Done (23 tool uses · 58.7k tokens · 2m 22.0s)

It's magnificent and can be done in parallel. This is such a good way to keep the context window of your main task in order and keep Claude focused.

#Tell Claude to Think

Just like us old humans of flesh, Claude is lazy by default. E.g., when you tell Claude to do something, it'll choose the path of least resistance. If you tell it to do at least three things, I bet you it will not do a single thing more.

The same holds true about using extended thinking capabilities. To get better results, especially during planning processes, I recommend telling Claude to ultrathink.

#Edit Previous Messages

Whenever you're too eager to hit send or just feel like a previous message could be more precise to get better results, you can press Escape twice to jump to a previous message and fork the conversation. I use this all the time to refine prompts or simply have Claude try again.

Oh, and if you somehow want to get back to the previous state, you can start Claude with the --resume flag to list all prior threads.

#Yolo Mode

This is probably extremely irresponsible of me, but I mostly run Claude with --dangerously-skip-permissions now (thanks Peter for being a bad influence). It's not necessary for everything, but if I have Claude working on some longer-running tasks, I really don't want to have to focus-switch back to it every minute because it uses a new terminal command.

I have this set up in my zsh profile:

alias yolo="claude --dangerously-skip-permissions"

Funny enough, now that Claude can do whatever it wants, I have been running against the rate limit quota warning much more often too.

#MCP Servers

I'm personally not super excited about MCP servers since none have really brought me any value. In most cases, I find they just use up valuable tokens with stuff that I don't need most of the time. The built-in tools in Claude Code are enough for me (especially when used to the ways I outline here).

In the past, I used Playwright MCP. While it's incredibly fascinating to see Claude start a browser, click buttons, and make screenshots, I found that it mostly just fills the context window very quickly without really making for a better result.

#Claude SDK

Claude has an SDK. It's quite powerful, especially if you're happy to deal with the stream-json output format. But even for small things, being able to pass a prompt directly to claude and have it print back the reply is making for great shortcuts.

As an example, I have a gcauto executable in my path that does the following:

#!/bin/bash
git commit -m "$(claude -p "Look at the staged git changes and create a summarizing git commit title. Only respond with the title and no affirmation.")"

So whenever I commit stuff now, I just stage them and run gcauto.

#Planning Mode

Claude Code has a built-in planning mode, that is triggered when you press Shift+Tab twice. In this mode, Claude won't write to your file system.

I personally like to do planning with another model though, just to spice it up a bit. In the past weeks, I've been using Gemini 2.5 Pro in Google AI Studio directly. I don't really know how that's possible but I don't think I have to pay for it even?

#Let Claude RTFM

A rookie mistake I've made in the beginning is to tell Claude to set up a new project with framework x. It works, sure, but I noticed Claude often using outdated setups and project structures, especially for fast-moving frontend frameworks!

What I do now is ask Claude to read the manual first. This can be done in different ways:

• Paste a link to the docs and ask Claude to read it first
• Ask Claude to find out the state-of-the-art
• Use the Task tool and have Claude conduct deep-research on a particular topic

An example for a deep research task can look like this:

> create a deep research task to figure out how to migrate a website from tailwind 3 to 4 and then present me with a
  short summary of the results

⏺ I'll create a research task to investigate migrating from Tailwind CSS v3 to v4, focusing on the specific context of
  your Tailwind UI codebase.

⏺ Task(Tailwind v3 to v4 migration research)
  ⎿  Done (4 tool uses · 29.9k tokens · 5m 47.6s)

⏺ Summary

  Migrating from Tailwind CSS v3 to v4 involves significant changes but comes with major performance improvements (3.5x
   faster builds) and a better developer experience.

  Key points:
  - Use the automated upgrade tool: npx @tailwindcss/upgrade@next
  - Configuration moves from JavaScript to CSS-first using @theme directive
  - Breaking changes include dropped browser support, new import syntax, and removed deprecated utilities
  - Performance gains: builds are now measured in microseconds
  - Container queries are now built-in (no plugin needed)

  The migration is straightforward with the upgrade tool, but plan for testing time to ensure all components render correctly.

#Voice Input

Apps like Superwhisper make it very easy to dictate a prompt. I found this super effective when I want to write a longer prompt since it'll get the ideas out of my head much faster.

This works incredibly well with any LLM input field, really, because LLMs can usually figure out what you mean even if the transcript is poor and full of mistakes.

#Stage Early, Stage Often

One feature I'm missing in Claude Code is the ability to make automatic file system snapshots. It happens quite often for me that Claude gets a bit too trigger happy and starts to make large changes when I don't want it to. If this happens after I've been getting some good changes, this can screw up the working directory quite a bit.

To circumvent this, I started to stage (i.e. git add) changes early and often. If I'm happy after a turn, I'm usually going to stage everything just so I know I can easily revert to it later.

#Git Worktrees

I am so obsessed by Claude Code that I now have at least two working trees of every major project I work on on my machine. This allows me to have Claude running on two different problems in the same repository.

It's very easy to set up, too! It's like creating a branch but the code will be in a different directory. Inside your git repository, run:

git worktree add ../tailwindcss.com-2 chore/upgrade-next

And, voila, you now have another working directory for Claude Code to go absolutely feral in.

#Experiment with One-Off Work

With AI, code is becoming really cheap. This means that you can now build stuff that you only ever use once without feeling bad about it. Everything that you wish would make your current task easier can just be created out of thin air. Here are some examples of things I built recently that would never have been worth my time before coding agents:

• A dashboard that visualizes my current progress during a large migration at work
• A chrome extension that shows me which version of Tailwind CSS a website is using (or, god-forbid, whether it isn't using Tailwind CSS at all)
• A CLI and backend to upload Claude Code transcripts to be shared publicly
• A CLI to sum up my Claude Code API costs to see how much value I get out of the Max plan (oh so much...)
• An Electron app that experiments with Claude Code inside a git GUI

#If Possible, Don't Attempt to One-Shot

I'm currently focused on a large-scale change that requires me to touch many Tailwind Plus components in the process. My naive first idea was to create an amazing, thought-out prompt with a lot of detail that can surely make the AI do all of this in one go... That surely must be possible, right?

Well, spoiler alert but I failed miserably with this approach. Not only did it not do what I wanted it to do in the first place, it also made it impossible for me to review the changes or make any meaningful changes. I had to start fresh.

This time I asked Claude Code questions about the problems first. We discussed possible changes before writing any code. Only when I felt certain it knew what I wanted, I let it change one component. After some testing and feedback, I let it do two more. Then another five until I finally let it fan out and do the remainder of the work.

While this obviously wasn't as spectacular as creating the perfect prompt, it got me to the end result much faster and with tighter feedback loops and supervision. I still was able to save so much time compared to doing this change by hand across hundreds of different components.

This might very well be an issue of me holding it wrong. I've been seeing a lot of other people claiming to be successful with large one-shot tasks (some of which say that Claude is working for hours straight). However, in my own experience, errors compound quickly and LLMs often loose the thread with a growing context window (and that was with extensive sub-agent calls and even trying Gemini 2.5 Pro). I would love it if someone could share their secrets with me!

#Autonomous Feedback or Human in the Loop?

Related to the issue above, this is also an area I still struggle with. Whenever I see people praising AI agents, they mention the importance of some autonomous feedback cycles so that the LLM can improve the result on their own.

However, I have not been able to do this effectively yet. When I try to set up unit tests or linter feedback, Claude will read it and then suggest everything is working just fine when there still many are issues/warnings left. When I set it up so it can navigate to the page and make screenshots, the context window is quickly full with tokens. Safe to say that the experience hasn't been great for me.

What I like to do instead is just have the dev server running myself. Whenever Claude gets back to me, I take a look at it myself and either copy paste any eventual stack traces as-is, or give some hints as to what I want done differently. I personally find this approach is far more likely to get me to what I want.

#Interrupt Early, Interrupt Often

Whenever I see something going wrong, I usually press Escape to interrupt Claude right away and ask it to revert the latest changes and then guide it more to the direction I want. Of course this only works when you're keeping an eye which I frankly often don't do.

#Configure Your Terminal

Claude Code has a hidden /terminal-setup command that will look at your current terminal setup and make some changes like making it possible to use Shift+Enter to add newlines or register the right bell type. While I wasn't able to figure out the newline thing with Warp, my terminal now beeps whenever Claude needs some human input again.

#Connect Your IDE

Another relatively new feature is that you can connect Claude to see what files you have open in your IDE and read linter warnings, etc. This is set up either when you run claude from within your IDE's terminal, or by running the /ide command. This is handy if you want to tell Claude to "fix my linter issues."

#Custom Commands

You can create custom slash commands in Claude Code. If you find yourself writing a similar prompt more than once, this might be your chance to save even more time.

I have something set up to clean up temporary scripts or helper files that Claude is very eager to create, for better or worse.

#Paste Images into Claude

You can paste in images into Claude Code. Just copy the image directly or drag a file into your Terminal, and it'll be added as an attachment to your next message. I use this sometimes when i want to make small visual changes.

#Conclusion

Claude Code has fundamentally changed how I approach many programming tasks. While it's not perfect and requires adapting your workflow, the productivity gains are real. The key is finding the right balance between automation and human oversight, and being willing to experiment with different approaches.

As AI coding assistants continue to evolve, I expect many of these patterns will change. But for now, these techniques have made my daily coding life significantly more productive and, dare I say, more fun.

This made me realize how common this problem has become—and why it's about to get even more important.

#The Product-Focused Engineer

What they're looking for is what I call the product-focused engineer. These are software engineers with a strong sense of ownership (almost an obsession) over the product areas of the software they're working on.

They're usually characterized by being very proactive with product ideas and opinions, striving for high quality user experiences while being mindful of quick validation cycles. They prefer pragmatic solutions to unblock users and deeply care about making their users successful. I recommend reading Gergely Orosz's article if you want to learn more about these roles.

In past organizations that I've been hiring for, it's always been hard to find these engineers that can connect to your user base and strive to build great product experiences. However, individuals with these traits have been far more impactful for the companies than their peers.

In traditional software companies, teams usually consist of very few of these engineers with more general purpose engineers being the main ingredient and product managers making up for it.

However, we're in a world now where more and more software companies are promising to replace engineers with AI agents over the next few years, so naturally, these structures are changing fast. A single product-focused engineer with AI assistance can now prototype, test, and ship features that previously needed many more people.

#What This Means for Engineering Teams

I'm writing this now because I think the future of engineering teams will center much more around this archetype. High-agency individuals that are striving to build the best experiences possible while making pragmatic trade-offs. They won't need large teams to do what traditional teams were doing before, but instead they'll leverage the new tools available to them and just ship.

My prediction is that the demand for these engineers will skyrocket. Companies that cling to traditional team structures with layers of handoffs will be outpaced by small teams of product-obsessed builders who just ship.

If you're an engineer reading this, the best investment you can make isn't learning another framework. It's developing that product instinct—talking to users, understanding business metrics, and treating code as a means to an end rather than the end itself.

The engineers who thrive in the next decade won't be the ones writing the most elegant code. They'll be the ones who can't sleep because they know exactly which user problem they're solving tomorrow.

#1. Know Your Audience

This is a technique that a more senior engineer at Meta shared with my pretty much after the first document I wrote there. The idea is simple: define the kind of person that your writing is for in advance. And then write only for them.

I use this to get an understanding of what kind of previous knowledge I can assume from the audience and will make me avoid falling into the trap of using too much jargon or technical terms when writing for product teams and customers or being too broad and unspecific when writing for engineers.

The second thing I really like about this technique is that it will give you a cue when your writing is addressing an audience that is too broad. I realized this when I wrote project status reports that were read by my peers but also product managers, designers, and leadership. These reports should not be focused on technical details so instead I split up the report into two parts: one for my team and one for the rest of the organization.

#2. Align on a Shared Goal

This is especially helpful whenever you reach out to someone for the first time. Before going deep into the details, give some context and align on a shared goal.

I use this all the time when I reach out to different engineering teams (within the organization or broader community), especially platform teams (so teams working on frameworks and infrastructure). People on these teams have a lot of requests from other teams so aligning to their goals is going to give you the best chance of getting your request prioritized.

What I do is usually a paragraph with the following content:

1. Some context as to what I am trying to do (what is the feature you are building and why is it important)
2. Connect to their goals (e.g. we want this feature to be reliable, fast, or efficient.)

#3. Follow a Cohesive Train of Thought

Whenever I work on a longer document, I try to come up with one cohesive thread ahead of time that I try to follow with a relatively fixed pacing.

This is a bit hard for me to put in writing since I rely on intuition for this. One example is when I write a proposal for a new feature, I start with setting up the context and goals first, then explain the problem in more detail, then discuss the different solutions considered and narrow down on the proposed one before I conclude with the next steps necessary to move along. I try to give all sections the same amount of detail so that the reader can better orient themselves in the text.

I don't think the actual structure matters too much as long as it's consistent within the piece.

#4. Avoid Hierarchical Components

Do you know the feeling when you read a book and it lingers in your mind for months afterwards? This happened to me this year with The Courage to Be Disliked by Fumitake Koga and Ichiro Kishimi. This book introduced me to Adlerian psychology and the concept of vertical relationships—relationships with a hierarchical component like boss/employee or teacher/student.

It's hard in a work environment to not have vertical relationships, however I do think that relying on this hierarchy will help you write more effectively. Instead, I try to meet eye-to-eye with the reader and try to write from the same level. Creating a shared goal helps a lot with this.

#5. Do One Level Of Homework

Whenever I write something, I take a few minutes afterwards to think about the immediate next question that a reader might have and then incorporate the answer into the writing. This works great for any documents but is especially helpful when I need to ask for help as it will sometimes even answer the question that I had in the beginning.

I started to call this "doing homework" and my intention is to save time for the reader and thus improve clarity. I need to work hard to only do this for one level, though, since it can be easy to get distracted this way.

#6. Keep It Short and Simple

I used to be really impressed by Software Engineers that write long prose with lots of fancy vocabulary even if I never fully understood what they were trying to communicate. If I don't understand what they are trying to say and it "sound smart", I concluded that I must be stupid.

This, of course, is nonsense and making your readers feel small is not something to aspire to. Instead, I try to keep my writings as inclusive as possible by focusing on simple and concise wording, even if this means that I have to put in more work.

#Conclusion

Effective written communication is hard and the only real way I found to improve them is by practice. The points above might seem trivial to some but they have not always been trivial for me. Who knows, maybe you can try one of these ideas the next time you write something? If so, I'd love to hear about your experience!

#The Archetypes

All of the people that came to mind were very senior engineers that have very specific areas that they excel in. This is typical for Staff level engineers and it's why it's so hard to compare them to each other and to give Senior engineers a clear path to Staff.

There are numerous attempts to define the different archetypes and if you haven't read Will Larson's Staff archetypes before, I recommend you look it up right away. I don't think the specific areas are too important though (e.g. there are different definitions across different companies) and I also think in reality, most people are a mix of all of them.

Here are just some of the archetypes that I have worked with:

• The excitement machine: This is a person that loves the area they work in so much that just talking to them makes you more enthusiastic. They often would work on a prototype for a new feature that would impress the whole organization. They have a unique skill to extrapolate the current trends into longer term visions and also know how to make the next logical step toward that vision. Their excitement helps to align different functions to work towards the same goals.
• The business expert: This person knows the industry they work in by heart. This allows them to make very good tradeoffs between when to focus on technical excellence and when to focus on the business impact. They are usually working really closely with the customers and the sales team and are able to translate the business needs into technical requirements.
• The tech lead: Having built the companies most complex features before, this person has an extremely deep expertise of the codebase. They have also learned, though, that it's not enough to just code solo and now use their experience to work on more strategical planning and mentoring. They bring alignment to the broader organization and help make sure projects are delivered on time and with the right quality.
• The hyperspecialized: This person is so deeply focused in one area that they start to use lingo that only a few people will understand. They are able to connect new problems to past research and will tell you about this one 1992 paper that they feel is massively undervalued.

#What They All Have In Common

After thinking of some concrete examples, I was trying to come up with common traits of these folks, too. I wanted to think of something more actionable than "go find your niche". In my experience, great engineers have the following in common:

• Broad technical knowledge: Being an engineer still means you are thinking about code and so all these folks are obviously very good at that. Even the hyperspecialized person has excellent mental models of areas around them. They all have a strong base for the T-shaped skills model.
• Strong communication skills: When I started out, I never thought how important communication skills are. Just show me some code, everything else is irrelevant, right... right? In reality, this can't be further from the truth. The best engineers I know are able to communicate their ideas in a way that is easy to understand for the target audience. They usually demonstrate their skills by writing technical documents or prepare talks that help shape the direction of the company or industry.
• Large networks: To scale their work beyond themselves, great engineers have built and maintain connections to lots of different people in the organization or the broader industry. They are like Saul Goodman in breaking bad and always "know someone" for whatever problem they face. These networks usually span across the engineering organizations and might contain sales, leadership, or even customers. It takes a village to raise a child, right?

#The Rest?

I had a daunting realization after thinking through the above that I know so, so many great people that did not came to my mind at all when I thought about great engineers. This is odd because these are people that I would immediately hire and that definitely cover the common traits listed above. So why have I not thought about them?

The answer I arrived at is scale: These engineers, while being absolutely amazing individually, do not scale their impact beyond only a few people. Which lead me to my final conclusion: Great engineers have figured out how to scale their work. They do this by influencing the product/technical direction, upleveling others, being role models or simply giving excellent advice. They are the people you look up to for feedback and that will make you better at what you're doing simply by being around them.

Since I started making web apps, many technologies have caused major shifts in how I think about the platform. I began my freelancing projects with a custom PHP stack, but Ruby on Rails and Bootstrap allowed me to ship much faster. I felt a similar empowerment when I started using modern front-end libraries like React and later, full-blown frameworks like Next.js together with TypeScript.

My most recent shift happened when I fully embraced Tailwind CSS for some of my projects. It took some getting used to, but it was incredibly fun to create experiences with it. The success of the Tailwind CSS project, however, proves that I’m not the only one who feels this way!

Because of this, I am beyond excited to join the fantastic team at Tailwind Labs. Together, we’ll make building for the web even more fun and help shape the future of the platform. It’s only getting better from here on.

This was really confusing to me. The more senior folks are supposed to be the teachers, and I am just the student. What is there to learn from me?

However, being fortunate to have been on the other end, I now get it.

Good teachers are not the ones who only preach their own way of thinking. Instead, they will be your peers when exploring the problem and will solve it with you, not for you. In doing so, they will pick up your way of articulating the problem, your way of thinking about the world, your way of approaching the problem, and so much more.

Learning, at its best, is a bidirectional relationship away from any hierarchical structure. Everyone gets better as a result of it.

However, if you work in larger tech companies, you will quickly come into contact with goals like this:

• "We are working on improving our sign-up rate by 20% in the next quarter."
• "The goal of the platform rewrite is to reduce defect rate by 50%."

These numbers seem fine at first but once you start digging into it, you learn how extremely arbitrary these are, because:

• It is entirely unclear to the team how to increase sign-up rate at all.
• The platform rewrite is going to increase reliability, but there is no certainty into how it will affect the metrics.

When I worked on web performance at Meta, I came into contact with this very early and my rational personality was quickly overwhelmed: How can I come up with a number that is truly achievable? Do I need to scope out all exact work streams ahead of time and hope that they are all successful? How are goals like this made?

Luckily, I had an amazing colleague back then who told me the one secret about goals at Meta, which she called the 50-50 goal: Choose a target that feels achievable 50% of the time (so you will have an equal chance of not hitting it). At the time this was confusing but I've seen this used extensively at many platform teams at Meta and only now, after many years, I finally understand why this system works:

• 50-50 goals are about embracing failure: If there's an equal chance of you missing the goal, you set yourself up for failure. And, in this case, that's a good thing! No one actually cared whether the sign-up rate increased by 20%. It's important that it increases at all. The trick is to remove the psychological burden of missing a goal and instead focus on actually driving these goals.
• These goals help with alignment: Setting an ambitious target will make it clear to everyone in the room that they need to get creative. It embraced risk-taking and encourages people to think outside the box.
• It creates excitement across the organization: By choosing ambitious goals, you will more effectively communicate the goal of the project. This helps to get buy-in from other teams and stakeholders and sets the stage for better collaboration.

So, if you ever think about setting a target for your team, think about the 50-50 goal. Oh and don't forget to communicate that it's a 50-50 goal. You don't want to set wrong expectations.

#Most Choices Are Not Permanent

When standing before a hard choice, it's easy to fall into the trap of seeing it as a permanent, life-altering event. This type of thinking has had a huge impact on me previously and made me spiral down the "thinking-train" even more. If I think just a bit more, I might avoid making a big mistake.

In reality, however, most choices are not permanent and it's important to keep that in mind when facing a hard choice. If it's only a temporary choice, it doesn't have to be the best choice, does it?

#The False Dichotomy

We often box ourselves into thinking there is only option A or B. But what if neither option is the right choice at the moment? Take the example of moving to a new house—if neither option feels quite right, perhaps the best choice is to wait.

Decision-making is not just about choosing between given options, though. Instead, we have the power to actively shape those options and the reasons behind our choice.

Not choosing now doesn't prevent you from making a similar choice in the future.

#The "Gut Feeling"

I have a bit of a gripe with this term because while my gut does many great things, it certainly doesn't have feelings. It took me long to understand what is meant by it but I now think a better term would be emotional feeling.

If you have no rational explanation as to why an option is better or worse than the other, but you have a strong emotional feeling, don't undervalue this signal. Emotions have, after all, made humans as successful as they are today.

#Embrace the Complexity

If you haven't seen it, I highly recommend you check out Ruth Chang's talk on how to make hard choices. It has highly influenced me in this area. The core takeaway I have from this talk is that I now start to embrace the complexity of hard choices in life and see them as opportunity to steer my life's narrative towards who I truly want to be.

It's extremely freeing to not think of hard choices as confining moments but as rare opportunities that you can use to grow.

Here are a few books I rated 5 stars recently:

• The Three-Body Problem by Cixin Liu
• The Collini Case by Ferdinand von Schirach
• Project Hail Mary by Andy Weir
• Exhalation by Ted Chiang
• Hyperion by Dan Simmons
• Rendezvous with Rama by Arthur C. Clarke
• The Courage to Be Disliked: How to Free Yourself, Change your Life and Achieve Real Happiness by Fumitake Koga and Ichiro Kishimi
• The Wager: A Tale of Shipwreck, Mutiny and Murder by David Grann
• Flowers for Algernon by Daniel Keyes
• Blindsight by Peter Watts

Last update: Aug 11, 2024

Update: Well, turns out there is actually quite good documentation on that API in the Cloudflare API Docs 🙃.

#1. Bundle your Worker

If you already have wrangler set up, you can bundle your worker by running wrangler build. This will build the worker into the dist/ folder.

#2. Prepare your Metadata

Worker metadata is a configuration format that contains the runtime info from your wrangler.toml file. You can learn more about it in the Worker metadata docs.

Without any bindings, the minimum metadata might look like this:

{"main_module":"worker.js","bindings":[]}

#3. Upload your Worker

Now upload your worker:

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/workers/scripts/<SCRIPT_NAME>" \
    -H "Authorization: Bearer <CF_API_TOKEN>" \
    -H "Content-Type: multipart/form-data" \
    --form 'worker.js=@"dist/worker.js";type=application/javascript+module' \
    --form 'metadata="{\"main_module\":\"worker.js\",\"bindings\":[]}"'

{
  "result": {
    "created_on": "2024-04-02T21:27:40.527498Z",
    "modified_on": "2024-04-02T21:27:40.527498Z",
    "id": "<SCRIPT_NAME>",
    "tag": "aabbcc",
    "tags": [],
    "deployment_id": "aabbcc",
    "tail_consumers": null,
    "logpush": false,
    "etag": "aabbcc",
    "handlers": [
      "fetch"
    ],
    "last_deployed_from": "api",
    "usage_model": "standard"
  },
  "success": true,
  "errors": [],
  "messages": []
}

Notes on the params:

• ACCOUNT_ID can be found in the Cloudflare dashboard URL
• SCRIPT_NAME is the name of your new worker and will be part of the default subdomain
• CF_API_TOKEN must be an Edit Cloudflare Workers API token

#4. Publish the Worker via Subdomain

The last step is to publish the Worker to be accessible via subdomain. The domain for this will depend on the workers.dev subdomain assigned for your Cloudflare account, e.g.: <SCRIPT_NAME>.myapp.workers.dev.

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/workers/services/<SCRIPT_NAME>/environments/production/subdomain" \
 -H "Authorization: Bearer $CF_API_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"enabled": true}'
{
  "result": null,
  "success": true,
  "errors": [],
  "messages": []
}

Here's a quick guide on how to record performances traces of VS Code extensions:

/Applications/Visual\ Studio\ Code.app/Contents/MacOS/Electron --inspect-extensions=9333

After VS Code is started, you want to head over to Chrome and go to chrome://inspect which should open up a view like this:

From here you want to configure the inspect server that we just started on port 9333. To do this, click on "Open dedicated DevTools for Node", go to the "Connection" tab if that is not open yet, and make sure to add localhost:9333 to the list like this:

Now, head back to the chrome://inspect tab and you should see a new remote target that you can inspect. For me this looks like this:

Clicking this will open a (somewhat reduced) DevTools view. Great! We've almost got it. From here you can go to the "Performance" tab to record a trace. Then, swap tabs to the VS Code window and interact with the extension. Come back later to stop the recording and export it. Voila!

• Avoid big bang releases: With feature flags, you can push out changes regularly without affecting all users at once. This makes it easier to review pull requests since the changes are smaller. No more waiting days or weeks to merge in order to batch changes.

• Reduce risk: New features can be released to a small percentage of users first. If issues come up, simply turn off the flag before rolling out widely. This protects your whole user base from potentially breaking changes.

• Enable experimentation: By targeting feature flags to different user segments, you can run A/B tests and collect data on how new features are performing. This allows you to validate ideas before fully releasing (and allows you to collect awesome graphs for your next review period 😉).

• Simplify rollbacks: If a new feature causes problems after being released, you can instantly roll back by disabling the flag (often referred to as a kill switch). This is especially handy if you can remotely control those flags.

• Improve code hygiene: Make sure to clean up unused flags over time. Centralize flags in one place like an enum to avoid combinatorial complexity.

Feature flags don't have to be complex, either. Something as simple as a config boolean can get you started. And you don't necessarily need third-party tools for simple use cases. Just try it out on your next feature branch!

But have you ever noticed that great engineers ship all the time? They ship, even if the product is not updating. They ship by sharing quick demos and building excitement and urgency by sharing their prototypes with other engineers. I started to refer to this as "demo culture" and it's something you see to great extend in high performing teams.

Demo culture is the practice of regularly sharing quick demos to build hype and validate ideas in the cheapest possible way. It's a way of showing off your work and getting feedback from your team and stakeholders without all the red tape. It's a way to make every team more engineering driven.

So how can you start building a demo culture in your team? Here are a few tips:

1. Share early and often. Someone needs to start setting an example. If you can hack something together 30. The more brittle, the better, so others understand that there's no need for quality.
2. Make it fun. Demos should be engaging and exciting. I like to create little stories of potential use cases to lighten the mood.
3. Keep it short and sweet. Demos should be quick and to the point. If it's over 2 minutes, it's probably too long. Make sure your audience has your attention and make it easy for them to consume the information.
4. Encourage and provide feedback. After your demo, ask for feedback and suggestions. This will help you improve your work and make sure you're on the right track. Similarly, if someone else gives a demo, make sure to share your thought. And do not forget to show them how excited you are about the demo. 🔥

So, the next time your meeting ends 5 minutes early, just share your screen and say "hey I have a quick demo to show you" and start a transformation in your team.

Whenever arguments in video game Discord chats arise about how to optimally play in a certain scenario, people would cite the research made by Theorycraft. But sometimes people insist that playing in a different way is better. Well, you know the internet folks, these people will be called words. One of the words that stuck with me was "Feelscraft". Huh, what an insult!

But what is Feelscraft software? Well, for me it is acting on intuition and experience rather than data and common knowledge when making product decisions. It is shipping a feature even though you do not have the metrics to back it up. And, as usual, I have ambivalent feelings about it.

Much like the Theorycraft folks in the video game scene, I strive to make the best product choices. Working on the most requested feature that is also sure to increase revenue and that has measurable impact on our user base. And, in a perfect world, we also have all the data necessary to make these decisions and there is only one valid way to solve a problem to begin with. However, in reality, this is hardly the case and this is when Feelcraft comes in handy.

I do think that intuition is often overused, though. When it's used, it's very hard to understand why certain choices were done for people outside of the decision metrics process. One example of Feelscraft Software is from my time at Meta when I read a product announcement that stated that a new implementation of an existing feature is being shipped because it shows no regression in usage metrics over the old one. And that after weeks and weeks of improvements on the new implementation... I think that's a low standard for pushing a new product, don't you think?

Another more recent example that I have seen are numerous changes of an LLM prompt in the hope to improve the product. LLMs are inherently prone to variation in their outcome and making decisions on whether a prompt is better than another normally requires thousands and more different samples. That's why we at Cody are investing so heavily into online and offline evaluation methods. Yet, every now and then I see the industry making changes on prompts based on intuition.

I have been guilty, too, of course! In my most recent work on Cody autocomplete I have often made subtle decisions in the because it felt better. Things like setting initial debounce times too low or cut-off ratios too aggressive. However, we had to get the product out in some way or another and only after getting usage we were able to validate these initial assumptions and make informed decisions (which, of course, resulted in my tweaking these values later).

So, the next time you try to understand how a software decision has been made, remember to think about the Feelcraft behind it. 😉

#Mental model

In my mental model, embeddings are used to encode words into meaning. Embeddings are encodings in n-dimensional vector space where every parameter is a signed a specific meaning in the object space.

I can't really imagine n-dimensional vectors but for an embedding system with two vectors, I like to visualize it like this:

terrain (y-axis)
|
|
|             o (mountain bike)
|
|                       o (road bike)
|
|
|      o (horse)
|
|                                    o (car)
|
|
+------------------------------- speed (x-axis)

In this example, each point represents a mode of transportation. Items with similar speed and terrain capabilities are placed closer together. For example, a mountain bike and a road bike are closer to each other because they have similar speeds and are both used on different terrains, while a car is further away since it operates at higher speeds on more paved terrains.

There are two super-powers from being able to map natural language onto an n dimensional vector space:

• We can use relatively simple vector algorithms to quickly find relevant words. Algorithms like kNN are easy to be optimized with spacial maps so lookup is fast. In our example, we can see that a mountain bike is closer to a road bike than it is to a horse.
• Embeddings compress insanely well. It's entirely possible to compress pages of written language into a vector size of a few hundred vectors.

There are also some downsides, though:

• Training an embedding system is like training any other ML system: It's a complex and expensive task. And even with a fully trained model, you will need a lot of compute power to convert a piece of text into embeddings. That's why it's currently common to outsource embeddings generation to third-party APIs like OpenAI.
• When a model is trained, we don't really know what meaning each value of the vector is assigned to. This makes it hard to understand why a specific pair of text is considered close to each other or not.

#How are embeddings used?

Because of the fast way to find related vector pairs, embeddings are often used to answer search problems. In the current AI discourse, embeddings are used to quickly and efficiently find relevant context in order to put it into the prompt of a large-language model (LLM).

Imagine an AI system to ask questions about your code documentation. We can, ahead of time, create embeddings for every paragraph in the documentation and store it in a vector database (a database that can hold the embedding vectors for us and has some index to efficiently query it. Like the pgvector extension for Postgres).

Now, when the user enters a question in natural text into our AI system, we can find the most relevant paragraphs into our documentation. We usually want to pick as many as we can fit into the prompt of the LLM. The LLM now has an understanding of your documentation when answering the question. Fascinating!

One important thing from the paragraphs above is that we have to split the documentation into meaningful chunks. Since we can only retrieve similarity in windows of this chunk site, you can easily see how important it is to pick a proper system.

#Some links I want to remember

• Getting Started With Embeddings
• MTEB: Massive Text Embedding Benchmark
• MTEB Leaderboard

This is where Jaccard similarity is helpful. Jaccard similarity is a metric to find similarity between two sets of data, typically used for comparing text data.

The equation for Jaccard distance is:

J(A, B) = |A ∩ B| / |A ∪ B|

Here's a simple example in TypeScript to calculate the Jaccard distance between two sentences:

function jaccardDistance(sentence1: string, sentence2: string): number {
  const set1 = new Set(sentence1.split(' '));
  const set2 = new Set(sentence2.split(' '));
  
  const intersection = new Set([...set1].filter(x => set2.has(x))).size;
  const union = new Set([...set1, ...set2]).size;
  
  return intersection / union;
}

The Jaccard similarity comes in handy for finding similar text, like detecting plagiarism or comparing documents. It might not be the most advanced method for text comparison, but it's simple and fast, making it great for many applications.

You can even do some pre-processing on the text to increase its accuracy. The above example is naively comparing words but you could use stemming to make it easier to compare words with the same meaning.

Why not give it a try with some sample texts and see how it works for you?

Inspired by Drizzle ORM and Zod, my goal was to create the table definitions fully in TypeScript code so that I can generate the schema by simply executing the code, and also having an easy way to get the resulting TypeScript definitions:

const loggerConfig = createLoggerConfig("test", {
  message: string(),
  randomNumber: float64(),
  timestamp: datetime(),
});

Here is how I implemented this!

⚠️ We make heavy use of TypeScript generics for this. Make sure to catch up on them first.

We start by implementing the createLoggerConfig function. It's typed as a generic with two generic types:

• The event name: A literal string (test in the example above)
• The properties: An object of field definitions.

One neat thing about TypeScript is that it can infer the type of the generics if they are referenced from the function definition, so if we can do something like this without requiring extra work when someone calls this function:

function createLoggerConfig<E, F>(event: E, fields: F) {
  // ...
}

We can also restrict the type of the event and fields table of that generic so that it only accepts string types for the event name and valid field definitions for the fields:

function createLoggerConfig<
  E extends string,
  F extends { [key: string]: Field<any, any> }
>(event: E, fields: F) {
  // ...
}

We'll look into the return type and the Field type more closely in a second.

#But why do we use generics at all?

You might be thinking: Why all this fuzz when I can also restrict the arguments via normal TypeScript syntax. That's what it's used for, after all!

function createLoggerConfig(
  event: string,
  fields: { [key: string]: Field<any, any> }
) {
  // ...
}

You're right, this does restrict the argument. Remember that one of the foals of this ORM is that we will be able to use the declared schema to also generate a TypeScript object definitions for the logger. The problem without using generics is that you will always have a non-generic return type. So no matter what you pass into the createLoggerConfig, the returned thing won't have any type definition that depend on the arguments.

#Defining the Fields

The ORM I needed to build only had to support a couple of types available in the ClickHouse database, specifically:

• string
• float64
• datetime

If you remember the example snipped above, these should be declared as function calls. Nothing easier than that!

To make sure they retain the type information and later have a way to map to the JavaScript type, here's how I created and typed these:

type FieldType = "string" | "float64" | "datetime";

class Field<T extends FieldType, JST extends unknown> {
  constructor(public type: T, public jsType: JST) {}
}

function string(): Field<"string", string> {
  return new Field("string", "");
}

function float64(): Field<"float64", number> {
  return new Field("float64", 0);
}

function datetime(): Field<"datetime", Date> {
  return new Field("datetime", new Date());
}

The only thing that is a bit odd here is that we define both a T on the field, which maps to the literal of the ClickHouse type, and a JST which maps to the equivalent of the type that we want to be using in TypeScript when we create entries for this logger config.

We also assign a placeholder value to the JS type and store it as a public member of the Field class. This is perhaps unexpected (and maybe even unnecessary? Let me know!) but I found this to be useful to later access the TypeScript type from the field definition.

#Return type

One thing that we have not specified yet is the return type of createLoggerConfig. To make it easier to later add implementations to the schema, I decided to create a class for this:

class LoggerConfig<
  E extends string,
  F extends { [key: string]: Field<FieldType, unknown> }
> {
  constructor(public event: E, public fields: F) {}
}

With this we can change the initial createLoggerConfig function to do something like this:

function createLoggerConfig<
  E extends string,
  F extends { [key: string]: Field<any, any> }
>(event: E, fields: F): LoggerConfig<E, F> {
  return new LoggerConfig<E, F>(event, fields);
}

#✨ The magical Infer<>

As mentioned in the beginning, one goal of this exercise was to later be able to map the schema declaration to a TypeScript object type which, for the example above, should look like this:

interface Test {
  message: string;
  randomNumber: number;
  timestamp: Date;
}

This way, when inserting new rows into the logger table, we can leverage the TypeScript type safety and get helpful errors if we're passing invalid values.

In Drizzle and Zod, this is done by a magical Infer type that can be used like this:

const loggerConfig = createLoggerConfig(/* insert config from above */);

type Test = Infer<typeof loggerConfig>;

But how do we implement this Infer<T> type?

Turns out, it's possible to do this by combining a few TypeScript features:

• We rely on the generics that are passed from the createLoggerConfig call.
• We use keyof to get all keys (properties) from the fields property inside the logger config
• We use mapped types to map over each of the fields and access the public jsType property we set earlier

If this sounds super confusing to you, you're not alone! Here's what I ended up with:

type Infer<T extends LoggerConfig<any, any>> = {
  [Property in keyof T["fields"]]: T["fields"][Property]["jsType"];
};

Pretty awesome! If we wire everything up together and use the power of the TypeScript IDE integrations, we can see hover over the inferred type and see that it works as we expect it to:

Check out the TypeScript playground to play around with it yourself!

This is a list of features that are perhaps less known about but also quite powerful:

• Materialized Columns: This feature allows you to add new columns (which, given the fact that ClickHouse is column based, is very cheap) that derive the data from existing fields. You can imagine a generic log table with a json text field and you want to extract a specific field from the JSON into a custom column. With this feature, you can start your log table in an unstructured form and gradually migrate to a schema over time. Check out this video from Altinity for more informations.
• TTL: ClickHouse allows you to define how long data inside tables and even specific columns is being retained. I think this is an amazing feature for sensitive data, ensuring the data is only retained as long as it is necessary for analytical purposes.
• Automatic schema inference from JSON: Granted, this is a very niche feature but I assume it could be amazing in combination with materialized columns to gradually and automatically convert an untyped JSON payload into a typed column structure.
• Quotas: A feature to allow you to limit resources in a multi-tenant ClickHouse deployment. You don't care about it until you absolutely need it, and here you just get it for free.

• Accessibility: Making web apps accessible because it’s so easy with the Web fundamentals to break things.

• Bundle coverage: A lot of the code that is shipped in today’s bundles (CSS, JS, etc.) is not needed for the first render.

• Data waterfalls: Waterfalls is a term used to describe serial loading dependencies. E.g. to render a list of users we first download the list component, wait for it to load, then the list component makes a request to an API, waits for it to load, etc.

  This is the number one issue that I have seen causing websites to be slow. It often manifests itself as a myriad of uncontrolled loading states that sometimes end in another loading state popping up. 😵‍💫

  An interesting observation: Most applications could be able to resolve all the data needed for the initial page load on the server side based on the URL, params, and authentication tokens.

• Overfetching/underfetching: A client should only ever get as many data as it needs to render. Anything more is not needed and everything less is not enough.

• Interaction delays: If I interact with an item on the website, it should show an instant response.

• Layout shifting: Once the first elements on a website are shown, you don't want to have them jump around. This only causes confusion to the user and results in a poor experience.

• Developer experience: I think this term is often overused but the current way we write apps is definitely not the end game. We need constant improvements to the tooling because the cost of building is still way too high.

• Hydration: When you have a server-rendered HTML page and it needs to become interactive ASAP.

• Reliability: A meta-term that is all about knowing if your app functions. There are many vectors this can be done, however easy mechanisms also have a weak correlation to actual user problems.

  • Error handling/tracking. Unfortunately knowing that an error was thrown does not often relate to a broken website—Is the error recoverable by a user or is it crashing the whole page?
  • Browser crashes/freezes/loops
  • Uptime
  • Tracking core interaction uptime

• Performance: This is a very convoluted term that justifies it’s own note. Until then, here are some thoughts:

  • Measuring page loads is usually simpler than measuring interactions (navigations, popups).
  • You can measure performance in a lab but this will only ever be a proxy to the real-user performance metrics (aka RUM—Real User Monitoring).

• Efficiency: Another meta-term for a few lower-level optimzations that rarely cause problems (but when they do, they are noticeable):

  • Memory usage
  • Heavy CPU usage
  • Uncontrolled scheduled tasks (e.g. setInterval)
  • Browser rendering issues
  • Network/IO overhead

• Testing: While software testing is hard in every environment, front-end has a couple of special complexity with things like visual regression testing, accessibility testing, the reliance on a backend API, or the flakiness of browser instrumentation.

• Observability: Knowing how your app functions is a complex problem in itself. Traditionally, the web platform was very limited in how much data we have available with a big focus on analytics. Lately there have been a few amazing developments though:

  • Async Context is a recent proposal to bring zones.js to the platform which will allow for easer tracing APIs in the future.
  • JavaScript Self-Profiling API brings process sampling features to the web platform.

Inspired by Josh Branchaud’s til, Lee Byron’s til, and Shawn Wang’s Learn In Public.

All these parallel steps can lead to slow and unresponsive interfaces and unhappy users, so let’s learn how we can fix this.

#Scheduling in User Interfaces

Our users expect immediate feedback. Whether they are clicking on a button to open a modal or adding text to an input field, they don’t want to wait before seeing some kind of confirmation. For example, the button could show a modal and the input field could display the key that was typed.

To visualize what happens when this is not the case, let’s take a look at the demo application that Dan Abramov presented at his talk, Beyond React 16, at JSConf Iceland 2018.

The application works like this: The more you type into the input below, the more detailed the charts below will get. Since both of the updates (the input element and the chart) run at the same time, the browser has to do so much computation that it will drop some frames. This leads to noticeable delays and a bad user experience:

However, a version that prioritizes updating the input with new keystrokes will appear to the end user as though it’s running a lot faster. This is because users receive immediate feedback even though the same computation time is required:

Unfortunately, current web user interface architectures make it non-trivial to implement prioritization. One way to work around this problem is by debouncing the chart update. The problem with this approach is that the charts still render synchronously when the debounced callback fires, which will again cause the user interface to be unresponsive for some time. We can do better!

#Browser Event Loop

Before we learn more about how proper prioritizing of updates can be achieved, let’s dig deeper and understand why the browser has issues with these kind of user interactions.

JavaScript code is executed in one thread, meaning that only one line of JavaScript can be run at any given time. The same thread is also responsible for other document lifecycles, like layout and paint.¹ This means that whenever JavaScript code runs, the browser is blocked from doing anything else.

To keep the user interface responsive, we only have a very short timeframe before we need to be able to receive the next input events. At the Chrome Dev Summit 2018, Shubhie Panicker and Jason Miller gave a talk, A Quest to Guarantee Responsiveness. During the talk, they showed the following visualization of the browser’s run loop, in which we can see that we only have 16ms (on a typical 60Hz screen) before the next frame is drawn and the next event needs to be processed:

Most JavaScript frameworks (including the current version of React) will run updates synchronously. We can think of this behavior as a function render() that will only return once the DOM is updated. During this time, the main thread is blocked.

#Problems with Current Solutions

With the information above, we can formulate two problems that we have to solve in order to get to more responsive user interfaces:

1. Long-running tasks cause frame drops. We need to make sure all of our tasks are small and can be completed within a couple of milliseconds so that we can run them within one frame.

2. Different tasks have different priorities. In the example application above, we saw that prioritizing the user input leads to a better experience overall. To do this, we need a way to define the order and to schedule tasks accordingly.

#Concurrent React and the Scheduler

⚠️ Warning: The following APIs are not yet stable and will change. I will do my best to keep this post updated (Last Update: April 2019).

To implement a properly scheduled user interface with React, we have to look into two upcoming React features:

• Concurrent React (also known as Time Slicing). With the help of the new Fiber architecture rewrite that was released with React 16, React can now pause during rendering and yield² to the main thread.

  We will hear more about Concurrent React in the future. For now it is important to understand that when this mode is enabled, React will split the synchronous rendering of our React components into pieces that are run over multiple frames.

  ➡️ With this feature, we’re able to split long-running rendering tasks into small chunks.

• Scheduler. The general purpose cooperative main thread scheduler is developed by the React Core team and makes it possible to register callbacks with different priority levels in the browser.

  At the time of writing this article, the priority levels are:

  • Immediate for tasks that need to run synchronously.
  • UserBlocking (250ms timeout) for tasks that should run as the result of a user interaction (e.g. a button click).
  • Normal (5s timeout) for updates that don’t have to feel instantaneous.
  • Low (10s timeout) for tasks that can be deferred but must still complete eventually (e.g. an analytics notification).
  • Idle (no timeout) for tasks that do not have to run at all (e.g. hidden offscreen content).

  The timeouts for each priority level are necessary to make sure that lower priority work still runs even if we have so much higher priority work to do that the higher priority work could run continuously. In scheduling algorithms, this problem is referred to as starvation. The timeouts give us the guarantee that every scheduled task will eventually run. For example, we won’t miss a single analytics notification, even if we have ongoing animations in our app.

  Under the hood, the Scheduler will store all registered callbacks in a list ordered by the expiration time (which is the time at which the callback was registered plus the timeout of the priority level). Then, the Scheduler will itself register a callback that is run after the next frame is drawn by the browser.³ Within this callback, the Scheduler will execute as many of the registered callbacks as possible until it’s time to render the next frame.

  ➡️ With this feature, we can schedule tasks with different priorities.

#Scheduling in Action

Let’s see how we can use these features to make an app feel a lot more responsive. To do this, we’ll take a look at ScheduleTron 3000, an app I built that allows users to highlight a search term in a list of names. Let’s take a look at the initial implementation first:

// The app shows a search box and a list of names. The list is
// controlled by the searchValue state variable, which is updated
// by the search box.
function App() {
  const [searchValue, setSearchValue] = React.useState();

  function handleChange(value) {
    setSearchValue(value);
  }

  return (
    <div>
      <SearchBox onChange={handleChange} />
      <NameList searchValue={searchValue} />
    </div>
  );
}

// The search box renders a native HTML input element and keeps
// it controlled using the inputValue variable. When a new key
// is pressed, it will first update the local inputValue, then it
// will update the App component’s searchValue, and then it will
// simulate an analytics notification to our servers.
function SearchBox(props) {
  const [inputValue, setInputValue] = React.useState();

  function handleChange(event) {
    const value = event.target.value;

    setInputValue(value);
    props.onChange(value);
    sendAnalyticsNotification(value);
  };

  return (
    <input
      type="text"
      value={inputValue}
      onChange={handleChange}
    />
  );
}

ReactDOM.render(<App />, container);

ℹ️ This example uses React Hooks. If you’re not familiar with this new React feature, take a look at the CodeSandbox code. Additionally, you might wonder why we use two different state variables for this example. We’ll find out why this is needed in a bit.

Try it out! Type a name (e.g. “Ada Stewart”) in the search box below and see how it works:

You might notice that the interface is not very responsive. To amplify the issue, I artificially slowed down the rendering time of the names list. And since this list is big, it has a significant impact on the application’s performance. This is not good 😰.

Our users expect immediate feedback, but the app is unresponsive for quite some time after a keystroke. To understand what’s going on, let’s take a look at the DevTools’ Performance tab. Here’s a screenshot of a recording I made while I type the name “Ada” into the search box:

We can see there are a lot of red triangles, which is usually not a good sign. For every keystroke, we see a keypress event being fired. All three events run within one frame,⁴ which causes the duration of the frame to extend to 733ms. That’s way above our average frame budget of 16ms.

Inside this keypress event, our React code will be called, which causes the input value and the search value to update and then send the analytics notification. In turn, the updated state values will cause the app to rerender down to every individual name. That’s quite a lot of work that we have to do, and with a naive approach, it would block the main thread!

The first step toward improving the status quo is to enable the unstable Concurrent Mode. This can be done by creating the React root with the new ReactDOM.createRoot API like this:

- ReactDOM.render(<App />, container);
+ const root = ReactDOM.unstable_createRoot(rootElement);
+ root.render(<App />);

However, enabling Concurrent Mode alone will not change the experience in our case. React will still receive both state updates at the same time, so there’s no way of knowing which is less important.

We instead want to set the input value first so that we only need to update the search box in the beginning. Updates to the search value and our analytics notification should happen later. To do this, we’re using an API exposed by the Scheduler package (which can be installed with npm i scheduler) to enqueue a lower priority callback:

import { unstable_next } from "scheduler";

function SearchBox(props) {
  const [inputValue, setInputValue] = React.useState();

  function handleChange(event) {
    const value = event.target.value;

    setInputValue(value);
    unstable_next(function() {
      props.onChange(value);
      sendAnalyticsNotification(value);
    });
  }

  return <input type="text" value={inputValue} onChange={handleChange} />;
}

Inside the API we’re using, unstable_next(), all React updates will be scheduled with the Normal priority, which is lower then the default priority inside an onChange listener.

Indeed, with this change, our input box already feels a lot more responsive, and frames no longer get dropped while we’re typing. Let’s take another look at the Performance tab together:

We see that the long-running tasks are now broken down into smaller ones that can be completed within a single frame. The red triangles that indicate frame drops are also gone.

However, one thing that is still not ideal is that the analytics notification (highlighted in the above screenshot) is still executed with the rendering work. Since the users of our app do not see this task, we can schedule a callback with an even lower priority for that:

import {
  unstable_LowPriority,
  unstable_scheduleCallback
} from "scheduler";

function sendDeferredAnalyticsNotification(value) {
  unstable_scheduleCallback(unstable_LowPriority, function() {
    sendAnalyticsNotification(value);
  });
}

If we now use sendDeferredAnalyticsNotification() in our search box component and take another look at the Performance tab with this change and scroll toward the end, we’ll see that our analytics are now sent after all rendering work has completed, and so all the tasks in our app are perfectly scheduled:

Try it out:

#Limitations of the Scheduler

With the Scheduler, it’s possible to control in what order callbacks are executed. It’s built deep into the latest React implementation and works out of the box with Concurrent mode.

That said, there are two limitations of the Scheduler:

1. Resource Fighting. The Scheduler tries to use all of the resources available. This causes issues if multiple instances of a scheduler run on the same thread and compete for resources. We need to ensure that all parts of our application will use the same instance.
2. Balancing user-defined tasks with browser work. Since the Scheduler runs in the browser, it only has access to the APIs the browser exposes. Document lifecycles like rendering or garbage collection can interfere with the work in an uncontrollable way.

To remove these limitations, the Google Chrome team is working together with React, Polymer, Ember, Google Maps, and the Web Standards Community to create a Scheduling API in the browser. What an exciting time!

#Conclusion

Concurrent React and the Scheduler allow us to implement scheduling of tasks in our applications which will allow us to create highly responsive user interfaces.

The official release for these features will likely happen in Q2 2019. Until then, you can play around with the unstable APIs, but be aware that they will change.

If you want to be among the first to know when these APIs change or when documentation for the new features is written, subscribe to This Week in React ⚛️.