Next.js support
The Next.js versions and features Arkor builds and serves, and what to change before you deploy.
Arkor builds your app with its own next build and the Arkor adapter. Your repository needs no
Arkor dependency and no configuration file. An app that reads
storage adds @stayingupwind/sdk.
See Adapter API test results for recorded upstream deployment tests against Arkor, including the tested version, suite results and the reasons for Vercel-only exclusions. Its history charts show recorded pass rates and test counts over time, with each measurement's conditions available in the accompanying table.
Versions
- Next.js 16.3+ is officially supported.
- Next.js 16.2 generally works but is not guaranteed. See Next.js 16.2.
- A build with Next.js 16.1 or earlier, or with Next.js 17, fails with This Next.js version is not supported.
- Turbopack builds only, which is the default of
next buildin Next.js 16. A build run with--webpackfails. Static exports are the exception.
Next.js 16.2
Next.js 16.2 generally works but is not guaranteed. As with 16.3, Arkor serves the cached shell and streams the dynamic parts. Next.js 16.2 records less about its build than 16.3 does, so a deployment of one has these limits:
| Feature | On a 16.2 deployment |
|---|---|
| The deployment's Build output tab (Inspecting a build) | Shows the routes, but how each page is rendered reads Not recorded and no route has details to open: Next.js 16.3 records both. A notice over the tree says so. |
Static files under /_next/static/immutable/ | None, as Next.js 16.2 does not write them. The build's other static files are served as usual. |
| The build's own generation of an entry in the Cache Inspector | Shown, but its compute and response read unknown. |
| Error monitoring | Reports what your app throws on the server. Errors thrown in the browser are not reported: Next.js 16.2 cannot load Arkor's browser module before hydration. |
The log of a build from your repository says so as well. To have all of it, upgrade Next.js to a supported Next.js 16.3+ release and deploy again.
What works
| Feature | On Arkor |
|---|---|
| App Router, Cache Components, Partial Prerendering | The prerendered shell of a page is sent from the edge at once; the parts that were left dynamic are streamed from your app. |
| Fully static pages | Served whole from the edge. |
ISR, use cache, cacheLife, cacheTag, revalidateTag, updateTag, revalidatePath | Work as on a Next.js server. See ISR and caching. |
A custom cacheHandler or cacheHandlers in next.config | Bundled into your app, and the build log says so. See Your own cache handler. |
Pages Router: getStaticProps, getServerSideProps, fallback, API routes, res.revalidate() | Supported. |
Middleware and proxy.ts | Run before the page is sent. See Middleware. |
| Route handlers and Server Actions | Run in your app. |
| Draft mode | Supported. |
next/image | Optimized at the edge with the default loader, in AVIF or WebP. A source image may be up to 20 MB. |
next/font, next/og (ImageResponse, opengraph-image) | Supported. |
Routes with export const runtime = 'edge' | Run, without a prerendered shell and without ISR, as in Next.js. |
WebAssembly, instrumentation.ts | Supported. |
output: 'export' | Supported. See Static exports. |
@vercel/analytics, @vercel/speed-insights | Work unchanged. See Web Analytics and Speed Insights. |
Your own cache handler
A cacheHandler or cacheHandlers set in next.config is bundled into your app, and the build
log warns that it is. A cacheHandler takes the data cache, fetch and unstable_cache, and
pages keep Arkor's ISR. A kind of cacheHandlers takes that kind of use cache, and the other
kinds stay Arkor's. revalidateTag, revalidatePath and updateTag reach both.
- The handler runs in each instance of your app, so what it keeps in memory is that instance's alone. To share a cache, keep what it stores where every instance reaches it, such as storage.
- What Arkor's own cache does beside storing is not done for it: the response does not wait for a write to finish, and a value Next.js serves stale is revalidated in the background only while the request is still running.
- What it imports is bundled with it. A file it reads from disk at runtime is not.
- A handler that is an ES module with a top-level
awaitfails the build.
What to change before you deploy
| If your app uses | Do this |
|---|---|
experimental.optimizeCss | Remove it. Pages that use it fail to render. |
next build --webpack | Build with Turbopack. |
Native Node.js addons, node:vm, or require() of a computed path | Replace them. Arkor cannot run them: the build fails, and its log names the module. |
child_process | Don't call it. Your app cannot start a process on Arkor: an import of it builds, and the call fails when it runs. |
Code built from a string, with eval or new Function | Replace it. Arkor refuses it, with EvalError: Code generation from strings disallowed. |
| A connection, a stream or a pending promise kept for later requests | Open it in the request that uses it. Arkor does not let a request use what another one opened: Cannot perform I/O on behalf of a different request. |
| Files read from disk at runtime | Only files Next.js traces into the build, inside the app's directory and outside node_modules, are there: a package that reads its own files at runtime finds none. Import the data, or keep it in the build output. |
| A page that throws for a parameter it does not know | Call notFound() instead. Before a deployment is published, each dynamic route is rendered at a placeholder path, and a render that fails keeps the deployment from being published; see validation_failed. |
| WebSockets | Not supported. |
Pages Router i18n | Not verified yet. Some cases fail, such as a rewrite or a middleware matcher under a locale, and domain routing has not been tested. |
A query parameter named grant or __arkor_share | Rename it. Arkor removes both from every request with a redirect. |
Check with an AI assistant
To go through your project against this list, give an AI assistant in your editor this prompt:
I want to deploy a Next.js app to Arkor (https://www.arkor.dev), which builds it with its own next build. Check my project against what Arkor needs.
What Arkor needs:
1. Next.js 16.3+, built with Turbopack: not next build --webpack. Next.js 16.2 generally works but is not guaranteed.
2. No experimental.optimizeCss in next.config. A cacheHandler or cacheHandlers is bundled, but what it keeps in memory is one instance's alone: a shared cache needs a shared store.
3. No native Node.js addons, no node:vm, no require() of a computed path, no eval or new Function, and no calls to child_process: Arkor cannot run them.
4. No connection, stream or pending promise kept at module scope and used again by a later request.
5. Files read from disk at runtime only when Next.js traces them and they are inside the app's directory, outside node_modules.
6. No WebSockets.
7. redirects, rewrites and headers in next.config rather than vercel.json. crons in vercel.json are read as they are.
8. Every dynamic route renders for a parameter it does not know, because Arkor renders one at a placeholder path before publishing: notFound() rather than an error.
9. Middleware that stays within 50 ms of CPU time and five subrequests.
10. An up-to-date lockfile for the package manager the project uses, and no Yarn Plug'n'Play.
Look at my project and list each thing that does not meet these, with the file and what to change. Say which of them you could not check.
Arkor's guide: https://www.arkor.dev/docs/getting-started/nextjs-support#what-to-change-before-you-deployIt reads your code, not a build: the first build on Arkor is what proves the rest. If it fails, see Troubleshooting.
Runtime
Arkor supports Node.js compatibility and provides 128 MB of memory per instance. Requests include these headers:
| Header | Value |
|---|---|
x-forwarded-host | The hostname the visitor asked for: my-app.arkor.app or your own domain |
x-forwarded-proto | https |
x-forwarded-for | The visitor's IP address |
x-arkor-ip-country | The visitor's country code, such as JP. Read it where you would read x-vercel-ip-country. |
Your app is bundled as for Node.js: where a package publishes a separate build for another runtime, its Node.js build is the one used.
after() works: what it schedules has 30 seconds after the response to finish.
Streaming
The part of a page your app streams after the shell has 15 seconds to start and 5 minutes to finish. When it runs over, or your app fails while it streams, the browser loads the page once more, and your app renders it whole.
Middleware
Middleware runs before the prerendered shell of a page is sent, so keep it light: it has 50 ms of CPU time, five subrequests and three seconds. When it fails or runs out, the request is served whole by your app instead, which runs the middleware itself.
Response headers
- On a page sent from the edge, only these headers from
next.configheaders()are sent:content-type,content-language,vary,link,x-robots-tag,x-frame-options,x-content-type-options,x-dns-prefetch-control,content-security-policy,content-security-policy-report-only,referrer-policy,permissions-policy,strict-transport-security,cross-origin-opener-policy,cross-origin-embedder-policy,cross-origin-resource-policy,accept-ch,critical-chandorigin-agent-cluster. A custom header such asx-powered-by-teamis not. - On a response from your app,
publicinCache-Controlbecomesprivateands-maxageis removed; Arkor decides what is cached. A response with noCache-Controlis sentprivate, no-store.
Limits
These are Arkor’s limits.
| Limit | Value |
|---|---|
| Size of your app's server code, and of its middleware's, each with its modules together, uncompressed | 60 MiB each |
| Files in one deployment: static files and the server code's modules together, identical files counted once | 4,000, each up to 32 MiB, and 1 GiB together |
| Modules of the server code the build makes | 4,000 together |
| The deployment's manifest, which describes its routes, prerendered pages, files and rules | 8 MiB |
| Routing rules (redirects, rewrites, headers and middleware matchers) | 5,000 |
images.remotePatterns, localPatterns and domains, together | 200 |
The 32 MiB upload limit is separate from storage limits: a shell or rendering placed in KV must fit within 25 MiB. Native framework Static Assets also keep their 25 MiB per-file limit.
A build over a limit fails, and the failure or the build log says which one; see Troubleshooting.