Manu Martínez-Almeida — Writing

Qwik: Resumability That Feels Like React

Manu Martínez-Almeida — Tue, 09 May 2023 00:00:00 GMT

Performance is a human problem, not a technology one

The thing I came to believe working on Qwik is that the web’s performance problem isn’t a technology problem. It’s a design and developer-experience problem. Developers, like water, follow the path of least resistance, and in most frameworks the easy way to build something is also the way that ships a slow site. We then tell people to go optimize it afterward, as a chore, trading off capabilities or DX or their weekend to claw the performance back.

I find it more honest to stop blaming developers and fix the path instead. A framework should be designed so the path of least resistance lands you on a fast site by default. You shouldn’t have to be a performance expert to ship a fast page; you should have to work to ship a slow one.

And the thing worth optimizing is almost always JavaScript. Most sites already handle their images and CSS reasonably well, so there’s little left on the table there. JavaScript is where the big wins hide. The difference between a sluggish page and a snappy one is often tens of points of Lighthouse score, and for anyone running an e-commerce or consumer site, that gap is revenue. Resumability is the lever Qwik pulls on exactly that.

The idea: resume, don’t rebuild

Every mainstream framework hydrates. The server renders HTML, then the browser downloads the whole component tree as JavaScript, re-executes it, and reattaches event listeners to reconstruct state the server already had. You pay, in bytes and CPU, to rebuild something you were handed seconds ago.

Islands and partial hydration, the approach Astro popularized, make this better by only hydrating the interactive bits. But each island still has to download and execute its JavaScript before it’s ready, and someone has to draw and maintain those island boundaries by hand.

Resumability skips the rebuild entirely. The server serializes the application’s state and its event wiring into the HTML itself. The browser ships almost no JavaScript up front. Conceptually the app becomes a hashmap: an event on an element points at the one chunk of code that handles it. When you click a button, Qwik reads an attribute on that element, fetches that small chunk, restores the state it captured, and runs it. There’s no global “boot the app” step, because there’s no app to boot.

There’s a neat way to see the flip. In a hydrated app, event handlers are the last thing to become ready, after the whole tree has downloaded and executed. In a resumable app they’re the first. The page is interactive the moment it arrives.

The first version worked; writing it was the hard part

Proving resumability was one thing. The developer experience was another. In that early version the philosophy leaked all the way into the API. You split your code into many small files by hand, you referenced lazy-loadable symbols by name, and you wrote a lot of ceremony to tell the runtime how the pieces fit together. It worked, and it asked too much of the person typing.

My bet was that all of that ceremony could become the compiler’s job. A developer should write something that looks like ordinary React, with components, event handlers, and local state, and the build step should do the hard work of making it resumable. The point of the whole project, after all, was to make the fast path the easy path, and an API that demanded this much manual wiring was the opposite of that.

Making it feel like React

In the design I led, you write a component with handlers and hooks, the way you already think. The magic lives in the compiler.

export const Counter = component$(() => {
  const count = useSignal(0);
  // looks like an ordinary closure; the compiler will extract it
  return <button onClick$={() => count.value++}>{count.value}</button>;
});

The compiler reads the AST, finds every $-marked boundary (a component$, an onClick$), and pulls that closure out into its own module with no dependencies except the variables it closed over. Those captured variables get serialized straight into the HTML. When the user clicks, the runtime loads that one module, restores the state it captured, and runs the handler. Nothing else downloads.

The captured state can be a live signal, so the handler reads and updates a reactive count and the DOM follows along. useSignal lets the runtime make a surgical update to exactly the text node that changed, with no component re-render in the browser. The signal model drew on Solid’s reactivity. The result reads like React and behaves like a resumable app, with none of the manual wiring the first version demanded.

One thing I like about this model over React Server Components: a Qwik component is universal. The same component runs on the server or the client, and the developer doesn’t annotate the boundary. With RSC it’s easy to reach for use client everywhere out of convenience and quietly opt back into shipping everything. In Qwik there’s no boundary to get wrong, because the compiler is the one deciding what crosses it.

Rust and SWC

The optimizer that does all this is written in Rust, on top of SWC. It runs on every build and across large codebases, so it had to stay fast enough to disappear into the dev loop. Rust kept the AST passes quick as projects grew, which matters when the entire premise is that the compiler, and not the developer, carries the complexity.

QwikCity

Later, with Adam Bradley (co-creator of Ionic and Stencil), I worked on the design of QwikCity, the meta-framework that sits on top: routing, data loading, and the conventions that make Qwik a way to build whole sites. That part was a close back-and-forth between the two of us.

Credit where it’s due

I want to be precise about this. The resumability concept, and much of how it works under the hood, including the runtime and the Solid-inspired signals, came from Miško Hevery, the creator of Angular. What I led was the developer-facing redesign and the compiler beneath it: turning closures into independent, serializable modules and working out the reachability analysis that decides what to ship.

The throughline to the rest of my work is that compiler. Make the source look ordinary, push the hard analysis to build time, and let the runtime stay lazy, so the path of least resistance is also the fast one. I’d wired the same instinct into Gin’s router years earlier, and I’d reach for it again tomorrow. If you’re designing a framework, that’s where I’d spend the effort: on the compiler that lets people write the easy thing while you quietly ship the simple one.

If you want the longer version of this argument, I gave a talk on it.

This article has interactive figures — read it on manualmeida.dev.

I Broke My Ankle, Then Rendered It in a Browser

Manu Martínez-Almeida — Wed, 20 May 2020 00:00:00 GMT

In October 2019 I went out for drinks with friends in Kreuzberg, a few minutes from my office in Berlin. I broke my ankle that night. Everything I’d been building stopped at once, and for the first time in years I had nothing to ship.

Fourteen days to think

I spent fourteen days in a Kreuzberg hospital, waiting for the swelling to go down before they could operate. Once I calmed down, it wasn’t all bad. I read the books I’d been meaning to get to, reached out to people I’d lost touch with, designed a tattoo for the ankle, and learned enough German to order a coffee with milk and no sugar.

Mostly, it switched off the autopilot. I’d gone years without a single week away from code, and the quiet was the first chance I’d had to think about what I wanted to build next.

My data was mine, and I couldn’t reach it

The surgery worried me even after the doctors said it had gone well. I wanted a second opinion, and that meant getting my own scans out of the hospital. It turned into a small ordeal. I left with my medical imaging burned onto a CD, then ordered a USB CD reader from Amazon so I could open my own body on my own laptop.

The second opinion sent me straight back to Spain, where my family is. There were real problems: the joint spacing was off, there was nerve damage from the suture, an unrepaired tendon, and a screw sitting in the wrong place. A second surgery fixed it, and I finally found some calm.

Somewhere in that mess the product idea formed. Patients own their medical data. Reaching it, reading it, and sharing it is absurdly hard.

Visualizing my own ankle

With no deadlines left, I opened my laptop and went back to something I hadn’t touched in years: writing rendering code from scratch, the way I used to build game engines. I wanted to see my own scan in 3D, in a browser, with nothing to install. The first time my ankle rotated on screen, rendered from the CD I’d fought to get, I knew this was the thing I wanted to work on.

Figure 1. My own ankle, reconstructed from the CT scan on that CD and ray-cast in the browser. The loose fragments along the right are the displaced pieces of the break.

Rendering gigabytes of voxels in a browser

A CT scan is a 3D grid of density samples, often hundreds of slices deep, which adds up to gigabytes. You can’t download all of it before drawing anything, and you can’t fit all of it in GPU memory. Yet a radiologist expects to spin and re-window the volume with no lag.

The rendering itself is ray casting through a 3D texture. For each pixel on screen, march a ray into the volume, sample density along the way, map each sample to color and opacity, and composite front to back until the pixel goes opaque.

// simplified: march a ray through the CT volume and accumulate color + opacity
vec4 raymarch(vec3 origin, vec3 dir) {
  vec4 acc = vec4(0.0);
  for (int i = 0; i < STEPS; i++) {
    vec3 p = origin + dir * (float(i) * stepSize);
    float density = texture(volume, p).r;    // sample one voxel
    vec4 s = transfer(density);              // density -> color + alpha
    acc.rgb += (1.0 - acc.a) * s.a * s.rgb;  // front-to-back compositing
    acc.a   += (1.0 - acc.a) * s.a;
    if (acc.a > 0.99) break;                 // early ray termination
  }
  return acc;
}

Three decisions made it run in real time on WebGL. We split each volume into smaller blocks, so the GPU only ever held the parts in view and could skip the empty space between them. We quantized the data, including the normal vectors used for shading, to shrink what had to live in texture memory. And we loaded progressively, coarse first and detail as you leaned in, so the first frame appeared fast even on a multi-gigabyte study.

Figure 2. OpenView Health, the free viewer we built on the Sethealth SDK. Slices and the 3D render stay in sync, and you can measure, window, and annotate straight in the browser.

Keeping the data safe by never seeing it

Medical data raises the stakes on security, so we ran end-to-end encryption on the client. A scan never left the device in the clear, which meant we couldn’t read it, and that was the point. The data we never held unencrypted is data we could never leak. That one decision collapsed a large amount of compliance and liability surface into something we could reason about.

What it became

Sethealth shipped as an SDK and a compliant backend across iOS, Android, and the web, and it ran until 2026. The use case that clicked was custom prosthetics. A doctor could shape an implant against a patient’s real anatomy, an engineer could validate it, and the two could hold a precise conversation inside the same 3D view, all running on our SDK.

Figure 3. A custom-implant planning and ordering tool a partner built on the SDK: plan plates, screws, and surgical guides against a real fracture, leave notes, and order the printed parts. The tool is no longer online.

I built it on a simple conviction. Healthcare carries more weight than most software, and patients are the rightful owners of their data even when the system makes that ownership painful to exercise. Sethealth was my bottom-up attempt to hand some of that ownership back.

The deeper lesson came from the ankle. For years I never went a week without coding, and I’d mistaken motion for progress. Stepping back to ask why, and not only how, paid off more than any sprint I can remember. You don’t need to break a bone to get there. Close the laptop for a week and notice which idea refuses to leave you alone.

Building Gin: Simple Over Easy

Manu Martínez-Almeida — Tue, 30 Jun 2026 00:00:00 GMT

In 2014 I came back from San Francisco with no plan and one useful scar: I had seen what small software teams needed from their tools. I had spent a year building SDKs at Joypad and TinySpark after shipping one of my first games. Then I was back in Spain, about to start Telecommunications Engineering, and trying to decide what to build next.

The answer was Fyve, a social network built around people’s interests. I chose Go for the backend because the language felt plain in the right way. Gin started as the web framework for that product, written while I was still learning Go and still deciding what kind of engineer I wanted to be. The code lives at gin-gonic/gin.

Fyve faded. Gin kept going.

Simple over easy

At the time, the Go web framework people kept pointing me to was Martini. I understood why immediately. The README was small, the middleware model felt elegant, and you could get a route responding in minutes.

Martini used reflection-based dependency injection to wire handlers together. That made the first demo feel smooth. It also moved important behavior out of sight. Services appeared in handlers by magic, control flow became harder to trace, and reflection ran on the request path.

I was reading the Go community through Rob Pike’s Simplicity is Complicated lens around then. The line that stuck with me was not a slogan about minimalism. It was the cost model: simple software often takes more work from the person building it so it can take less work from the person using it.

That became the design line for Gin. Easy is what looks good in the first example: fewer lines, nicer syntax, less ceremony on the page. Simple is lower count: fewer moving parts, fewer concepts to learn, fewer exceptions to remember. Martini made the first version easy. I wanted Gin to stay simple after the codebase was old enough to surprise me.

Finding the middle ground

Aristotle’s version of virtue was the middle ground: not too much, not too little. That was the shape of the framework problem too.

Martini gave you too much magic. Go’s standard net/http gives you the honest version of web programming: no magic, explicit control flow, and a handler shape you can hold in your head. But it gives you too little help. You write the same plumbing for route params, request parsing, validation, and responses in handler after handler. None of it is hard. Enough of it becomes noise.

Gin was my attempt to find the useful point between them: keep the request path explicit, run no reflection there, and put the boring work behind one object you can inspect: the Context.

r := gin.Default()
r.GET("/users/:id", func(c *gin.Context) {
    id := c.Param("id")          // path params, no reflection
    c.JSON(200, gin.H{"id": id}) // response rendering, one call
})
r.Run(":8080")

That *gin.Context carries the request, response writer, path parameters, validation helpers, and rendering. You pass one thing around. The obvious operations stay one method call away, while the machinery remains visible enough that you can debug it when production gets weird.

Funny enough, gin.Context shipped in 2014, two years before Go’s standard library had a context.Context. When it landed, we didn’t rename ours — we made gin.Context satisfy the standard interface, adding full compatibility without a single breaking change.

That was the product sense from SDK work showing up in a web framework. Developer experience is a feature when it makes the fast path feel natural.

A router built around a radix tree

The router is where the simplicity line became concrete. Martini could walk a list of regular expressions and ask each one whether it matched. That is flexible. You can make a route match only numbers, or hide extra rules inside the pattern. It is also another language inside your framework.

Gin chose a smaller route language: static segments, named parameters, and catch-alls. That choice made the router faster because it could use a radix tree, the same approach httprouter made popular in Go. More importantly, it made routes easier to reason about. The framework pushed you toward regular paths instead of clever matchers.

Matching /blog/42/comments walks /blog/ down to the :slug node, binds 42, and continues into /comments. The work follows the length of the URL, not the number of routes registered in the app. Routes that look separate in a file collapse into one compact path through memory.

For a router holding $n$ routes and a request path of length $k$, a radix-tree lookup runs in

$$ T_\text{match}(k) = O(k), \quad \text{independent of } n, $$

where linear regex matching costs $O(n \cdot m)$ for $m$-length patterns. The tree trades that per-request scan for a single walk down the shared prefix.

The same idea showed up in the small allocation choices. Parameters live in a preallocated slice. Context objects come from a sync.Pool and get reset between requests. The garbage collector gets less junk to clean up, so latency has fewer reasons to wobble.

That is the kind of performance work I trust: fewer operations on the hot path, and fewer concepts in the programmer’s head.

Designing for zero breaking changes

The quiet goal was zero breaking changes. I wanted Gin to feel like it belonged in Go’s ecosystem, which meant learning from Go’s own compatibility promise.

That constraint changes how you design. You add a method before you remove one. You reject the clever rename that saves five characters. You treat every public function as something a stranger might build a company on.

It held. Some of the first programs written against Gin still compile and run more than ten years later. The benchmarks matter. That compatibility matters more.

Hacker News, and then growth

I released Gin on Hacker News at the right moment. Go was getting attention there, and a framework that fit in one README, avoided reflection on the hot path, and benchmarked well was easy to try.

The growth after that was steady rather than cinematic. People used it, filed issues, sent patches, and put it in real services. Today Gin sits around 88k stars with more than 290k projects depending on it.

Open source numbers can be vanity metrics. In this case, the dependency count matters more to me than the stars. It means the API decisions kept compounding long after the original startup disappeared.

Letting it graduate

A few years in, I stepped back and handed Gin to maintainers who kept improving it without me. I think of that as the project graduating. Special kudos to Bo-Yi Wu and Javier Provecho, who carried it forward and kept the bar high.

The part of open source I respect is when the thing stops needing its author. It survives contact with other people’s use cases, other people’s priorities, and other people’s taste.

If you’re building a library, that is the bar I would aim for. Design the API you can imagine keeping for ten years. Make it simple underneath, even when that costs more than making it easy. Build it so it can outgrow you.

I tried to do the same thing a few years later on a compiler, which is the story of Qwik.

This article has interactive figures — read it on manualmeida.dev.

Half-Truths

Manu Martínez-Almeida — Tue, 28 Jun 2022 00:00:00 GMT

On writing as little as possible

Software is best without classes, or functions, or code. But if you must, write as little as possible.
The only thing that really matters in software is KISS.
That is classic over-abstraction.
When in doubt, add setTimeout.
No hack is complete without .replace().
try/catch is for cowards.

On shipping

Never merge a PR.
If you’re afraid to release on Friday, the problem isn’t Friday.
If you can’t release fast, you have tech debt to solve.
Precommit hooks are the root of all evil.
The difference between a hobby and a job is that you don’t write documentation for the former.

On things one if-statement away from disaster

Almost all software is one if-statement away from disaster.
If you code just to make things work, one day suddenly nothing will work.
Dependencies are the root of all evil.
Developers will always find unexpected ways to use your API.
There are two hard things in computer science: cache invalidation and symlinks.

On knowing better

Debugging skills are underrated.
You are only an expert in a given technology when you know when not to use it.
A good engineer balances not underestimating apparently simple tasks against not overengineering apparently complex ones.
An experienced developer is the one who knows when to be volatile and when to be stable. (I figured it out, by the way: a stable is someone who installs linting build scripts, and a volatile is someone who disables them.)
I love monorepos, but I hate lerna.

If you got this far looking for a coherent philosophy, I’m sorry. The honest version is that good engineering is mostly knowing which of these to ignore today.

Disclaimer: a good number of these were forged in long, unhinged rants with Adam Bradley. I’ll take half the blame and none of the credit.