Week 20: Next.js — Route Handlers & Server Actions

1. Route Handlers

A file named route.ts inside any app/ folder replaces page.tsx for that segment and turns it into an HTTP endpoint instead of a page — the App Router's equivalent of an Express route from the Node/Express course, colocated with the rest of your app instead of living in a separate backend.

import { NextRequest, NextResponse } from 'next/server';

export async function GET() {
  const products = await db.product.findMany();
  return NextResponse.json(products);
}

export async function POST(request: NextRequest) {
  const body = await request.json();
  const product = await db.product.create({ data: body });
  return NextResponse.json(product, { status: 201 });
}

Each exported function name — GET, POST, PUT, DELETE — maps to that HTTP method, exactly like Week 18's [productId] dynamic segment maps a folder name to a URL param. A dynamic Route Handler reads params the same way a dynamic page does:

export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ productId: string }> },
) {
  const { productId } = await params;
  const product = await db.product.findUnique({ where: { id: productId } });
  if (!product) {
    return NextResponse.json({ error: 'Not found' }, { status: 404 });
  }
  return NextResponse.json(product);
}

2. Server Actions & 'use server'

A Server Action is an ordinary async function marked with a 'use server' directive — Week 18's 'use client', in reverse. Next.js compiles it into a callable network endpoint automatically; you write and call it like a normal function, with no fetch, no URL, and no Route Handler to define.

'use server'; // every exported function in this file becomes a Server Action

import { revalidatePath } from 'next/cache';

export async function addProduct(formData: FormData) {
  const name = formData.get('name') as string;
  const price = Number(formData.get('price'));

  await db.product.create({ data: { name, price } });
  revalidatePath('/products'); // see Section 5
}

A Server Action can be wired directly to a plain HTML <form>'s action prop — no onSubmit handler, no client-side state, and it still works with JavaScript disabled, because it's a genuine form submission under the hood.

import { addProduct } from '../actions';

export default function NewProductPage() {
  return (
    <form action={addProduct}>
      <input name="name" required />
      <input name="price" type="number" required />
      <button type="submit">Add product</button>
    </form>
  );
}

This is the App Router's replacement for Week 5's controlled-input pattern in the cases where the form's only job is "submit this to the server" — no useState tracking every keystroke, because the browser's native form submission carries the FormData to the action directly.

3. Calling Actions from Client Components

A Server Action isn't limited to a plain form — a Client Component can import and call one directly from an event handler, which is what most real "favorite this", "delete this row", or "like this post" buttons actually do.

'use client';

import { useTransition } from 'react';
import { deleteProduct } from './actions';

export function DeleteButton({ productId }: { productId: string }) {
  const [isPending, startTransition] = useTransition();

  return (
    <button
      disabled={isPending}
      onClick={() => startTransition(() => deleteProduct(productId))}
    >
      {isPending ? 'Deleting…' : 'Delete'}
    </button>
  );
}

useTransition marks the action call as a non-urgent update — the UI stays responsive while the request is in flight, and isPending gives you the loading state directly, without Week 9's manual mutation-state bookkeeping. Under the hood, calling a Server Action from the browser is still a network request to the endpoint Next.js generated for it — it just never shows up as a URL you'd write yourself.

4. useActionState & useFormStatus

For a plain <form action={...}>, two hooks give you the pending state and any returned result without reaching for useTransition by hand. useActionState wraps the action and tracks its last return value — useful for validation errors:

'use server';

export async function addProduct(prevState: unknown, formData: FormData) {
  const name = formData.get('name') as string;
  if (!name || name.length < 2) {
    return { error: 'Name must be at least 2 characters' };
  }
  await db.product.create({ data: { name } });
  revalidatePath('/products');
  return { error: null };
}

'use client';

import { useActionState } from 'react';
import { addProduct } from '../actions';

export function AddProductForm() {
  const [state, formAction] = useActionState(addProduct, { error: null });

  return (
    <form action={formAction}>
      <input name="name" />
      {state.error && <p className="error">{state.error}</p>}
      <SubmitButton />
    </form>
  );
}

function SubmitButton() {
  const { pending } = useFormStatus(); // must be a child of the 
, not the form itself
  return <button disabled={pending}>{pending ? 'Saving…' : 'Save'}</button>;
}

useFormStatus only works inside a component nested under the <form> it's reporting on — it reads pending state from the nearest parent form's submission, which is why SubmitButton is split into its own component rather than called inline in AddProductForm itself.

5. Revalidating After a Mutation

Week 21 covers Next.js 16's Cache Components model in full — the "use cache" directive and tagging cached data with cacheTag. For now, the part that matters here: after addProduct writes to the database, any cached rendering of the products list is now stale, and something needs to tell Next.js to throw it away.

import { cacheTag } from 'next/cache';

export async function getProducts() {
  'use cache';
  cacheTag('products'); // labels this cached result so it can be targeted later

  return db.product.findMany();
}

'use server';

import { updateTag } from 'next/cache';

export async function addProduct(formData: FormData) {
  const name = formData.get('name') as string;
  const price = Number(formData.get('price'));

  await db.product.create({ data: { name, price } });
  updateTag('products'); // expires the 'products' cache immediately, in this same action
}

updateTag is the revalidation call written specifically for Server Actions: it expires the tagged cache entry immediately, so the very next read — including anything this same action does afterward, like a redirect to the products page — sees the fresh data, not a stale cached copy. Its sibling, revalidateTag, marks an entry stale rather than expiring it outright: the next visitor gets the still-cached page instantly while Next.js rebuilds it in the background — the right choice from a Route Handler or a webhook, where nothing is waiting to immediately read its own write the way a Server Action's caller is. revalidatePath('/products') still exists too, for the simpler case of invalidating everything cached for a specific route rather than a specific tag.

This is the App Router's answer to Week 9's queryClient.invalidateQueries — same underlying idea, cache correctness after a write, expressed at the framework level instead of by a client-side query library, because the cache being invalidated here can live on the server, not just in the browser.

6. useOptimistic + Server Actions

Week 9 introduced useOptimistic and promised its most natural home was here: a Server Action call, unlike a TanStack Query mutation, has no client-side cache of its own to optimistically update — useOptimistic is exactly the tool built for pairing with it directly.

'use client';

import { useOptimistic, useTransition } from 'react';
import { toggleFavorite } from './actions';

export function FavoriteButton({ productId, initialFavorited }: {
  productId: string;
  initialFavorited: boolean;
}) {
  const [isPending, startTransition] = useTransition();
  const [optimisticFavorited, setOptimisticFavorited] = useOptimistic(initialFavorited);

  function handleClick() {
    startTransition(async () => {
      setOptimisticFavorited(!optimisticFavorited); // flips instantly
      await toggleFavorite(productId); // real Server Action call, in the background
    });
  }

  return (
    <button onClick={handleClick} disabled={isPending}>
      {optimisticFavorited ? '★ Favorited' : '☆ Favorite'}
    </button>
  );
}

The star flips the instant the button is clicked, before toggleFavorite has even reached the server. useOptimistic's update must run inside a transition — startTransition, exactly like Section 3's DeleteButton — so that if the action ultimately throws, optimisticFavorited automatically reverts to initialFavorited with no onError code of your own, the same revert-on-settle behavior Week 9 covered for a purely client-side case.

7. Hands-on Exercise

8. Knowledge Check

Four quick questions. Expand each to check your answer.