{"id":404,"date":"2026-07-01T05:04:34","date_gmt":"2026-07-01T05:04:34","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/nextjs-server-actions-when-i-stopped-writing-api-routes\/"},"modified":"2026-07-01T05:04:34","modified_gmt":"2026-07-01T05:04:34","slug":"nextjs-server-actions-when-i-stopped-writing-api-routes","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/nextjs-server-actions-when-i-stopped-writing-api-routes\/","title":{"rendered":"Next.js Server Actions: When I Stopped Writing API Routes"},"content":{"rendered":"

Short version for the impatient: I rewrote a side project’s checkout flow last weekend and deleted seven app\/api\/...<\/code> route handlers in the process. The form components now call Server Actions directly. The code is shorter, the types are tighter, and I spent about an hour fighting a redirect bug I didn’t see coming. If you want to know why I made the switch (and where I still keep API routes around), read on.<\/p>\n

I’m not going to pretend Server Actions are some revolution. They’re a small idea with big consequences for how you organize Next.js apps. After about six months of using them in production, I have opinions on when they pay off, when they don’t, and the specific footguns I keep hitting. This is that writeup.<\/p>\n

The mental shift I had to make<\/h2>\n

The thing that finally clicked for me: a Server Action isn’t an API endpoint that happens to live next to your component. It’s an RPC call dressed up as a function. You write a function on the server, mark it with \"use server\"<\/code>, and the client gets a generated POST stub that calls it for you.<\/p>\n

Here’s what mutating data looked like in my Next.js 13 codebase, before I switched:<\/p>\n

\/\/ app\/api\/notes\/route.ts\nimport { NextResponse } from 'next\/server'\nimport { auth } from '@\/lib\/auth'\nimport { db } from '@\/lib\/db'\n\nexport async function POST(req: Request) {\n  const session = await auth()\n  if (!session) return NextResponse.json({ error: 'unauthorized' }, { status: 401 })\n\n  const body = await req.json()\n  const title = String(body.title ?? '').trim()\n  if (!title) return NextResponse.json({ error: 'title required' }, { status: 400 })\n\n  const note = await db.note.create({\n    data: { title, userId: session.user.id }\n  })\n  return NextResponse.json(note)\n}\n<\/code><\/pre>\n
And the client side:<\/p>\n
\/\/ app\/notes\/NewTodo.tsx\n'use client'\nimport { useState } from 'react'\n\nexport function NewTodo() {\n  const [title, setTitle] = useState('')\n  const [pending, setPending] = useState(false)\n\n  async function submit(e: React.FormEvent) {\n    e.preventDefault()\n    setPending(true)\n    const res = await fetch('\/api\/notes', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application\/json' },\n      body: JSON.stringify({ title })\n    })\n    setPending(false)\n    if (res.ok) setTitle('')\n  }\n\n  return (\n    <form onSubmit={submit}>\n      <input value={title} onChange={e => setTitle(e.target.value)} \/>\n      <button disabled={pending}>Add<\/button>\n    <\/form>\n  )\n}\n<\/code><\/pre>\n
Look at that. Two files, a hand-rolled fetch, a hand-rolled pending state, manual JSON serialization on both ends, and zero type safety between them. The client doesn’t know what the server returns; if I rename title<\/code> to name<\/code> on the server, the client compiles cleanly and breaks at runtime.<\/p>\n
Here’s the same thing with a Server Action:<\/p>\n
\/\/ app\/notes\/actions.ts\n'use server'\nimport { auth } from '@\/lib\/auth'\nimport { db } from '@\/lib\/db'\nimport { revalidatePath } from 'next\/cache'\n\nexport async function createTodo(formData: FormData) {\n  const session = await auth()\n  if (!session) throw new Error('unauthorized')\n\n  const title = String(formData.get('title') ?? '').trim()\n  if (!title) throw new Error('title required')\n\n  await db.note.create({\n    data: { title, userId: session.user.id }\n  })\n  revalidatePath('\/notes')\n}\n<\/code><\/pre>\n
\/\/ app\/notes\/NewTodo.tsx\nimport { createTodo } from '.\/actions'\n\nexport function NewTodo() {\n  return (\n    <form action={createTodo}>\n      <input name="title" \/>\n      <button>Add<\/button>\n    <\/form>\n  )\n}\n<\/code><\/pre>\n
No client component. No useState<\/code>. No fetch. The form’s action<\/code> attribute now accepts a server function directly, and Next.js handles the wire protocol. If I rename the export, TypeScript yells at me on both sides because the import is a real function reference. That’s the whole pitch in one diff.<\/p>\n
What actually replaced API routes for me<\/h2>\n
I didn’t go nuclear and delete every route handler. I made a rule for myself: a Server Action is right when the call is internal<\/strong>, mutating<\/strong>, and co-located<\/strong> with the component that calls it. An API route is right when any of those three break.<\/p>\n
Internal: the only consumer is my own UI. Server Actions are not a public API. Their endpoints are POST-only, the URLs include an action ID, and they’re meant to be called by the framework’s generated stubs. If a mobile app or a Zapier webhook needs to hit the same logic, that’s an API route (or a tRPC procedure, which I covered in my tRPC writeup<\/a>).<\/p>\n
Mutating: writes, not reads. Reads should happen in Server Components during render, not via a POST round-trip. I see people use Server Actions for getUser()<\/code> and it makes me twitch. They’re called via POST, they bypass the React cache, and you lose streaming. Just await<\/code> the query in the Server Component.<\/p>\n
Co-located: the component that triggers the action is the only one that calls it. The moment two pages need the same mutation logic with different UX, I extract the underlying function and let both call it. The Action stays a thin shell.<\/p>\n
The Next.js docs are direct about this. The official Server Actions guide<\/a> calls them “asynchronous functions that are executed on the server” and explicitly frames them as a tool for mutations and form submissions. They are not a replacement for your whole backend.<\/p>\n
The progressive enhancement bit that surprised me<\/h2>\n
I’d read about progressive enhancement with Server Actions before I tried them. I assumed it was a checkbox feature nobody actually relied on. Then I disabled JavaScript in DevTools, hit submit, and the form still worked. Not “degraded gracefully”. Actually worked. Submitted the form, ran the action, redirected back, showed the new note.<\/p>\n
That’s because passing a server function to form action<\/code> produces real HTML that posts to a real URL. The client JS hijacks it when it’s available and turns it into a fetch, but the underlying form is a form. This is the part of React 19’s design that I think is undersold. The React Actions documentation<\/a> treats this as the default, not an edge case.<\/p>\n
For a content site or an admin dashboard where users might have flaky connections, this is genuinely useful. For a SPA-feel product, it’s a nice-to-have. But I stopped writing client components for forms unless I have a real reason \u2014 most of mine don’t need state at all.<\/p>\n
Pending UI without writing pending UI<\/h2>\n
The pending state I used to track with useState<\/code> is now useFormStatus<\/code>. You drop it inside the form and it tells you whether the action is in flight:<\/p>\n
'use client'\nimport { useFormStatus } from 'react-dom'\n\nexport function SubmitButton() {\n  const { pending } = useFormStatus()\n  return (\n    <button disabled={pending}>\n      {pending ? 'Adding\\u2026' : 'Add'}\n    <\/button>\n  )\n}\n<\/code><\/pre>\n
The gotcha: useFormStatus<\/code> reads from the nearest parent <form><\/code>. It only works in a child component, not in the form itself. That tripped me up the first time. I had the hook in the same component that rendered the <form><\/code>, and pending<\/code> was always false. Five minutes of staring before I read the docs properly. The hook is reading the wrong form’s context, because it’s the form’s parent<\/em>.<\/p>\n
For optimistic UI I reach for useOptimistic<\/code>, which I wrote about in detail in my post on optimistic UI I stopped hand-rolling<\/a>. The pair is meant to be used together: useFormStatus<\/code> for the spinner, useOptimistic<\/code> for the optimistic update, and the Server Action for the actual write.<\/p>\n
The error handling story is rougher than I’d like<\/h2>\n
This is the part where I admit I’m not fully sold yet. Throwing in a Server Action gives you a stack trace on the server and a generic error on the client. There’s no built-in field-level validation pattern. You can return an error object instead of throwing, but then every action becomes a tagged union and every form has to discriminate it.<\/p>\n
The pattern I’ve settled on uses useActionState<\/code>:<\/p>\n
\/\/ actions.ts\n'use server'\nexport type CreateTodoState = { error?: string } | { ok: true }\n\nexport async function createTodo(\n  _prev: CreateTodoState,\n  formData: FormData\n): Promise<CreateTodoState> {\n  const title = String(formData.get('title') ?? '').trim()\n  if (!title) return { error: 'Title is required' }\n  if (title.length > 200) return { error: 'Title too long' }\n\n  try {\n    await db.note.create({ data: { title, userId: '...' } })\n  } catch (e) {\n    return { error: 'Could not save. Try again?' }\n  }\n  return { ok: true }\n}\n<\/code><\/pre>\n
\/\/ NewTodo.tsx\n'use client'\nimport { useActionState } from 'react'\nimport { createTodo } from '.\/actions'\n\nexport function NewTodo() {\n  const [state, formAction] = useActionState(createTodo, { ok: true } as any)\n  return (\n    <form action={formAction}>\n      <input name="title" \/>\n      <button>Add<\/button>\n      {'error' in state && state.error && <p role="alert">{state.error}<\/p>}\n    <\/form>\n  )\n}\n<\/code><\/pre>\n
It works. It’s also more ceremony than I’d want for every form. I’ve started reaching for a small wrapper that takes a Zod schema and returns a validated action, which gets me back to the brevity I had before. If you’re already using Zod with the validation patterns I covered for runtime types<\/a>, this is the natural extension.<\/p>\n
For unexpected errors (database down, third-party API timing out), I let them throw and catch them at the route’s error.tsx<\/code> boundary. That’s worked fine. The split is: expected user-input errors return state, infrastructure failures throw.<\/p>\n
Security: what you actually have to think about<\/h2>\n
Next.js encrypts the action ID and includes a CSRF check when the request origin doesn’t match the host. That covers the basic case where a third-party site tries to POST to your action. What it does not cover: authorization.<\/p>\n
Every Server Action runs your code with whatever permissions the request has. There’s no automatic “is this user allowed to do this” gate. If you ship a deleteTodo(id)<\/code> action without checking session.user.id === note.userId<\/code>, anybody with an authenticated session can delete anybody’s notes by sending the right form data. I caught this in code review on a project last quarter \u2014 the original author assumed the action being “server-only” meant it was somehow protected. It is not. It’s a POST endpoint that anyone with a logged-in session can hit.<\/p>\n
My rule: every Server Action starts with an auth check and an authorization check. No exceptions. If the action mutates a resource owned by a user, it verifies ownership before doing anything else. The Next.js security docs for Server Actions<\/a> call this out specifically, and it’s the first thing I review when somebody adds a new action to one of my projects.<\/p>\n
Where I still keep API routes<\/h2>\n
Four cases, in order of how often they come up for me:<\/p>\n
Webhooks. Stripe, Resend, Clerk, whatever. They’re external callers, they need a stable URL, they need to verify a signature against a raw body, and they don’t fit the Server Action pattern at all. These stay as route handlers.<\/p>\n
Public JSON APIs for a mobile client or partner integration. Same logic \u2014 Server Actions aren’t a public surface. If somebody outside my web app needs to call this, I write a real route handler with documented request\/response shapes.<\/p>\n
Long-running streaming responses. SSE for a chat UI, for example. Server Actions are POST request\/response; they don’t stream a body back. Route handlers with ReadableStream<\/code> do.<\/p>\n
File downloads with custom headers. Generating a CSV with Content-Disposition: attachment<\/code>, signing a PDF, that kind of thing. The action wire protocol is not built for this.<\/p>\n
Everything else \u2014 the form submissions, the toggle buttons, the “add to cart” clicks, the comment posts \u2014 I write as Server Actions now. If you want a sense of the kind of thing I build with this setup, I keep a few of these patterns documented in my work<\/a>.<\/p>\n
One concrete thing to try this week<\/h2>\n
Pick one form in your Next.js app that currently posts to an API route. Probably a login form or a comment form. Rewrite it as a Server Action and a Server Component. Notice how much code you delete. Notice the things that get harder (you’ll probably want useActionState<\/code> for the error display).<\/p>\n
If the experience is good, you’ll find yourself doing it to the next form, and the one after that. If it isn’t, at least you have a concrete data point about what your codebase actually needs, instead of arguing about it on Twitter. I went through this exact exercise on a project last spring and ended up keeping about 30% of my route handlers; the rest became Actions. Your number will be different. The point is to find out by doing it once, not by debating it.<\/p>\n
The API routes I kept are the ones I should have kept. The forms I migrated were the ones I should have migrated. Six months later, I haven’t reversed any of those decisions, and that’s the closest thing to a recommendation I’m willing to make.<\/p>\n","protected":false},"excerpt":{"rendered":"
How I stopped writing Next.js API routes for mutations, what Server Actions actually replaced, the bugs they caused me, and where I still keep API routes around.<\/p>\n","protected":false},"author":2,"featured_media":403,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"How I stopped writing Next.js API routes for mutations, what Server Actions actually replaced, the bugs they caused me, and where I still keep API routes around.","rank_math_focus_keyword":"nextjs server actions","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[388,354,35],"tags":[438,61,41,359,170,136,172],"class_list":["post-404","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-next-js","category-react","category-web-development","tag-next-js","tag-nextjs","tag-react","tag-react-19-2","tag-server-actions-2","tag-useactionstate","tag-web-development-2"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/404","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=404"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/404\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/403"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=404"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=404"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=404"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}