Mandu vs Next.js#

TL;DR — Same app/**/page.tsx mental model. Mandu adds runtime architecture Guard, contract-first APIs, and 100+ MCP tools so AI agents can drive your codebase end-to-end. Built on Bun, not Node.

When to pick which#

Side by side#

Code comparison — typical signup endpoint#

Next.js (~30 lines, hand-synced everywhere):

// app/api/signup/route.ts
import { z } from "zod";
import { NextRequest, NextResponse } from "next/server";

const SignupSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

export async function POST(req: NextRequest) {
  const csrf = req.headers.get("x-csrf-token");
  if (csrf !== req.cookies.get("__csrf")?.value)
    return NextResponse.json({ error: "csrf" }, { status: 403 });
  const raw = await req.json().catch(() => null);
  const parsed = SignupSchema.safeParse(raw);
  if (!parsed.success)
    return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
  try {
    const user = await db.user.create({ data: parsed.data });
    return NextResponse.json({ id: user.id }, { status: 201 });
  } catch (err) {
    if ((err as any).code === "P2002")
      return NextResponse.json({ error: "duplicate" }, { status: 409 });
    return NextResponse.json({ error: "internal" }, { status: 500 });
  }
}

Mandu (6 lines + a contract file, both type-checked together):

// app/api/signup/route.ts
import { Mandu } from "@mandujs/core";
import { SignupContract } from "@/spec/contracts/signup.contract";

export default Mandu.handler(SignupContract, {
  POST: async (ctx) => ctx.created({ id: (await ctx.db.user.create({ data: ctx.body })).id }),
});

The contract file (spec/contracts/signup.contract.ts) is the single source of truth — Mandu derives request/response types, runtime validation, OpenAPI export, and a typed client wrapper from it. An agent only has to read the contract to know what the API does.

Migration path#

If you're already on Next.js, you can move incrementally:

1. Same routing tree — copy app/ over; page.tsx, layout.tsx, [lang], [...slug] work as-is.
2. Replace route.ts handlers with Mandu.filling() chains or Mandu.handler(contract, ...) — the handler signature is the only meaningful diff.
3. Lift hand-wired auth to the chain (.use(withSession()), .use(withCsrf())).
4. Add mandu.config.ts and run mandu guard to surface any architectural violations in the existing code.

When Next.js is still the right call#

• Heavy reliance on Vercel-specific Next features (ISR-by-tag, Server Actions ecosystem, partial pre-rendering) that Mandu has equivalents for but with smaller community footprint.
• Team has zero appetite for Bun runtime (the @mandujs/cli package keeps you on Node-style npm install at least, but the runtime itself is Bun).
• Plugin you depend on only ships as a Next plugin.

🤖 Agent Prompt — explore Mandu against your existing Next code#

I have a Next.js app and I'm evaluating Mandu (https://mandujs.com).

1. Pick a representative route (an API + a page) from my codebase.
2. Show me what the same route would look like as Mandu —
   `Mandu.filling()` chain or `Mandu.contract({...})` +
   `Mandu.handler(contract, ...)` — using the exact paths and types
   my Next route already uses.
3. Highlight which lines disappear (CSRF, manual zod parse, status
   code branching) because Mandu derives them from the contract.
4. Estimate how much of the codebase would migrate cleanly vs need
   rewriting (give me a percentage with reasoning).
5. List the top 3 risks of switching for my project specifically.

Related#

• start/quickstart — install Mandu in 5 minutes
• recipes/create-api — both Mandu API patterns
• architect/guard — what Guard catches at runtime
• migrate — full migration guides (Next, Remix, Astro, SvelteKit)