Next.js Server Actions: Using Outbox Patterns for Distributed Transactions

When I first started building features with Next.js Server Actions, I assumed that wrapping a database call and an API request in a single function was "good enough." It felt like a transaction. But during a recent high-traffic deployment, we saw exactly why that assumption is dangerous: if the database commit succeeds but the downstream service call fails—or worse, times out—you're left with a split-brain state that’s a nightmare to reconcile.

We’ve been exploring how to handle these failures by decoupling our operations. While we've previously looked at Next.js Server Actions: Implementing Saga Pattern Orchestration for complex multi-step workflows, simpler side-effects often benefit more from an Outbox Pattern.

The Problem with Direct Side-Effects

In a standard Server Action, you might do this:

TYPESCRIPT
// DON'T DO THIS for critical side-effects
async function createOrder(data: OrderInput) {
  const order = await db.order.create({ data });
  // If this fails, the order is already in the DB, but the user doesn't know.
  await stripe.paymentIntents.create({ ... }); 
  return order;
}

If stripe throws an error, your database has an order, but your billing system is unaware. You’ve broken atomicity. We tried wrapping these in local try-catch blocks to trigger manual rollbacks, but that quickly leads to "callback hell" and fragile logic. We even experimented with Next.js Server Actions: Ensuring Data Integrity via Immutable Contracts to validate inputs, but validation doesn't fix a network partition between your server and a third-party API.

Implementing the Outbox Pattern

The Outbox Pattern shifts the paradigm. Instead of executing the side-effect immediately, you save an "event" into a dedicated table in the same transaction as your primary data change.

Here is the flow:

1. Open a database transaction.
2. Insert the Order record.
3. Insert an OutboxEvent record (e.g., PAYMENT_PENDING) in the same table.
4. Commit the transaction.
5. A background worker (or a cron job) polls the OutboxEvent table and processes the side-effect.

This ensures that your Next.js Server Actions always maintain data integrity. Even if your process crashes immediately after the commit, the event is persisted.

Building the Infrastructure

You don't need a complex message broker to start. A simple table in your existing Postgres instance works wonders.

SQL
CREATE TABLE outbox_events (
  id UUID PRIMARY KEY,
  aggregate_type TEXT NOT NULL,
  payload JSONB NOT NULL,
  processed BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT NOW()
);

In your Server Action, your logic becomes strictly atomic:

TYPESCRIPT
async function createOrder(data: OrderInput) {
  return await db.$transaction(async (tx) => {
    const order = await tx.order.create({ data });
    await tx.outboxEvent.create({
      data: {
        aggregateType: CE9178">'ORDER_CREATED',
        payload: { orderId: order.id, amount: order.total }
      }
    });
    return order;
  });
}

Managing Eventual Consistency

By using this approach, you've moved from immediate consistency to eventual consistency. The downside is that your UI might need to handle a state where the order is "Processing" rather than "Complete."

We’ve found that using a background worker—or even a lightweight Vercel Cron job—to process these events is the most resilient path. If the Stripe API is down, the worker simply retries the event later. This is significantly more robust than expecting a user to wait for a synchronous API call to finish during a Server Action execution.

When building these, keep in mind that your event processors must be idempotent. If your worker crashes halfway through processing an event, it will retry. Ensure your downstream services can handle receiving the same orderId twice without creating duplicate charges or records.

Is this overkill?

Not every action needs an outbox. If your side-effect is just sending an email notification, a simple background task might suffice. But if you’re managing distributed transactions involving money, inventory, or user account status, the overhead is worth the safety.

I’m still refining how we handle the "polling" aspect. We’ve considered using a dedicated queue like BullMQ, but keeping it inside the database keeps our infrastructure simple. It’s a trade-off between operational complexity and data safety.

What I’d do differently next time? I’d bake the Outbox logic into a Prisma middleware or a decorator to keep the Server Actions clean. Right now, it's a bit manual, and manual steps are where bugs hide.

FAQ

Q: Does this increase latency for the end user? A: No, it actually decreases it. Your Server Action only performs local database writes rather than waiting for slow, third-party network requests to resolve.

Q: How do I handle failures in the background worker? A: Implement a retry-with-backoff strategy. Since the event is persisted in the database, you can log failures, alert your team, and manually inspect the outbox_events table if a specific event keeps failing.

Q: Can I use this with non-relational databases? A: It's harder. The beauty of this pattern is the ACID compliance of a relational database transaction. If you're using a document store, you might need to look into Change Data Capture (CDC) tools like Debezium.