export const preferredRegion
Names the deployment region or regions a route segment should be deployed to (deprecated).
export const preferredRegion = // string || string[]- Deprecated since PHP v16.x — the API reference title reads "preferredRegion (deprecated)" and the deprecation message says to remove the export; no exact version is given in the changelog
Parameters
| Parameter | Type | Description |
|---|---|---|
$stringoptional | string | Deploy the route to a specific region. Available region codes are platform-specific, for example 'iad1'. |
$string[]optional | string[] | Deploy the route to multiple specific regions. The route is deployed to all listed regions, not to a single one chosen from the list, for example ['iad1', 'sfo1']. |
$'auto'optional | string literal= 'auto' | Vercel only. Default. Uses the default region. |
$'global'optional | string literal | Vercel only. Prefer deploying the route to all available regions. |
$'home'optional | string literal | Vercel only. Prefer deploying the route to the home region. |
Errors
On Vercel, passing an unsupported value throws an error.
Changelog
- PHP v16.xpreferredRegion deprecated. Remove the export from your route files; see the preferred-region-deprecated message. Regions were previously only supported alongside runtime = 'edge', which is itself now deprecated.
This one is a legacy of the Edge Runtime era. Regions were only ever meaningful for Edge functions, and with runtime = 'edge' deprecated the export went with it. The current guidance is a deletion: remove preferredRegion from page.ts, layout.ts, and route.ts.
What it did
The value is not interpreted by Next.js. It is passed straight through to the deployment platform, so the accepted codes and their meaning are the platform's, not the framework's. A string[] deploys the route to all the listed regions rather than picking one — a detail that surprised people who read it as a preference list.
Inheritance rules
An unset segment inherits from its nearest parent layout, and the root layout defaults to 'auto'. A child's value overrides the parent; the two are never merged. So a page listing ['sfo1'] under a layout listing ['iad1'] deploys to sfo1 only.
What trips people up
An unsupported value on Vercel throws rather than falling back to the default, and the classic reason to reach for this — putting a function in the same region as the database — is now handled at the project level, not per route.
Example
// Deprecated: remove this export and let the deployment
// platform place the function.
export const preferredRegion = 'iad1'
export async function GET() {
const res = await fetch('https://db.internal.example.com/orders')
const orders: { id: string; total: number }[] = await res.json()
return Response.json({ count: orders.length })
}When to use it
- Find and remove leftover region exports while clearing the deprecation warning during a Next.js 16 upgrade.
- Understand why an inherited region from a parent layout applies to a page that never set one.
- Read an older codebase that pinned an API route to the same region as its database.
Frequently asked questions
Is preferredRegion still supported in Next.js?
It is deprecated — the API reference is titled "preferredRegion (deprecated)" and the migration is to remove the export from page, layout and route files, since region pinning was tied to the now-deprecated Edge Runtime.
Does preferredRegion = ['iad1', 'sfo1'] pick the closest region?
No — the route is deployed to all listed regions, not to a single one chosen from the list.
Which region codes can I use with preferredRegion?
Next.js passes the value straight through to your deployment platform, so the valid codes are platform-specific; on Vercel the additional values 'auto', 'global' and 'home' are accepted and an unsupported value throws an error.
More examples
Clearing the deprecation warning
The documented migration is a removal with no replacement export. This is the same shape of fix as the Edge Runtime deprecation, and the two usually appear in the same files.
// app/api/orders/route.ts
// Before:
// export const preferredRegion = 'home'
// After: delete the line. Nothing replaces it — placement is
// handled by the deployment platform.
export async function GET() {
const res = await fetch('https://db.internal.example.com/orders')
const orders: { id: string; total: number }[] = await res.json()
return Response.json({ count: orders.length })
}Inheritance overrides, it does not merge
Illustrates the inheritance rule people get wrong. A segment with no value inherits its nearest parent layout's setting (the root layout defaults to 'auto'), and a segment that sets a value replaces the parent's list rather than adding to it.
// app/(eu)/layout.tsx
export const preferredRegion = ['fra1', 'cdg1']
export default function EuLayout({
children,
}: {
children: React.ReactNode
}) {
return <div>{children}</div>
}
// app/(eu)/checkout/page.tsx
// Overrides the layout entirely: this page deploys to iad1 only,
// NOT to fra1, cdg1 and iad1.
export const preferredRegion = 'iad1'
export default function CheckoutPage() {
return <h1>Checkout</h1>
}Multiple regions means all of them
The array form fans the route out to every listed region. Reading it as a fallback chain leads to unexpected cost and to functions running far from the data they query.
// app/api/search/route.ts
// Deployed to BOTH regions, not to whichever is closest.
export const preferredRegion = ['iad1', 'sfo1']
export async function GET(request: Request) {
const query = new URL(request.url).searchParams.get('q') ?? ''
const res = await fetch(
`https://search.example.com?q=${encodeURIComponent(query)}`
)
return Response.json(await res.json())
}
Discussion