DEV Community: Tanay Karnik

A closer look at the SpacetimeDB v2 benchmark: Is it really 23x faster than SQLite?

Tanay Karnik — Sun, 22 Mar 2026 10:43:48 +0000

A good way to market a new infrastructure tool is to loudly announce that it is a thousand times faster than whatever you are currently using. This is a very effective strategy because nobody wants to be the person using a slower database.

A few weeks ago, SpacetimeDB launched their v2 with exactly this premise. They released a slick video explaining that traditional web architecture—where your server talks to your database over a network—is fundamentally broken. The solution, they argue, is to just put your application code inside the database.

And to prove it, they showed a chart. This chart is basically a graveyard of modern infrastructure. They lined up Postgres, PlanetScale, Convex, CockroachDB and a few others, and declared victory over all of them.

First of all, you have got to love the cheeky little magnifying glass icons they added next to Convex, PlanetScale, and CockroachDB. Just to drive home how microscopic their numbers supposedly are.

But if you ignore that for a second, something else immediately stands out.

Setup	TPS
SpacetimeDB (Rust)	167,915
SpacetimeDB (JS)	104,485
Node.js + SQLite	7,416

That 7K TPS number for Node.js + SQLite is so clearly, obviously off that I just had to clone their code and try to reproduce the results myself.

Unlike the other databases on that list, SpacetimeDB and a Node.js + SQLite server share the exact same architectural paradigm: colocated compute and storage. The application and the database live on the exact same machine. There is no network boundary. Which makes the gap between them look suspicious.

Naturally, a benchmark chart like this raised eyebrows, sparked skepticism, and generated plenty of discussion. Vincent, an ex-PlanetScale engineer, wrote a great technical teardown shortly after the launch. He raised good questions about high availability, cluster deployments, and the perils of forcing your application and database to fight for the same CPU and RAM. Valid points.

He also reasonably questioned whether SpacetimeDB was skipping durability—the part where the database actually promises your data is safely written to the hard drive before returning a success message—to hit these astronomical numbers.

But they aren't. SpacetimeDB has a flag (withConfirmedReads), which was enabled during the benchmark, that ensures transactions are durably committed—actually flushed to the disk—before the server acknowledges the client.

So the secret sauce isn't skipping durability; it's something else. That SQLite number was still very wrong, and I needed to find out why.

Bare metal and broken code

I'm going to run the benchmark on my personal Linux machine. I have a 13th Gen Intel Core i7-13700K, 32GB memory, and a local NVMe SSD.

Since we are about to talk a lot about database durability and disk bottlenecks, here is a quick dd test to establish a baseline for this disk.

tanay:~$ dd if=/dev/zero of=fsync_test bs=4k count=1000 oflag=dsync
1000+0 records in
1000+0 records out
4096000 bytes (4.1 MB, 3.9 MiB) copied, 0.683005 s, 6.0 MB/s

What is this doing?
We are copying small blocks of data one after the other synchronously to the
disk. Divide the total time taken by the number of blocks copied, and you
roughly get the write latency of the disk.

1000 blocks copied in 0.683s. That's a write latency of 683 microseconds.

Roughly 5x faster than your usual EBS volume, which makes sense—EBS is network-attached storage with far better durability guarantees than a local NVMe drive. For comparison, here's the same test on EBS:

tanay:~$ dd if=/dev/zero of=fsync_test bs=4k count=1000 oflag=dsync
1000+0 records in
1000+0 records out
4096000 bytes (4.1 MB, 3.9 MiB) copied, 3.8657 s, 1.1 MB/s

3.86ms per write.

Still, my local SSD is relatively slow. If you use a good bare-metal server (like the AWS EC2 i7i series), you could get write latencies down to 76 microseconds:

tanay:~$ dd if=/dev/zero of=/mnt/nvme-data/fsync_test bs=4k count=1000 oflag=dsync
1000+0 records in
1000+0 records out
4096000 bytes (4.1 MB, 3.9 MiB) copied, 0.0760506 s, 53.9 MB/s

Why is write latency so important? More on that soon.

We can now clone their repository, install all the dependencies, set the env variables, run the prep script, and reproduce the results, right?

Wrong. The benchmark—especially for their own SpacetimeDB test—was broken out of the box. I ranted about it on X, and their founder Tyler invited me to their Discord to help get things running. Their engineering team was polite and responsive. They acknowledged a few bugs, some old code that broke during their v2 migration, and shipped a patch.

Except, the benchmark was still broken.

So, I'm only going to focus on the SQLite numbers. Once SpacetimeDB fixes their benchmarking code, I'll update the results here. I have no doubt that 100K–160K TPS is possible with their architecture. But as we'll see, it's possible for SQLite, too.

Initial results and more broken code

Running the benchmark is easy. First, we run the Node.js + SQLite RPC server:

pnpm tsx src/rpc-servers/sqlite-rpc-server.ts

Then we run the benchmark client with the default settings SpacetimeDB used:

pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_rpc

The benchmark runs for 10 seconds. Concurrency of 50 means we'll start 50 simultaneous connections (workers) to our RPC server. There's also a hidden maxInflightPerWorker parameter, which is the number of open, unresolved requests a worker can hold at a time. We aren't passing it explicitly just yet, but keep it in mind—it’s going to become relevant soon.

A note on alpha=1.5
In a Zipfian distribution, alpha controls skew—higher values mean more users
hit the same accounts, which raises contention. In a multi-writer database,
that kills throughput through lock contention. But SQLite and SpacetimeDB are
both single-writer systems. There are no locks. So contention actually
helps: repeated hits on the same accounts warm the CPU cache. I'm keeping
alpha=1.5 because that's what SpacetimeDB used.

The first run

The first result I got surprised me.

tanay:~$ pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_rpc
...
sqlite_rpc.ts: {
  tps: 12682.8,
  samples: 126828,
  p50_ms: 3.457,
  p95_ms: 5.971,
  p99_ms: 9.431,
  ...
}

Wait. 12,682 TPS? That is already almost double the 7,416 they show on their graph. ¹

This number is also impossibly wrong. Not because it's too low. Because it's too high.

By default, SQLite runs in journal_mode=delete. In this mode, SQLite does TWO fsync calls to the physical disk per transaction. First, it fsyncs the old data (the rollback journal). Then, it updates the main database and waits for a second fsync.

What is fsync?
When an application writes data, the operating system usually caches it in
memory and immediately says "done!" for speed. But if someone unplugs the
server right then, that data vanishes. To actually guarantee durability, the
database must issue an fsync system call. This forces the OS to physically
write the data to the storage drive, and the database halts until the hardware
returns a thumbs-up. That physical wait time is the disk latency.

If my disk takes 683 µs per write, two fsyncs take 1,366 µs.

1 second (1,000,000 µs) / 1,366 µs = a theoretical maximum of ~732 TPS.

So how in the world is the benchmark reporting 12,000 TPS on a disk that physically maxes out at 732?

I put my AI agent (opencode) to work debugging the benchmark's server code, and we found this:

db.transaction((tx) => {
  const rows = tx
    .select()
    .from(accounts)
    .where(inArray(accounts.id, [fromId, toId]))
    .all();

  if (rows.length !== 2) {
    throw new Error("account_missing");
  }

  // ...[balance math logic here]...

  tx.update(accounts)
    .set({ balance: Number(newFrom) })
    .where(eq(accounts.id, fromId));

  tx.update(accounts)
    .set({ balance: Number(newTo) })
    .where(eq(accounts.id, toId));
});

Can you spot the issue with this Drizzle ORM code?

The update statements are never RUN.

Drizzle requires you to call .run() at the end of an update statement to actually execute the query against the database. Because it was missing, there was no execution. No disk writes. No waiting for fsync.

The benchmark wasn't measuring database writes. It was just measuring the speed of Node.js executing a database SELECT and throwing some JSON in the garbage.

So, I fixed the code, added the .run() calls, and reran the script.

tanay:~$ pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_rpc
...
sqlite_rpc.ts: {
  tps: 360.8,
  samples: 3608,
  p50_ms: 133.759,
  p95_ms: 166.271,
  p99_ms: 276.991,
  ...
}

360 TPS. With a p50 latency of 133ms.

Now this makes way more sense. Our theoretical max was ~732 TPS. Add in the Node.js event loop overhead, IPC, the HTTP roundtrip, and Drizzle's ORM overhead, and 360 TPS is exactly where you expect standard, double-fsync SQLite to land on this disk.

We have found the true baseline. Now, let's fix it.

Getting SQLite to 160K TPS

We are at 360 TPS. SpacetimeDB is at 167,000 TPS. How do we bridge the gap?

By giving SQLite the exact same architectural privileges that SpacetimeDB gave itself.

Fix #1: Breaking the double-fsync

Nobody running a high-throughput application uses SQLite in journal_mode=delete. It is the absolute slowest configuration possible.

The first step is turning on Write-Ahead Logging (WAL). We'll keep synchronous=FULL, which means SQLite still waits for the fsync to complete before returning success. No durability shortcuts. We're still flushing every committed transaction to the physical drive.

db.run("PRAGMA journal_mode=WAL;");
db.run("PRAGMA synchronous=FULL;");

Why does this matter? In the default mode, SQLite has to wait for two physical disk writes. In WAL mode, SQLite simply appends the new transaction to the end of the Write-Ahead Log (fsync #1) and returns success immediately. The actual main database file is updated later in the background.

We still preserve 100% of our durability guarantees—if the server crashes, SQLite recovers all committed transactions from the WAL—but we just halved our physical disk wait time.

tanay:~$ pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_rpc
...
sqlite_rpc.ts: {
  tps: 1201,
  samples: 12010,
  p50_ms: 40.319,
  p95_ms: 49.439,
  p99_ms: 84.799,
  ...
}

1,201 TPS. By removing exactly one fsync, we more than tripled our throughput. Our latency also dropped from 133ms down to 40ms.

(Pause here if you'd like. Can you figure out why the latency dropped so drastically from removing just 0.683ms of disk wait time?)²

From our earlier calculation, if 2 fsyncs gave us a theoretical cap of 732 TPS, 1 fsync should get us to ~1,464 TPS. We're still slightly short. The bottleneck has moved.

Fix #2: Apples, oranges, and network protocols

SpacetimeDB keeps using the phrase "apples-to-apples".

But if you look at the benchmark setup, SpacetimeDB's apple is a runtime communicating over an active, stateful WebSocket connection. The connection opens once, and thousands of transactions flow through the pipe.

The SQLite apple is a Node.js server forced to spin up a brand-new, stateless HTTP request lifecycle for every single RPC call. TCP handshake, JSON parse, HTTP handler, DB query, JSON serialize, HTTP response. Over and over again.

Is this a database benchmark? Or an HTTP overhead benchmark?

If you care about latency and throughput, this is a workable problem. You don't need a new database runtime to keep your application code and storage on the same machine. It's straightforward to rewrite the SQLite RPC to use WebSockets instead of HTTP.

So, I wrote a new SQLite RPC server that communicates over WebSockets instead.

pnpm tsx src/rpc-servers/sqlite-ws-rpc-server.ts

Let's try it out.

tanay:~$ pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_ws_rpc
...
sqlite_ws_rpc.ts: {
  tps: 1478.6,
  samples: 14786,
  p50_ms: 31.663,
  p95_ms: 37.983,
  p99_ms: 64.991,
  ...
}

1,478 TPS. Our TPS went up, and our latency dropped again to 31ms, because we stopped forcing Node.js to construct and parse HTTP headers on every request.

Look at the math. SQLite is a single-writer database. My disk takes exactly 0.683 milliseconds to execute a single fsync.
1,000ms / 0.683ms = ~1,464 TPS.

We've stripped away all the overhead. We're now bottoming out directly against the physical write latency of the NVMe SSD.

Fix #3: The physics of batching

We are at ~1,500 TPS. Nowhere near 160,000.

At first, this seems like a hard wall. If durability costs 0.683ms per write, aren't we capped? We can't make the disk faster.

Shouldn't SpacetimeDB also hit the same wall? Are they doing some insane Rust wizardry to speed up the disk?

No. That's impossible.

Think about it like transportation. We have a bridge, and crossing it takes exactly 0.683ms. A bicycle crosses the bridge carrying one passenger (transaction). You can only move ~1,464 passengers across per second.

The only way to move more people without breaking the speed limit is to upgrade the vehicle. You swap the bike for a bus. The bus also takes 0.683ms to cross the bridge. The bridge speed hasn't changed. But the bus can now carry 100 passengers at a time.

Batching.

Once we know what to do. It's straightforward to implement in Node.js.

I added a simple batching queue: accumulate up to 10 requests, or wait 2 milliseconds—whichever comes first—then flush the entire batch with a single fsync.

SQLITE_WS_RPC_BATCH_SIZE=10 SQLITE_WS_RPC_BATCH_MS=2 pnpm tsx src/rpc-servers/sqlite-ws-rpc-server.ts

Cross your fingers.

tanay:~$ pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_ws_rpc
...
sqlite_ws_rpc.ts: {
  tps: 13438,
  samples: 134380,
  p50_ms: 2.861,
  p95_ms: 5.111,
  p99_ms: 7.403,
  ...
}

13,438 TPS. And our p50 latency dropped to 2.8ms.

The math checks out. Our disk maxes out at ~1,464 fsyncs per second. Group 10 transactions per fsync (1,464 × 10) and our physical ceiling is 14,640 TPS. We're nearly there.

But wait—our latency dropped to 2.8ms. We introduced extra waiting with batching. Why is it lower?

Because of head-of-line blocking. With 50 concurrent workers, every request waits in a single queue. Without batching, each request waits for all the individual fsyncs ahead of it—the median request sits behind roughly 25 separate disk writes. With a batch size of 10, those 50 requests collapse into at most 5 groups. The median request now waits for a handful of batches instead of a long chain of individual disk writes. That's why the queue time collapses.

So, if batching 10 gets us 13K TPS, batching 100 should get us 130K, right?

tanay:~$ pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_ws_rpc
...
sqlite_ws_rpc.ts: {
  tps: 14467.8,
  samples: 144678,
  p50_ms: 2.047,
  p95_ms: 3.769,
  p99_ms: 5.047,
  ...
}

Hmm. 14,467 TPS. We barely moved.

Remember that maxInflightPerWorker parameter I mentioned at the start and told you to keep in mind? Here it is.

The default SQLite benchmark restricts the client to maxInflightPerWorker=1. With 50 concurrent workers, there are never more than 50 requests sitting at the server at any given moment.

Our bus holds 100 people. But there are only 50 people at the bus stop.

The bus never fills up. The database sits idle, waiting for the 2ms timeout to fire and the next trickle of requests to arrive.

The SpacetimeDB Secret

SpacetimeDB sets maxInflightPerWorker to 1 for the SQLite connector. But they set it to 16,384 for their own benchmark.

How did SpacetimeDB get 167K TPS? By keeping the bus stop permanently packed. With 16,384 in-flight requests per worker, batches fill instantly and throughput is maximized.

(Note: In their demo, they show only TPS—not p50, p95, or p99. Flooding the server with in-flight requests maximizes throughput while destroying latency. 50 workers × 16,384 in-flight = 819,200 unresolved requests in memory.)

We now have three knobs to play with: batch size, batch timeout, and in-flight requests per worker. Let's dial them up gradually.

With batch=100 and 8 in-flight per worker, the bus stop is finally busy:

tanay:~$ SQLITE_WS_RPC_BATCH_SIZE=100 SQLITE_WS_RPC_BATCH_MS=2 pnpm tsx src/rpc-servers/sqlite-ws-rpc-server.ts
tanay:~$ MAX_INFLIGHT_PER_WORKER=8 pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_ws_rpc
...
sqlite_ws_rpc.ts: {
  tps: 51753,
  samples: 517531,
  p50_ms: 6.439,
  p95_ms: 10.119,
  p99_ms: 12.607,
  ...
}

51,753 TPS. With a p50 of 6.4ms.

You don't need 800,000 concurrent requests to saturate a single-writer database. You just need enough to keep the batching window full. Let's push further—batch=200, inflight=40:

tanay:~$ SQLITE_WS_RPC_BATCH_SIZE=200 SQLITE_WS_RPC_BATCH_MS=2 pnpm tsx src/rpc-servers/sqlite-ws-rpc-server.ts
tanay:~$ MAX_INFLIGHT_PER_WORKER=40 pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_ws_rpc
...
sqlite_ws_rpc.ts: {
  tps: 109508,
  samples: 1095080,
  p50_ms: 14.767,
  p95_ms: 31.407,
  p99_ms: 37.087,
  ...
}

109,508 TPS. Doubling the batch size roughly doubled the throughput. Let's keep going—batch=1000, inflight=80:

tanay:~$ SQLITE_WS_RPC_BATCH_SIZE=1000 SQLITE_WS_RPC_BATCH_MS=2 pnpm tsx src/rpc-servers/sqlite-ws-rpc-server.ts
tanay:~$ MAX_INFLIGHT_PER_WORKER=80 pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_ws_rpc
...
sqlite_ws_rpc.ts: {
  tps: 137528,
  samples: 1375280,
  p50_ms: 22.287,
  p95_ms: 46.687,
  p99_ms: 52.415,
  ...
}

137,528 TPS. The gains are compressing. We're running into a CPU ceiling now, not a disk one. Let's try batch=2000:

tanay:~$ SQLITE_WS_RPC_BATCH_SIZE=2000 SQLITE_WS_RPC_BATCH_MS=2 pnpm tsx src/rpc-servers/sqlite-ws-rpc-server.ts
tanay:~$ MAX_INFLIGHT_PER_WORKER=80 pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_ws_rpc
...
sqlite_ws_rpc.ts: {
  tps: 157436,
  samples: 1574359,
  p50_ms: 23.135,
  p95_ms: 29.999,
  p99_ms: 35.519,
  ...
}

157,436 TPS. And finally, batch=4000, inflight=120:

tanay:~$ SQLITE_WS_RPC_BATCH_SIZE=4000 SQLITE_WS_RPC_BATCH_MS=2 pnpm tsx src/rpc-servers/sqlite-ws-rpc-server.ts
tanay:~$ MAX_INFLIGHT_PER_WORKER=120 pnpm tsx src/cli.ts --seconds 10 --concurrency 50 --alpha 1.5 --connectors sqlite_ws_rpc
...
sqlite_ws_rpc.ts: {
  tps: 163075,
  samples: 1630751,
  p50_ms: 31.935,
  p95_ms: 45.023,
  p99_ms: 55.711,
  ...
}

163,075 TPS.

We did it. We touched SpacetimeDB's benchmark numbers, maintained durable disk writes, and used nothing but Node.js and out of the box SQLite + Drizzle ORM.

Why did it stop at 160K?

If the disk can do 1,464 fsyncs per second and we're batching 4,000 requests per fsync, shouldn't we easily hit millions of TPS? And why did a batch size of 100 only give us 51K instead of the expected 140K? Why doesn't the throughput scale linearly?

Because we traded the disk bottleneck for a CPU bottleneck.

Node.js is single-threaded, and better-sqlite3 is synchronous. When SQLite calls fsync, it blocks the entire Node.js process. The event loop freezes. No JSON parsing. No SQL execution. Just waiting.

Think about a 1-second time budget. Your process splits that second between two things:

Sleeping while the disk fsyncs.
Running your actual application code.

If you try to hit 140,000 TPS with a batch size of 100, you need 1,400 fsyncs per second.
1,400 × 0.683ms = 956 milliseconds frozen.

You have 44 milliseconds left to parse 140,000 JSON requests. 0.314 microseconds / request. Physically impossible.

But with a batch size of 4,000, you only need 40 fsyncs per second to reach 160,000 TPS.
40 × 0.683ms = 27 milliseconds frozen.

You've bought yourself 973 milliseconds of pure CPU time.

At 163,000 TPS, our single Node.js thread has exactly 6.25 microseconds per transaction to parse the WebSocket JSON, construct the query, traverse the B-Tree, and serialize the response. We haven't just maxed out the disk; we've maxed out the processor.

Could we go faster? Yes. Drop Drizzle ORM for raw better-sqlite3 prepared statements, or swap the ws library for a C++ implementation like uWebSockets.js, and you'd squeeze tens of thousands more transactions out of this single core. You could also offload the database writes to a dedicated worker thread—keeping JSON parsing and WebSocket I/O on the main thread while a separate thread handles SQLite calls and blocks on fsync—so the two never compete for the same CPU time. Bridging the final gap between Node.js and a native Rust runtime is entirely possible. But 163K TPS proves the point.

The results

To recap: here is the actual story of the benchmark, told through the data.

Setup	Inflight/Worker	TPS	p50 Latency
Fake Benchmark	1	12,682	3.5ms
True Default SQLite	1	360	133ms
WAL Mode	1	1,201	40ms
WebSockets	1	1,478	32ms
Batching (Batch=10)	1	13,438	2.9ms
Batch=100, Inflight=8	8	51,753	6.4ms
Batch=200, Inflight=40	40	109,508	14.8ms
Batch=1000, Inflight=80	80	137,528	22.3ms
Batch=2000, Inflight=80	80	157,436	23.1ms
Batch=4000, Inflight=120	120	163,075	31.9ms
SpacetimeDB (JS)	16,384	104,485	not disclosed
SpacetimeDB (Rust)	16,384	167,915	not disclosed
SpacetimeDB's Node.js + SQLite	1	7,416	not disclosed

Standard, boring tech performs beautifully when you configure it properly.

Closing thoughts

If SQLite can hit 163K TPS on a single machine, why does SpacetimeDB exist?

Not for the performance.

SpacetimeDB as a product

SpacetimeDB is a cool piece of tech. But step back and think about what the WASM reducer model is actually solving: running user-generated code safely, supporting multi-tenant platforms where you can't trust what's being executed. Stuff that they need for their Maincloud offering.

Their v2 launch tried to expand the original pitch to general web apps—but deploying a web app and deploying a game server are two completely different problems.

And even for multiplayer games: if it's your own code on your own server, there's no untrusted code to sandbox. The WASM runtime buys you nothing. At that point, I'd rather roll my own application layer with SQLite or RocksDB as a storage engine than learn a proprietary runtime and get locked into it.

The licensing is also worth noting. SpacetimeDB is BSL-licensed. The open source release is enough to run a single node—that's it. Clustering, replication, anything that looks like a real multi-node production setup is closed source and part of their Maincloud offering. The open-source version is primarily just marketing for that.

There are also rough edges throughout, and I wouldn't recommend it for anything serious today.

On durability and production

163K TPS on a local NVMe is fun. But it is not a production setup. If that drive dies, the data is gone.

EBS is the obvious next step, but EBS has its own failure story that PlanetScale wrote about. Also worth knowing: EBS doesn't replicate across availability zones. If cross-AZ replication matters to you, EFS handles this reasonably well—SQLite on EFS with a single writer is a workable setup.

There's also a harder structural problem with the colocation pattern itself. Vertical scaling gets painful when your application server and your database are competing for the same CPU and RAM on the same machine. It's not a dealbreaker, but it's a real constraint.

One of the few offerings that actually does this pattern well is Cloudflare Durable Objects. You get low-latency local access with real durability guarantees. Because they replicate writes across a quorum before acknowledging a response (or "communicating with the outside world") through something they call output gates. They scale horizontally. And there's less lock-in than you'd expect since you write plain TypeScript and SQLite with an ORM like Drizzle if you like.

Infrastructure marketing will always try to convince you that your stack is broken and their new paradigm is the only way forward. But before you rewrite your backend, look at their code. You might just find they forgot to call .run().

SpacetimeDB's benchmark docs list two server options: a PhoenixNAP bare-metal i9-14900k or a GCP c4-standard-32 with RAID 0 across five local SSDs. It's unclear which they used. Either way, both run fast local storage—NVMe or local SSDs in RAID 0—putting disk writes roughly in the ~20–100 µs range. That's far faster my dev machine, which makes this initial local result even more suspicious. ↩
Why did the latency drop so drastically? Because of head-of-line blocking. With 50 concurrent workers, request #50 is stuck in a queue behind 49 others. In delete mode (double fsync = 1.3ms per request), the 50th request waits ~65ms just to start. Switch to WAL (single fsync = 0.68ms) and the line moves twice as fast—request #50 only waits ~34ms. Batching takes this further by collapsing the queue even more aggressively. ↩

Cloudflare Durable Objects & Nuxt: Building a Real-Time Chat App

Tanay Karnik — Wed, 09 Apr 2025 14:10:03 +0000

This has been the most requested topic ever since I started working on Nuxflare.

What are Cloudflare Durable Objects? How can we leverage them with Nuxt?

Durable Objects are powerful and surprisingly affordable, but they can also seem a bit mysterious at first. I thought I'd break them down in a series of posts explaining how to get the most out of them.

Here's a preview of what we're going to build:

Try it out live: https://websockets-demo.nuxflare.com

Check out the GitHub repo: https://github.com/nuxflare/durable-websockets

Let's get started

I'm using Bun for its cool DX, but you can follow along with npm, pnpm, or yarn—whatever you're most comfortable with.

First, let's create a new Nuxt project:

bunx nuxi@latest init durable-websockets -t v4-compat

We're using Nuxt 4 compatibility mode, which allows us to use the Nuxt 4 project structure, getting ready for it when it releases.

Now, let's install the dependencies:

bunx nuxi@latest module add ui vueuse # Nuxt UI v3, @vueuse/core
bun i -D nuxflare @cloudflare/workers-types

We'll use Nuxflare to deploy two things to Cloudflare:

The main Nuxt app to Cloudflare Workers.
The WebSockets server with Durable Objects.

While you can follow this tutorial without Nuxflare, there's really no reason not to use it. Even if you're comfortable writing wrangler.toml configuration yourself, Nuxflare makes it easy to create and destroy resources and deploy to multiple environments. You still retain full control to customize your Wrangler configuration however you want.

Setting up Nuxflare

Let's initialize Nuxflare:

bun nuxflare init

Nuxflare will ask you several questions about your project name, custom domains (for dev and prod deployments), and GitHub Actions setup. Everything is optional.

I'm using websockets-demo.nuxflare.com as the production domain and leaving the development domain empty to use the default Cloudflare Workers subdomain.

For GitHub Actions, I'm using the "Production deployments only" preset, which means code updates to the main branch in the nuxflare/durable-websockets repository will automatically deploy to websockets-demo.nuxflare.com.

The Nuxflare CLI will also prompt you to create and configure a CLOUDFLARE_API_TOKEN for deploying resources to Cloudflare.

Once complete, Nuxflare will install development dependencies like sst (SST.dev) and wrangler, which are needed to manage Cloudflare resources. You'll also notice a new folder called nuxflare and a file called sst.config.ts.

Feeling overwhelmed? Don't worry about it. For the most part, you can completely ignore the nuxflare folder—it's where all the infrastructure-as-code "wizardry" happens. Just commit everything to source control.

Configuring the Infrastructure

Now let's configure the infrastructure for our app by updating the run() function inside sst.config.ts:

async run() {
  const { Nuxt } = await import("./nuxflare/nuxt");
  const { Worker } = await import("./nuxflare/worker");

  const domain =
    $app.stage === "production"
      ? prodDomain || undefined
      : devDomain
        ? `${$app.stage}.${devDomain}`
        : undefined;

  // Create WebSockets worker
  const { websocketsUrl } = await Worker({
    name: "WebSockets",
    dir: "./websockets",
    main: "index.ts",
    durableObjects: [{ className: "WebSockets", bindingName: "WEBSOCKETS" }],
  });
  // Create Nuxt app and pass the WebSockets URL
  Nuxt("App", {
    dir: ".",
    domain,
    outputDir: ".output",
    extraVars: {
      NUXT_PUBLIC_WEBSOCKETS_URL: websocketsUrl,
    },
  });
}

As mentioned, we're creating two components:

The WebSockets server with Durable Objects.
The Nuxt app that connects to the WebSockets server.

For the Nuxt app, we specify dir: ".", and Nuxflare will build and deploy it with Cloudflare Workers. For the WebSockets server, we specify a websockets directory with index.ts as the worker entrypoint.

Understanding Durable Objects

So, what's the deal with Durable Objects?

A Durable Object is essentially a class. You can create multiple instances of it, and each instance manages its own state and handles its own WebSocket connections.

What makes Durable Objects special is that they're automatically placed close to the user. For example, in our chat app, when a user creates a new room, it creates a new Durable Object instance on a Cloudflare server closest to that user. When others join the same chat room (from anywhere in the world), they connect to that same Durable Object instance.

This is powerful because you can focus on writing your real-time logic without worrying about server deployment, while users still get the best possible latency.

Note: A Durable Object—at least for now—doesn't relocate once created. If the first user who creates a Durable Object instance is geographically distant from later users, those users might experience suboptimal latency. This limitation is difficult to solve with alternative approaches too.

So yeah, a Durable Object is a class, and we're calling ours "WebSockets". But what's a binding name?

Cloudflare has this thing: everything that gets used through a Worker has to go through a "binding"—whether it's KV, D1, Queues, or Durable Objects. For each feature, you need a binding name.

We're saying: if any Worker needs to use the "WebSockets" Durable Object, it should do so through a binding called "WEBSOCKETS" (env.WEBSOCKETS).

Creating our Durable Objects Class

Now that we understand the basics, let's write our Durable Objects class:

export class WebSockets extends DurableObject {}

Our Durable Object needs to:

Handle WebSocket connection requests (when a Worker identifies a Durable Object instance that should handle a WebSocket connection).
Process incoming WebSocket messages (when a user sends a message in the chat).
Handle when a WebSocket connection closes (cleaning up state for that connection).
Expose a publish function to broadcast messages to specific users connected via WebSockets.

Handling WebSocket Requests

For #1, let's write a fetch function. We'll receive the full request object from the Worker. From there, we should check if it's a WebSockets request, and if it is, we create a WebSockets pair. A WebSocket pair is like walkie-talkies: for each client that opens a WebSockets connection with the server, the server keeps one node and gives the other to the client. Then we can use the node on the server to send and receive messages.

export class WebSockets extends DurableObject {
  override async fetch(request: Request): Promise<Response> {
    if (request.headers.get("upgrade") === "websocket") {
      try {
        const { room, userId } = extractRoomAndUser(request);
        const protocols =
          request.headers
            .get("sec-websocket-protocol")
            ?.split(",")
            .map((x) => x.trim()) || [];
        protocols.shift(); // remove the room:userId from protocols

        const webSocketPair = new WebSocketPair();
        const [client, server] = Object.values(webSocketPair);
        if (server) {
          server.serializeAttachment({
            room,
            userId,
          });
          this.ctx.acceptWebSocket(server, [room, userId]);
        }

        const res = new Response(null, { status: 101, webSocket: client });
        if (protocols.length > 0) {
          res.headers.set("sec-websocket-protocol", protocols[0] as string);
        }
        return res;
      } catch (err) {
        console.error("Error in websocket fetch:", err);
        return new Response(null, { status: 400 });
      }
    }
    return new Response(null);
  }
}

There are still a few more things to unpack. Let's go one by one.

Authentication with the WebSocket Protocols Header

Let's talk about the WebSocket protocols header hack we're using for authentication.

WebSockets don't natively support passing authentication data in the initial handshake like HTTP headers. However, there's a workaround: the WebSocket protocol header can include custom protocols as comma-separated values.

We're encoding our room and user ID in base64 and passing it as the first protocol. The server extracts this information to determine which room the user wants to join and to identify them in the chat.

// NOTE: in a real-world scenario, the token should instead be JWT or similar
// from which we could extract and validate room/user/topic and such
// or, the info can even be stored inside a KV
function extractRoomAndUser(request: Request): {
  room: string;
  userId: string;
} {
  const protocolHeader = request.headers.get("sec-websocket-protocol");
  if (!protocolHeader) {
    throw new Error("Missing sec-websocket-protocol header");
  }
  const [encoded] = protocolHeader.split(",").map((x) => x.trim());
  if (!encoded) {
    throw new Error("Invalid sec-websocket-protocol format");
  }
  const decoded = Buffer.from(encoded, "base64").toString("utf-8");
  const [room, userId] = decoded.split(":");
  if (!room || !userId) {
    throw new Error("Room and User ID must be separated by a colon");
  }
  return { room, userId };
}

Read this Stack Overflow post for more info about WebSocket authentication: https://stackoverflow.com/questions/4361173/http-headers-in-websockets-client-api

For the purposes of this tutorial, we are doing no "validation" on the server to make sure the user is who they say they are. This won't work in production where we should probably use a JWT token or similar that can be verified on the server.

WebSocket Hibernation and Serialize/Deserialize Attachment

With Durable Objects, you pay for the time they're active.

This can get expensive with WebSockets because if users are connected to a chat room but not actively chatting, the Durable Object sits idle, costing you money while it maintains the WebSocket connection state.

Thankfully, Cloudflare offers WebSocket Hibernation. This means if a Durable Object has active WebSocket connections but isn't processing messages, it can "hibernate," and you won't pay for the inactive time. The WebSocket connection with the client remains open, and if there's activity, the Durable Object is "revived" to handle it.

Durable Objects let you store a small amount of state (2KB) for each WebSocket that gets restored when it comes back online. This should contain minimal information to identify the client. For storing more info, you should use the Durable Objects Storage API, which lets you use a full-fledged KV store for persistence.

Handling WebSocket Events

For handling WebSocket messages:

We first identify the client based on the object we attach to each client.
We support two types of incoming messages: one where a user announces (or changes) their name, and another where the user can send chat messages.

export class WebSockets extends DurableObject {
  // ...
  override async webSocketMessage(
    ws: WebSocket,
    message: ArrayBuffer | string,
  ) {
    const { room, userId } = ws.deserializeAttachment();
    // Validate message type and size
    // [...]
    try {
      const parsed = JSON.parse(message) as WebSocketMessage;
      if (parsed.type === "chat") {
        if (
          typeof parsed.text !== "string" ||
          parsed.text.trim().length === 0
        ) {
          throw new Error("Invalid chat message");
        }
        const userName =
          (await this.ctx.storage.get<string>(`name:${userId}`)) || userId;
        this.publish(room, {
          type: "chat",
          userId,
          userName,
          text: parsed.text,
          time: new Date().toISOString(),
        });
      } else if (parsed.type === "name") {
        if (
          typeof parsed.name !== "string" ||
          parsed.name.trim().length === 0
        ) {
          throw new Error("Invalid name");
        }
        await this.ctx.storage.put(`name:${userId}`, parsed.name.trim());
        this.publish(room, {
          type: "name",
          userId,
          name: parsed.name.trim(),
          time: new Date().toISOString(),
        });
      } else {
        throw new Error("Unknown message type");
      }
    } catch (err) {
      console.error("Message processing error:", err);
      ws.close(1003, "Invalid message format");
    }
  }
  override async webSocketClose(
    ws: WebSocket,
    code: number,
    reason: string,
    _wasClean: boolean,
  ) {
    const { userId } = ws.deserializeAttachment();
    await this.ctx.storage.delete(`name:${userId}`);
    ws.close(code, reason);
  }
}

I'm using the Durable Objects Storage API for storing the user name with await this.ctx.storage.put and await this.ctx.storage.get.

When a WebSocket connection is closed, we clear the KV for that user.

The Publish Function

To send messages to the users connected to the room, we are using the publish function.

We loop through all the WebSockets connected to our Durable Object instance and send them the message payload.

export class WebSockets extends DurableObject {
  async publish(room: string, data: any) {
    try {
      const websockets = this.ctx.getWebSockets();
      if (websockets.length < 1) {
        return;
      }
      for (const ws of websockets) {
        const state = ws.deserializeAttachment() || {};
        if (state.room === room) {
          ws.send(JSON.stringify(data));
        }
      }
      return null;
    } catch (err) {
      console.error("publish err", err);
    }
  }
}

Note: The room check here is redundant because we are anyway creating a Durable Object instance for each room. But the redundancy is intentional in case we later change the logic for creating Durable Object instances.

Writing our Worker

Now that our Durable Objects are ready to manage state and handle WebSocket connections, let's write the Cloudflare Workers code that uses these Durable Objects:

export default class Worker extends WorkerEntrypoint {
  override async fetch(request: Request) {
    const binding = (this.env as any)
      .WEBSOCKETS as DurableObjectNamespace<WebSockets>;
    try {
      const { room } = extractRoomAndUser(request);
      const stub = binding.get(binding.idFromName(room)); // infer durable object instance from room name
      return stub.fetch(request);
    } catch (err) {
      console.error("Error in worker fetch:", err);
      return new Response(null, { status: 400 });
    }
  }
  async publish(room: string, data: any) {
    const binding = (this.env as any)
      .WEBSOCKETS as DurableObjectNamespace<WebSockets>;
    const stub = binding.get(binding.idFromName(room)); // infer durable object instance from room name
    await stub.publish(room, data);
    return new Response(null);
  }
}

We are using WEBSOCKETS as the binding name to find the Durable Objects class.

Durable Objects don't have a create method to create an instance. So we just use get. A Durable Object gets created on the go, if it's accessed for the first time.

The idFromName function takes a string to generate an ID for the instance such that it will generate the same ID for the same string (and different IDs for different strings). Like we wanted, we use the room name to uniquely identify the Durable Objects.

We also expose a publish method for the worker that passes things off to the this.publish method in the Durable Object. This is useful because we can then call this method from some other worker with a service binding, and this will give us a way to send impromptu "server" messages to users.

Writing the Frontend with `useWebSocket`

In the repository, we have a basic chat UI using Nuxt UI v3 and Tailwind. The important part is in the Messages.vue component where we connect to the WebSockets server:

const protocol = btoa(`${chatRoom}:${currentUser.id}`);
const { send } = useWebSocket(useRuntimeConfig().public.websocketsUrl, {
  protocols: [protocol.replaceAll("=", ""), "chat"],
  onConnected: () => {
    send(
      JSON.stringify({
        type: "name",
        name: currentUser.name,
      }),
    );
  },
  onMessage: (_ws, event) => {
    const data = JSON.parse(event.data);
    if (data.type === "chat") {
      messages.value.push({
        sender: {
          id: data.userId,
          name: data.userName,
        },
        content: data.text,
        timestamp: data.time,
      });
    }
  },
});

We're using useWebSocket from @vueuse/core because it automatically handles reconnections and heartbeats for us.

For the websocketsUrl, we have our runtimeConfig:

export default defineNuxtConfig({
  // [...]
  runtimeConfig: {
    public: {
      websocketsUrl: "ws://localhost:8787", // default used for dev
    },
  },
});

We specify a default value for development, but we override this when deploying to Cloudflare Workers in the sst.config.ts:

// [...]
Nuxt("App", {
  dir: ".",
  domain,
  outputDir: ".output",
  extraVars: {
    NUXT_PUBLIC_WEBSOCKETS_URL: websocketsUrl,
  },
});

I'm currently working on an update to make development easier for Nuxflare. This will simplify using Durable Objects and service bindings in dev mode. The challenge is that you need a separate workers dev server running for these features. Dev mode for D1, KV, R2, etc., is already supported with @nuxt-hub/core and nitro-cloudflare-dev.

Deploying Our Application

To deploy, simply run:

bun nuxflare deploy --stage hello # Use whatever stage you like

You can also completely remove a stage:

bun nuxflare remove --stage hello

And that's it! You now have a real-time chat application running on Cloudflare Workers with Durable Objects and Nuxt. Pretty cool, right?

This only scratches the surface of what you can do with Durable Objects. In future posts, I'll dive deeper into more advanced stuff.

Let me know (X, Discord) if you have any questions or if there's anything specific about Durable Objects you'd like me to cover next!

Before You Go...

Hey, if you've read this far, I'm guessing you found this useful.

I've been working Nuxflare Pro – it's a complete Nuxt + Cloudflare starter kit that saves you tons of setup time.

It's a one-time purchase with lifetime access to all future Nuxflare products
You'll be directly supporting my work to keep building in open-source and create content (like this post)
You'll get early access to everything I create for the Nuxt and Cloudflare ecosystem

Speaking of which... I'm currently building Nuxflare Landing – an AI coding optimized landing page builder that works seamlessly with Nuxt UI and Nuxt Content. As a Pro member, you'll get it completely free when it launches (soon).

Check out Nuxflare Pro

No pressure at all – and thanks for reading either way.

Announcing Nuxflare 0.2: UX improvements, better NuxtHub compatibility, custom domains, GitHub Actions support

Tanay Karnik — Fri, 07 Mar 2025 20:56:59 +0000

I'm super excited to share the release of Nuxflare 0.2.2 with you today.

Here's what's new:

🚀 Better CLI Experience

We've completely rebuilt the CLI to make it easier to use. Getting started is now as simple as:

nuxflare init

Just run this command in your project and follow the simple steps to set up and deploy.

🌐 Custom Domains

You can now easily set up your own domain during the initial setup (with nuxflare init).
This domain is used when you deploy to production:

nuxflare deploy --production

Want separate domains for testing? No problem! Set up a dev domain and use stages:
For example, if your dev domain is dev.nuxflare.com and you deploy to stage tanay, your app will be at tanay.dev.nuxflare.com

nuxflare deploy --stage tanay

🔄 Works Like NuxtHub CLI

If you've used NuxtHub before, you'll feel right at home. We now support familiar commands like:

nuxflare logs --production  # see real-time remote logs
nuxflare open --stage tanay  # quickly view your deployed site

🤖 GitHub Actions Support

Automate everything with our new GitHub Actions support! You can now set up:

Manual deployments
Automatic production deployments with the main branch
Create preview deployments for each PR

🏗️ Cleaner Project Structure

We now create a dedicated nuxflare folder for all the technical stuff, keeping your main sst.config.ts file clean and simple.

🧩 Works With Monorepos

You can now use Nuxflare in projects with multiple Nuxt apps—more about this soon. This is how Nuxflare Pro works.

🛠️ More Reliable Than Ever

We've fixed lots of issues to make everything work better:

Smoother deployments
Better resource handling
Cleaner cleanup when you remove things

Give Nuxflare 0.2 a try today and let me know what you think! I'd love to hear your feedback as we keep making Nuxflare better together.

Nuxt Deployment Guide: How to Deploy Nuxt to Cloudflare

Tanay Karnik — Sat, 22 Feb 2025 15:06:48 +0000

When I first tried deploying a Nuxt app to Cloudflare, I wanted speed, simplicity, and control—here’s the guide I wish I had back then.

Why Cloudflare + Nuxt?

Cloudflare is awesome for deploying Nuxt apps. Here's why:

Your app runs on Cloudflare Workers, which means it's scalable and deployed right at the edge (close to your users) with super-low cold-start times.
The Nuxt community has built first-class support for Cloudflare.
- Nuxt is actually one of the few frameworks specifically optimized to work with Cloudflare.
- Under the hood, Nuxt uses something called unenv to make sure everything plays nicely with the Workers runtime.

The NuxtHub Story

You might have heard of NuxtHub—it's an amazing tool for deploying Nuxt apps to Cloudflare. With just one command (npx nuxthub deploy), you can get your app up and running. Pretty cool, right?

NuxtHub offers:

Super simple deployments with a single command.
Great developer experience with strong support for Cloudflare (D1, KV, AI, R2, Vectorize) through the @nuxt-hub/core module.
Cloudflare bindings setup, and database migrations.
Dev tools to manage your database, blob storage, and KV storage while you're developing.

Where NuxtHub Falls Short: Why I Built Nuxflare

While NuxtHub is great, it has a few limitations that were bugging me:

You don't have full control over how your resources are deployed.
- You can't deploy certain things like Durable Objects (a powerful Cloudflare offering for real-time apps and persisting state in serverless edge deployments), queues, cron triggers, etc.
- You can't set up custom Cloudflare bindings (e.g., service bindings).
While they have a generous free tier now, that could change anytime.

That's why I created Nuxflare. I wanted to keep all the great stuff from NuxtHub but give developers complete control over their deployments.

Here's what Nuxflare offers:

It's completely open-source.
It supports multi-stage deployments (dev, production, staging, etc.).
It works with the NuxtHub core module, so you still get all those great developer tools and features.
It uses open-source tools like SST.dev and Pulumi for deploying and managing resources (infrastructure as code).
- Using Cloudflare's APIs and Wrangler under the hood, so you don't have to expose access to your Cloudflare account.
Bonus: You can mix in components from other cloud providers like AWS, Neon, PlanetScale, Azure, or Vercel (I'll write more about using SST.dev with Nuxflare soon).

Think of NuxtHub as having two parts: their open-source module (the good stuff for developers) and their deployment platform. Nuxflare lets you keep using that first part while giving you more flexibility with the deployment side.

Coming soon: Our next major Nuxflare release will include GitHub Actions integration and even better NuxtHub compatibility.

Ready to Deploy?

I'll walk you through the whole process of getting your Nuxt app up and running on Cloudflare using Nuxflare.

1. Clone an Example NuxtHub Project

First, let's grab a template that shows what Nuxflare can do.

This template demonstrates NuxtHub core features like AI, Blob, Database, Cache, KV, and Vectorize. We can get all this to work with zero config using Nuxflare.

git clone https://github.com/RihanArfan/chat-with-pdf.git
cd chat-with-pdf
npm install

2. Set Up Nuxflare

Run this command and follow the prompts:

npx nuxflare init

It'll ask you for:

Your project name.
Your preferred package manager (npm, yarn, or pnpm).

This creates a special file called sst.config.ts that handles your deployment with SST.dev.

3. Get Your Cloudflare Access Ready

Create an API token using this link.

Set it as an environment variable in your shell:

   export CLOUDFLARE_API_TOKEN=your_token_here

4. Deploy Your App

Ready to go live? Run this:

npx nuxflare deploy --stage dev

You can specify different stage names to deploy copies of your app.
This is useful when deploying development, staging, production, or more environments in the same account.

Working on Your App Locally

When you're developing, you can run the Nuxt dev server manually:

npm run dev

To connect to your remote Cloudflare resources (e.g., database, KV, storage, AI):

npx nuxflare dev --stage dev

This starts up your development server and connects it to all your Cloudflare services.

Under the hood, Nuxflare sets the NUXT_HUB_PROJECT_URL and NUXT_HUB_PROJECT_SECRET_KEY environment variables to connect to your remote Cloudflare resources.

Cleaning Up

Want to remove all resources? Just run:

npx nuxflare remove --stage dev

What's Next?

I'm working on some exciting updates including GitHub Actions support and better NuxtHub compatibility. Stay tuned!

If you're building something serious, check out Nuxflare Pro. It comes with extras like team auth, role-based access control, emails, payments, notifications and real-time features.

Need help? Join our Discord community—we're always happy to help out!

Building something cool with Nuxflare? I'd love to hear about it! Drop me a note or share it in our Discord.

Nuxflare Auth: A lightweight self-hosted auth server built with Nuxt, Cloudflare and OpenAuth.js

Tanay Karnik — Mon, 13 Jan 2025 10:21:25 +0000

Nuxflare Auth is a modern, lightweight, self-hosted authentication server designed to make adding auth to your apps a breeze. Built with Nuxt 3, Cloudflare Workers, and OpenAuth.js, it bundles everything you need in one place.

nuxflare / auth

A modern, lightweight, self-hosted auth server built with Cloudflare, Nuxt, and OpenAuth.js.

Nuxflare Auth

A modern, lightweight, self-hosted auth server built with Cloudflare, Nuxt, and OpenAuth.js.

What's This?

Nuxflare Auth lets you add authentication to your apps without the headache. It's a monorepo that bundles everything you need:

A slick auth UI built with Nuxt 3 and @nuxt/ui
Backend auth magic running on Cloudflare Workers
A ready-to-use example so you can see how it all fits together

Features

🔒 Complete authentication UI including:
- Code-based login
- Password-based login
- Forgot password flow
- User registration
🔑 OAuth2 authentication with GitHub and Google (easily add more providers)
✉️ Emails using Resend (or use any other provider)
⚡ Lightning-fast, powered by Cloudflare's edge network

Project Layout

packages/
  ├── auth-frontend/   # auth UI components
  ├── emails/          # react email templates
  ├── example-client/  # example nuxt client
  └── functions/       # cloudflare workers

Prerequisites

Before getting started, you'll need:

pnpm
A Cloudflare account
OAuth credentials from Google…

View on GitHub

Why Nuxflare Auth?

With Nuxt, there are already good auth modules like nuxt-auth-utils and sidebase-auth.
So, what’s different about Nuxflare Auth?

Decoupled Auth: Nuxflare Auth lets you deploy the auth server and auth UI (built with Nuxt UI) separately from your main app. This means you can easily reuse your auth server to work with multiple client-side apps (built with Nuxt or not), external APIs, mobile apps, and more.
Encourages Monorepo Architecture: By splitting your Nuxt app and auth module, Nuxflare Auth keeps the bundle size minimal—perfect for deployments to Cloudflare Workers, which have strict size limits: 3 MB for the free plan and 10 MB for the paid plan.

Project Structure

packages/
  ├── auth-frontend/   # auth UI components
  ├── emails/          # react email templates
  ├── example-client/  # example nuxt client
  └── functions/       # cloudflare workers

Deploying Nuxflare Auth

Prerequisites

pnpm
A Cloudflare account
OAuth credentials from Google and GitHub
A Resend API key for sending emails

Getting Started

Clone the repository and install dependencies:

   git clone https://github.com/nuxflare/auth nuxflare-auth
   cd nuxflare-auth
   pnpm install

Create and Configure API Token:

a. Create a Cloudflare API token with the required permissions using this link.\
b. Set the CLOUDFLARE_API_TOKEN environment variable:

   export CLOUDFLARE_API_TOKEN=GahXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Configure your secrets:

   # OAuth stuff
   pnpm sst secret set GoogleClientID your_client_id
   pnpm sst secret set GoogleClientSecret your_client_secret
   pnpm sst secret set GithubClientID your_client_id
   pnpm sst secret set GithubClientSecret your_client_secret

   # For emails
   pnpm sst secret set ResendApiKey your_resend_api_key

Configure your fromEmail in sst.config.ts:

   async run() {
     const fromEmail = "hi@nuxflare.com";
     // ...
   }

Start local development:

   pnpm dev

Deploy to production:

   pnpm sst deploy --stage production

Example Client App

The repository includes a simple example client app at packages/example-client.

The API for the composables is very similar to nuxt-auth-utils:

export const useSession = () => {
  const sessionState = useSessionState();
  const accessToken = useAccessTokenCookie();
  const refreshToken = useRefreshTokenCookie();
  const clear = () => {
    sessionState.value = {};
    accessToken.value = null;
    refreshToken.value = null;
  };
  return {
    loggedIn: computed(() => !!sessionState.value.user),
    user: computed(() => sessionState.value.user || null),
    session: sessionState,
    clear,
  };
};

You should point the client to the endpoint of your deployed auth instance:

```typescript [packages/example-client/app/utils/auth.ts]
const client = createClient({
clientID: "nuxt",
issuer: "https://authdemo.nuxflare.com", // <-- replace this with your endpoint
});




---

Thanks for reading!
If you encounter any issues or have suggestions, please [open an issue](https://github.com/nuxflare/auth/issues) on our GitHub repository.

Nuxt Authorization: How to Implement Team Role-Based Access Control in Nuxt 3

Tanay Karnik — Wed, 04 Dec 2024 16:33:26 +0000

If you're building a multi-tenant SaaS in Nuxt 3, you'll need a robust permissions system.
Here's how I built a type-safe RBAC system that scales from small teams to enterprise, using Prisma and tRPC.

The Stack

nuxt-authorization for defining abilities
Prisma for the database layer
tRPC for type-safe API calls
Works with any auth provider (sidebase/nuxt-auth in this example)

Basic Setup

First, install the authorization module:

pnpx nuxi@latest module add nuxt-authorization

Client-Side Authorization

Set up a plugin to resolve the user on the client:

export default defineNuxtPlugin({
  name: "authorization-resolver",
  parallel: true,
  setup() {
    return {
      provide: {
        authorization: {
          resolveClientUser: () => useAuth().data.value?.user,
        },
      },
    };
  },
});

Server-Side Authorization

Similarly for the server:

import { getServerSession } from "#auth";

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook("request", async (event) => {
    event.context.$authorization = {
      resolveServerUser: async () => {
        return (await getServerSession(event))?.user;
      },
    };
  });
});

Defining Type-Safe Abilities

Here's how we define shared abilities that work on both client and server:

interface User {
  id: string;
  teams?: string[];
  permissions?: Record<string, string[]>;
}

const hasTeamPermission = (
  user: User | null,
  teamId: string,
  permission: string,
): boolean =>
  !!user?.teams?.includes(teamId) &&
  (user?.permissions?.[teamId] || []).includes(permission);

export const listTeams = defineAbility(() => true);

export const getTeamDetails = defineAbility(
  (user: User, teamId: string) => !!(teamId && user?.teams?.includes(teamId)),
);

export const updateTeamDetails = defineAbility(
  (user: User | null, teamId: string) =>
    hasTeamPermission(user, teamId, PERMISSIONS.TEAMS.UPDATE),
);

Database Schema

Your Prisma schema needs to support roles and permissions:

model TeamMembership {
  id     String @id @default(cuid())
  role Role @relation(fields: [roleId], references: [id])
  // [...]
}

model Role {
  id           String  @id @default(cuid())
  teamId       String?
  name         String
  description  String?
  isDefault    Boolean @default(false)
  isSystemRole Boolean @default(false)
  permissions Permission[]
  // [...]
}

model Permission {
  id          String  @id @default(cuid())
  title       String
  description String?
  action      String
  roleId      String
  // [...]
}

Using Abilities in Components

Check permissions in your Vue components:

<Can :ability="deleteTeamAbility" :args="[team?.id || '']">
  <!-- Protected content here -->
</Can>

Type-Safe API Authorization

Create a tRPC procedure for checking abilities:

export const abilityProcedure = protectedProcedure.use(async (opts) => {
  const { ctx } = opts;
  return opts.next({
    ctx: {
      ...ctx,
      allows: async function allow<Ability extends BouncerAbility<any>>(
        ability: Ability,
        ...args: BouncerArgs<Ability>
      ) {
        return await allows(ctx.event, ability, ...args);
      },
      authorize: async function auth<Ability extends BouncerAbility<any>>(
        ability: Ability,
        ...args: BouncerArgs<Ability>
      ) {
        try {
          await authorize(ctx.event, ability, ...args);
        } catch (error) {
          throw new TRPCError({
            code: "FORBIDDEN",
            message: error instanceof Error ? error.message : "Not authorized",
          });
        }
      },
    },
  });
});

Use it in your API routes:

{
  get: abilityProcedure
    .input(
      z.object({
        teamIdentifier: z.string(),
      }),
    )
    .query(async ({ ctx: { authorize, user, prisma }, input }) => {
      await authorize(getTeamDetails, team.id);
      // Protected logic here
    }),
}

Why this works well

Fully type-safe from database to UI
No external authorization service needed
Works seamlessly with any auth provider
Scales from simple to complex permission structures

Try it yourself

Want to see this RBAC system in action? This exact implementation is part of my Nuxt SaaS boilerplate.

If you're building a multi-tenant SaaS, check it out—it comes with everything you need: type-safe APIs using tRPC, team management, authentication, billing, and more. Every feature is built with the same attention to developer experience as this permissions system.

Sending Emails in Nuxt 3: How I Handle Emails in My SaaS Boilerplate

Tanay Karnik — Wed, 27 Nov 2024 15:40:40 +0000

If you're building anything serious in Nuxt 3, you'll need to send emails.
Here's my setup that lets you switch between Resend, SendGrid, or any other provider without rewriting code.

The Setup

AdonisJS Mail (I made it work outside AdonisJS so it works with any JS backend)
Vue Email for templates
Works with any email provider (Resend, AWS SES, Mailgun, Sparkpost, Brevo, Custom SMTP)

Basic Configuration

const generateMailer = async () => {
  const mailer = await generateMailer({
    default: "resend",
    from: {
      address: "hi@saas-boilerplate.dev",
      name: "SaaS Boilerplate",
    },
    mailers: {
      resend: transports.resend({
        key: process.env.RESEND_API_KEY || "",
        baseUrl: "https://api.resend.com",
      }),
      // Easy to add more providers!
      sendgrid: transports.sendgrid({
        key: process.env.SENDGRID_API_KEY || "",
      })
    },
  });

  return mailer;
};

Email Templates with Vue Email

Here's a simple magic link email template:

<template>
  <Html>
    <Body>
      <Container>
        <Heading>Sign In to Your Account</Heading>
        <Text>Hi {{ username }},</Text>
        <Text>Click the button below to sign in:</Text>
        <Section>
          <Button :href="signInLink">Sign In</Button>
        </Section>
        <Text>
          Or copy this link: 
          <Link :href="signInLink">{{ signInLink }}</Link>
        </Text>
        <Hr />
        <Text>This link expires in 1 hour.</Text>
      </Container>
    </Body>
  </Html>
</template>
<script setup lang="ts">
import {
  Body, Button, Container, Heading,
  Html, Link, Section, Text, Hr
} from "@vue-email/components";

interface Props {
  username?: string;
  signInLink?: string;
}

withDefaults(defineProps<Props>(), {
  username: "User",
  signInLink: "https://app.example.com/sign-in",
});
</script>

Sending Emails

import MagicLinkSignIn from "~/emails/MagicLinkSignIn.vue";
const mailer = await getMailer();
await mailer.send(async (message) => {
  message
    .to(email)
    .subject("Magic Link Sign In")
    .html(
      await render(MagicLinkSignIn, {
        username: user?.name,
        signInLink: url,
      })
    );
});

Cool Features from AdonisJS Mail

AdonisJS Mail comes with tons of powerful features that we can use:

Multiple Transport Support: Switch between email providers with one line of code
Calendar Events: Attach calendar invites to your emails
File Attachments: Easily attach files, streams, or buffers
HTML/Text Templates: Support for both HTML and plain text emails

For example, attaching a calendar invite is as simple as:

message.icalEvent((calendar) => {
  calendar.createEvent({
    summary: 'Team Meeting',
    start: DateTime.local().plus({ minutes: 30 }),
    end: DateTime.local().plus({ minutes: 60 }),
  })
});

Why this works well

Switch providers anytime
Write templates in Vue
Easy to test
All the power of AdonisJS Mail in any JS backend

Try it yourself

Want to learn more about what AdonisJS Mail can do? Check out their detailed documentation.

This email setup is part of my Nuxt SaaS boilerplate.

If you're building a SaaS, check it out—it comes with type-safe APIs using tRPC, enterprise-grade RBAC (role-based access control), and production-ready features like auth, team management, and billing.

Every feature is built with the same attention to developer experience as this email system.

Building a Card with Gradient Hover Effect Inspired by Nuxt UI

Tanay Karnik — Thu, 31 Oct 2024 04:05:54 +0000

I came across an amazing card hover effect on the Nuxt UI website.

Unfortunately, it’s a pro component—so I decided to build it myself!

I tried getting some inspiration by inspecting their code, but it was more complex than I expected.
I'm no CSS wizard, so I came up with a much simpler version of this effect.

Here’s a tutorial on how to make a card with a cool gradient hover effect using TailwindCSS.

1. Set up a simple card component

<template>
  <div :class="['bg-neutral-950', props.class || '']"></div>
</template>

<script setup>
const props = defineProps(["class"]);
</script>

Let’s start by building a basic card component with a black background, arranged in a grid.

This setup will be our testing ground.

I'm using Vue here, but this can be easily replicated with React, Vanilla JS, or any other framework.

2. Add a circular gradient that follows the mouse

<template>
  <div
    ref="target"
    :style="cssVars"
    :class="['shine bg-neutral-950', props.class || '']"
  ></div>
</template>

<script setup>
import { ref, computed } from "vue";
import { useMouseInElement } from "@vueuse/core";
const props = defineProps(["class"]);
const target = ref(null);
const { elementX, elementY } = useMouseInElement(target);
const cssVars = computed(() => ({
  "--x": `${target.value ? elementX.value : -1000}px`,
  "--y": `${target.value ? elementY.value : -1000}px`,
}));
</script>

<style scoped>
.shine {
  background-image: radial-gradient(
    300px circle at var(--x) var(--y),
    #6366f1 0,
    transparent 100%
  );
}
</style>

The next step is adding a circular gradient that follows the mouse.

First, add a shine class to the card div and set it up with a radial-gradient.
This gradient is centered at CSS variables --x and --y, going from bright (any color) at the center to fully transparent, with a 300px radius (adjustable).

To make the gradient follow the mouse, I’m using a useMouseElement composable. Here, elementX and elementY are the mouse coordinates relative to the position of the target element.

Depending on your framework, you could use a different hook or add a mousemove event listener to update these CSS variables.

3. Stacking divs

<template>
  <div
    ref="target"
    :style="cssVars"
    :class="['p-[2px] shine bg-neutral-950', props.class || '']"
  >
    <div class="w-full h-full bg-neutral-950/80"></div>
  </div>
</template>

<script setup>
import { ref, computed } from "vue";
import { useMouseInElement } from "@vueuse/core";
const props = defineProps(["class"]);
const target = ref(null);
const { elementX, elementY } = useMouseInElement(target);
const cssVars = computed(() => ({
  "--x": `${target.value ? elementX.value : -1000}px`,
  "--y": `${target.value ? elementY.value : -1000}px`,
}));
</script>

<style scoped>
.shine {
  background-image: radial-gradient(
    300px circle at var(--x) var(--y),
    #6366f1 0,
    transparent 100%
  );
}
</style>

I know what you’re thinking—it doesn’t look like the final card effect at all.

The trick to achieving the right look is to stack another div on top with a small amount of padding (I used 2px).

There are other ways to achieve this effect, like using ::before pseudo-elements or Tailwind rings, but I found this to be the simplest and cleanest approach.

4. Finishing touches

<template>
  <div
    ref="target"
    :style="cssVars"
    :class="['rounded-[15px] p-[2px] shine', props.class || '']"
  >
    <div
      class="rounded-[13px] w-full h-full bg-gradient-to-b from-neutral-800/50 to-neutral-950/50 bg-neutral-950/80"
    ></div>
  </div>
</template>

<script setup>
import { ref, computed } from "vue";
import { useMouseInElement } from "@vueuse/core";
const props = defineProps(["class"]);
const target = ref(null);
const { elementX, elementY } = useMouseInElement(target);
const cssVars = computed(() => ({
  "--x": `${target.value ? elementX.value : -1000}px`,
  "--y": `${target.value ? elementY.value : -1000}px`,
}));
</script>

<style scoped>
.shine {
  background-image: radial-gradient(
    300px circle at var(--x) var(--y),
    #6366f1 0,
    transparent 100%
  );
}
</style>

Finally, give the outer div a subtle background gradient and rounded borders.

To keep the padding and border-radius looking clean, I added 2px to the border radius of the outer div (general tip: adjust by padding * 1.141 for a proportional look).

Here's the GitHub repo to see the code in action:

tanayvk / shiny-cards

Shiny Cards

Nuxt shiny card hover effect.

View on GitHub

How I built PeerSplit: A free, peer-to-peer expense-splitting app—from idea to launch in just 2 weeks

Tanay Karnik — Tue, 22 Oct 2024 07:00:00 +0000

I built PeerSplit—a free, peer-to-peer alternative to Splitwise—in just two weeks, from idea to launch!

PeerSplit is a local-first app for splitting group expenses. It works offline, is 100% free and private, and doesn't require signups or any personal data.

Here’s how I built it and everything I learned along the way.

Why PeerSplit?

I’ve relied on Splitwise for years to manage expenses with friends and roommates. But with its recent daily transaction limits and intrusive ads, it’s become frustrating to use.

I wanted a free, privacy-first alternative that didn't require servers to store or sync data. I wouldn't trust my expenses with a third-party server.

After working on peer-to-peer, local-first projects like a workout tracker and a distraction-free writing app, I realized I could apply the same approach to expense splitting.

That’s how PeerSplit was born. I started designing the app.

Building the UI with Nuxt + Nuxt UI

I suck at designing UIs.

A few months ago, I wouldn't have thought I could build a UI as polished as PeerSplit's (some people even say it has better UX than Splitwise).

So, how did I manage to do it? Nuxt UI.

Nuxt UI is gorgeous, and it has amazing developer experience (DX).

It also comes with other useful Nuxt modules like @nuxt/icon, @nuxtjs/tailwindcss, and @nuxtjs/colormode.

All I had to do was pick a primary color, and I had all the components I needed—icons, dark mode, and everything else—to bring PeerSplit’s UI together.

cr-sqlite for local syncing 🔗

For local data storage and syncing, I went with cr-sqlite, which builds on wa-sqlite and uses CRDTs (conflict-free replicated data types).

CRDTs are great for peer-to-peer systems because they handle conflicts automatically—so users can work offline, and when they reconnect, changes merge seamlessly.

However, cr-sqlite doesn't sync changes over the network by itself. It only provides APIs to export and merge changes. You need to manually send those changes between devices.

Gun.js for peer-to-peer syncing 🌐

To handle secure peer-to-peer syncing, I used Gun.js, which provides a peer-to-peer, distributed graph database.

Gun’s gun.user API lets me create encrypted nodes for each group. All changes for a group are stored on that node and synced only with group members, keeping everything private.

When a user performs an action, I take the changes exported from cr-sqlite and push them to the node. When the user comes back online, Gun syncs the new changes, keeping everyone up-to-date.

Implementing this in a performant way was tricky. For more details, you can check out the source code here.

Simplifying debts 💰

One cool feature of Splitwise (and now PeerSplit) is "simplifying debts."

Here’s how it works: If A owes B and B owes C, A can just pay C directly to potentially reduce the number of repayments.

In PeerSplit, I first calculate the net balance for each person. Then I sort those balances and suggest payments one by one to bring at least one person’s balance to zero each time.

This sorting ensures that everyone sees the same repayments on their devices.

It’s not 100% optimal (some groups might still have up to n-1 payments), but it works well in most cases.

An optimal solution would be exponential to calculate and would only save a few payments. So this was the best tradeoff for simplicity and speed!

export const groupGetPayments = (group) => {
  const payments = [];
  const balances = Object.entries(groupGetBalances(group)).map(([a, b]) => [
    b,
    a,
  ]);
  balances.sort();
  let i = 0,
    j = balances.length - 1;
  while (i < j) {
    if (balances[i][0] === 0) {
      i++;
    } else if (balances[j][0] === 0) {
      j--;
    } else if (-balances[i][0] > balances[j][0]) {
      payments.push({
        from: balances[i][1],
        to: balances[j][1],
        value: round(balances[j][0]),
      });
      balances[i][0] += balances[j][0];
      balances[j][0] = 0;
    } else {
      payments.push({
        from: balances[i][1],
        to: balances[j][1],
        value: round(-balances[i][0]),
      });
      balances[j][0] += balances[i][0];
      balances[i][0] = 0;
    }
  }
  return payments;
};

PWA

I wanted PeerSplit to function as an offline app, but I didn’t want to go through the hassle of building multiple native applications or dealing with the lengthy process of publishing them on app stores. So, opting for a Progressive Web App (PWA) was the clear choice.

A PWA combines the best of web and mobile apps, allowing users to install it on their devices while still enjoying offline capabilities.

To transform my Nuxt app into a PWA, I used vite-pwa.
I designed an SVG logo in Figma and used it to generate all the necessary PWA assets through vite-pwa’s asset generator.

After that, I configured the PWA manifest, and vite-pwa automatically set up the service worker for me.

I configured Nuxt to prerender all the routes, so that my app could fully function offline.

And that's a wrap. Thanks for reading!

Product Hunt Launch

PeerSplit just launched on Product Hunt! It's my first launch, and I’d love your support and feedback.

Check out PeerSplit on Product Hunt

PeerSplit is fair-source, so feel free to contribute or submit feature requests on GitHub.

tanayvk / peersplit

PeerSplit is a free, local-first, peer-to-peer app that helps you easily and privately split and track group expenses.

PeerSplit

PeerSplit is a free, local-first, peer-to-peer app that helps you easily and privately split and track group expenses.

Features

💯 100% Free — No sign-up required
🌐 Local-First — Works fully offline
📱 Cross-Platform PWA — Use it on mobile, desktop, or laptop
🔒 Peer-to-Peer — Collaborate with friends while keeping your data private
⚡ Simple UX — A smooth and minimal interface that stays out of your way
🌙 Dark and Light Modes — Switch between themes to match your preferences
🔄 Import/Export — Import from Splitwise and export data to CSV

Planned Features

🔢 Advanced Bill Splitting — Add an itemized bill as a single expense.
🧾 Bill Scanning — Automatically scan and split bills by taking a picture.
💱 Multi-Currency Support — Handle expenses in different currencies with real-time conversion rates.
📝 Transaction Notes & Comments — Add notes and comments for each transaction to keep…

View on GitHub

DEV Community: Tanay Karnik

A closer look at the SpacetimeDB v2 benchmark: Is it really 23x faster than SQLite?

Bare metal and broken code

Initial results and more broken code

The first run

Getting SQLite to 160K TPS

Fix #1: Breaking the double-fsync

Fix #2: Apples, oranges, and network protocols

Fix #3: The physics of batching

Why did it stop at 160K?

The results

Closing thoughts

SpacetimeDB as a product

On durability and production

Cloudflare Durable Objects & Nuxt: Building a Real-Time Chat App

Let's get started

Setting up Nuxflare

Configuring the Infrastructure

Understanding Durable Objects

Creating our Durable Objects Class

Handling WebSocket Requests

Authentication with the WebSocket Protocols Header

WebSocket Hibernation and Serialize/Deserialize Attachment

Handling WebSocket Events

The Publish Function

Writing our Worker

Writing the Frontend with useWebSocket

Deploying Our Application

Before You Go...

Announcing Nuxflare 0.2: UX improvements, better NuxtHub compatibility, custom domains, GitHub Actions support

🚀 Better CLI Experience

🌐 Custom Domains

🔄 Works Like NuxtHub CLI

🤖 GitHub Actions Support

🏗️ Cleaner Project Structure

🧩 Works With Monorepos

🛠️ More Reliable Than Ever

Nuxt Deployment Guide: How to Deploy Nuxt to Cloudflare

Why Cloudflare + Nuxt?

The NuxtHub Story

Where NuxtHub Falls Short: Why I Built Nuxflare

Ready to Deploy?

1. Clone an Example NuxtHub Project

2. Set Up Nuxflare

3. Get Your Cloudflare Access Ready

4. Deploy Your App

Working on Your App Locally

Cleaning Up

What's Next?

Nuxflare Auth: A lightweight self-hosted auth server built with Nuxt, Cloudflare and OpenAuth.js

nuxflare / auth

A modern, lightweight, self-hosted auth server built with Cloudflare, Nuxt, and OpenAuth.js.

Nuxflare Auth

What's This?

Features

Project Layout

Prerequisites

Why Nuxflare Auth?

Project Structure

Deploying Nuxflare Auth

Prerequisites

Getting Started

Example Client App

Nuxt Authorization: How to Implement Team Role-Based Access Control in Nuxt 3

The Stack

Basic Setup

Client-Side Authorization

Server-Side Authorization

Defining Type-Safe Abilities

Database Schema

Using Abilities in Components

Type-Safe API Authorization

Why this works well

Try it yourself

Sending Emails in Nuxt 3: How I Handle Emails in My SaaS Boilerplate

The Setup

Basic Configuration

Email Templates with Vue Email

Sending Emails

Cool Features from AdonisJS Mail

Writing the Frontend with `useWebSocket`