The request path
client ──▶ Functions front end ──▶ Function `server` ({*path}) ──loopback──▶ Next.js server (same worker)
│
cache handlers ──▶ Blob (entries) + Table (tags)
- The Function app has one function,
server, on{*path}with streaming enabled (main.mjs, fromsrc/runtime/entry.mjs). The first request starts the Next.js standalone server (server.js) inside the same worker, on127.0.0.1:3000, and waits until the port is open. - Every request is forwarded to that server with
node:http. The response is passed on as a stream.Set-Cookievalues are converted to the structuredcookiesof the Functions response, because the host keeps only one value per header name. x-forwarded-protois not forwarded: withhttps, Next.js stops treating its own loopback address as the same origin and a middleware rewrite fails with a 500. The public scheme is put back into theLocationheader of redirects.- Request bodies are buffered before they are forwarded (forwarding the host's request stream hung on POST).
- Routing, rendering, middleware, Server Actions, streaming and image optimization are done by Next.js itself. This package does not reimplement any of them.
Caches
Next.js asks two interfaces for storage; both are implemented on Storage and loaded by path from next.config (withAzure() sets them):
| Interface | Used for | Storage |
|---|---|---|
cacheHandler (cache-handler.cjs) |
pages, route handlers, fetch results, revalidateTag, revalidatePath |
entries as JSON blobs <build id>/<sha256 of the key>.json in the cache container; Buffers and Maps are serialized; tags in the table |
cacheHandlers (cache-handlers.cjs) |
'use cache' |
streamed entries stored as one JSON document (value in base64) under use-cache/<build id>/... |
| tags (both) | revalidation state | table tagcache: partition = build id, row key = base64url of the tag, revalidatedAt in epoch ms |
An entry is dropped when any of its tags (and the soft tags of the request) was revalidated after it was written. A page's tags come from the x-next-cache-tags header, a fetch entry's from its context. Nothing is deleted on revalidation, so it is one small write per tag.
The key prefix is the build id: a new deployment starts with an empty cache, and the old entries are never read. They are not cleaned up.
Time-based ISR is Next.js's own: a request that finds an entry older than revalidate gets the stale page at once (x-nextjs-cache: STALE) and the server regenerates the page in the background, in the same process. There is no queue. If the instance is removed in the meantime, the regeneration is lost and the next request starts it again.
The build output and priming. next build prerenders pages into .next/server. Next.js reads them through its own file-system cache; with a custom cache handler it asks the handler instead. So on a miss in Blob the handler reads them itself, with Next.js's own FileSystemCache class (read-only, no memory cache), and checks the tags of the page against Table Storage as for any entry. A route without a fallback (dynamicParams = false) needs this: Next.js does not render a page that is not in the cache for such a route. Once a page is regenerated, its entry is in Blob and is read from there. next-on-azure prime (run by deploy) requests every route of .next/prerender-manifest.json once: it warms the instance and starts the regeneration of pages that are already past their revalidate time.
after() and other deferred work
Next.js asks the platform for waitUntil through globalThis[Symbol.for("@next/request-context")]; the entry provides it and tracks the work. A response is held open until the work registered before the response ended has settled (at most WAIT_UNTIL_MAX_SECONDS). The reason: an idle instance disappears after roughly 1.5 to 3.5 minutes and deferred work that outlives it is lost (Azure notes, item 18). The work cannot be tied to one request, because it is registered inside the Next.js server, which the request reached over loopback.
Packaging
next-on-azure package makes a Function app from .next/standalone:
- checks the Next.js version and the Server Actions key;
- copies the standalone directory and turns the pnpm
node_modulesinto a plain tree without symbolic links (Azure notes, item 13); - copies
.next/staticandpublic/next toserver.js, and the completesharppackage (file tracing leaves outdist/index.cjson Next.js 16, and the optimizer then silently returns the original image), with the Linux x64 binaries for Azure; - writes
main.mjs,cookies.mjs,front-door.mjs,host.json(HTTP routes at/, no extension bundle) and apackage.jsonwith@azure/functions, installs it, and zips the result.
The cache handler files are required without the node: prefix on purpose: Next.js 16 bundles them into the proxy bundle with Turbopack, which cannot load node: externals from CommonJS.