Friction Log: Convex

ℹ️ Background: what is Convex?

This is how Convex describes itself:

The open-source reactive database for app developers

You can go through their fantastic docs yourself, or ask your favorite LLM about it. Here's my attempt to capture the "why" behind Convex:

In a "classical" web-app architecture, you'd have some database on the backend, some sort of APIs to access that data and then wired it up with some HTML/Javascript for the frontend. Depending on the complexity, you might have to think about things like:

• consistency between your dev env and prod (e.g. are you using an in-memory DB for dev or testing?)
• how quickly does your app react to changes in the database? Are you pushing or pulling changes?
• keeping data consistent (e.g. if you have a cron job that updates some aggregate data daily or weekly)
• if you're adding search features, do you implement them within your DB or keep search data in a separate system? If latter, you need to now keep the DB and search index in-sync
• caching (and the consistency challenges that come with it)

The list goes on. Convex can potentially address all this, and more. Over the past week I've played around a bunch with Convex, and I'll document what worked well for me and where I encountered friction. Let's dive in!

🟢 Chef is 🤌

Of all the "one shot" app builders, especially for stateful applications, I've had the most consistent success with Chef. Yes I've tried Gemini, Claude Code, and OpenAI Codex. I have not seriously tested Replit or v0. Regardless, the point is, Chef works very well in my experience.

🟡 Wish I could run Chef locally

Chef pulls together a LOT of stuff to deliver the kind of experience it does. I wish there was a way for me to run Chef-lite locally – basically a pre-configured set of prompts that I could throw into Gemini CLI or Codex. Why? Because even with all the LLM help, building up a Chef project from the ground up is still a lot of work and the nature of the JS ecosystem is that it's easy to mess things up. Yes I could run Chef and then download the project, but sometimes I just want to get going locally! Or I might want to use Convex with a different set of tools than what Chef uses by default.

🟢 Docs + overall DevEx

Docs are comprehensive and easy to follow. Convex plays really nicely with Node / React. Typescript everywhere simplifies the devex a lot. Dev server plugs seamlessly into the Convex dashboard, which is very convenient for inspecting data and debugging during development. I didn't test out fully local mode, but it's nice to have that option.

🟡 LLM / Agent support

Convex docs have an entire section devoted to this! So why not green? Because Zed is my editor of choice these days 😅 Guys, please add instructions for Zed 🥺 Seriously though, Zed works reasonably well with Cursor rules so this isn't a big deal!

🟡 Convex will make you think

I mean, this is not a bad thing 😅 What I mean is, Convex is a whole new way of building applications. Which is exciting, but it also means some unlearning / embracing a new way of thinking. All the new concepts and tooling can get overwhelming, so pace yourself!

🟠 Actions require careful consideration

Perhaps my biggest frustration in using Convex was the different ways Actions caught me by surprise. To be clear, I'm not saying these behaviors are not documented - this could entirely be a PEBKAC 😅.

The way Convex works, all interactions with the data (queries, mutations etc) happen via Convex functions. An obvious – but easy to forget – repercussion is that these functions must run in a very tightly managed environment. That's the only way Convex can provide the consistency guarantees it makes.

And that also has other implications for actions. Here are some specific things that surprised me. For context, this is my action was doing: download an RSS feed (large-ish, 10+ MB); parse and extract bunch of metadata; make mutations (100s of updates).

• All actions run in a custom runtime (presumably isolated instances). This means in some cases a Node package or dependency you want might not work. In my case I was trying to parse some HTML in an action, and several of the NPM packages I found to do this wouldn't work in an action runtime.
• Actions can be slow! Maybe I missed some obvious optimization, but for my action running similar code locally against sqlite took a few seconds; in Convex's dev environment it took hours and I actually ran into project limits before it could complete.
• I/O usage was surprising! Again, I'm sure there's a better way of doing what I was trying to do, but my action above ended up consuming 2.85 GB in "Database Bandwidth" and 100+ MB in "Database Storage". Both these numbers feel very high (esp. the bandwidth number) for what my action was doing.

🎁 Wrapping Up

Convex is ambitious. The concept is very compelling. It will require you to rethink how applications are built, so in that sense it is demanding. The founders are wicked smart (I was lucky to work with them at Dropbox). As with any paradigm shift, there will be some learning along the way. I'm super excited to keep testing and build more things on Convex. Definitely give Chef a try if you haven't, easiest way to get started!