Álvaro Cuesta | All

Why I built my own timeline

2026-04-12T00:00:00Z

I recently launched my timeline or, as we used to call it, my microblog. It is not all that different from ~~Twitter~~ X or Mastodon, which raises an obvious question: why build this instead of using an existing social media platform?

It was not really a conscious choice so much as something that... happened.

Making my personal notes public

I have been building my own website for a while now (with Xenon SSG¹), and I wanted to have a place where I could share my thoughts and updates in a more casual way, without the pressure of writing a full blog post.

My goal was clear: I wanted a ledger of my thoughts, ideas, and updates. Nothing more. Nothing less. But... why not share it with the world in the process?

Since I had already done a lot of work on the blog system, adding a new section for my timeline was not a big deal. But it is still more work than posting on an established platform. So, is it worth it?

Asocial media

"Why not Twitter" may be obvious to some, but Mastodon or BlueSky are often framed as the alternative. I dislike both, though not only for the reasons you might expect (censorship, moderation, addictive design, etc.).

I think the social angle fundamentally taints the experience. Followers, likes, retweets, and all that jazz create a dynamic that is not conducive to genuine self-expression. They create a feedback loop where you are constantly trying to optimize for engagement rather than simply sharing your thoughts and updates. Gamification at its finest: say what you are supposed to say, and earn those juicy Internet Points™.

Social is not inherently bad, and you might think you are immune to it, but humans interact with websites the way they are designed to be used, just as we behave in public the way we are expected to. We play a role, and we do so subconsciously. If you give us a platform designed for social interaction, we will use it socially. If you give us a platform designed for reflection, we will reflect on the ideas presented.

Friction is good

Social media platforms are designed to be as frictionless as possible, to keep you engaged and coming back for more. That only exacerbates the social problem. It becomes too easy to react without giving ideas the thought they deserve. You do not need to react, but you are absolutely encouraged to do so.

I believe that a little friction can be a good thing. It gives us a moment to pause and reflect before we react. It allows us to think about what we want to say rather than blurting out the first thing that comes to mind. Limitations breed creativity, and friction breeds quality.

In a world flooded with information and constant updates, having a space that encourages thoughtful reflection can be refreshing. It can help us to slow down and appreciate the content we are consuming, rather than just mindlessly scrolling through an endless feed.

And I built my timeline with that in mind. It is easy for me to post, but not too easy.

My content is mine

...and I am obsessed with my data.

My mind is busy (well, whose isn't?) Over time, I built systems to keep myself organized. As a software engineer, I naturally gravitate toward Git² as a platform. It has become my second brain: a place where I store notes, ideas, and updates, where I can look back and see how my thoughts evolve over time.

So it has always felt wrong to keep part of my thoughts and updates on a platform I do not control. I want all my content in one place, where I can access it, edit it, and share it as I see fit. I do not want to be at the mercy of algorithms or platforms that can change the rules at any time, or worry about my content being deleted, censored, or lost.

I have been migrating more and more of my infrastructure and workflows to Git repositories. Deploying a new domain is as simple as changing a few lines in a config file and pushing to GitHub, and automated workflows handle the rest. I can easily back up my content, and I have a clear history of every update. It is a system that works well for me.

So it felt natural to build my blog and my timeline on top of it. All the source files for my blog and my timeline are just Markdown files in a Git repository. I can edit them, organize them, and publish them from GitHub's web UI or my local Git client.

"But isn't GitHub just another established platform?" Well, yes, but Git itself gives me an exit. I can choose to store my data on GitHub and publish it on Amazon's servers, and if GitHub ever becomes a problem, I can migrate to another Git hosting service or even self-host it. That is the nice thing about Git being a distributed version control system: the repositories on my computer are just as valid as the ones on GitHub's servers.

The IndieWeb

Turns out that my goals are not very different from the IndieWeb movement:

The IndieWeb is a people-focused alternative to the “corporate web”.

We are a community of independent and personal websites based on the principles of: owning your domain and using it as your primary online identity, publishing on your own site first (optionally elsewhere), and owning your content.

— indieweb.org

That framing resonates with me because it treats a personal website not as a portfolio or a business card, but as an actual place to live online. A place that can be messy, opinionated, evolving, and fully yours. Not every thought needs to be optimized for reach. Not every update needs to be packaged for a feed algorithm. Sometimes you just want a small corner of the web that answers to you.

That is also why the IndieWeb idea of publishing on your own site first feels so right to me. I want the URL to be mine, the content to be mine, and the surrounding context to be mine too. No algorithmic timeline, no engagement bait, no platform reshaping what the post is supposed to be. Just a home for the most precious thing I have and what makes me, me: my thoughts and ideas.

My timeline is a tiny expression of that. It is not an attempt to build the next social network. Quite the opposite: it is an attempt to have less network and more personal space. A simpler, quieter, more durable way to publish small things without handing them over to platforms whose incentives do not match mine.

And I hope you enjoy it.

Footnotes

Xenon SSG is a React static site generator that aims to radically challenge how websites can be built and maintained. It powers this very website! ↩
Git is a distributed version control system that allows you to track changes in your files and collaborate with others. Think of it as Dropbox for code, on steroids. It is the backbone of many modern software development workflows, and it has become a powerful tool for personal organization and content management as well. ↩

What if you don't need MCP at all? Is #…

2026-04-11T13:21:00Z

What if you don't need MCP at all?

Is #mcp necessary? How #llms already speak the language of code, and what that means for the future of #ai.

Hello, world! This is the first post on …

2026-04-11T11:47:00Z

Hello, world! This is the first post on the timeline.

Short-form thoughts, quick updates, and random musings will live here.

What is AI good for in 2026?

2026-03-14T00:00:00Z

Disclaimer: this post has been hand-crafted by me (and only me), with only very minor editorial assistance from AI, to improve wording and clarity. All em-dashes are mine, and only mine 😉

Me, myself and AI

I have always been suspicious of AI hype, but I am not the kind of engineer who dismisses things outright. I have been following AI for years through hands-on use and plenty of reading across forums and social media. I have seen multiple hype waves come and go, and I have also seen real progress in the field.

What has always bothered me is how many AI people¹ make huge claims about LLMs for software engineering without giving practical examples. You hear "AI is amazing, it can do X, Y, and Z", but rarely see concrete evidence in a real project.

So I kept asking myself:

Are the hype and claims justified?
Is it only useful on small projects?
Is it mainly for junior developers, or can it help experienced engineers too?
Is it just boilerplate generation, or can it solve non-trivial problems?
Does it make experienced developers faster or slower?
Does it make them better engineers, or only faster typists?
Will it hurt long-term maintainability?

In short: are LLMs actually useful in real projects for experienced engineers, or are they mostly just another buzzword in the current AI startup wave?

I wanted to find out with experience, not vibes.

Combating AI hype with experience

I had already used LLMs in personal and professional work, but mostly in limited, tactical ways. I had never really tested them end-to-end, so I gave it a fair shot.

Because I am an open source advocate, and my work is public on GitHub, I am in a good position to share evidence. My goal was simple: fight AI hype with hard data and document where these tools help, and where they still fail.

Here is what the experiment looks like:

I have a personal project (Lambda Musika, code available on GitHub) that I do not think can be classified as common, regurgitated², or just-another-CRUD³-slop.
The project is a web-based music production environment, scriptable with JavaScript and running completely in the browser.
It is still in the early stages, but already a non-trivial codebase with a few thousand lines and multiple features. It is not a toy project, but it is also not a large-scale production system.
Written in TypeScript with React.
My tooling was just GitHub Copilot in VSCode, using GPT-5.3-Codex. I have not tried other models or tools, so I cannot speak for them (yet).
The project is set up with extensive linting and automated testing.
My workflow uses agent mode plus a medium-sized copilot-instructions.md. I will be in the loop at all times (no vibe coding).

I hope this experiment is useful for other skeptical engineers who still want to test whether AI can actually help in real projects.

Where AI surprised me

Experiment 1: replace the editor library

Lambda Musika features a code editor that allows users to write scripts that drive the music generation. I had originally implemented it with the Ace editor, which is mature and widely used. However, I wanted to experiment with migrating to VSCode's Monaco editor, which is more modern and has better TypeScript support.

(Note that this is currently a branch in progress and unmaintained, so the code is not publicly available yet. I will update this post with links once it is ready.)

To achieve feature parity during the migration, I asked Copilot to generate a full inventory of existing editor features and quirks. Then I asked it to (1) migrate to Monaco while preserving behavior and configuration and (2) integrate TypeScript type-checking into the editor, including types from my internal library. It got surprisingly close on the first try.

Experiment 2: refactor internal library into a separate package

As part of the preparation for Experiment 1, I wanted to share types from an internal library with the editor package. This required a significant refactor of the project structure, including setting up a monorepo, migrating to pnpm, and configuring TypeScript paths and build scripts.

Copilot struggled with this one, often getting lost in the details and making mistakes in the configuration, and I had to stop Copilot in its tracks. However, after migrating the project structure and setting up the monorepo's first couple packages myself, it still provided a huge amount of help migrating additional packages.

Experiment 3: build a Vite plugin for the editor types

After the refactor in Experiment 2, I needed to build a custom Vite plugin to serve the internal library types to the editor across packages. This was a non-trivial task that involved understanding Vite's plugin API, configuring TypeScript compilation, and handling different behavior in development and production modes.

In particular, the plugin needed to:

Compile the internal library types using TSC and make it available via import musikaTypes from "@lambda-musika/musika?types" (note the ?types suffix).
Serve and hot-reload the compiled types from a virtual Vite import in development mode.
Emit a static asset with the compiled types in production mode.

Then I needed to integrate the output of this plugin into the editor setup to provide type-checking for user scripts.

Copilot got most of this right on the first attempt with little assistance. I had to correct some details and add some missing pieces, but overall it was a huge time saver for a complex task.

Experiment 4: accessibility improvements

As part of my previous work in Deedmob, I had done extensive accessibility audits and improvements, learning a lot in the process. I had a good mental model of common ARIA issues and best practices for web accessibility.

Accessibility is surprisingly complex and nuanced, and it requires a good understanding of both the technical aspects and the user experience. I wanted to see whether Copilot could help me identify and fix accessibility issues in my project.

One particular aspect that is often overlooked is the accessibility of dropdown menus and other "expandable" UI elements. These can be tricky to get right, especially when it comes to keyboard navigation and screen reader support. There are lots of nuances, like attaching aria-expanded and aria-controls to the right element, managing focus properly, and ensuring that the expanded content is accessible to screen readers.

Lambda Musika features a bottom bar with multiple expandable panels, and I wanted to improve their accessibility. I asked Copilot to audit the existing implementation and suggest improvements, then implement them. It got most of the ARIA attributes right on the first try, including focus management and keyboard navigation (which I did not even ask for!)

It also helped spot some redundant attributes and text content that would have added noise for screen reader users, as well as some missing group roles, which was a nice bonus.

You can see the implementation in commits 0b3795c and 49123ce.

Experiment 5: end-to-end feature implementation

I wanted to implement a new feature from scratch, starting with the design and user experience, then moving on to the implementation and testing.

The feature was to add support for metadata in user scripts, which would allow users to add custom information (like title, author, description...) to their scripts and have it displayed in the UI. This was a non-trivial feature because the scripting system is a bit quirky due to browser limitations, and it required changes in multiple parts of the codebase, including script parsing, editor integration, and the UI for displaying the metadata.

(Code is publicly available in branch feat/metadata, PR#7.)

Experiment 5.1: metadata in comments

The first iteration I asked for was to extract metadata from script comments, which is a common approach in many scripting environments like Strudel. Copilot got the implementation right on its first attempt, but I quickly realized that the approach was suboptimal for my use case.

Experiment 5.2: metadata as exports

This was a perfect opportunity to test the model's ability to adapt and iterate based on feedback. I explained the issues with the comment-based approach and asked it to come up with a better solution. Copilot's response was to migrate the scripts to a CommonJS-like interface (which is exactly what I had in mind!), where the metadata would be defined as an export from the script file.

This meant a significant refactor of the existing scripts (which were mostly written in a simple, ad-hoc style) to support this new module system.

I decided to keep all the existing metadata-handling code and let the model iterate on top of its previous implementation. This way, I could test its ability to adapt and improve without starting from scratch.

The model got the new implementation mostly right on the first try, but after the refactor there was a lot of leftover code from the previous implementation that I had to explicitly ask to be removed. Iteration also generated very similar functions that should have been part of the same metadata pipeline. For example, it created ad-hoc functions for each metadata field instead of a unified approach that handled all fields consistently. This was a bit of a mess, but it was still a huge time saver compared to doing the whole thing myself, since the model was able to fix the issues once I pointed them out.

Additionally, the model did not really handle the user-facing documentation updates properly: it generated documentation, but often forgot to update it as we iterated on the implementation, and it ended up reflecting implementation details that were irrelevant to users.

Experiment 5.3: use metadata for filename generation

After the migration to the new metadata system, I wanted to make use of the metadata for something practical. One idea I had was to use the title from the metadata to generate more human-friendly filenames for the scripts when they are exported or saved. For example, instead of exporting a script as script-20260314.musika, it could be exported as Author - Title.musika based on its metadata.

This was a relatively simple change, but it required understanding the new metadata structure and integrating it into the export logic. I asked Copilot to implement this feature, and it got it right on the first try without any guidance, which was a nice surprise. It handled all the edge cases gracefully (like missing metadata fields, multiple metadata fields like multiple authors, etc.), which showed an impressive understanding of the task.

One aspect that left me a bit unsatisfied was that the model opted to implement filename sanitization manually instead of reusing an existing library.

Experiment 5.4: add metadata panel in the UI

Finally, I asked Copilot to add a human-friendly metadata panel in the UI to display this information. The feature is currently stuck in a draft PR because the generated UI was not up to my standards, and I have not yet found the time to iterate on it. The implementation was mostly correct, but the visual design was not good enough for my taste, and I did not want to merge it as is.

The generated UI was functionally correct but visually poor, which is not surprising given LLMs' limitations with visual design. Iterating on the visual issues did not work well, and it often generated ad-hoc solutions that were inconsistent with the rest of the UI or were contrary to best practices.

What AI still gets wrong

Good coder, bad engineer

LLMs are very good at writing code, but still weak at engineering.

What I mean is: they can produce working code, but they often miss the bigger picture: (1) how code fits into the system, (2) how it will be maintained, (3) how it will evolve, and therefore (4) which architectural and design tradeoffs to make.

Some actual drawbacks I experienced:

It had trouble with architectural decisions, often making suboptimal choices that I had to correct as seen in Experiment 2.
It often duplicates logic instead of abstracting it. I frequently saw near-identical code blocks side by side with tiny variations that I had to abstract manually or ask the model to abstract.
It often writes tests that assert too many concerns at once. Asking it to split tests and improve naming helps, but still requires supervision.
Comments and test names often explain "what" but not "why"⁴. Newer models generate fewer useless comments (good), but often swing too far toward under-commenting (bad).

I wonder if these are particular tendencies in GPT-5.3-Codex, Copilot, or if it's a common issue in the current state of AI-assisted coding.

Diligent but not smart

Current models follow instructions very well, but they do not reliably reason about context and consequences. They execute what you ask, often literally, without strong critical judgment about what to avoid. That means they can produce valid code that is still the wrong strategic choice.

Sloppy before lazy

Models tend to reimplement code that already exists in the project instead of reusing it. Sometimes that is fine, but often it creates duplicate logic and avoidable technical debt.

They also show a kind of NIH (Not Invented Here)⁵ behavior with ecosystem tooling, rebuilding things that mature libraries already solve. Adding dependencies is not always right, but this is a tradeoff call LLMs still struggle to make.

Not visual thinkers

They are weak at visual work. They can generate UI code, but they are still poor at making interfaces actually look good or improving them through iteration. Feeding them images of the current state and asking for improvements does not work well.

This limitation showed up very clearly in Experiment 5.4.

I wonder if this is a fundamental limitation of LLMs, GPT-5.3-Codex in particular, or just a sign that we haven't yet found the right prompting strategy.

When "documenting" is not "documentation"

They can output documentation, but they are still inconsistent at producing useful documentation. Without guidance, they often produce too much or too little, and they miss key project-specific details. Unimportant quirks and implementation details are often over-documented, while important design decisions and tradeoffs are under-documented or not documented at all. In user-facing documentation, they often focus on implementation details instead of user needs and mental models.

In particular, I noticed they tend to replicate and reword your original instructions instead of documenting the actual information that would help newcomers understand the code, the project, or the rationale behind decisions. This is a problem because it creates a false sense of security, and wastes the reader's time.

Best practices I learned

Static types are a must

LLMs are much more effective when working with statically typed languages. The type system provides a strong safety net that allows the model to experiment and iterate with less risk. It also provides a clear contract, which helps the model understand structure and intent more reliably.

TypeScript in particular proved essential for this experiment, and working with it made me appreciate it even more than I already did.

Copilot instructions

Having a good copilot-instructions.md file is a game changer. It lets you set up shared context and guidelines for the model, which improves consistency and reduces the need for repeated instructions. I highly recommend it for any project using Copilot.

Does the model keep repeating the same mistake over and over? Add a section in the instructions about it, with examples of how to do it right and how to avoid doing it wrong.
Is the model wasting effort in understanding the project structure and conventions? Add a section in the instructions about it, with an inventory of existing patterns, key files and directories, and examples of how to follow them.
Do you want the model to follow a certain workflow or process? Add a section in the instructions about it, with a step-by-step guide and examples of how to execute it.

To top it off: you can ask the model to improve the instructions themselves! This is a great way to keep them up to date and relevant as the project evolves.

See the latest version of Lambda Musika's copilot-instructions.md file for a practical example of how I use it in my project.

Affordances and guardrails

It is very important to have good affordances and guardrails when using LLMs. This means having a solid test suite, good linting, and, in general, a workflow that allows you to quickly catch mistakes and prevent wasteful detours.

These tools are not just safety nets, but also enablers. They allow the model to experiment and iterate without your explicit supervision on every change. They also make it easier to trust the model, which can lead to faster development and more ambitious use of AI assistance.

This was especially visible in Experiment 5, where linting and tests helped catch regressions quickly while we iterated across parser, editor, and UI layers.

Human in the loop

LLMs are not yet at the point where you can just ask them to do something and forget about it. You need to be in the loop, reviewing their output, guiding them with feedback, and making strategic decisions about when to accept or reject their suggestions.

Always keep human review and judgment in the decision path, especially for architectural choices, risk acceptance, and quality tradeoffs.

Take every opportunity to steer the model toward better choices. Do not just ask it to do something and hope for the best. Review its output, give feedback, and iterate as it goes. Otherwise, the model might get trapped in a local minimum of bad choices, wasting time and effort on suboptimal solutions that a bit of guidance could have avoided.

The shift from Experiment 5.1 to Experiment 5.2 is a good example: the first solution worked, but only human review surfaced that it was the wrong fit for user experience.

Preparation before execution

One strategy I found useful for end-to-end, large-scale tasks is to first ask the model to explore the code, prepare, and document a guide for the task. Spend some time reviewing that guide, giving feedback, and iterating until you are happy with it.

Once the guide is ready, start the session from scratch (to clear the model's context window) and let it execute the task following the guide. This way, you can ensure that the model has a clear plan and understanding of the task before it starts writing code, which can lead to better results and fewer mistakes along the way.

Context pollution⁶ is a real issue, and starting with a clean slate after preparation can help mitigate it.

This strategy was really helpful in Experiment 1, where the task was complex and required a good understanding of the project and the desired outcome.

Copilot as Co-Reviewer

One workflow I brought over from my day job is using Copilot in GitHub PRs to review code, whether written by me or generated by the model. This creates an interesting meta-dynamic: you are asking AI to review AI-generated code. It sounds circular, but in practice it still catches real issues you would otherwise miss.

Copilot is nowhere near a perfect reviewer. It is hit-or-miss, and will sometimes insist on suggestions that are odd (or plain wrong). But it has caught genuine bugs and inconsistencies that I (and other human reviewers) had missed. When the same wrong suggestion keeps coming back, copilot-instructions.md (see above) is the right tool to reduce noise, and one-off bad suggestions are fast enough to dismiss that the net cost is still positive.

Does it replace human reviewers? Not at all. But it works well as a first-pass filter, catching the obvious issues early so that human review time can focus on what actually requires human judgment. At work, this pattern has measurably shortened our PR async review cycles.

Conclusion

My current take: AI is already a strong coding assistant, but still a weak software engineer.

I used to be firmly in the "AI is impressive but it might be making me slower" camp. That is changing. Rapidly.

If you are skeptical, my advice is simple: run your own controlled experiment on a real project following the best practices above. That is where the signal is, and how you will find out for yourself what works and what does not.

I expect these tools to keep improving quickly, but today they still need an experienced human in the loop. Let's see if that changes in the next few months and I get the opportunity to turn this post into a series!

Footnotes

Not AI researchers or practitioners, but rather those who loudly praise LLMs without backing it up. ↩
The criticism that LLMs are only useful for boilerplate and repetitive tasks since they only regurgitate their training data. ↩
Acronym for Create, Read, Update, Delete. Apps that are mostly boilerplate, with no logic beyond basic database operations. ↩
The "what" is usually visible in the code itself. The "why" (and especially "why not") is what actually drives maintainability, and is consistently missing from both AI-generated and junior-written comments. ↩
The tendency to rebuild solutions from scratch just because they were not created in-house. ↩
Long sessions accumulate stale, irrelevant, or conflicting details that gradually degrade model performance and decision quality. ↩

Your React refs might be breaking someone else's code…

2025-08-23T00:00:00Z

...and someone else's refs might be breaking yours! 😱

React `ref` callback guarantees

React's ref callbacks provide an important guarantee (emphasis mine):

When you pass a different ref callback, React will call the previous callback's cleanup function if provided. If no cleanup function is defined, the ref callback will be called with null as the argument. The next function will be called with the DOM node.

This means that the following code:

function MyDiv({ children }: { children?: ReactNode }) {
  const ref = (div: HTMLDivElement) => {
    console.log("Inserted", div);
    return () => {
      console.log("Removed", div);
    };
  };

  return <div ref={ref}>{children}div>;
}

function App() {
  const [count, setCount] = useState(0);
  const increaseCount = () => {
    setCount((count) => count + 1);
  };

  return (
    <div>
      <MyDiv>Clicked {count} times.MyDiv>
      <button onClick={increaseCount}>Increasebutton>
    div>
  );
}

CodeSandbox

...will log:

Inserted on initial mount, when the
HTML element is inserted into the DOM.
Removed and then Inserted on every
Removed on unmount, when the
HTML element is removed from the DOM.

We can fix this issue by making the function reference stable across renders, for example, by wrapping it in useCallback:

function MyDiv({ children }: { children?: ReactNode }) {
  // Now `ref` will be stable across renders since`useCallback` memoizes it
  const ref = useCallback((div: HTMLDivElement) => {
    console.log("Inserted", div);
    return () => {
      console.log("Removed", div);
    };
  }, []);

  return <div ref={ref}>{children}div>;
}

function App() {
  const [count, setCount] = useState(0);
  const increaseCount = () => {
    setCount((count) => count + 1);
  };

  return (
    <div>
      <MyDiv>Clicked {count} times.MyDiv>
      <button onClick={increaseCount}>Increasebutton>
    div>
  );
}

CodeSandbox

...which will only log:

Inserted on initial mount.
Removed on unmount.

Notice the callback is no longer called on button clicks.

Merging refs

Just like

has a ref prop to receive React refs, you often need to provide ref props for your own components.

function TextInput({ ref }: { ref?: Ref<HTMLInputElement> }) {
  return <input type="text" ref={ref} />;
}

// Now other components can access the internal  like this:
function App() {
  const inputRef = useRef(null);
  /* ... do stuff with `inputRef` ... */

  return <TextInput ref={ref} />;
}

Low⁠-⁠level UI components often need to use their own refs while also forwarding external ones, like this:

function MyInput({ externalRef }: { externalRef?: Ref<HTMLInputElement> }) {
  const inputRef = useRef<HTMLInputElement>(null);
  /* ... do stuff with `inputRef` ... */

  // How can we pass both `inputRef` and `externalRef` here?
  return <input ref={/* ... */} />;
}

React does not offer a way to set two refs inside the ref property (see facebook/react#29757), which means the community has created many small utility libraries to solve this issue, like this:

import { mergeRefs } from "some-ref-merging-library";

function MyInput({ externalRef }: { externalRef?: Ref<HTMLInputElement> }) {
  const inputRef = useRef<HTMLInputElement>(null);
  /* ... do stuff with `inputRef` ... */

  // Here we pass the combined refs to the underlying input
  return <input ref={mergeRefs([externalRef, inputRef])} />;
}

Someone else's refs might be breaking your code

There are a few interesting use cases for refs. For example, we might want to focus an as soon as it is inserted into the DOM:

function MyInput() {
  const focusInput = useCallback((input: HTMLInputElement | null) => {
    input?.focus();
  }, []);

  return <input ref={focusInput} type="text" />;
}

CodeSandbox

As we saw earlier, React's ref callback guarantees ensure this works flawlessly because the callback is only called once (when the is initially inserted into the DOM). But what happens when we want to support an external ref from props?

import { mergeRefs } from "some-ref-merging-library";

function MyInput({ externalRef }: { externalRef?: Ref<HTMLInputElement> }) {
  const focusInput = useCallback((input: HTMLInputElement | null) => {
    input?.focus();
  }, []);

  return <input ref={mergeRefs([externalRef, focusInput])} type="text" />;
}

CodeSandbox

Since mergeRefs creates a new function on every render, its reference is by definition unstable, causing the same issue we saw earlier. Can we fix it the same way as before?

Well, it depends.

External refs might be breaking your code

Let's fix the issue as we did earlier, by memoizing the merged ref so its reference is also stable across renders:

function MyInput({ externalRef }: { externalRef?: Ref<HTMLInputElement> }) {
  const focusInput = useCallback((input: HTMLInputElement) => {
    input?.focus();
  }, []);

  const ref = useMemo(
    () => mergeRefs([externalRef, focusInput]),
    // (1)
    [externalRef, focusInput],
  );

  return <input ref={ref} type="text" />;
}

Can you spot the issue?

The problem with that code is that you don't control externalRef so, if it is unstable, the dependencies in (1) will invalidate and the memoized function will be recreated. If someone uses your component like this:

function App() {
  const [count, setCount] = useState(0);
  const increaseCount = () => {
    setCount((count) => count + 1);
  };

  return (
    <div>
      <input type="text" />
      <MyInput
        // This ref is unstable!
        externalRef={(input) => {
          console.log(input);
        }}
      />
      Clicked {count} times.
      <button onClick={increaseCount}>Increasebutton>
    div>
  );
}

CodeSandbox

...React will see a new function on every render, and your input will be focused every time the user clicks the "Increase" button.

Of course you could say that your component's consumer is breaking your component's API and they should just in turn memoize their ref callback as well. That's fine, but the problem is that...

Components using your ref are breaking your code

Since you are aware of this issue, you memoize all your callback refs to avoid breaking someone else's code:

import { SomeoneElsesInput } from "some-ui-library";

function App() {
  const [count, setCount] = useState(0);
  const increaseCount = () => {
    setCount((count) => count + 1);
  };

  // We are good citizens and memoize our ref callbacks
  const inputRef = useCallback((input: HTMLInputElement | null) => {
    console.log("This should only log once, on mount", input);
  }, []);

  return (
    <div>
      <SomeoneElsesInput ref={inputRef} />
      Clicked {count} times.
      <button onClick={increaseCount}>Increasebutton>
    div>
  );
}

CodeSandbox

Again, can you spot the issue?

Even if you memoize your callback refs, SomeoneElsesInput might merge them with unstable callbacks (possibly even from third-party libraries) and create unstable callbacks. This pattern is common across React's ecosystem. The worst part is you cannot fix it from userland without hacks—you would need to patch some-ui-library, manually track reference equality to ignore spurious callbacks (which is not always possible) or report the issue and wait for them to fix it.

Technically, merging your refs in this way could be a breaking change per semver, but this hidden interaction often violates semantic versioning guarantees without being obvious. Adding a ref (in your own private code) and merging it with an (already-existing) external ref doesn't seem to affect the public API, does it?

This is not a theoretical concern (guess how I found this issue?)

What can you do about it?

I reported the issue to the fantastic react-merge-refs library, which is widely used in the ecosystem. Unfortunately, many other libraries implement this small utility too and, to my knowledge, none of them correctly handle this case (many don't even support React 19's cleanup functions for refs!).

As we have seen, this leads to code breaking: (1) unknowingly, (2) at a distance, (3) both by the consumer and the provider, (4) in patch releases and (5) without recourse for the affected parties.

So I did what any self-respecting engineer would do: add another library to the mix. I published react-best-merge-refs to handle all these edge cases, with thorough unit and integration tests.

As part of this work, I designed the utility with a very strict API to make it difficult to use incorrectly. In particular:

I only expose useMergeRefs and not a raw mergeRefs that would return an always-unstable merged ref. This makes it essentially impossible to break other people's code.
I changed the API to take a keyed object.
```
// This is my signature.
function useMergeRefs<T>(refs: Record<string, Ref<T>>): Ref<T>;
useMergeRefs({ externalRef, myRef }); // <- usage

// Other libraries usually do this...
function useMergeRefs<T>(refs: Ref<T>[]): Ref<T>;
useMergeRefs([externalRef, myRef]);

// ...or this.
function useMergeRefs<T>(...refs: Ref<T>[]): Ref<T>;
useMergeRefs(externalRef, myRef);
```
In this design, each ref has a unique key associated with it, which allows it to be tracked over time. This makes it very hard to use incorrectly and trigger a situation where an external ref might be made unstable under obscure circumstances.

The problem it solves (and the solution I came up with) is similar to React's key prop.

See my rationale, where I explain why the usual APIs offered by other libraries (either an array argument or a variadic function taking refs) feel a bit footgun-y to me.

I'm not 100% convinced that (2) is the perfect choice, but since the difference in usage is minimal ({} instead of []), I went for it in hopes of learning more through experience. It may only impact efficiency in hot paths, but I strongly believe micro-optimizations should come after correctness. You can always expose an unsafe_mergeRefs if efficiency is critical.

I still believe facebook/react#29757 should be built into the framework: the implementation is very easy to get wrong and can break with React updates (as happened with React 19's introduction of cleanup functions for refs).

If you want a safer way to merge refs today, check out react-best-merge-refs.

Will React ever fix this natively? We can only hope.

(Bonus track) Everything is breaking everything

(The plot thickens.)

I'll leave these as an exercise for the reader but, trust me, they are subtly buggy. Can you spot why?

Exhibit A

function App() {
  const [count, setCount] = useState(0);
  const increaseCount = () => {
    setCount((count) => count + 1);
  };

  // We are good citizens and memoize our ref callbacks
  const inputRef = useCallback(
    (input: HTMLInputElement | null) => {
      console.log(input, count);
    },
    [count],
  );

  return (
    <div>
      <MyInput ref={inputRef} autoFocus />
      Clicked {count} times.
      <button onClick={increaseCount}>Increasebutton>
    div>
  );
}

Exhibit B

function App() {
  const [count, setCount] = useState(0);
  const increaseCount = () => {
    setCount((count) => count + 1);
  };

  // We are good citizens and memoize our ref callbacks
  const inputRef = useCallback((input: HTMLInputElement | null) => {
    console.log(input);
  }, []);

  return (
    <div>
      <MyInput ref={count > 10 ? inputRef : undefined} autoFocus />
      Clicked {count} times.
      <button onClick={increaseCount}>Increasebutton>
    div>
  );
}

Álvaro Cuesta | All

Why I built my own timeline

Making my personal notes public

Asocial media

Friction is good

My content is mine

The IndieWeb

Footnotes

What if you don't need MCP at all? Is #…

Hello, world! This is the first post on …

What is AI good for in 2026?

Me, myself and AI

Combating AI hype with experience

Where AI surprised me

Experiment 1: replace the editor library

Experiment 2: refactor internal library into a separate package

Experiment 3: build a Vite plugin for the editor types

Experiment 4: accessibility improvements

Experiment 5: end-to-end feature implementation

Experiment 5.1: metadata in comments

Experiment 5.2: metadata as exports

Experiment 5.3: use metadata for filename generation

Experiment 5.4: add metadata panel in the UI

What AI still gets wrong

Good coder, bad engineer

Diligent but not smart

Sloppy before lazy

Not visual thinkers

When "documenting" is not "documentation"

Best practices I learned

Static types are a must

Copilot instructions

Affordances and guardrails

Human in the loop

Preparation before execution

Copilot as Co-Reviewer

Conclusion

Footnotes

Your React refs might be breaking someone else's code…

React ref callback guarantees

Merging refs

Someone else's refs might be breaking your code

External refs might be breaking your code

Components using your ref are breaking your code

What can you do about it?

(Bonus track) Everything is breaking everything

React `ref` callback guarantees