Work after the response: after()

An order that answers before the bookkeeping

Asha orders Mint tea in the tea shop. Two things have to happen: the shop saves her order and tells her it's placed, and the shop counts the order for its sales report. Asha cares about the first. The second is bookkeeping: she shouldn't wait for it.

Next.js has a function for exactly this split: after(), from next/server. You give it a function, called the callback, and Next.js runs it once the response has gone out. Here is the shop's order endpoint, a Route Handler, with one after(). This is a recording of a real Next.js 16.4.3 project: it was built with next build, run with next start, and used in real Chrome.

1import { after } from "next/server";2import { logLine } from "../../_lib/activity";3 4let nextId = 7;5 6export async function POST(request: Request) {7  const { tea } = await request.json();8  const order = { id: nextId++, tea };9  logLine(`Order ${order.id} saved: ${tea}`);10 11  after(() => {12    logLine(`after(): order ${order.id} counted for the sales report`);13  });14 15  logLine(`Order ${order.id}: answering now`);16  return Response.json(order, { status: 201 });17}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (5/5)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ◐ /activity└ ƒ /api/orders ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed contentƒ  (Dynamic)            server-rendered on demand $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ ReadyOrder 7 saved: Mint teaOrder 7: answering nowafter(): order 7 counted for the sales report

app/api/orders/route.ts answers POST /api/orders. Line 7 reads the order from the request's body, and line 8 gives it the id 7. Line 9 calls logLine from app/_lib/activity.ts, a stand-in for the shop's log service: it prints the line and adds it to a file. Then:

• Lines 11 to 13 call after() with an arrow function. Nothing inside it runs yet: Next.js keeps the function for later.
• Line 15 logs Order 7: answering now, and line 16 answers 201 with the order as JSON.
• Once that answer has finished, Next.js calls the function, and line 12 writes the report line.

Open the Terminal tab: after the build's output, it shows what next start printed. The three lines come in that order: Order 7 saved: Mint tea, Order 7: answering now, and last after(): order 7 counted for the sales report, even though line 12 sits above line 15 in the file. Then open the Steps tab. Asha opened /, clicked Place order, and the page showed Order 7 placed from the 201. The last step opened /activity?lines=3, a page that shows the log once it has three lines (it waits at most 5 seconds, since the callback runs a moment after the answer).

Before the answer, or after it

Without after(), the report line would be one more line in the handler. Everything a handler does before its return is something the visitor waits for, because the answer can't leave until the function returns it. Here are both versions of app/api/orders/route.ts, each built and used in Chrome the same way. Before you pick one, guess where the report line lands in the log.

1import { logLine } from "../../_lib/activity";2 3let nextId = 7;4 5export async function POST(request: Request) {6  const { tea } = await request.json();7  const order = { id: nextId++, tea };8  logLine(`Order ${order.id} saved: ${tea}`);9 10  logLine(`order ${order.id} counted for the sales report`);11 12  logLine(`Order ${order.id}: answering now`);13  return Response.json(order, { status: 201 });14}

Both logs have the same three lines. Before the answer, the report line sits in the middle: it ran inside the handler, so the 201 waited for it. In after(), it comes last: the 201 went out first. Writing a line to a file is quick, so here the difference is small. The same split matters when the bookkeeping is a call to another company's service that takes a second, or that fails. Step through both versions below. Before you start, guess: in which version does the report work stand between Asha's click and her answer?

In both versions, Asha sees Order 7 placed in step 5, once the answer arrives. Before the answer, step 3 is the report work itself, so it stands between her click and her answer. With after(), step 3 only hands the function over, and the report work is the last step: Next.js runs it once the response has finished, while the page already shows the answer.

When the after() work runs

"After the response" is a strong claim, so test it. In this version, the callback waits for a signal before it writes its line. The signal is a file, signal.txt, and only a later request writes it: POST /api/signal. If the response waited for the callback, the order would never get an answer.

1import { after } from "next/server";2import { logLine } from "../../_lib/activity";3import { signalSent } from "../../_lib/signal";4 5let nextId = 7;6 7export async function POST(request: Request) {8  const { tea } = await request.json();9  const order = { id: nextId++, tea };10  logLine(`Order ${order.id} saved: ${tea}`);11 12  after(async () => {13    await signalSent();14    logLine(`after(): order ${order.id} counted for the sales report`);15  });16 17  logLine(`Order ${order.id}: answering now`);18  return Response.json(order, { status: 201 });19}

{"tea":"Mint tea"}

{"id":7,"tea":"Mint tea"}

Line 13 waits until signal.txt exists, checking every 50 milliseconds (app/_lib/signal.ts). Open the Network tab and go through the four requests, in the order the recording sent them:

1. POST /api/orders answered 201 with {"id":7,"tea":"Mint tea"}, while its callback was still waiting.
2. /activity?lines=2 shows two lines: saved, and answering now. The report line isn't there: the callback is still waiting.
3. POST /api/signal writes the file and answers 204, which means "done, with nothing to send back".
4. /activity?lines=3 now shows the third line, after(): order 7 counted for the sales report.

So the answer never waits for the callback. In Next.js's code, each request's callbacks wait in a queue that is paused until the response closes. A callback that waits for a file is only an experiment; real callbacks do their work and end.

A build-time render, a request-time render, a failed response

A callback runs once the work it belongs to has finished. That isn't always a visitor's request. Pick each version below and read its Terminal: the build's output comes first, then what next start printed while it answered two requests.

1import { after } from "next/server";2 3export default function Home() {4  after(() => {5    console.log("after(): the home page was rendered");6  });7  return (8    <main>9      <h1>Tea shop</h1>10      <p>Fresh tea, sent every week.</p>11    </main>12  );13}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...after(): the home page was renderedafter(): the home page was rendered✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /└ ○ /_not-found ○  (Static)  prerendered as static content $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ Ready

• A page made during the build. The home page calls after() and reads nothing from the request, and the build still prints ○ /, prerendered as static content. after() isn't a request-time API, so calling it doesn't make a page render for each request. The build printed after(): the home page was rendered twice: in this build, Next.js rendered Home twice while it prerendered the page. Don't count on how many times. The two visits got the saved page, so Home didn't run, and neither did its callback.
• A part made for each request. Greeting reads a cookie inside Suspense, so the route is ◐ /: a static shell, with Greeting made for each request (Partial Prerendering). Its callback runs after the visit's response: next start printed after(): home page shown to Asha on Mozilla/5.0 for Asha's visit.
• A handler that fails. The handler schedules its callback on lines 4 to 6, then throws on line 7. The caller gets 500, and Next.js prints ⨯ Error: The payment service did not answer. The callback runs anyway: its line is in the Terminal. The docs say the same holds when a page calls notFound() or redirect().

What the callback can read

Logging usually wants something about the visitor: who they are (a cookie) and what they use (the user-agent header). cookies() and headers() from next/headers read them (Request-time APIs teaches both). Whether the callback can call them itself depends on where after() was called. Each version below asks for the same two values in a different place. Before you pick one, guess which version fails.

1import { Suspense } from "react";2import { cookies, headers } from "next/headers";3import { after } from "next/server";4 5async function Greeting() {6  const name = (await cookies()).get("name")?.value ?? "guest";7  after(async () => {8    const agent = (await headers()).get("user-agent");9    console.log(`after(): home page shown to ${name} on ${agent}`);10  });11  return <p>Welcome back, {name}.</p>;12}13 14export default function Home() {15  return (16    <main>17      <h1>Tea shop</h1>18      <Suspense fallback={<p>Loading…</p>}>19        <Greeting />20      </Suspense>21    </main>22  );23}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ◐ /└ ○ /_not-found ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ ReadyAn error occurred in a function passed to `after()`: Error: Route / used `headers()` inside `after()` while rendering. This is not supported. If you need this data inside an `after()` callback, use `headers()` outside of the callback. See more info here: https://nextjs.org/docs/app/api-reference/functions/after    at n (.next/server/chunks/ssr/_0aqpghaus1lkm._.js:30:14654)    at <unknown> (.next/server/chunks/ssr/_0aqpghaus1lkm._.js:1:211)An error occurred in a function passed to `after()`: Error: Route / used `headers()` inside `after()` while rendering. This is not supported. If you need this data inside an `after()` callback, use `headers()` outside of the callback. See more info here: https://nextjs.org/docs/app/api-reference/functions/after    at n (.next/server/chunks/ssr/_0aqpghaus1lkm._.js:30:14654)    at <unknown> (.next/server/chunks/ssr/_0aqpghaus1lkm._.js:1:211)

Only the first version fails. Its Greeting is a Server Component, and line 8 calls headers() inside the callback. The page still answered 200 with Welcome back, Asha., but next start printed:

An error occurred in a function passed to `after()`: Error: Route / used `headers()` inside `after()` while rendering. This is not supported. If you need this data inside an `after()` callback, use `headers()` outside of the callback.

In plain words: in a page, read the request while the component renders, not inside the callback. The reason is Partial Prerendering. Next.js finds out which parts of a page depend on the request by watching what each part reads while it renders. A callback runs after React has finished rendering, too late to be seen, so Next.js refuses request data there. The second version does it right:

import { Suspense } from "react";
import { cookies, headers } from "next/headers";
import { after } from "next/server";

async function Greeting() {
  const name = (await cookies()).get("name")?.value ?? "guest";
  const agent = (await headers()).get("user-agent");
  after(() => {
    console.log(`after(): home page shown to ${name} on ${agent}`);
  });
  return <p>Welcome back, {name}.</p>;
}

export default function Home() {
  return (
    <main>
      <h1>Tea shop</h1>
      <Suspense fallback={<p>Loading…</p>}>
        <Greeting />
      </Suspense>
    </main>
  );
}

Lines 6 and 7 read the cookie and the header while Greeting renders. The arrow function on lines 8 to 10 uses name and agent: it closes over them, so it still has them when it runs later. next start printed after(): home page shown to Asha on Mozilla/5.0.

Route Handlers and Server Actions don't have this rule: the docs, and the check in Next.js's code, let them call request APIs everywhere, inside after() too. The third version's callback read the header itself and printed after(): Mint tea ordered on TeaApp/2.1. Each row is one place you can call after() from:

after() in Server Actions and proxy.ts

A Server Action is where many writes happen, so it's a common place for after(). This order form posts to one. It's the version from the playground above:

1"use server";2 3import { cookies, headers } from "next/headers";4import { redirect } from "next/navigation";5import { after } from "next/server";6 7export async function placeOrder(formData: FormData) {8  const tea = String(formData.get("tea"));9  console.log(`Order saved: ${tea}`);10  after(async () => {11    const name = (await cookies()).get("name")?.value ?? "guest";12    const agent = (await headers()).get("user-agent");13    console.log(`after(): ${tea} ordered by ${name} on ${agent}`);14  });15  redirect("/thanks");16}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)┌ ○ /_not-found├ ○ /order└ ○ /thanks ○  (Static)  prerendered as static content $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ ReadyOrder saved: Mint teaafter(): Mint tea ordered by Asha on Mozilla/5.0

The recording submitted the form the way a browser does before the page's JavaScript has loaded, with Asha's cookie. In app/order/actions.ts, line 9 logs the order (a stand-in for saving it; a real action would also check who is asking, as Authorization shows). Lines 10 to 14 schedule the callback, which reads cookies() and headers() itself. Line 15 calls redirect("/thanks"). In the Network tab, POST /order answered 303 with location: /thanks. In the Terminal, the callback still printed after(): Mint tea ordered by Asha on Mozilla/5.0, after Order saved: Mint tea.

after() also works in proxy.ts, which runs before every matched request. Logging each request there, after the response has gone, keeps the check in front of your routes quick:

1import { after, NextResponse, type NextRequest } from "next/server";2 3export function proxy(request: NextRequest) {4  const path = request.nextUrl.pathname;5  after(() => {6    console.log(`after(): proxy.ts let ${path} through`);7  });8  return NextResponse.next();9}10 11export const config = { matcher: ["/((?!_next/).*)"] };

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found└ ○ /teas ƒ Proxy (Middleware) ○  (Static)  prerendered as static content $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ Readyafter(): proxy.ts let / throughafter(): proxy.ts let /teas through

Line 4 reads the path from the request object while proxy.ts runs. Lines 5 to 7 hand after() a function that logs it. Line 8 lets the request through to its page. The recording asked for /, then /teas, then / again, and the Terminal shows after(): proxy.ts let / through and after(): proxy.ts let /teas through, each printed after its page had been sent.

Logging and analytics, and when they fail

Analytics usually means calling another company's service. That call can be slow, and it can fail. In after(), neither reaches the visitor. In this recording, the analytics service is a stand-in: a small server the recording starts in its place, whose address the route reads from ANALYTICS_URL. For order 7 it answers 503, "down for maintenance"; for order 8 it answers 200.

1import { after } from "next/server";2import { logLine } from "../../_lib/activity";3 4let nextId = 7;5 6export async function POST(request: Request) {7  const { tea } = await request.json();8  const order = { id: nextId++, tea };9  after(async () => {10    const response = await fetch(`${process.env.ANALYTICS_URL}/events?order=${order.id}`);11    if (!response.ok) throw new Error(`Analytics answered ${response.status}`);12    logLine(`after(): order ${order.id} sent to analytics`);13  });14  return Response.json(order, { status: 201 });15}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)┌ ○ /_not-found├ ◐ /activity└ ƒ /api/orders ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed contentƒ  (Dynamic)            server-rendered on demand $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ ReadyAn error occurred in a function passed to `after()`: Error: Analytics answered 503    at <unknown> (.next/server/chunks/[root-of-the-server]__0vw7ijbc6l9p6._.js:1:248)after(): order 8 sent to analytics

Line 10 calls the service with fetch. Line 11 throws when it answers with an error, and line 12 logs the order when it doesn't. In the Network tab, both orders answered 201, order 7 too. The stand-in received GET /events?order=7 and GET /events?order=8 while next start ran, so both callbacks ran. In the Terminal, Next.js printed An error occurred in a function passed to `after()`: Error: Analytics answered 503 for order 7, and after(): order 8 sent to analytics for order 8.

A few more things the docs say about the function you pass:

• You can wrap it. after() calls can be nested, so a helper like track(event) can call after() itself, and any route can call the helper.
• It can reuse what the render loaded. In Server Components, a function wrapped in React's cache() returns the value the render already computed, so the callback doesn't load it again.

Limits on serverless platforms

With next start, as in every recording above, the server keeps running between requests, so it can finish a callback whenever the response has gone. The docs list after() as fully supported on a Node.js server and in Docker. When you stop such a server, send it SIGTERM or SIGINT and give it time: it finishes the requests in flight and runs the waiting callbacks before it exits. A static export has no server, so it has no after().

Many platforms run Next.js as serverless functions instead: a copy of your server code that the platform starts for requests and may freeze or stop once it has answered. Work still running after the answer would be cut off. So the platform gives Next.js a function called waitUntil(promise), which keeps the function running until the promise settles. after() passes its work to it. On Vercel it's built in. An adapter for another platform provides its own, in the place the docs describe:

const RequestContext = globalThis[Symbol.for("@next/request-context")];
const waitUntil = RequestContext?.get()?.waitUntil;

Line 1 reads a request context that the platform puts on globalThis, under a shared symbol. Line 2 takes its waitUntil. If there's none, Next.js throws when you call after(): `after()` will not work correctly, because `waitUntil` is not available in the current environment.

Even with waitUntil, the function has a time limit, and after() work counts toward it. The docs say the callback runs for the platform's default or configured maximum duration of the route. Platforms that let you set it read maxDuration, in seconds, from the route's file:

// app/api/orders/route.ts
export const maxDuration = 30;

export async function POST(request: Request) {
  // …the order and its after() work, as above
}

Line 2 exports the limit. For Server Actions, the docs say to set it in the page that uses them. It's for hosting platforms, which read it from the build's output; each platform has its own default and maximum.

after() isn't a job queue

A job queue is a list of work saved outside your server, like in Redis or a database, with one or more workers: programs that take the next job and run it. Libraries like BullMQ, and hosted services like Inngest, Trigger.dev and Upstash QStash, work this way. Each row compares the two:

Use after() only for work you can afford to lose. Long work, work that must be retried, and work for later go in a queue, and a job that must happen is added before the request is confirmed, never in after(): if the server crashed between the answer and the callback, the job would be lost while Asha had already read Order 7 placed. Best of all, save the job in the same database transaction as the order (this is called a transactional outbox): either both are saved or neither is, and a worker sends the saved jobs to the queue.

Which work belongs in after()?

For each piece of work, ask: does the answer depend on it? Then it runs before the answer. Is it small, and fine to lose now and then? after(). Is it long, retried, or for later? A job queue. Sort the tea shop's jobs:

Common mix-ups

• "after() runs its function right away, in the background." No. It keeps the function, and Next.js calls it once the response has finished. The log shows answering now before the callback's line.
• "The response waits for after() work to finish." No. In the experiment, the order answered 201 while its callback was still waiting for a later request.
• "Calling after() makes a page render for each request." No. It isn't a request-time API: the page with only after() was ○ /, and its callback ran during the build.
• "A page can read cookies() inside its after() callback." No. In Server Components the callback stops with an error. Read the values while the component renders, and use them in the callback.
• "If the callback throws, the visitor gets an error." No. The answer has already gone. Next.js logs the error, as it did for order 7's failed analytics call.
• "after() is a job queue." No. It runs once, right after this response, within the route's time limit, and never retries. Long or retried work belongs in a queue.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

import { after } from "next/server";
import { logLine } from "../../_lib/activity";

let nextId = 7;

export async function POST(request: Request) {
  const { tea } = await request.json();
  const order = { id: nextId++, tea };
  logLine(`Order ${order.id} saved: ${tea}`);

  after(() => {
    logLine(`after(): order ${order.id} counted for the sales report`);
  });

  logLine(`Order ${order.id}: answering now`);
  return Response.json(order, { status: 201 });
}

import { after } from "next/server";

export default function Home() {
  after(() => {
    console.log("after(): the home page was rendered");
  });
  return (
    <main>
      <h1>Tea shop</h1>
      <p>Fresh tea, sent every week.</p>
    </main>
  );
}

import { Suspense } from "react";
import { cookies, headers } from "next/headers";
import { after } from "next/server";

async function Greeting() {
  const name = (await cookies()).get("name")?.value ?? "guest";
  after(async () => {
    const agent = (await headers()).get("user-agent");
    console.log(`after(): home page shown to ${name} on ${agent}`);
  });
  return <p>Welcome back, {name}.</p>;
}

export default function Home() {
  return (
    <main>
      <h1>Tea shop</h1>
      <Suspense fallback={<p>Loading…</p>}>
        <Greeting />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { cookies, headers } from "next/headers";
import { after } from "next/server";

async function Greeting() {
  const name = (await cookies()).get("name")?.value ?? "guest";
  const agent = (await headers()).get("user-agent");
  after(() => {
    console.log(`after(): home page shown to ${name} on ${agent}`);
  });
  return <p>Welcome back, {name}.</p>;
}

export default function Home() {
  return (
    <main>
      <h1>Tea shop</h1>
      <Suspense fallback={<p>Loading…</p>}>
        <Greeting />
      </Suspense>
    </main>
  );
}

import { logLine } from "../../_lib/activity";

let nextId = 7;

export async function POST(request: Request) {
  const { tea } = await request.json();
  const order = { id: nextId++, tea };
  const response = await fetch(`${process.env.ANALYTICS_URL}/events?order=${order.id}`);
  if (!response.ok) throw new Error(`Analytics answered ${response.status}`);
  logLine(`order ${order.id} sent to analytics`);
  return Response.json(order, { status: 201 });
}

import { after } from "next/server";
import { logLine } from "../../_lib/activity";

let nextId = 7;

export async function POST(request: Request) {
  const { tea } = await request.json();
  const order = { id: nextId++, tea };
  after(async () => {
    const response = await fetch(`${process.env.ANALYTICS_URL}/events?order=${order.id}`);
    if (!response.ok) throw new Error(`Analytics answered ${response.status}`);
    logLine(`after(): order ${order.id} sent to analytics`);
  });
  return Response.json(order, { status: 201 });
}

import { headers } from "next/headers";
import { after } from "next/server";

export async function POST(request: Request) {
  const { tea } = await request.json();
  after(async () => {
    const agent = (await headers()).get("user-agent");
    console.log(`after(): ${tea} ordered on ${agent}`);
  });
  return Response.json({ tea }, { status: 201 });
}

1. Write one line to the log when an order is placed.
2. Send each of 4,000 customers an email about a new tea.
3. Charge a card again tomorrow if today's charge fails.

Check your understanding

For each question, picture the answer leaving first, then ask where the callback was scheduled.

Key takeaways

• after(callback) from next/server keeps the function and runs it once the response has finished. The visitor never waits for it.
• It works in Server Components, Server Actions, Route Handlers and proxy.ts. It isn't a request-time API: in a page made during the build, the callback runs during the build.
• The callback runs even when the response failed: after an error, a redirect or a not-found page.
• In a Server Component, read cookies() and headers() while it renders and use the values in the callback. Route Handlers and Server Actions can read them inside the callback.
• A callback that throws is logged with console.error. The visitor keeps their answer, and nothing retries.
• On serverless platforms, after() uses the platform's waitUntil, within the route's time limit (maxDuration). Long, retried or later work belongs in a job queue.

Coming next: Building AI features. A model's answer is slow and costs money for every word, so it's streamed to the page piece by piece, with the key, the costs and the input under control on the server.