Mike Cann

3 months ago

The bare minimum you need to know about Convex

So you've heard people like Theo, Cody or Jack talking about Convex and decided it sounds like a good fit for your next project. So you fire up your favourite coding agent and tell it to get cracking.

Then it starts talking about queries, mutations, actions, deployments and components, and you're just sitting there wondering what on earth this stuff means. Here's my agent doing exactly that with a cat video app I asked it to build:

Now this is 2026, and you're not going to go back and write all this code yourself, are you? You're not some sort of savage 😉

But you probably should understand just enough about what your agent is building to be able to give it sensible instructions, and maybe notice when it's heading off in the wrong direction. So that's what I'm going to give you here, the bare minimum you need to know about Convex.

So without further ado, grab yourself a lovely cup of tea and let's get into it.

What is Convex?

In a video I did a while back I described Convex as four things: database, functions, sync and components, and I think that's probably still the best way to think about it. So let's quickly talk about each one of those.

Database

Firstly, Convex is primarily a database. It's a new kind of database, a bit like a relational database and a bit like a document database, if you know what those terms are.

The important thing you need to know is that it stores your app's data, gives you an efficient way to query it, and is designed to let your agent grow the app in a sane way without accidentally corrupting any of your data.

It also has something called indexes. You don't need to know how they work, but you should probably expect your agent to use them when it needs to query large amounts of data efficiently.

Functions

The second big thing you need to know about Convex is that in addition to storing your data, it also lets you run code on the server. So not on your users' devices, on the server.

This server-side code is a bit like AWS Lambda or Cloudflare Workers if you've heard of those, so you don't need to provision any servers yourself, Convex just takes care of all that for you.

Convex differs a little bit from those guys tho, in that it has three different kinds of function that are designed to all work nicely together.

The first kind is queries. These can read data from the database, but they can't write to it or call third party services, which is why the outside world is crossed out here:

The second kind is mutations. These can read and write data to the database, but they can't call third party services either:

And the third kind is actions. These guys can call third party services and run code with side effects, but they can't directly access the database. They can call into queries and mutations when they need to read or write data tho:

You probably won't be writing these yourself, but so you recognise them when your agent shows you one, here's what each kind looks like in a little made up cat app:

1// a query can read from the database
2export const listVideos = query({
3  args: {},
4  handler: async (ctx) => {
5    return await ctx.db.query("videos").order("desc").take(20);
6  },
7});
8
9// a mutation can read and write
10export const likeVideo = mutation({
11  args: { videoId: v.id("videos") },
12  handler: async (ctx, { videoId }) => {
13    const video = await ctx.db.get(videoId);
14    if (!video) throw new Error("Video not found");
15    await ctx.db.patch(videoId, { likes: video.likes + 1 });
16  },
17});
18
19// an action can call the outside world, then save what it got through a mutation
20export const fetchCatFact = action({
21  args: {},
22  handler: async (ctx) => {
23    const res = await fetch("https://catfact.ninja/fact");
24    const { fact } = await res.json();
25    await ctx.runMutation(internal.cats.saveCatFact, { fact });
26  },
27});
28

(saveCatFact there is just another little mutation that inserts the fact into a table.)

And Convex does actually enforce this. If your agent tries to call fetch from a query or a mutation then it's going to get yelled at:

1Uncaught TypeError: fetch to https://catfact.ninja/fact failed: Can't use fetch() in queries and mutations. Please consider using an action. See https://docs.convex.dev/functions/actions for more details.
2

So you might be wondering at this point, why does Convex need three kinds of function when other platforms like AWS Lambda or Cloudflare Workers only need one?

Two big reasons. The first is that splitting your reading, writing and effects like this is a great way to help your app grow over time, without your agent getting itself tangled in a big ball of spaghetti after two weeks of development.

The second big reason is that it unlocks Convex's big superpower, which is...

Sync

When a mutation changes data, Convex knows which subscribed queries depend on that data, and it automatically updates the clients listening to them. In this one the yellow bar in the database is the data that changed, then the queries re-run and all four clients get the new result:

On the frontend that's just one hook, and whenever the result changes your component re-renders with it:

1const videos = useQuery(api.cats.listVideos);
2

This means you can build really interactive realtime apps that just feel great to use, because everything just updates instantly. In practice it means your agent normally shouldn't need to build polling or manual refresh logic just to keep Convex data up to date.

Whenever I encounter websites these days that have got a refresh button, or worse just show you stale data until you refresh the page, I'm just like... come on, just use Convex please.

Components

The fourth and final big thing you need to know about Convex is that it has this rich component system. You can kind of think of components as little building blocks or plugins for your application, that your agent can grab to quickly add functionality that is secure and scalable.

Components get their own little database and functions and everything else that your application gets actually, but they're segregated from your own application's tables and functions. That makes them really secure, because it creates this clear boundary between your app's code and data and the component's. You or your agent can obviously poke holes in that boundary to let data and compute through, but you get to control that explicitly.

Components are great for really common tasks such as queues (Workpool), rate limits or presence, and other stuff like that which can be really tricky for you or your agent to get right. There are also ones for things such as email, payments and agents, and some of what's in the directory comes from the community and third party vendors rather than from us.

You don't need to know about all of these of course. Just be aware that components are a thing, and have your agent check to see whether one exists for your use case before it starts hacking away and building its own. It's worth asking too, as on my cat app it hadn't actually looked until I gave it a nudge:

Hosting

Once your agent has finished making your lovely app you might be wondering how you're going to share it with the rest of the world.

Well Convex is a backend platform, so you need a server to run that database and compute on. Now it is open source and self-hostable so you can just run it on your own hardware, but to be honest I personally wouldn't recommend it. It's a lot of extra work, and having seen the lengths the infrastructure engineers here go to in order to avoid downtime, I wouldn't want that responsibility myself. Still, it's good to know the option is there. Otherwise you should probably just use the cloud service, which is what you get out of the box.

For the frontend, that is your HTML, JS and CSS, you can have your agent host that on something like Vercel, Cloudflare or Netlify. Or if it's just a simple site then we've also got the Static Hosting component, which is nice because it keeps everything self-contained inside your Convex application and means you don't have to sign up for another service. I did a whole other video on that one if you want to find out more.

Other services

Talking about other services, in addition to the database, functions, sync and components, Convex also has a bunch of other useful things built right in. You don't need to know about them in detail, but it's useful to know they're there.

So things like the scheduler and crons for running work in the future, auth to protect parts of your application, file storage, full text search, vector search and more. It's definitely worth pointing your agent at the docs if you aren't sure whether something is built into Convex or not.

What is Convex not for?

Okay, at this point I think we've probably talked enough about what Convex is and why you probably should use it. But I also think it's important when evaluating a new technology to understand some use cases it's not a good fit for.

So because Convex is what's known as a stateless compute platform, it's not particularly well suited for systems that require extremely high frequency updates. I'm thinking things such as first-person shooters like Fortnite or real-time strategy games like StarCraft. This probably also means high-frequency trading or high-hertz IoT sensor data wouldn't be an ideal fit either.

By the way, I've since made a component that fakes high frequency updates for things like multiplayer cursors, but I still wouldn't try to build a first-person shooter on it.

The same goes if you need direct access to the GPU or some other specific hardware, as Convex doesn't give you low-level hardware access like that. For those sorts of workloads you probably want more specialised infrastructure.

Having said that tho, a pattern you can use, and one I use all the time, is to have Convex as the central orchestrator and then just call out to those external services via actions:

This post from Jashwanth is a good example of doing that with GPU work on RunPod.

Oh and if you need to run some kind of obscure binary or .exe file then Convex might not be the ideal fit either. But for the vast majority of workloads Convex should just work great.

The dashboard

Alright, so the final thing I'd say you need to know about Convex is its dashboard. Every Convex project comes with its own little UI, where you can get a nice overview of your running application, its functions, any errors, things like that.

The green dropdown along the top lets you view or create different deployments for your project:

Deployments are instances or copies of your project that you can use for different environments like development or production, which lets you keep your data separate between them.

The dashboard has also got lots of other stuff that I won't go into here, such as your project settings, environment variables and whatnot, but your agent should probably know about all of these and be able to direct you there if it can't do something itself.

Getting the most out of your agent

To get the absolute best Convex experience I recommend you install the Convex plugin for whichever agent you're using. For Claude Code and Codex this one command will do it:

1npx convex plugins install
2

That command doesn't support Windows yet, and Cursor has its own install from the Cursor Marketplace, so the plugin docs have the commands for each agent.

The plugins come loaded with all the best practices and up-to-date info that your agent can consume while working on your project. They can also proactively let your agent know when your project is running into errors, in development or in production, and they let it read your dev deployment's logs and insights rather than having to guess.

Conclusion

So just to recap: Convex is a database, three kinds of function (queries read, mutations read and write, and actions talk to the outside world), realtime sync that keeps your clients up to date by itself, and components for the common stuff you don't want your agent reinventing. You probably want the cloud service rather than self-hosting, it's not the right fit for really high frequency stuff like games, and the plugin is well worth installing.

Well I hope I didn't lose you in all of that. There's obviously a ton more I could have talked about, but hopefully you now understand the basics and the most important parts of what makes Convex Convex. If you want more detail then the docs are the place to start, How Convex Works by Sujay goes a lot deeper, and I've got heaps more videos on our channel that go into each of these topics.

Until next time, cheerio! 👋